Development - NatLabRockies/alfalfa GitHub Wiki

How to Set Up a Development Environment

Prerequisites

Alfalfa leverages containers for running code and thus has only a few prerequisites for development

  1. Docker
  2. Poetry
  3. Git or Github Desktop

Setting up

  1. Clone Alfalfa repository 
    git clone [email protected]:NREL/alfalfa.git
  2. Enter the repository folder 
    cd alfalfa
  3. Install Python dependencies 
    poetry install

How to Deploy Alfalfa for Development

Alfalfa has several configurations in which it can be run. These can be selected by using combinations of the docker-compose.yml files in the repo.

  • docker-compose.yml is the base compose file needed for all alfalfa deployments
  • docker-compose.dev.yml adds auto reloading and rebuilding of worker and web containers on source code changes
  • docker-compose.historian.yml adds influxdb and grafana for recording timeseries data and plotting

Example compose commands

For documentation on docker compose command see here.

docker compose build

Build Alfalfa images for base compose file.

docker compose up -d

Run Alfalfa from base compose file. --build can be added to any up command to rebuild any changes, this insures that the images are up to date. -d runs the containers in detached mode.

docker compose down -v

Delete containers and associated volumes. Clears all databases, good for cleaning house every now and then.

docker compose -f docker-compose.yml -f docker-compose.dev.yml up --build

Run alfalfa with auto reloading and rebuilding of worker and web containers when source code is updated. --build will rebuild images before running.

How to Run Local Tests

Unit Tests

  1. Start services for Alfalfa 
    docker compose up -d mongo redis minio mc goaws
  2. Run unit tests 
    poetry run pytest

Docker-based Simulation Tests

  1. Run docker dev stack locally (in detached mode)

    docker compose -f docker-compose.yml -f docker-compose.dev.yml up --build -d

  2. Run simulation tests

    docker exec alfalfa_worker_1 bash -c "cd /alfalfa && pytest -m docker tests/jobs"

  3. Clean up stack

    docker compose down

Integration Tests

  1. Run stack locally in detached mode 
    docker compose up --build -d
  2. Run integration tests 
    poetry run pytest -m "integration"
  3. Clean up stack 
    docker compose down

Release Instructions

  1. Release dependent projects as needed (e.g., alfalfa-client).
  2. Update version in pyproject.toml, package.json and point alfalfa-client dependency in pyproject.toml to point to released alfalfa-client
  3. Create a PR with the release prep branch against develop.
  4. Update the change log. It is easiest to use GitHub's "Generate Release Notes" which is accessible on the Draft New Release Page. Add in a tag and target (to the release prep branch), then click on the "Generate Release Notes".
  5. Wait for tests to pass
  6. Merge to develop
  7. Create a tag on develop with the format vX.X.X
  8. Create PR against main.
  9. Wait for tests and MERGE PR (squashing or rebasing will lead to strange behavior between main and develop)
  10. After merge to main images will automatically be released to Docker Hub under the following images. It is recommended to verify that these images are updated (which can take up to an hour).
  1. Release drafted release in Alfalfa repo
  2. Celebrate!