Docker Shortcuts

About Docker

Docker is an open platform for developing, shipping and running applications. GridAPPS-D uses Docker to package applications, services, and the individual components of the GridAPPS-D Platform.

Each application and underlying platform component run in a loosely isolated environment known as a Docker Container. Each container is assigned a unique identifier string and a human-readable name which are used to interact with that container during runtime.

More detailed information about Docker and Docker Containers is available on Docker Docs

Managing Running Containers

View Running Containers

To view all containers that are currently running, use the docker ps command.

A list of all containers with the container ID, image name, and ports currently used will be printed to the terminal window.

docker-ps

Enter a Running Container

To enter a container, use the docker exec command with the container name. For example, to enter the GridAPPS-D container, run

docker exec -it gridappsd /bin/bash

Note that earlier releases of the GridAPPS-D platform did not use consistent names, so if you are running a 2021 or earlier release, it is necessary to use the container ID obtained from the docker ps command:

docker exec -it 123con45name /bin/bash

docker-exec

View Contents of a Container

After entering a container with docker exec -it containername /bin/bash, use the ls -l command to view the contents of a container.

Directories inside the GridAPPS-D container that you may wish to access:

applications: This directory contains custom applications loaded into the platform
log: This directory contains a copy of the log, which can be viewed by running cat gridappsd.log
services: This directory contains available services and service config files

It is also possible to access any other folder in container, such as /tmp by running cd /tmp from inside the container

docker-ls

Exit a Running Container

To exit a running container, simply type exit from inside the container

docker-exit

Kill a Running Container

To stop a running container, use docker kill container_name. This command should only be used if a container has crashed or become unresponsive. The GridAPPS-D platform should be stopped with the ./stop.sh script.

docker-kill

3. Managing Container Images

Managing Container Images

This section lists common docker commands for managing containers and images stored on your hard disk

Prune Unused Images

To free up hard disk space, delete unused containers and images by running docker system prune -a

Delete All Containers

Use this command with caution! This command will delete *everything*!

If the docker containers have been corrupted, it may be necessary to delete all containers and images. This will delete all local copies of the GridAPPS-D Platform, all simulation data, and all custom models uploaded to Blazegraph.

Stop all containers: docker-compose down
Delete all containers: docker rm -f $(docker ps -a -q)
Delete all volumes: docker volume rm $(docker volume ls -q)

docker-delete

Update Containers Manually

Generally, the GridAPPS-D platform automatically checks for new container images when running the /run.sh command.

It is also possible to force docker to check for new images and download new containers by running docker-compose pull

Transferring Container Data

Files in docker containers are isolated from the rest of the file directories. To edit or run them with another program, such as OpenDSSCMD or GridLAB-D, it is necessary to copy those files using the docker cp command

Transferring Configuration File API Output

The Configuration File API contains two calls for converting the CIM XML power system and exporting all GridLAB-D files and exporting all OpenDSS files.

These API calls write the requested files to the directory in the gridappsd: container specified by the "directory": key.

To transfer the requested files from inside the container to the machine hard disk, use the docker cp source_path dest_path command:

Default GLM path: docker cp gridappsd:/tmp/gridlabdsimulation /home/your_username/your_dest_path
Default DSS path: docker cp gridappsd:/tmp/dsssimulation /home/your_username/your_dest_path

Transferring Simulation GLM Files

During simulation startup, the GridAPPS-D Platform stores the GridLab-D simulation startup files and model in a temporary folder named after the simulation ID.

When debugging why the simulation solution of a new power system model does not converge, it is extemely useful to copy the GLM solution files to debug the model outside of the docker container.

First, start a simulation of the desired power system model using the GridAPPS-D Viz or using the Simulation API.

Copy the simulation id from Viz by left-clicking on the simulation ID or from your application’s API call:

copy-sim-id

The simulation files can be copied out of the Docker container by running

docker cp gridappsd:/tmp/gridappsd_tmp/sim_id /home/your_username/your_dest_path

Example: For the simulation above with simulation ID 78890427, the command to copy the files to a new folder named “my_glm_files” would be

docker cp gridappsd:/tmp/gridappsd_tmp/78890427 /home/ubuntu/my_glm_files

Configuring GridAPPS-D Containers

The GridAPPS-D Platform can be configured and customized by editing the docker-compose.yml file in the gridappsd-docker directory using your preferred text editor

Adding Applications

… .

Adding New Services

To add a new underlying service, add the local path for the new service to the volumes: section of the gridappsd container:

volumes:
    - ~/my_path/my_service:/gridappsd/services/my-service
    - ~/my_path/my_service/my-service.config:/gridappsd/services/my-service.config

The example below shows how a repository containing two new services is added manually to the gridappsd-container

volumes-add-service

Changing Tags of a Container

The GridAPPS-D platform can be pinned to use a particular container by specifying the particular release in the image: section of the particular container:

image: gridappsd/container_name:releases_release_name

It is not recommended to pin to a specific container except for debugging or if the application uses a deprecated feature from an old GridAPPS-D Platform release.

The example below shows how the main gridappsd container and viz can be pinned to particular releases.

image-pinned

Building a Local GridAPPS-D Container

To build and test a local version of the GridAPPS-D container (such as for a feature pull request), first clone the desired branch of the GOSS-GridAPPS-D repository:

git clone https://github.com/GRIDAPPSD/GOSS-GridAPPS-D.git -b branch_to_test

Change directories into GOSS-GridAPPSD folder and run the container build script. It make take a few minutes for the container to build.

cd GOSS-GridAPPS-D
./build-gridappsd-container

build-container

Then edit the docker-compose.yml file and change the gridappsd image to local:

image: gridappsd:local

image-local

After saving the docker-compose.yml file, restart the gridappsd platform by running ./stop.sh and the ./run.sh

gridappsd-logo