Nomad

Getting Started

1. Check out the code

   git clone git@github.com:RagtagOpen/nomad.git
   

2. Go into the checked out repository

   cd nomad

3. Local Variables

   Create a file for your local environment variables. This file should be called .env and live at the root of the nomad project directory.

   touch .env
   echo FLASK_APP=wsgi.py >> .env
   echo FLASK_DEBUG=1 >> .env

4. Add a SECRET_KEY to your .env. The value for SECRET_KEY can be any value for the purposes of local development.

    echo SECRET_KEY=your_secret_key >> .env

5. (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 .env file.

   echo GOOGLE_MAPS_API_KEY=YOUR_KEY_HERE >> .env

6. (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

7. 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.

1. Install Docker

   This will install Docker and Docker Compose. That should be everything you need.

2. 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

3. Run the project

   This will set up your database, run migrations, and start the application server for you.

   docker-compose up nomad nomad_worker

4. Browse to http://127.0.0.1:5000/ in your browser to check it out.

5. (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

On requirements

If 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 docker-compose.yml.

Running on Localhost

1. Install pipenv

   brew install pipenv

   or

   pip install pipenv

2. 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 psql command 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

3. Install the Python dependencies.

   pipenv install
   pipenv shell

4. Set up the database

   source .env
   flask db upgrade

5. Run the Flask application

   source .env
   flask run

6. 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.

1. With the app running, visit the login page in your browser and login with Facebook or Google.

2. 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
   

3. Add an admin Role to your single Person instance:

   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()
   

4. Visit http://127.0.0.1:5000/admin to verify your account now has the appropriate role.

Sending Email

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

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 .env configuration:

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

Then run source .env and flask run again to activate the changes.

Running tests

Using Docker:

docker-compose run nomad pytest

Locally:

pipenv install -d
pytest

Branding

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"
• BRANDING_SUPPORT_EMAIL - default support@ragtag.org

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."
• BRANDING_PRIVACY_URL - default /terms.html; the default terms.html uses values of BRANDING_ORG_NAME, BRANDING_ORG_SITE_NAME, and BRANDING_SUPPORT_EMAIL

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 .env

branding QA

• BRANDING_ORG_NAME in terms.html (ie "Ragtag Nomad Privacy Policy")
• BRANDING_ORG_SITE_NAME in terms.html ie "nomad.ragtag.org, the "Site""
• BRANDING_SUPPORT_EMAIL in terms.html ie "email support@ragtag.org"
• BRANDING_LIABILITY_URL in email templates: driver_reminder, ride_approved.html
• BRANDING_EMAIL_SIGNATURE in all email templates
• logo on home page, defined in CSS referenced by BRANDING_CSS_URL
• BRANDING_HEADLINE_1 and BRANDING_HEADLINE_1 on home page, below "SHARE YOUR RIDE"
• BRANDING_PRIVACY_URL privacy policy links on login and mobile and desktop nav

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.