nrel/docker-urbanopt repository overview

⁠nrel/docker-urbanopt

Docker container for URBANopt CLI on Ubuntu 22.04.

⁠Features

• URBANopt CLI: Pre-installed and configured
• Ubuntu 22.04: Base image with all required dependencies

⁠Usage

⁠Pull from Docker Hub

docker pull nrel/docker-urbanopt:latest

⁠Run the Container

# Run with default command (shows version)
docker run --rm nrel/docker-urbanopt:latest

# Run interactively
docker run -it --rm nrel/docker-urbanopt:latest bash

# Run with a mounted workspace
docker run -it --rm -v $(pwd):/work nrel/docker-urbanopt:latest

⁠Running on the Cloud

⁠Option 1: Docker-Based URBANopt Execution

For a single-server cloud deployment (for example, an AWS EC2 instance), the simplest and most reproducible approach is to run URBANopt inside a Docker container. This avoids installing URBANopt directly on the virtual machine and makes upgrades, rollbacks, and environment consistency as simple as changing the container tag.

In this workflow, URBANopt runs entirely inside a container, while project files and simulation outputs live on the host filesystem.

URBANopt CLI commands and workflows are unchanged. You will still use familiar commands such as uo create, uo run, uo process, and related workflows — the only difference is that these commands are executed inside the container rather than directly on the host operating system.

⁠Step 1: Launch a Cloud Instance

Launch a Linux-based virtual machine on your preferred cloud platform:

• AWS EC2
• Azure Virtual Machines
• Google Compute Engine
• On-premise or HPC cloud nodes

Recommended configuration

• Ubuntu 22.04 LTS
• Adequate CPUs for parallel simulations
• Sufficient disk space for OpenStudio/EnergyPlus outputs

⁠Step 2: Connect via SSH

Once the instance is running, connect using SSH:

ssh user@your-instance-ip

All remaining steps are performed inside this SSH session.

⁠Step 3: Install Docker

Most cloud VMs do not include Docker by default.

On Ubuntu 22.04:

sudo apt-get update
sudo apt-get install -y docker.io
sudo systemctl enable docker
sudo systemctl start docker

Managed container services (AWS ECS, AWS Batch, Kubernetes) already include Docker and do not require this step.

⁠Step 4: Obtain Your URBANopt Project Files

This guide assumes your URBANopt project is stored in a Git repository and cloned onto the instance:

git clone https://github.com/your-org/your-urbanopt-project.git
cd your-urbanopt-project

Other transfer methods (for example, SCP, rsync, or cloud storage downloads) may also be used.

⁠Step 5: Pull the URBANopt Docker Image

URBANopt is provided as a prebuilt Docker image on Docker Hub:

nrel/docker-urbanopt:1.1.0

Pull the image locally:

docker pull nrel/docker-urbanopt:1.1.0

⁠Step 6: Run URBANopt Using Docker

Run URBANopt by mounting the project directory into the container:

docker run --rm -it \
  -v "$(pwd):/work" \
  nrel/docker-urbanopt:1.1.0 \
  uo run -f example_uo/example_project.json \
         -s example_uo/baseline_scenario.csv

⁠Notes

• example_project.json and baseline_scenario.csv are example files provided by URBANopt
• User projects will typically use different filenames
• URBANopt CLI usage and workflows are unchanged from a native installation

⁠Simulation Outputs

Because the project directory is mounted into the container, all outputs are written directly to the host filesystem.

For example:

/work/example_uo/run/

maps to:

your-urbanopt-project/example_uo/run/

No results are stored only inside the container.

⁠Parallel Execution

The number of parallel URBANopt simulations is controlled in runner.conf:

num_parallel = 10

The container uses the CPUs available on the host VM. No special Docker configuration is required on Linux-based cloud instances.

⁠Running Locally on Windows (Docker Desktop)

The same container can be used on Windows with Docker Desktop:

docker run --rm -it ^
  -v "C://path//to//urbanopt-project://work" ^
  nrel/docker-urbanopt:1.1.0 ^
  uo run -f example_uo/example_project.json ^
         -s example_uo/baseline_scenario.csv

Ensure Docker Desktop is configured with enough CPUs to match num_parallel.

⁠License

See the URBANopt CLI license for details.