Alfalfa is an open source web application forged in the melting pot of Building Energy Modeling (BEM), Building Controls, and Software Engineering domain expertise. Alfalfa transforms Building Energy Models (BEMs) into virtual buildings by providing industry standard building control interfaces for interacting with models as they run. From a software engineering perspective, Alfalfa leverages widely adopted open source products and is architected according to best practices for a robust, modular, and scalable architecture.
Documentation resides in the GitHub wiki!
We are currently working on increasing our developer documentation. See how to run the tests on the GitHub wiki. For releasing, see the wiki's release instructions.
Alfalfa runs as a Docker Compose stack (web, worker, MongoDB, Redis, and MinIO). Configuration is read from the .env file in the repository root. Requires Docker with the Compose plugin.
Builds the optimized web bundle and runs the web service with node build/index.js:
docker compose up --buildThe web application is served at http://localhost/ and the API docs at http://localhost/docs. MinIO is available at http://localhost:9000.
Mounts alfalfa_web and alfalfa_worker into the containers and runs them in watch mode so code changes reload automatically (webpack watch for the web, watchmedo for the worker):
docker compose -f docker-compose.yml -f docker-compose.dev.yml up --buildHISTORIAN_ENABLE=true docker compose -f docker-compose.yml -f docker-compose.historian.yml up --buildGrafana is served at http://localhost:3000.
docker compose down # or: docker compose down -v to also remove volumesThe Alfalfa docker images are published to the GitHub Container Registry (GHCR) under the natlabrockies org for easy deployment via Helm or other docker services. The images include:
- Alfalfa Web —
ghcr.io/natlabrockies/alfalfa/web - Alfalfa Worker —
ghcr.io/natlabrockies/alfalfa/worker - Alfalfa Grafana —
ghcr.io/natlabrockies/alfalfa/grafana
Pull an image with:
docker pull ghcr.io/natlabrockies/alfalfa/web:latestIf the packages are private, authenticate first with a GitHub personal access token that has the read:packages scope:
echo "$GHCR_TOKEN" | docker login ghcr.io -u <github-username> --password-stdinAn Alfalfa Python Notebook repository contains examples on how to interact with Alfalfa.
The Alfalfa Client is a Python library for making API calls to Alfalfa easier. The source code is available on GitHub and the package is released through PyPi.