Author: rgardler
Date: Thu Aug 13 22:18:27 2015
New Revision: 1695791
URL: http://svn.apache.org/r1695791
Log:
add some initial docs on working without docker, plus some small web app docs
improvmenets
Modified:
comdev/tools/readme.md
Modified: comdev/tools/readme.md
URL:
http://svn.apache.org/viewvc/comdev/tools/readme.md?rev=1695791&r1=1695790&r2=1695791&view=diff
==============================================================================
--- comdev/tools/readme.md (original)
+++ comdev/tools/readme.md Thu Aug 13 22:18:27 2015
@@ -3,9 +3,9 @@ development.
# Features #
-Currently we have a Command Line Interface and a Web Interface. The
-CLI is easy to use but very simple. The web application has more
-features but is more complex to use (and is in rapid development).
+Currently we have a Command Line Interface and a Web Interface. At the
+time of writing the CLI provides three output formats whereas the web
+interface focusses on better data management.
## Command Line Features ##
@@ -20,43 +20,13 @@ application.
## Web Application Features##
-Basic features (mimicking the CLI):
-
- 1) Visit http://yourhost.com/events
- 2) View the meetups that have been imported already (if any)
- 3) [OPTIONAL] Click the "actions" dropdown in the top right and select
"Import Meetups" to import any new meetups (be patient)
- 4) Click the "actions" dropdown in the top right and select "Upcoming
(Markdown)"
-
-Now you have your markdown file like the one generated in the
-CLI. we've not implemented the email or twitter files yet. But will
-gladly do so if you actually use them - let us know.
-
-Now for the additional features (there is more than this, poke around,
-I just enumerate the ones I think you will find useful)...
-
-We can define multiple search terms we want to include. It's currently
-set up for "Apache" only but we could add "Hadoop" for
-example. Duplicate events will be removed.
-
-When viewing the events at http://yourhost.com/events you can click
-"Mark Event N/A" and this will hide the event from view (and from the
-markdown export). Better yet you can click "Mark Group N/A" this will
-mark all meetups organized by this group in the database as N/A
-(including ones that are subsequently imported). In other words make
-the "Apache Junction" group as N/A and you'll never see a meetup from
-them again.
-
-Click on a specific meetup and you are given a summary of the
-event. On this page there is a "Later" button. Create yourself a
-Hootsuite account and you can use this to schedule tweets at a
-convenient time.
-
-There is more to the application than this but the above are the
-things that most people find useful from the start. We welcome your
-feature requests (preferably via the ComDev issue tracker). We welcome
-contributions even more and are happy to help you figure out where to
-put them if you want to do it yourself.
-
+ * Import new meetups from meetups.com
+ * Export a markdown formated list of events in the next two weeks
+ * Schedule tweets via Hootsuite
+ * Mark events as not applicable (will no longer appear in event lists)
+ * Mark groups as not applicable (their events will never appear in event
lists)
+ * Import members of groups
+
# Python CLI Script #
To run the application as a Python script simply execyte get_meetups
@@ -74,24 +44,40 @@ command line menu allowing you to work w
Note that these are POSSIBLY Apache-related. Typically, there's around
a 50% false positive rate, what with hiking trails, native American
-dance enthusiasts, and helicopter fans. These lists MUST be manually
+dance enthusiasts, and heilcopter fans. These lists MUST be manually
filtered before they are used anywhere publicly.
-See above for a description of a feture in the webapp version that
-helps immensly with this filtering.
-
If you use this script be respectful of the included API key.
-# Webapp #
+# Development #
-The webapp is a Dockerized application, the easiest way to get going
-is to read the development section below.
+ALthough not required it is recommended that you use Docker to manage
+your development and deployment environment as this will automatically
+configure your environment for you, though it does require you to have
+installed Docker.
+
+## Without Docker ##
+
+To work without Docker (untested please improve these docs if you go this
route):
+
+ * [Install Python 2.7.x](https://www.python.org/downloads/)
+ * [Install Django and
PostgreSQL](https://docs.djangoproject.com/en/1.8/topics/install/)
+
+ * pip install -r requirements
+ * python manage.py makemigrations
+ * python manage.py migrate
+ * python manage.py runserver
+
+You should now have a copy running localy on port 8000.
+
+For more information on how the application is built you need to
+understadn Django. A great starting point is the [Django
+tutorial](https://docs.djangoproject.com/en/1.8/intro/tutorial01/)
-# Development #
## Docker Prerequisites ##
-If you are using Windows as your client mhine then it is a good idea
+If you are using Windows as your client machine then it is a good idea
to install Git for Windows from http://msysgit.github.io/. This will
provide both Git and a Bash shell. We will use the Bash shell as a
convenience since the scripts we have built are Bash scripts.
@@ -112,36 +98,32 @@ Machine on other platforms see: http://d
### Docker Hosts ###
-We provide a number of convenience scripts for working with the
-application in the form of docker containers. In order to use these
-scripts you will need to do the following:
-
- $ cp scripts/config.tmpl scripts/config.sh
-
-As a minimum you will need a Docker host for development. By default
-this is called "dev" (you can change this name in the config.sh file
-you just created). You'll most likely want this to be on your local
-machine. So run the following command (as an administrator):
+As a minimum you will need a Docker host for development. You'll most likely
+want this to be on your local machine. So run the following command (as an
+administrator):
- $ docker-machine create -d hyper-v dev
+ $ docker-machine create -d hyper-v comdev
Note the "-d hyper-v" is for Windows machines, you may want to use a
different provider if you are developing on a different platform.
-If you want to use a cloud provideor for your staging server then
-create a machine on the appropriate cloud using docker-machine and
-edit config.sh to point to the right machine name.
+You'll also need to ensure that your docker client is using this
+machine. Run the following command:
+
+ $ eval "$(docker-machine env comdev)"
#### Share your project code with the Docker Host ####
You need to ensure your project directory is available on the Docker
Host. On Windows you will need to share it explicitly. We've provided
-a helper script to do this.
+a helper script to do this. First, create a confiduration file:
+
+ $ cp scripts/config.tmpl scripts/config.sh
-You will need to edit the 'config.sh' file, paying close attention to
-the section on Windows share configuration.
+Edit the 'config.sh' file, paying close attention to the section on
+Windows share configuration.
-Now run:
+No run:
$ scripts/configHyper-v.sh
@@ -158,96 +140,52 @@ containers during development. Your loca
will be mapped into /project on the container, thus local edits will
be available in your development container immediately.
-We have provided a script that will setup a development environment
-for you. To setup a clean environment (i.e. no starting data) on
-either your dev or staging server using the command:
-
- $ scripts/push.sh
-
-NOTE: this command kills any running containers and restarts them
-(see below for less destructive scripts). This will remove any data
-that has been changed during the most recent development
-activity. Only run this command if you are prepared to go back to a
-clean dev state.
-
-Note that while this will start your development environment it does
-not provide any starting data. Log in to your admin interface
-(http:://yourhost.com/admin) and enter at least one
-"hashtag". Hashtags are search terms used when searching meetups.com.
-
-## Migrating to a new DB version on the Dev machine
+The first time you run the container you will need to configure the
+database. Subsequent runs will just require standard Django commands
+to be run.
-If, rather than creating a clean development environment, you want to
-migrate the database in a running instance of the application to a new
-version of the application use the following command to generate any
-migrations and execute them):
+### First Run ###
- $ script/migrateDev.sh
+As with all Docker containers the first time you build and run them
+the images and corresponding layers need to be downloaded. This can
+take a few minutes. After the first run everything is very quick.
-TODO: make the migration scripts work on staging servers not just dev
-servers
+Ensure you are in the project root and then start the postgres
+database container:
-NOTE: This will only work if each new field has defaults provided. The
-system will report errors if no defaults are defined. If you do not
-want to have a default in the final version of the database simply add
-a default, run the migration, then remove the default and run the
-migration again.
+ $ docker run -d -v //home/docker/project:/project -p 5432:5432 --name
comdev_db postgres
-## Backup and Restore
+Build the application container:
-In order to backup your data run the following command on the
-meetups_app container (as root):
+ $ docker build -t comdev .
- docker exec meetups_app python manage.py dumpscript >
/home/project/comdev/tools/fixtures/events_list_data.py
+Configure the application and the database:
-This will use the docker_extensions command
-"[dumpscript](http://django-extensions.readthedocs.org/en/latest/dumpscript.html)"
-to create a script that can be used for rebuilding the database to
-it's current state.
+ $ docker run --rm -v //home/docker/project:/project --link comdev_db:db
comdev python manage.py makemigrations events_list
+ $ docker run --rm -v //home/docker/project:/project --link comdev_db:db
comdev python manage.py migrate
-When running in production it is recommended that you run this script
-via a cron job or similar. However, note that depending on your setup
-this may result in the backup data being saved to an ephemeral disk -
-not ideal for a data backup. It is your responsbibility to ensure the
-data is securely backed up from within the container.
+Now, run the application:
-### Interim backup solution
+ $ docker run --rm -v //home/docker/project:/project --link comdev_db:db
-p 80:8000 --name comdev_app comdev python manage.py runserver 0.0.0.0:8000
-One way to backup the data, since it is just a text file, is to put it
-in SVN along with the project code. This will be handled automatically
-for you if you add a second argument "commit".
+Now you can visit the app at http://docker.host
-However, for this to work the script needs to be run by a user with
-commit access to the repository. Also note that there is a danger that
-users will overwrite the data with there own data from a local
-instance of the application.
-
-Despite these drawbacks this is a good temporary workaround since you
-will always have SVN history to revert to.
-
-TODO: implement a restore script
-
-## Running Django Commands on your Application Server ###
+### Running Django Commands ###
From this point development is just like any other Django application,
but to run Django commands in the app container you will need to open
a terminal on that machine. To do this run:
- $ docker exec -it meetups_app bash
+ $ docker exec -it comdev_app bash
-To run individual commands rather than entering an interactive shell:
-
- $ docker exec meetups_app python manage.py COMMAND
-
-## Using the Admin Interface ##
+### Using the Admin Interface ###
To access the admin interface of the application you need an admin
-user account. If you used the push.sh script you will have defined an
-admin user during initial deployment of the application.
-
-If you need to create another admin user then run the following
-command:
+user account. Assuming you are starting from a clean development
+container (i.e. with no data in the database) you will need to create
+an admin user. To do this run the following command in your Django
+terminal.
- $ docker exec -it meetups_app python manage.py createsuperuser
+ $ python manage.py createsuperuser
Now you can log into the admin app at http://docker.host/admin
