Deployment

General Deployment Considerations

Alfalfa is a containerized application that can be deployed via docker-compose, Docker Swarm, or Kubernetes. Experience deploying and troubleshooting Docker applications is a pre-requisite.

The Alfalfa Helm Chart repo contains resources for deployment to Kubernetes. This is the recommended pathway for production deployments. Instructions below are for deployment with docker-compose and Docker Swarm and intended primarily for local development and testing.

Caveats

1. All deployment instructions here use environment variables that are committed to the repo. These are set to allow local deployments to work seamlessly out of the box, but it is your responsibility to update any sensitive variables (ie credentials) before deploying.
2. Unlike your average web application, Alfalfa is heavily dependent on in-memory state because the underlying models must run in memory. This means that deployments are not resilient to worker restarts; if a worker is restarted while a model is running, that model state will be lost.

How to Deploy Historian

Alfalfa includes optional Historian functionality, which is enabled by setting the HISTORIAN_ENABLE=true environment variable for the worker container and adding two containers to the stack:

1. InfluxDB for timeseries data storage
2. Grafana for visualization

Notes

1. Note that in images published to DockerHub, the datasource has been provisioned to connect to InfluxDB using the username and password in the repo's .env file. If you have updated these (as you should) for your deployment, you will also need to manually update them via the Grafana UI, which can be accessed at <grafana-host>/datasources/edit/1/
2. Model time is always treated as UTC, which is also the default for chart display. This means that plot filters like "past 6 hours" are relative to current UTC time.
3. The Historian only considers model time and has no concept of the real-world time as simulations run. All plots are of model time.

How to Deploy with docker-compose

This assumes that you have installed Docker and docker-compose and are in the root of this repo.

1. update .env file: replace any credentials with real values and modify VERSION_TAG if appropriate to a tag available on DockerHub. To build the containers yourself, do not run the pull command and append --build to the up commands below.
2. Without Historian:

docker compose pull && docker compose up -d

With Historian:

HISTORIAN_ENABLE=true && docker compose -f docker-compose.yml -f docker-compose.historian.yml pull && docker-compose -f docker-compose.yml -f docker-compose.historian.yml up -d

3. Confirm the web server is up at http://localhost
4. Confirm the minio (file upload) server is up at http://localhost:9000
5. Confirm the historian (if applicable) is up at http://localhost:3000
6. Clean up with docker compose down or docker compose -f docker-compose.yml -f docker-compose.historian.yml down
7. To clear the database and delete uploaded models run docker compose down with -v argument

How to Deploy with Docker Swarm

1. Swarm deployments don't load .env, so do that explicitly: export $(cat .env | xargs)
2. Without Historian: docker stack deploy -c docker-compose.yml alfalfa
3. With Historian: HISTORIAN_ENABLE=true && docker stack deploy -c docker-compose.yml -c docker-compose.historian.yml alfalfa
4. Confirm the web server is up at http://localhost
5. Confirm the minio (file upload) server is up at http://localhost:9000
6. Confirm the historian (if applicable) is up at http://localhost:3000
7. Clean up: docker stack rm alfalfa