{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Docker Shortcuts"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## About Docker\n",
    "\n",
    "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.\n",
    "\n",
    "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.\n",
    "\n",
    "More detailed information about Docker and Docker Containers is available on [Docker Docs](https://docs.docker.com/get-started/overview/)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "---"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Managing Running Containers"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### View Running Containers\n",
    "\n",
    "To view all containers that are currently running, use the `docker ps` command.\n",
    "\n",
    "A list of all containers with the container ID, image name, and ports currently used will be printed to the terminal window. "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "![docker-ps](images/1.6/docker_ps.png)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "---"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Enter a Running Container\n",
    "\n",
    "To enter a container, use the `docker exec` command with the container name. For example, to enter the GridAPPS-D container, run\n",
    "\n",
    "`docker exec -it gridappsd /bin/bash`\n",
    "\n",
    "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:\n",
    "\n",
    "`docker exec -it 123con45name /bin/bash`\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "![docker-exec](images/1.6/docker_exec.png)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "---"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### View Contents of a Container\n",
    "\n",
    "After entering a container with `docker exec -it containername /bin/bash`, use the `ls -l` command to view the contents of a container."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Directories inside the GridAPPS-D container that you may wish to access:\n",
    "\n",
    "* `applications`: This directory contains custom applications loaded into the platform\n",
    "\n",
    "* `log`: This directory contains a copy of the log, which can be viewed by running `cat gridappsd.log`\n",
    "\n",
    "* `services`: This directory contains available services and service config files\n",
    "\n",
    "It is also possible to access any other folder in container, such as /tmp by running `cd /tmp` from inside the container"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "![docker-ls](images/1.6/docker_exec_ls.png)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "---"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Exit a Running Container\n",
    "\n",
    "To exit a running container, simply type `exit` from inside the container"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "![docker-exit](images/1.6/docker_exit.png)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "---"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Kill a Running Container\n",
    "\n",
    "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."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "![docker-kill](images/1.6/docker_kill.png)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "---"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Managing Container Images\n",
    "\n",
    "This section lists common docker commands for managing containers and images stored on your hard disk"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Prune Unused Images\n",
    "\n",
    "To free up hard disk space, delete unused containers and images by running `docker system prune -a`"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": []
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "---"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Delete All Containers\n",
    "\n",
    "__Use this command with caution! This command will delete *everything*!__\n",
    "\n",
    "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.\n",
    "\n",
    "* Stop all containers: `docker-compose down`\n",
    "\n",
    "* Delete all containers: `docker rm -f $(docker ps -a -q)`\n",
    "\n",
    "* Delete all volumes: `docker volume rm $(docker volume ls -q)`"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "![docker-delete](images/1.6/docker_delete.png)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "---"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Update Containers Manually\n",
    "\n",
    "Generally, the GridAPPS-D platform automatically checks for new container images when running the `/run.sh` command.\n",
    "\n",
    "It is also possible to force docker to check for new images and download new containers by running `docker-compose pull`\n",
    "\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": []
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "---"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Transferring Container Data\n",
    "\n",
    "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"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Transferring Configuration File API Output\n",
    "\n",
    "The Configuration File API contains two calls for converting the CIM XML power system and [exporting all GridLAB-D files](../api_usage/3.4-Using-the-Configuration-File-API.ipynb#Export-all-GridLab-D-Files) and [exporting all OpenDSS files](../api_usage/3.4-Using-the-Configuration-File-API.ipynb#Export-all-OpenDSS-Files). \n",
    "\n",
    "These API calls write the requested files to the directory in the `gridappsd:` container specified by the `\"directory\": ` key.\n",
    "\n",
    "To transfer the requested files from inside the container to the machine hard disk, use the `docker cp source_path dest_path` command:\n",
    "\n",
    "* Default GLM path: `docker cp gridappsd:/tmp/gridlabdsimulation /home/your_username/your_dest_path`\n",
    "\n",
    "* Default DSS path: `docker cp gridappsd:/tmp/dsssimulation /home/your_username/your_dest_path`\n",
    "\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "---"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Transferring Simulation GLM Files\n",
    "\n",
    "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. \n",
    "\n",
    "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. \n",
    "\n",
    "First, start a simulation of the desired power system model [using the GridAPPS-D Viz](../installation/1.5-Using-GridAPPS-D-Viz.ipynb#Creating-a-Simulation) or [using the Simulation API](../api_usage/3.5-Creating-Running-Simulation-API.ipynb#Starting-the-Simulation). \n",
    "\n",
    "Copy the simulation id from Viz by left-clicking on the simulation ID or from your application's API call:"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "![copy-sim-id](images/1.6/copy_sim_id.png)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The simulation files can be copied out of the Docker container by running\n",
    "\n",
    "`docker cp gridappsd:/tmp/gridappsd_tmp/sim_id /home/your_username/your_dest_path`\n",
    "\n",
    "__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 \n",
    "\n",
    "`docker cp gridappsd:/tmp/gridappsd_tmp/78890427 /home/ubuntu/my_glm_files`"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "---"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Configuring GridAPPS-D Containers\n",
    "\n",
    "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"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Adding Applications \n",
    "\n",
    ".\n",
    ".\n",
    ".\n",
    "."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "---"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Adding New Services\n",
    "\n",
    "To add a new underlying service, add the local path for the new service to the `volumes:` section of the gridappsd container:\n",
    "\n",
    "```\n",
    "volumes:\n",
    "    - ~/my_path/my_service:/gridappsd/services/my-service\n",
    "    - ~/my_path/my_service/my-service.config:/gridappsd/services/my-service.config\n",
    "```\n",
    "\n",
    "The example below shows how a repository containing two new services is added manually to the gridappsd-container"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "![volumes-add-service](images/1.6/volumes_add_service.png)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "---"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Changing Tags of a Container\n",
    "\n",
    "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:\n",
    "\n",
    "* `image: gridappsd/container_name:releases_release_name`\n",
    "\n",
    "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.\n",
    "\n",
    "The example below shows how the main gridappsd container and viz can be pinned to particular releases. "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "![image-pinned](images/1.6/image_pinned.png)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "---"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Building a Local GridAPPS-D Container\n",
    "\n",
    "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:\n",
    "\n",
    "* `git clone https://github.com/GRIDAPPSD/GOSS-GridAPPS-D.git -b branch_to_test`\n",
    "\n",
    "\n",
    "Change directories into GOSS-GridAPPSD folder and run the container build script. It make take a few minutes for the container to build.\n",
    "\n",
    "* `cd GOSS-GridAPPS-D`\n",
    "\n",
    "* `./build-gridappsd-container`\n",
    "\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "![build-container](images/1.6/build_local_container.png)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "\n",
    "Then edit the `docker-compose.yml` file and change the gridappsd image to `local`:\n",
    "\n",
    "* `image: gridappsd:local`"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "![image-local](images/1.6/image_local.png)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "After saving the `docker-compose.yml` file, restart the gridappsd platform by running `./stop.sh` and the `./run.sh`"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "---"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "![gridappsd-logo](../images/GridAPPS-D_narrow.png)"
   ]
  }
 ],
 "metadata": {
  "celltoolbar": "Tags",
  "kernelspec": {
   "display_name": "Python 3 (ipykernel)",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.8.5"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}