Getting Started

This page is about how to setup Engage development environment on machine. Docker provides a way to run applications securely isolated in containers packaged with all dependencies and libraries. We use Docker in this project. In the following sections, we’ll focus on how to setup development environment using Docker.

Before step into environment setup, please make sure Docker and Docker Compose are installed. If not, please follow the official documentation for installation.

• Docker: Please refer to Docker Documentation.

• Docker Compose: Please refer to Docker Compose.

Fork Project

Please fork this project to your own account on GitHub, and then clone it from there.

git clone https://github.com/{your-account}/engage.git

Environment Variables

Create a folder .envs in the root directory of project, then within .envs create a file .local with following environment variables:

# Django
DJANGO_SECRET_KEY=YN3ZBsDH8r7r0QBjWc7nSmGqU5Cr0tMHdLufTQNl

# PostgreSQL
POSTGRES_HOST=calliope-postgres
POSTGRES_PORT=5432
POSTGRES_DB=postgres
POSTGRES_USER=postgres
POSTGRES_PASSWORD=

# Celery
CELERY_BROKER_URL=redis://redis:6379/0

# Mapbox
MAPBOX_TOKEN=

# NREL PVWatts & PySAM API
NREL_API_EMAIL=
NREL_API_KEY=

# MapBox is used to render interactive maps throughout the application’s user interface. Must obtain a mapbox token for accessing the Mapbox basemap resources.To obtain a Mapbox Token, please refer to get-started-tokens-api.

# PVWatts is used to import PV solar capacity factor timeseries in the Locations tab of the user interface. Must obtain a PVWatts token for accessing the NREL API resources. To obtain a NREL_API_KEY, please refer to NRREL’s api-key.

The following environment variables about AWS SES are optional.

# AWS SES (Optional)
AWS_ACCESS_KEY_ID=
AWS_SECRET_ACCESS_KEY=
AWS_SES_REGION_NAME=
AWS_SES_REGION_ENDPOINT=
AWS_SES_FROM_EMAIL=

Build Images

Make sure you’re on the root directory of the project, then run:

$ docker-compose build

Go to grap a drink, it’ll take a few minutes to build the related images.

Start Services

After the images are built, to start docker container services and run in background,

$ docker-compose up --detach

Setup Database

Execute the app service, and enter the docker container.

$ docker-compose up --detach
$ docker-compose exec app bash

Next, we need to migreate django models, create a superuser and load sample data into database.

• Migrate Django Models

python manage.py migrate

• Create a Superuser

python manage.py createsuperuser

• Load Admin Data

Load parameters

python3 manage.py loaddata --app api \
  admin_run_parameter.json \
  admin_parameter.json \
  admin_abstract_tech.json \
  admin_abstract_tech_param.json \
  admin_group_constraint.json

Load templates

python3 manage.py loaddata --app template \
  admin_template_type.json \
  admin_template_type_variables.json \
  admin_template_type_techs.json \
  admin_template_type_locs.json \
  admin_template_type_loc_techs.json \
  admin_template_type_loc_tech_params.json \
  admin_template_type_tech_params.json \
  admin_template_type_carriers.json

• Load Sample Model (Optional)

python3 manage.py loaddata --app api \
  sample_model.json \
  sample_location.json \
  sample_technology.json \
  sample_tech_param.json \
  sample_loc_tech.json \
  sample_loc_tech_param.json \
  sample_timeseries_meta.json \
  sample_scenario.json \
  sample_scenario_loc_tech.json \
  sample_scenario_param.json

Web Server

The development web server in docker is running on port 8000 at the IP address 0.0.0.0, please visit: http://0.0.0.0:8000

If you want to bring container services to front with live logs on terminal, please run

docker-compose up

Done! Now, the docker development environment gets setup successfully, you can get start the development of Engage.