Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Update readme.md file. #71

Open
wants to merge 1 commit into
base: develop
Choose a base branch
from
Open

Update readme.md file. #71

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
113 changes: 66 additions & 47 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,62 +1,75 @@
# Official VOLTTRON docker image

# Introduction
## Introduction

This image provides a reproducible way to install VOLTTRON within a docker container.
By using a volume mount of the `VOLTTRON_HOME` directory, runtime changes made by the platform are visible on the host and are preserved across instances of the container.
Similarly, changes made from the host are reflected in the container.
The image uses the utility [gosu](https://github.com/tianon/gosu), which allows the non-root user executing the volttron platform inside the container to have the same UID as the host user running the container on the host system.
In conjunction with volume mounting of the directory, this ensures that file ownership and permissions in `VOLTTRON_HOME` match the host user, avoiding cases where root in the container leaves files inaccessible to a user without sudo permissions on the host.

# Prerequisites
## Cloning the repository

This docker image uses submodules to load the correct version of the main VOLTTRON repository into the image during building. Please
use the following command to build the VOLTTRON docker image locally.

```bash
git clone https://github.com/VOLTTRON/volttron-docker
cd volttron-docker

# initialize submodules
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If the default behavior should be to pull volttron image from docker hub, do we need "git submodule" or "docker build" commands?
If so, that should be updated in README, docker-compose.yml should be updated to point to right docker hub image and latest version. And note should be provided for user that docker-compose.yml can be updated to point to different tag if they want to pull a diffferent version.
Provide link to docker image in docker hub
Building locally should probably under development heading.
Also we should mention that docker-compose.yml need to be updated to correct port mapping - if 8443 is already mapped to something else. Or at least mention it in Troubleshooting

git submodule update --init --recursive
```

## Prerequisites

* Docker ^20.10.8
* Docker-compose ^1.29.2

If you need to install docker and/or docker-compose AND you are running this image on an Ubuntu machine, you can use the script in this repo. From the root level, execute the following command:

```bash
$ ./docker_install_ubuntu.sh
$> ./docker_install_ubuntu.sh
```

# Quickstart:
## Quickstart

To create the container and start using the platform on the container, run the following commands from the command line. Ensure that you are in the root level of the directory.

```
```bash

# Build the image locally. Set <tag> to some tag. Then update the
docker-compose script with the updated image name that uses the tag as part of
its name.

# Example below
$ docker build -t eclipsevolttron/volttron:<some tag> --build-arg install_rmq=false --no-cache .
$> docker build -t eclipsevolttron/volttron:<some tag> --build-arg install_rmq=false --no-cache .

# Create and start the container that has runs Volttron
$ docker-compose up
$> docker-compose up
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Could we add a note saying this should not be repeated once the container is created successfully. As currently setup-platform.py doesn't handle already existing config and hence fails with error. i.e. docker stop and start only after 'docker up' creates the container


# SSH into the container as the user 'volttron'
$ docker exec -itu volttron volttron1 bash
$> docker exec -itu volttron volttron1 bash
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Add instructions as for running volttron commands (say vctl status) from within the container's bash shell


# Stop the container
$ docker-compose stop
$> docker-compose stop

# Start the container
$ docker-compose start
$> docker-compose start

# To get a list of all containers created from docker-compose
$ docker-compose ps
$> docker-compose ps

# To stop and remove the container
$ docker-compose down
$> docker-compose down
```

For Volttron instances using ZMQ message bus:

* Set the master username and password on the Volttron Central Admin page at `https://0.0.0.0:8443/index.html`
* To log in to Volttron Central, open a browser and login to the Volttron web interface: `https://0.0.0.0:8443/vc/index.html`
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Do we have a default browser in the container? Or do you mean using port forwarding from host machine? if so shouldn't url be https://localhost:8443/index.html, where 8443 needs to be updated to whatever is the local mapped port?



# Platform Initialization
## Platform Initialization

An initialization routine is available within the docker container
to allow installation of agents before launching Volttron.
Expand All @@ -66,7 +79,8 @@ of this repository.

The `platform_config.yml` file has two sections: `config`, which configures the main instance and populate's the main config file ($VOLTTRON_HOME/config), and `agents`, which contains a list of agents with references to configurations for them (note the frequent use of environment variables in this section).

## Main Configuration
### Main Configuration

The Volttron configuration is defined under the section "config" in `platform_config.yml`. Note: This image requires that the Volttron Platform enable web. Thus, the platform configuration must set 'bind-web-address'.

For example, the `vip-address` and `bind-web-address` would be set to specific values as seen in the following:
Expand All @@ -85,7 +99,8 @@ config:
...
```

## Agent Configuration
### Agent Configuration

The agent configuration section is under a top-level section named "agents". All agents that need to be defined and configured
within the Volttron platform must be listed in this section.

Expand Down Expand Up @@ -134,9 +149,10 @@ agents:
```

## Other Notes

Agents within the `platform_config.yml` file are created sequentially, it can take several seconds for each to spin up and be visible via `vctl` commands.

# Development
## Development

If you plan on extending or developing `platform_config.yml`, `configs/`, or the setup scripts in `core/`, build the
Docker image, "Dockerfile-dev", only once using `docker-compose -f docker-compose-dev.yml build --no-cache volttron1`.
Expand All @@ -149,42 +165,45 @@ the image build. Once you are satisfied your changes, update 'Dockerfile' with t

To set up your environment for development, do the following:

0. Give execute permissions for ./core/*
```
chmod a+x core/*
```
1. Give execute permissions for ./core/*

```bash
chmod a+x core/*
```

1. Pull in volttron from the [official volttron repo](https://github.com/VOLTTRON/volttron) using the following git command:

```bash
# Clones https://github.com/VOLTTRON/volttron.git into the 'volttron' directory
git submodule update --init --recursive
```
```bash
# Clones https://github.com/VOLTTRON/volttron.git into the 'volttron' directory
git submodule update --init --recursive
```

Why are we doing this? This repo has a directory called 'volttron', which contains the volttron codebase. In other words, this repo contains another repo in a subfolder.
When you initially clone this repo, the 'volttron' directory is empty. This directory contains the volttron codebase used to create the volttron platform.
Why are we doing this? This repo has a directory called 'volttron', which contains the volttron codebase. In other words, this repo contains another repo in a subfolder.
When you initially clone this repo, the 'volttron' directory is empty. This directory contains the volttron codebase used to create the volttron platform.

OPTIONAL: This repo uses a specific version of volttron based on the commit in the 'volttron' submodule. If you want to use the latest volttron from the `develop`
branch from the volttron repo, execute the following command (NOTE: this is not required):
OPTIONAL: This repo uses a specific version of volttron based on the commit in the 'volttron' submodule. If you want to use the latest volttron from the `develop`
branch from the volttron repo, execute the following command (NOTE: this is not required):

```bash
# Ensure that you are in the `volttron` folder
git pull origin develop
```
```bash
# Ensure that you are in the `volttron` folder
git pull origin develop
```

2. Build the image locally:
1. Build the image locally:

* Using docker-compose (preferred)
```bash
docker-compose -f docker-compose-dev.yml build --no-cache --force-rm
```
* Using docker-compose (preferred)

3. Run the container:
```bash
docker-compose -f docker-compose-dev.yml build --no-cache --force-rm
```

* Using docker-compose (preferred)
```
docker-compose -f docker-compose-dev.yml up
```
1. Run the container:

* Using docker-compose (preferred)

```bash
docker-compose -f docker-compose-dev.yml up
```

## Testing

Expand All @@ -203,22 +222,22 @@ $ ./run-test-docker-image.sh -s

If you are not part of the Volttron Core development team, you can skip this section.

See: https://confluence.pnnl.gov/confluence/display/VNATION/Docker+Image+Publishing+Procedures
See: <https://confluence.pnnl.gov/confluence/display/VNATION/Docker+Image+Publishing+Procedures>

# Advanced Usage
## Advanced Usage

In order for volttron to keep its state between runs, the state must be stored on the host. We have attempted to make this as painless as possible, by using gosu to map the hosts UID onto the containers volttron user. The following will create a directory to be written to during VOLTTRON execution.

1. Create a directory (eg `mkdir -p ~/vhome`). This is where the VOLTTRON_HOME inside the container will be created on the host.
1. Start the docker container with a volume mount point and pass a LOCAL_USER_ID environmental variable.

``` bash
docker run -e LOCAL_USER_ID=$UID -v /home/user/vhome:/home/volttron/.volttron -it volttron/volttron
```

In order to allow an external instance connect to the running volttron container one must add the -p <hostport>:<containerport> (e.g. 22916:22916)


# Troubleshooting
## Troubleshooting

*My VC Platform agent can't connect to the Volttron Central address. I see `volttron.platform.vip.agent.subsystems.auth ERROR: Couldn't connect to https://localhost:8443 or incorrect response returned response was None` in the logs*

Expand Down