Skip to content

Latest commit

 

History

History
96 lines (72 loc) · 4.4 KB

deploy.md

File metadata and controls

96 lines (72 loc) · 4.4 KB
Raw

Deploying OpenDC

This document explains how you can deploy OpenDC in your local environment. The official way to run OpenDC is using Docker. Other options include building and running locally, and building and running to deploy on a server.

Contents

  1. Setting up Auth0
  2. Installing Docker
  3. Running OpenDC from source

Setting up Auth0

OpenDC uses Auth0 as Identity Provider so that OpenDC does not have to manage user data itself, which greatly simplifies our frontend and backend implementation. We have chosen to use Auth0 as it is a well-known Identity Provider with good software support and a free tier for users to experiment with.

To deploy OpenDC yourself, you need to have an Auth0 tenant and create:

  1. An API
    You need to define the OpenDC API server in Auth0. Please refer to the following guide on how to define an API in Auth0.

    Remember the identifier you created the API with, as we need it in the next steps (as OPENDC_AUTH0_AUDIENCE).

  2. A Single Page Application (SPA)
    You need to define the OpenDC frontend application in Auth0. Please see the following guide on how you can define an SPA in Auth0. Make sure you have added the necessary URLs to the Allowed Callback URLs: for a local deployment, you should add at least http://localhost:3000, http://localhost:8080.

    Once your application has been created, you should have a Domain and Client ID which we need to pass to the frontend application (as OPENDC_AUTH0_DOMAIN and OPENDC_AUTH0_CLIENT_ID respectively).

  3. A Machine to Machine Application (M2M)
    You need to define a Machine to Machine application in Auth0 so that the simulator can communicate with the OpenDC API. Please refer to the following guide on how to create such an application.

    Once your application has been created, you should have a Client ID and Client Secret which we need to pass to the simulator (as OPENDC_AUTH0_CLIENT_ID_RUNNER and OPENDC_AUTH0_CLIENT_SECRET_RUNNER respectively).

Installing Docker

OpenDC uses Docker and Docker Compose to orchestrate the deployment of the software stack. Please refer to Docker Desktop for instructions on how install Docker on your machine.

Running OpenDC from source

To build and run the full OpenDC stack locally on Linux or Mac, you first need to clone the project:

git clone https://github.com/atlarge-research/opendc.git

# Enter the directory
cd opendc/

In the directory you just entered, you need to set up a set of environment variables. To do this, create a file called .env in the opendc folder. In this file, replace your-auth0-* with the Auth0 details you got from the first step. For a standard setup, you can leave the other settings as-is.

MONGO_INITDB_ROOT_USERNAME=root
MONGO_INITDB_ROOT_PASSWORD=rootpassword
MONGO_INITDB_DATABASE=admin
OPENDC_DB=opendc
OPENDC_DB_USERNAME=opendc
OPENDC_DB_PASSWORD=opendcpassword
OPENDC_FLASK_SECRET="This is a secret flask key, please change"
OPENDC_AUTH0_DOMAIN=your-auth0-domain
OPENDC_AUTH0_CLIENT_ID=your-auth0-client-id
OPENDC_AUTH0_AUDIENCE=your-auth0-api-identifier
OPENDC_AUTH0_CLIENT_ID_RUNNER=your-auth0-client-id-for-runner
OPENDC_AUTH0_CLIENT_SECRET_RUNNER=your-auth0-client-secret-for-runner
OPENDC_API_BASE_URL=http://web

We provide a set of default traces for you to experiment with. If you want to add others, place them in the traces directory and add entries to the database (see also the database folder)

If you plan to deploy publicly, please also tweak the other settings. In that case, also check the docker-compose.yml and docker-compose.prod.yml for further instructions.

Now, start the server:

# Build the Docker image
docker-compose build

# Start the containers
docker-compose up

Wait a few seconds and open http://localhost:8080 in your browser to use OpenDC. We recommend Google Chrome for the best development experience.