Local Test Deployment

This guide provides step-by-step instructions for deploying OpenDSO on a local machine or VM for development, testing, and training purposes.

Overview

A local test deployment is ideal for:

Development and testing of OpenDSO applications and services
Training and familiarization with the platform
Proof-of-concept demonstrations
Integration testing before production deployment

This deployment uses self-signed certificates and local domain names, making it unsuitable for production use.

For production deployments, see the Production Deployment Guide.

Repository Overview

A local OpenDSO deployment consists of three repositories working together:

opendso-docker-compose - Generic OpenDSO Docker Compose orchestration
{client}-config-docker-compose - Client-specific configuration files
{client}-docker-compose - OpenFMB adapter configurations for field devices

This guide uses generic examples. Replace \{client\} with your actual client/project name.

Prerequisites

Ensure the following are installed on your local machine:

Docker Engine 20.10 or later
Docker Compose v2.0 or later
bash shell
jq (JSON processor)
go (Go language runtime)
git

Install Prerequisites on Linux (Ubuntu/Debian)

# Update package index
sudo apt-get update

# Install Docker
curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh
sudo usermod -aG docker $USER

# Install jq
sudo apt-get install -y jq

# Install Go
sudo apt-get install -y golang-go

# Install git (if not already installed)
sudo apt-get install -y git

Log out and back in for Docker group membership to take effect.

Initial Setup

1. Clone Required Repositories

Create a directory for the deployment and clone all three repositories:

mkdir opendso-local
cd opendso-local

# Clone the generic OpenDSO orchestration
git clone https://github.com/openenergysolutions/opendso-docker-compose.git opendso

# Clone client-specific configuration
git clone https://github.com/openenergysolutions/\{client\}-config-docker-compose.git config

# Clone client OpenFMB adapter configurations
git clone https://github.com/openenergysolutions/\{client\}-docker-compose.git models

Your directory structure should now look like:

opendso-local/
├── opendso/                   # Deployment orchestration
├── config/                    # Client-specific configs
└── models/                    # OpenFMB adapter configs

2. Generate TLS Certificates

Navigate to the orchestration directory and run the setup:

cd opendso
./run.sh -s opendso.localhost

This command will:

Clone and build mkcert if not already present
Generate self-signed TLS certificates for the opendso.localhost domain
Install the certificates in ../certs/ directory
Display required host file entries for your system

Important - Domain Name Selection:

Do not use .local domains on macOS - The .local TLD is reserved by mDNS/Bonjour and will not work
Use .localhost or .test domains for cross-platform compatibility
This guide uses opendso.localhost which works on Linux, Windows, and macOS

Adding Host File Entries:

After running the setup, manually add the displayed entries to your hosts file:

Linux/macOS: /etc/hosts (requires sudo)
Windows: C:\Windows\System32\drivers\etc\hosts (requires administrator)

Example output to add to hosts file:

# --------------------- OpenDSO Domains ---------------------
0.0.1 opendso.localhost
0.0.1 api.opendso.localhost
0.0.1 auth.opendso.localhost
0.0.1 dataviewer.opendso.localhost
0.0.1 docs.opendso.localhost
0.0.1 events.opendso.localhost
0.0.1 historian.opendso.localhost
0.0.1 hmi.opendso.localhost
0.0.1 inspector.opendso.localhost
0.0.1 inventory.opendso.localhost
0.0.1 nats.opendso.localhost
0.0.1 oneline.opendso.localhost

To add entries on Linux/Mac:

# Copy the output from the setup command, then:
sudo nano /etc/hosts
# Paste the entries at the end of the file
# Save and exit (Ctrl+X, Y, Enter)

3. Verify Configuration Files

Check that the client configuration repository is properly cloned:

ls -la ../config/docker/.env

This .env file contains:

Docker image tags for all OpenDSO services and applications
Environment variables for service configuration
Version pins for deployed components

4. Verify OpenFMB Adapter Configurations

Ensure the adapter configurations are present:

ls ../models/

You should see directories for different device types, for example:

recloser/ - Recloser device configurations
airswitch/ - Air switch device configurations
etc

Each directory contains YAML files defining OpenFMB adapter configurations for specific devices. To learn more about OpenFMB Adapters and how to configure them, check out the OpenFMB documentation for more detailed information.

Deployment Command Line Tools

All deployment operations are performed using the OpenDSO run.sh script in the opendso-docker-compose directory.

View Available Profiles

As noted alreayd in the Deployment Overview page, the run.sh script can list all the available application and service profiles available in the deployment project:

./run.sh -l

Deploying the "all" Profile

To start all the base OpenDSO services, execute this in a bash shell:

./run.sh -p all -c

This command willl deploy:

OpenDSO's Core Platform: NATS message bus, historian, event service, topology services
OpenFMB Adapters: OpenFMB Adapters for field devices defined in the Models folder
Genesis Management Suite: Management console and APIs
OpenDSO Core Applications: Volt/VAR optimization, CVR, and other grid applications

Deploying Specific Profiles

Start only specific services for focused testing:

# Start only the NATS server 
./run.sh -p nats

# Start only the OpenDSO UI applications
./run.sh -p ui -c

# Start only backend services
./run.sh -p services -c

Verify Deployment

Check Running Containers

docker ps

You should see containers for the services you deployed.

Access Web Interfaces

Access the following URLs in your web browser (you may need to accept the self-signed certificate):

Service	URL
OpenDSO Documentation	https://docs.opendso.localhost
GMS API	https://api.opendso.localhost
Event Viewer	https://events.opendso.localhost
Historian	https://historian.opendso.localhost
HMI	https://hmi.opendso.localhost
Inspector	https://inspector.opendso.localhost
Inventory	https://inventory.opendso.localhost
One-Line Diagram	https://oneline.opendso.localhost

View Logs

Monitor service logs:

# Follow all logs
docker compose logs -f

# View logs for specific service
docker compose logs -f <service-name>

# View last 100 lines
docker compose logs --tail=100

Check Container Output

The output/ directory contains logs and processed files:

ls -la ../output/

Stop Services

To stop and remove containers:

./run.sh -p all -d

To also remove volumes (WARNING: deletes data):

./run.sh -p all -d

To remove everything including images:

./run.sh -p all -d -f

Data Management

Database Backup and Restore

OpenDSO uses multiple databases to store different types of data:

MongoDB - Stores GMS API configuration data, user settings, and application state
PostgreSQL (Topology Genesis) - Stores parsed CIM topology data and equipment information
SQLite (OpenADR Service) - Stores OpenADR VEN/VTN registration and event data

Backup MongoDB (GMS API Data)

The run.sh script provides a convenient backup command that uses mongodump to create a binary archive of the MongoDB database:

cd ~/opendso/opendso-docker-compose
./run.sh -b

What this does:

Connects to the running MongoDB container
Authenticates using credentials from environment variables
Creates a binary archive dump of the database
Saves the output to db.dump in the current directory

Requirements:

MongoDB container must be running
Credentials must be properly configured in the environment

Manual Backup (Alternative):

If you need more control over the backup process:

# Backup with custom filename
# Note: Use the database name as authenticationDatabase (typically settings_api)
docker exec mongodb sh -c 'mongodump --authenticationDatabase ${MONGODB_COLLECTION} \
  -u ${MONGODB_USERNAME} -p ${MONGODB_PASSWORD} \
  --db ${MONGODB_COLLECTION} --archive' > gms-backup-$(date +%Y%m%d-%H%M%S).dump

# Backup to a directory (not archive)
docker exec mongodb sh -c 'mongodump --authenticationDatabase ${MONGODB_COLLECTION} \
  -u ${MONGODB_USERNAME} -p ${MONGODB_PASSWORD} \
  --db ${MONGODB_COLLECTION} --out /data/backup'

Important: The SettingsAPIUser is created in the settings_api database, not in the admin database. Therefore, use --authenticationDatabase settings_api (or the database name from ${MONGODB_COLLECTION}) instead of --authenticationDatabase admin.

Restore MongoDB Database

To restore from a backup:

cd ~/opendso/opendso-docker-compose
./run.sh -r

Requirements:

db.dump file must exist in the current directory
MongoDB container must be running

Manual Restore (Alternative):

# Restore from custom backup file
# Note: Use the database name as authenticationDatabase (typically settings_api)
docker exec -i mongodb sh -c 'mongorestore --authenticationDatabase ${MONGODB_COLLECTION} \
  -u ${MONGODB_USERNAME} -p ${MONGODB_PASSWORD} \
  --db ${MONGODB_COLLECTION} --archive' < gms-backup-20240101.dump

# Drop existing database before restore
docker exec -i mongodb sh -c 'mongorestore --authenticationDatabase ${MONGODB_COLLECTION} \
  -u ${MONGODB_USERNAME} -p ${MONGODB_PASSWORD} \
  --db ${MONGODB_COLLECTION} --drop --archive' < db.dump

Backup PostgreSQL (Topology Genesis Data)

The Topology Genesis service uses PostgreSQL to store parsed CIM files and topology data:

# Backup PostgreSQL database
docker exec postgres sh -c 'pg_dump -U ${POSTGRES_USER} ${POSTGRES_DB}' > topology-backup-$(date +%Y%m%d-%H%M%S).sql

# Compressed backup
docker exec postgres sh -c 'pg_dump -U ${POSTGRES_USER} ${POSTGRES_DB}' | gzip > topology-backup-$(date +%Y%m%d-%H%M%S).sql.gz

Restore PostgreSQL:

# Restore from SQL dump
docker exec -i postgres sh -c 'psql -U ${POSTGRES_USER} ${POSTGRES_DB}' < topology-backup.sql

# Restore from compressed backup
gunzip < topology-backup.sql.gz | docker exec -i postgres sh -c 'psql -U ${POSTGRES_USER} ${POSTGRES_DB}'

Backup OpenADR Service Data

The OpenADR service uses SQLite for VEN registrations and event data:

# Locate and backup SQLite database
docker exec oadr-service sh -c 'sqlite3 /app/data/oadr.db ".backup /tmp/oadr-backup.db"'
docker cp oadr-service:/tmp/oadr-backup.db ./oadr-backup-$(date +%Y%m%d-%H%M%S).db

# Or simply copy the database file
docker cp oadr-service:/app/data/oadr.db ./oadr-backup-$(date +%Y%m%d-%H%M%S).db

Restore OpenADR Database:

# Stop the service first
docker stop oadr-service

# Copy backup to container
docker cp oadr-backup.db oadr-service:/app/data/oadr.db

# Restart service
docker start oadr-service

Complete System Backup Example

Use this script example to help create a backup of OpenDSO database systems:

#!/bin/bash
# Complete backup script

BACKUP_DIR="./backups/$(date +%Y%m%d-%H%M%S)"
mkdir -p "$BACKUP_DIR"

echo "Starting OpenDSO complete backup..."

# Backup MongoDB (GMS API)
echo "Backing up MongoDB..."
./run.sh -b
mv db.dump "$BACKUP_DIR/mongodb-gms.dump"

# Backup PostgreSQL (Topology Genesis)
echo "Backing up PostgreSQL..."
docker exec postgres sh -c 'pg_dump -U ${POSTGRES_USER} ${POSTGRES_DB}' | gzip > "$BACKUP_DIR/postgres-topology.sql.gz"

# Backup OpenADR Service (if running)
if docker ps | grep -q oadr-service; then
  echo "Backing up OpenADR Service..."
  docker cp oadr-service:/app/data/oadr.db "$BACKUP_DIR/oadr-service.db"
fi

# Backup configuration files
echo "Backing up configuration..."
cp -r ../config "$BACKUP_DIR/config-backup"

echo "Backup complete: $BACKUP_DIR"
ls -lh "$BACKUP_DIR"

Common Local Development Tasks

Testing Configuration Changes

To test changes to the .env file:

# Edit configuration
nano ../config/docker/.env

# Restart affected services
./run.sh -p all -d
./run.sh -p all -c

Testing Adapter Configurations

To test changes to OpenFMB adapter configs:

# Edit adapter configuration (example path)
nano ../models/\{client-or-feeder-name\}/recloser/\{device-id\}.yaml

# Restart services to apply changes
./run.sh -p all -d
./run.sh -p all -c

Troubleshooting

For local deployment issues, see the Local Deployment Troubleshooting Guide.

Common issues covered include:

Prerequisites installation problems
Certificate generation and trust issues
Host file configuration
Port conflicts
Service access problems
Complete deployment reset procedures

For Docker and container-specific issues, see the Docker Troubleshooting Guide.

Performance Considerations for Local Deployment

Docker Resource Allocation

For optimal performance on your local machine:

Allocate sufficient resources to Docker:
- Minimum: 8GB RAM, 4 CPU cores
- Recommended: 16GB RAM, 8 CPU cores
Configure Docker Desktop (Mac/Windows):
- Open Docker Desktop → Settings → Resources
- Adjust Memory and CPU limits
- Click "Apply & Restart"

Selective Service Deployment

Often you'll want to reduce resource usage during development, or for field node deployments. For example, you may only want to run the few services required test out some UI Design changes. For that, you could potentially run:

# Deploy only services needed for your current development work
./run.sh -p nats -p api -p ui -c

And to add services as needed in your development or testing of field node deployments.

# Add services as needed
./run.sh -p events -c

Next Steps

Production Deployment: See Production Deployment Guide for deploying to cloud infrastructure
Adding Services: See Adding Custom Services to extend the deployment
Architecture: Review OpenDSO Architecture for an overview of how OpenDSO Software is interconnected works.

Support

For issues or questions:

Contact the OpenDSO software team
Consult with your OES Support team.

Overview​

Repository Overview​

Prerequisites​

Install Prerequisites on Linux (Ubuntu/Debian)​

Initial Setup​

1. Clone Required Repositories​

2. Generate TLS Certificates​

3. Verify Configuration Files​

4. Verify OpenFMB Adapter Configurations​

Deployment Command Line Tools​

View Available Profiles​

Deploying the "all" Profile​

Deploying Specific Profiles​

Verify Deployment​

Check Running Containers​

Access Web Interfaces​

View Logs​

Check Container Output​

Stop Services​

Data Management​

Database Backup and Restore​

Backup MongoDB (GMS API Data)​

Restore MongoDB Database​

Backup PostgreSQL (Topology Genesis Data)​

Backup OpenADR Service Data​

Complete System Backup Example​

Common Local Development Tasks​

Testing Configuration Changes​

Testing Adapter Configurations​

Troubleshooting​

Performance Considerations for Local Deployment​

Docker Resource Allocation​

Selective Service Deployment​

Next Steps​

Support​