-
Check out the code
git clone [email protected]: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
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
-
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
If requirements.txt
changes, a docker-compose build
will reinstall all Python dependencies
To connect to the DB in docker, run:
docker-compose run --service-ports nomad "psql postgresql://nomad:nomad@db/nomad"
.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
.
-
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.
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 singlePerson
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.