Skip to main content

Deployment Overview

This section provides comprehensive documentation for deploying OpenDSO applications and services using the OpenDSO Docker Compose project. The deployment process is designed to be flexible, allowing you to run specific services or the entire OpenDSO stack from a command line tool.

Note: The git repositories listed in this sections require Github account access. If you're finding you don't have access but believe you should, please reach out to your Open Energy Solution support team or representative.

OpenDSO Deployment Architecture​

OpenDSO deployments are composed of three separate GitHub repositories that work together:

1. Opendso Docker Compose project​

The base OpenDSO Docker Compose orchestration used generically across many of OES's OpenDSO Deployments.

  • Repository: opendso-docker-compose
  • Contains: Docker Compose definition file, orchestration scripts
  • Purpose: Provides the generic, reusable Docker Compose configuration and command line tool.
  • Key files: compose.yaml, run.sh

2. OpenDSO Configuration Repository​

Client-specific configuration files needed by the opendso-docker-compose project.

  • Repository: {client_repo_name}-config-docker-compose
  • Contains: Environment variables, JSON/YAML configs, and service settings
  • Purpose: Provides the deployment-specific configuration and the files that are referenced in the opendso-docker-compose project.
  • Key files: app and services configrations.
    • Example: edo-adr-app/nginx/default.conf -- contains the nginx configuration for the EDO-ADR App's nginx server.

3. Client Specific docker-compose Repository​

OpenFMB adapter configurations for clients equipment.

  • Example: {client_repo_name}-docker-compose
  • Contains: OpenFMB adapter configurations for reclosers, air switches, and other devices.
  • Purpose: Maintains the adapter configuration files, and docker compose defintion for the deployment of OpenFMB Adapters.
  • Documentation: See OpenFMB documentation for detailed information on the OpenFMB Adapters.

Additional Components​

  • certs/ - Generated TLS certificates (created by setup scripts, certbot, or other certificate authorities)
  • output/ - Output from the running containers. Contains logs and processed files that are used for backup/restoration, and for troubleshooting.

Key Components​

In summary, the OpenDSO deployment architecture consists of several key components:

  • Docker Compose orchestration - Base orchestration system from opendso-docker-compose
  • Configuration files - Client-specific environment variables and service settings
  • TLS certificates - SSL/TLS certificates for secure deployments
  • OpenFMB adapter deployment & configurations - The definition for deployed OpenFMB adapters for field device communication

Opendso-Docker-Compose project overview​

The OpenDSO Docker Compose project is the base OpenDSO orchestration project. Designed to provide modular deployments, where OpenDSO Applications and Services are organized into seperate profiles. This approach allows specific services, applications and adapters to be deployed

OpenDSO is designed to be both deployed on larger "Backoffice" servers (capable of running more Apps and Services), or on smaller "Field Compute Devices" (often hosting a single service and openfmb adapter).

This is the list of the current modular profiles:

  • all - All the apps and services for the base OpenDSO deployment (except simulators). This profile is a good start for the "Backoffice" server.
  • api - GMS HMI API and MongoDB database
  • docs - Documentation application
  • events - Event service and application
  • historian - Historian service, Hisorian proxy, and Historian HMI application
  • hmi - OpenFMB HMI application
  • nats - NATS message broker. Either a singular deployment or leaf-node.
  • services - All backend services
  • ui - All user interface applications
  • volt - Volt/VAR optimization application
  • cvr - Conservation Voltage Reduction application

Prerequisites​

Before deploying OpenDSO, ensure you have the following dependencies installed on the host machine/server:

  • bash - Shell for running deployment scripts
  • docker - Docker Engine and Docker Compose v2+
  • jq - Command line JSON processor for script operations
  • go - Go language runtime
  • mkcert/certbot/etc - Certificate generation tools, depending on your deployment environment (local, test, or production), you'll use either mkcert, certbot, certmanager, or another Cert Providers cert generation process.

Deployment Structure​

For a typical client deployment, you'll clone the three repositories into a common directory. During OpenDSO Deployment, two other folders will be generated.

deployment-folder/
├── opendso/                    # Generic OpenDSO orchestration
├── config/                     # \{client_repo_name\}-config-docker-compose repo
├── models/                     # \{client_repo_name\}-docker-compose (OpenFMB adapters)
├── certs/                      # SSL/TLS certificates (generated during deployment)
└── output/                     # Container logs and outputs (generated during deployment)

The opendso/run.sh script orchestrates the deployment using:

  • Configuration files from ../config/
  • OpenFMB adapter configs from ../models/
  • Certificates from ../certs/

Deployment Workflow​

The Local and Platform documents will dive deep into the actual deployment steps for those deployment scenarios. But the typical deployment workflow regardless of the type of deployment consists of common steps.

  1. Initial Setup - Generation of certificates and configuration of Domain Name/DNS resources
  2. Configuration - Setting specific environment variables and service tags
  3. OpenDSO Deployment - Starting the needed OpenDSO Applications and OpenDSO Services
  4. Adapter (Model) Preparation - OpenFMB Adapter deployment and testing
  5. Verification (QA) - Confirm applications, services and OpenFMB adapters are running correctly
  6. Continuing Operations - Monitor, backup, and manage running services

Versioned Release Archives​

Production deployments do not clone the config and models repositories directly. Instead, both repositories use a GitHub Actions workflow to publish a versioned zip archive as a GitHub release asset whenever a git tag is pushed. The deployment host then downloads the appropriate zip for the tag it should be running.

This gives each client deployment a stable, auditable "version" composed of:

  • A tagged release of the \{client_repo_name\}-config-docker-compose repo (published as config.zip)
  • A tagged release of the \{client_repo_name\}-docker-compose (models) repo (published as models.zip)
  • A tagged release of opendso-docker-compose (published as opendso.zip)

How the Archive is Built​

Both the config and models repositories include a .github/workflows/main.yaml workflow with the same structure. The workflow is triggered on any tag push (on: push: tags: '*') and performs the following:

  1. Checkout the repository at the tagged commit (full history, fetch-depth: 0).
  2. Determine version using GitVersion.
  3. Write .version containing the tag name (echo "${GITHUB_REF#refs/*/}" > .version) so the deployed archive carries the version stamp.
  4. Zip the repository using thedoctor0/zip-release@main, excluding .git*, .vscode/*, and .editorconfig. The output is named config.zip for the config repo and models.zip for the models repo.
  5. Publish a GitHub release for the tag using ncipollo/release-action@v1, attaching the zip as a release asset.

The result is a release page on each repo (e.g. https://github.com/openenergysolutions/{client_repo_name}-config-docker-compose/releases) where every tag has a downloadable config.zip or models.zip attached.

How Deployments Consume the Archives​

On the deployment host, the setup-opendso.sh script (see Production Deployment) reads a config.json manifest that lists which repositories and asset names to fetch. For each entry it calls the GitHub API for the latest release on that repo and downloads the zip asset, then unzips it into a directory named after displayName (e.g. config/, models/, opendso/).

This means tagging a new version on the config or models repo and re-running setup-opendso.sh is the standard way to roll a deployment forward to a new version — no manual git pull on the deployment host. See Production Deployment for the full tag-and-deploy procedure.

Next Steps​

  • Local Deployment - For newcomers to OpenDSO deployments, it's recommends to run OpenDSO locally before moving onto a production environment. This will let you experiment and try out OpenDSO on your local desktop or laptop, allowing you to learn the basics within your own sandbox.