community-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From rgard...@apache.org
Subject svn commit: r1695791 - /comdev/tools/readme.md
Date Thu, 13 Aug 2015 22:18:28 GMT
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



Mime
View raw message