Check out the code
git clone firstname.lastname@example.org:RagtagOpen/nomad.git
Go into the checked out repository
Create a file for your local environment variables. This file should be called
.envand live at the root of the nomad project directory.
touch .env echo FLASK_APP=wsgi.py >> .env echo FLASK_DEBUG=1 >> .env
.env. The value for
SECRET_KEYcan be any value for the purposes of local development.
echo SECRET_KEY=your_secret_key >> .env
(Optional) Get a Google Maps Api Key
In order to run the search frontend you will need an API key for Google maps. You can get one here. On the "Enable Google Maps Platform" page choose "Maps" as the product. Then set the key as a variable in your
echo GOOGLE_MAPS_API_KEY=YOUR_KEY_HERE >> .env
(Optional) Configure Google Sign-In
In order to test Google authentication you'll need to create a Console Project.
For "Where are you calling from?" choose "Web server".
For "Authorized redirect URIs" enter http://localhost:5000/callback/google.
After creating credentials you'll get an OAuth Client ID and Client Secret.
echo GOOGLE_CLIENT_ID=YOUR_CLIENT_ID >> .env echo GOOGLE_CLIENT_SECRET=YOUR_CLIENT_SECRET >> .env
Configure Email Send
In order for the app to send email, you'll need to add details about what mail server it should use. See Sending Email below for instructions.
Running with Docker Compose
You can get up and running with Docker and Docker Compose. This will allow you to get up and running quickly while installing a smaller set of dependencies to your computer.
This will install Docker and Docker Compose. That should be everything you need.
Build the project
This will build the Docker images that you can use for local development
# Make sure you're at the root of the nomad project # Build the images. This will likely take a few minutes # the first time as it needs to download a few images from the Docker registry docker-compose build
Run the project
This will set up your database, run migrations, and start the application server for you.
docker-compose up nomad nomad_worker
Browse to http://127.0.0.1:5000/ in your browser to check it out.
(Optional) Taking more direct control
If you actually want to drop into a bash prompt in the nomad container you can execute to following command.
docker-compose run --service-ports nomad bash
Misc. notes on developing Nomad in Docker
Pipfile changes, a
docker-compose build will reinstall all Python dependencies
Accessing the DB
To connect to the DB in docker, run:
docker-compose run --service-ports nomad "psql postgresql://nomad:nomad@db/nomad"
Setting environment variables
.env does not get directly
source'd to the application context; rather, it's used to populate
docker-compose.yml, which can then be used to set environment variables in the applicaiton context. Therefore, if you add an environment variable in
.env that you want the app to be able to access, you must also add it in the
environment block of
Running on Localhost
brew install pipenv
pip install pipenv
Install the database. The app requires PostgreSQL and PostGIS. This guide describes how to get PostgreSQL running on your computer.
When you have PostgreSQL installed, you need to create a database for the data to go. Use the
psqlcommand to connect to your PostgreSQL instance:
psql # psql (9.6.1, server 9.5.4) # Type "help" for help.
Create the database and add the PostGIS extension:
create database carpools; # CREATE DATABASE \connect carpools # psql (9.6.1, server 9.5.4) # You are now connected to database "carpools" as user "iandees". create extension postgis; # CREATE EXTENSION \quit
Install the Python dependencies.
pipenv install pipenv shell
Set up the database
source .env flask db upgrade
Run the Flask application
source .env flask run
Browse to http://127.0.0.1:5000/ in your browser to check it out.
Adding the first admin user
Once you have the app running with Docker or locally, you need to add your first admin user.
With the app running, visit the login page in your browser and login with Facebook or Google.
In a console, bring up a Flask shell:
If you used Docker:
docker-compose run --service-ports nomad flask shell
If you are running the app locally:
# Make sure you've activated your virtual environment source venv/bin/activate # Run the flask shell source .env flask shell
Add an admin
Roleto your single
from app.models import Role, Person from app import db r = Role(name='admin', description='Administrator') db.session.add(r) p = Person.query.first() p.roles.append(r) db.session.commit()
http://127.0.0.1:5000/adminto verify your account now has the appropriate role.
The app has several email templates built in. In order to test them locally, you'll need to set up a few things.
Reading email in the Flask logs
By default, the email recipient, subject, and body of any outgoing message is written to the app's built-in logger, which is the console where you ran
flask run from. When the app sends an email (e.g., when requesting a spot in a carpool) look for the email contents in that terminal window.
Configuring SMTP settings
For more advanced testing, you can configure some SMTP settings to send to an actual mail server.
Mailgun or Gmail
For testing, you can use a Mailgun or Gmail account. Edit your .env file and add the following:
MAIL_LOG_ONLY=false MAIL_SERVER=smtp.mailgun.org MAIL_PORT=465 MAIL_USE_SSL=1 MAIL_USERNAME=your_username MAIL_PASSWORD=your_password
MailDev is a simple Node utility to listen for incoming SMTP connections and display the messages in an ephemeral Inbox.
With Docker, you can use the following
echo MAIL_SERVER=fakesmtp >> .env echo MAIL_PORT=25 >> .env echo MAIL_USE_SSL=0 >> .env
With that setup, you can run
docker-compose up nomad fakesmtp and view emails at http://localhost:8081/.
To set up MailDev without Docker, run the following in a separate Terminal from your main one:
npm install -g maildev # this may require sudo on some systems maildev
This should listen for email on 127.0.0.1 port 1025 and provide a browser interface at http://localhost:1080 which shows an Inbox of messages sent by the app. Keep that terminal window running in the background.
In your .env file, add the following:
# Maildev MAIL_LOG_ONLY=false MAIL_SERVER=localhost MAIL_PORT=1025 MAIL_USE_SSL=false MAIL_USE_TLS=false
source .env and
flask run again to activate the changes.
``` docker-compose run nomad pytest ```
``` pipenv install -d pytest ```
Organizations using Nomad need to set these environment variables:
BRANDING_ORG_NAME- organization name; default "Ragtag"
BRANDING_ORG_SITE_NAME- site name (not full URL), default "ragtag.org"
BRANDING_LIABILITY_URL- URL to organizer liability statement (required)
BRANDING_EMAIL_SIGNATURE- default "The Nomad team"
These environment variables have reasonable defaults; setting these is optional:
BRANDING_CSS_URL- URL to CSS with skin-specific overrides; default is no overrides. Leading / is required.
BRANDING_HEADLINE_1- default "Carpool to canvass in battleground districts near you"
BRANDING_HEADLINE_2- default "Find other volunteers near you and join a carpool."
/terms.html; the default terms.html uses values of
sample Swing Left branding
to use sample sample config for Swing Left locally:
cat branding/swing-left >> .env
sample branding config values: branding/swing-left
sample CSS overrides: static/css/swing-left.css
restart app to reload config from
BRANDING_ORG_SITE_NAMEin terms.html ie "nomad.ragtag.org, the "Site""
BRANDING_SUPPORT_EMAILin terms.html ie "email email@example.com"
BRANDING_LIABILITY_URLin email templates: driver_reminder, ride_approved.html
BRANDING_EMAIL_SIGNATUREin all email templates
- logo on home page, defined in CSS referenced by
BRANDING_HEADLINE_1on home page, below "SHARE YOUR RIDE"
Getting access to the repository
If you would like access to the repository either open an issue and ask for access or talk to one of the maintainers in the project's Slack channel.