Usage: Docker

Docker

The preferred way to install BUVIC is to use docker (see why).

Running the docker image can either be done with the installer or with docker-compose

Installer

installer.py is a small script to help deploy the docker UV Server image. It is the preferred way to run BUVIC.

Instructions:

installer.py requires python 3+. To run the script:

python installer.py

or on linux simply:

./installer.py

Then follow the instructions on terminal

Upgrading BUVIC

To upgrade, just run the installer again and choose the version you want.

Docker Compose

It is possible to use Docker Compose to easily configure and start BUVIC's docker image.

Instructions:

Docker Compose needs to be installed first. If you use Windows or Mac, you are lucky because Docker Compose comes preinstalled with docker. If you use another OS, see the install instructions.

Clone BUVIC's repository or download the docker-compose.yml file.

Open a terminal and navigate to the directory where the docker-compose.yml file is (it's in docker/ if you cloned the repository) and make the needed changes (see comments).

Then run

docker-compose up -d

The option -d tells docker-compose to run as a daemon (in the background). If you want the image to run in the terminal, skip this option.

Upgrading BUVIC

To upgrade BUVIC, run the following commands in the same directory as the docker-compose.yml file:

docker-compose down
docker pull pmodwrc/buvic
docker-compose up

Demo command

Note: The recommended way to run BUVIC is with the installer.py script or docker-compose. If you haven't read the previous sections, I suggest that you do so.

The simplest way to start a docker container with buvic is to run:

docker run -d -p <HOST_PORT>:80 --name buvic pmodwrc/buvic

Where <HOST_PORT> is the port on which the web app will listen (e.g. 8080).

The flag -d tells docker to run this container as a daemon (in the background). It may be omitted if you want to run it in your current terminal.

After running this command, you can access the web app in your browser at http://localhost:<HOST_PORT>. This instance of BUVIC however only uses some demo measurement files as input.

Mapping directories

To use BUVIC correctly, you will need to map input and output directories of your host machine to your docker container.

There are three relevant directories that need to be mapped (see Directory structure for more details):

1. /instr
2. /uvdata
3. /out

Each of these directories needs to be mapped to a directory on your host computer. We use docker volumes (the option -v) to map a host directory to a docker directory. When mapping a host directory (e.g. /home/user/buvic_data) to a docker directory (e.g. /path/in/docker/buvic_data), the directory inside the docker container will share the contents of the host directory.

Here is an example of command which maps host directories to /instr, /uvdata and /out:

docker run -d -p <HOST_PORT>:80 -v <INSTR_DIRECTORY>:/instr -v <UVDATA_DIRECTORY>:/uvdata -v <OUTPUT_DIRECTORY>:/out --name buvic pmodwrc/buvic

where <INSTR_DIRECTORY> is the absolute path to the instrument directory on the host (e.g. D:\buvic\instr on Windows or /home/user/buvic/instr on Linux), <UVDATA_DIRECTORY> is the absolute path to the uv data directory on the host and <OUTPUT_DIRECTORY> is the absolute path to the directory you want to save the outputs in.

Permissions

On linux machines, you may want to specify which user/group runs the docker container to avoid permission issues when writing to the output directory. This can be done with the parameter --user <user_id>:<group_id> or simply --user $(id -u):$(id -g) to use the current user and group.

Note that if you use another user than root, you will not get permission to listen to port 80 (the default port for buvic inside the container). A workaround for this is to specify on which port buvic will listen with the environment variable PORT. This is done by adding the following parameter to your docker run command -e PORT=<PORT_NUMBER> where <PORT_NUMBER> is the port number to use (must be greater than 1024 for non root users).

Example:

docker run -d -p <HOST_PORT>:4444 --user 1000:1000 -e PORT=4444 --name buvic pmodwrc/buvic

Notice that for the -p option, we don't use 80 anymore but the port specified with the PORT environment variable (4444 in this example).

Darksky

If you want darksky to be used, you will need to create an account and give your api key as environment variable. Using this functionality is not required and the cloud coverage values can be manually entered in the parameter file instead.

You can pass your darksky api token to BUVIC by adding the parameter -e DARKSKY_TOKEN=your_darksky_token. Example:

docker run -d -p <HOST_PORT>:80 -e DARKSKY_TOKEN=your_darksky_token --name buvic pmodwrc/buvic