Nomad

Getting Started

Check out the code

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

Go into the checked out repository
```
cd nomad
```
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
```
(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. Then set the key as a variable in your .env file.
```
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. After creating credentials you'll get an OAuth Client ID and Client Secret. These need to go into your .env file as well.
```
echo GOOGLE_CLIENT_ID="YOUR_CLIENT_ID" >> .env
echo GOOGLE_CLIENT_SECRET="YOUR_CLIENT_SECRET" >> .env
```
(Optional) Configure Email Send In order for the app to send email, you'll need to add details about what mail server it should use. For testing, you can use a Mailgun or Gmail account. Add those details to the .env file, too!

echo MAIL_SERVER=smtp.mailgun.org >> .env
echo MAIL_PORT=465 >> .env
echo MAIL_USE_SSL=1 >> .env
echo MAIL_USERNAME=your_username >> .env
echo MAIL_PASSWORD=your_password >> .env

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.

Install Docker

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

On requirements

If requirements.txt 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

Set up a virtual environment

virtualenv venv
source venv/bin/activate

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
```
Install the Python dependencies.
```
pip install -r requirements.txt
```
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 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()

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

tangphillip / nomad