Dokomo どこも Forms is a mobile data collection technology that doesn't suck.
-
Install PostgreSQL, the contributed packages, PostGIS, and the PostgreSQL server development packages:
sudo apt-get install postgresql postgresql-contrib postgis postgresql-server-dev-all
(or whatever the command is on your distribution)
You may also need to install a package like postgresql-X.Y-postgis-scripts (check your repositories).
Debian users: update your apt sources according to this guide else you will pull your hair out wondering why CREATE EXTENSION "postgis"; fails.
-
$ pip-python3 install -r requirements.txt(or whatever the command is on your distribution) -
Create a "doko" database (or whatever other name you want) and a system user (if desired -- the postgres default user should work fine) with access to that database.
-
Edit your dokomoforms/local_settings.py file with the correct PostgreSQL
CONNECTION_STRING(see dokomoforms/settings.py).If you run manage_db.py as user postgres (and because of the extension creation commands, you basically have to), here is how to change the postgres database (as opposed to unix user) password:
# sudo su - postgres $ psql
psql (9.3.5) Type "help" for help.
postgres=# \password postgres Enter new password: Enter it again: postgres=# \q
Now, run the next command (number 5) as unix user <tt>postgres</tt>.
5. `$ python3 manage_db.py --create`
6. `$ python3 webapp.py`
**Note that if `debug` is `True` in the `webapp.py` `config` variable, Anyone can log in as any user. DO NOT SET `debug` TO `True` IN PRODUCTION. Likewise, `APP_DEBUG=true` in local_settings.py sets the `debug` flag to `True`.**
**Finally `TEST_USER=USER` in local_settings permanently logs user USER in for everyone, DO NOT SET THIS IN PRODUCTION.**
# Running the tests
1. `$ pip-python3 install nose coverage selenium`
2. `$ nosetests -c tox.ini`
* **Note:** Selenium tests involve browser windows popping up. If this causes issues on your machine or you'd just prefer for that not to happen, install [Xvfb](http://en.wikipedia.org/wiki/Xvfb) and use this command instead: `xvfb-run nosetests -c tox.ini`
## Running Selenium tests on Sauce Labs
In order to make it easier to test across devices and browsers, you can run the Selenium tests on Sauce Labs.
1. Sign up for an account at [saucelabs.com](https://saucelabs.com/)
2. Install and run sauce-connect: https://docs.saucelabs.com/reference/sauce-connect/
3. Using your username and access key from Sauce Labs, edit your dokomoforms/local_settings.py file like so:
SAUCE_CONNECT = True SAUCE_USERNAME = 'username' SAUCE_ACCESS_KEY = 'access key' DEFAULT_BROWSER = 'firefox::Linux'
4. `$ nosetests tests.selenium_test`
# Using Docker for Local Dev Environment and Deployment
[Docker](https://en.wikipedia.org/wiki/Docker_(software)) is a container management software that aims at component separation and deployment automation. Please refer to [the Docker API](https://docs.docker.com/) for a fuller introduction.
## Using Docker Manually (Docker knowledge required)
There is a [Dockerfile](Dockerfile) in the root directory to build the Docker image of the Dokomo Forms webapp component building on top a Python 3 image. To build the webapp image, run
> $ docker build . -t selcolumbia/dokomoforms
However, Dokomo Forms as a service needs other components such as the database in order to work. We have referenced `mdillon/postgis` as the image, since we are using PostgreSQL with the PostGIS extension. You may also substitute `mdillon/postgis` with any image includes PostGIS. A manual way to run Dokomo Forms as a service would involve starting the `postgis` container and linking it to the Dokomo Forms image we have just built, such as:
> $ docker run -d -p 8888:8888 --link postgis:db selcolumbia/dokomoforms
## Using Docker for Local Development
`docker-compose` is the program that automates Docker container building, running, and linking as described above. It uses the [docker-compose.yml](docker-compose.yml) file which is provided in the root directory.
To start the service locally, run:
> $ docker-compose up
Docker will download the necessary images, then build and link them. This step takes 3-5 minutes for the first build. Once the command has finished, you can visit [http://localhost:8888](http://localhost:8888) and start using Dokomo Forms.
## Using Docker for Automated Deployment
`docker-machine` is the program that automates the deployment process. It can hook into many VPS providers such as [AWS](http://aws.amazon.com/), [Rackspace](http://www.rackspace.com/) and [DigitalOcean](https://www.digitalocean.com/).
Here is an example using DigitalOcean:
1. Obtain a token from DigitalOcean. Click on "Generate New Token" from the API page as indicated below.
2. Create a droplet with the token you have just acquired
> $ docker-machine create -d digitalocean --digitalocean-access-token YOUR_ACCESS_TOKEN dokomoforms
3. Make your local Docker environment aware of this new machine
> $ eval $(docker-machine env dokomoforms)
4. Run `docker-compose` with the new environment
> $ docker-compose up -d
Now you have an instance of Dokomo Forms running on your DigitalOcean droplet!