Draw My Life API / Admin
Draw My Life is an open source, volunteer-led initiative in partnership with Terre Des Hommes and partners, born at an EmpowerHack hackathon for refugee women and girls in 2016. The initiative consists of multiple, separate and inter-related projects aiming to improve mental health support for refugee children.
- An administration system used by field workers to upload images and data from art therapy sessions - status: live, with updates/improvement issues open
- A public API of this data (see Apiary spec), ensuring anonymity and with respect to consent - in progress, issues open
- A JSON endpoint to integrate with the UN's Humanitarian Data Exchange (HDX) collating open data sources. This endpoint will expose data using HXL standards and be used to create a separate HXL-formatted API via the open source HXL Proxy - (see example Draw My Life Proxy API interface). - in progress, issues open
We also have a team website being built with Jekyll/React with open issues over at empowerhack/DrawMyLife-Website
For New Volunteers
- Say hi to the team on Slack
- Read the starter document
- Check the Project Sprint Boards for issues in the Pick Me Up column. The boards are organised by goal. Open issues will typically have a milestone. We also have frontend-heavy project boards on our team website repository empowerhack/DrawMyLife-Website.
- If creating a new issue to work on, please ensure the task is discrete (i.e. easily transferred to a new assignee), clearly described, and has no more than 3 labels. Ideally we should clearly separate UX/design and dev tasks.
- Follow the instructions below to set up (feel free to holler/submit a pull request if it looks out of date)
- Install Prerequisites
- Get Up and Running
- Deployment and Production Notes
NB: These installation instructions are catered for Mac OS X users. You will need to look up alternative installation methods for different operating systems or feel free to chat to us on Slack for advice on how to get set up.
About the Command Line
Most of these instructions require typing commands into your shell prompt (if you're new to this, this is a nice beginner tutorial). Whenever you see a box like this:
$ echo "Hi! I'm a friendly command in your prompt."
these are commands you should type into your command line program, e.g. Terminal on a Mac. The $ represents a new line in your shell prompt, you need to type everything after it.
Homebrew package manager
This is a package management system for Mac that help you install a lot of dev tools easily.
Follow the download instructions at brew.sh
Git version control
$ brew install git
There are many methods for installing Ruby which you can explore here. We recommend installing using a version manager. The instructions below use rbenv. NB: It's always good to check official READMEs of external tools for detailed and up-to-date instructions.
Installing with rbenv (via homebrew):
$ brew install rbenv ruby-build $ rbenv init $ rbenv install 2.3.1
You'll use this to manage gems installed under your version/s of Ruby or specified in your project. Note if you're using a version manager like rbenv, you need to reinstall gems for each different version of ruby you switch to and you can see what gems are currently installed for your version of Ruby with the command
$ gem list. Bundler can be installed as a gem itself (I know, meta right?):
$ gem install bundler
We use Postgres for all our database needs. Download the latest version in a single package from PostgresApp.
You can also set up your path to use tools directly on your command line as per these docs:
$ echo 'export PATH=$PATH:/Applications/Postgres.app/Contents/Versions/latest/bin' >> ~/.bash_profile
Create your development and test databases
$ createdb drawmylife_development $ createdb travis_ci_test
For image uploads, you'll need ImageMagick installed. You can install nice and easily using our friend Homebrew:
$ brew install imagemagick
Get Up and Running
Run the app
Clone the repository on GitHub:
$ git clone email@example.com:empowerhack/DrawMyLife-Service
Enter your new project folder:
$ cd DrawMyLife-Service
Copy the example development ENV vars to your own .env file:
$ cp .env.development.example .env
The following steps should be done now any time you pull new changes in from the remote:
Install all the dependencies from your Gemfile using Bundler:
$ bundle install
Set up your database and seed sample data (including admin users to log in and an API key!):
$ bundle exec rake db:migrate $ bundle exec rake db:seed
Run the Rails server:
$ bundle exec rails s
You should now be able to access the admin app in your browser at localhost:3000. If you ran the database seed task you can log in with firstname.lastname@example.org or email@example.com (password is 'password')!
Try out the API
Once you've completed the steps above, you should also now be able to access the drawings API. The hypermedia API format is JSON HAL and is secured with very simple token access. You will need to pass a token through as a header with your request.
Find the seeded API key in your Rails console:
If this errors, you may not have run the seeds script yet. You can also generate one using:
Using this token, make a request via cURL on the command line, e.g:
$ curl http://localhost:3000/api/drawings.hal -H 'Authorization: Token token="cd1facb479c09638967c2dcf78d22d5b"'
Note the .hal extension there ^
Set up emails
In development, emails are configured to send to localhost:1025. You can install the mailcatcher gem for an interface to see these emails (follow instructions on the site and do not add this to the Gemfile!).
To run commands, queries and play around in the Rails console (in a new shell):
$ bundle exec rails c
Also, in the shell window you ran the actual server, you can see request logs as you navigate the site. If you stick the
byebug command anywhere in the codebase, it will pause any request and give you an interactive shell to step through the process, inspect variables etc.
To ensure your test database is up-to-date, run: $ RAILS_ENV=test bundle exec rake db:reset
We will be using rspec for tests. To run all tests, from your project's root, run:
$ bundle exec rspec spec
Or for just one set of tests:
$ bundle exec rspec spec/models/drawing_spec.rb
Deployment and Production Notes
Draw My Life is currently hosted on Heroku, with images automagically hosted on a free tier Amazon Simple Storage Service (S3) instance. The
.env.production.example file holds a template of the ENV vars required to be set on the live production environment.
Please ask the team for details if you need deployment instructions.
We have a staging environment set up which is auto-deployed to from the
staging branch in GitHub. Pushing any changes to this branch will update the staging environment.
The staging environment is set up as a replica of the Production environment, hosted on Heroku using an Amazon Simple Storage (S3) instance for image storage.