This guide is intended to explain how to use the docker-gui plugin coded @nicjo814 the front end developer of the zfs plugin . You can find more information about docker in the below link.
Docker allows to execute single applications with all the required libraries and dependancies all in one closed environment without affecting your host. Did you ever wanted to use an application that was only available at Jessie or Ubuntu? Most of the time this involves going through the complication of updating libs or recompiling binaries converting your server into FrankenDebian. Docker allows to run applications without any concern you're gonna break your system. Just download, setup and collect. You don't want the application anymore? remove the container and delete the image, no downgrading libs or apt-get sorcery commands.
- x86_64 machine (NO 32bit, ARM, RPI or POWERPC support)
- OMV 2.0
- Omv-extras plugin.
- Backport Kernel 3.16 (press the install button in OMV extras and reboot into the new kernel)
How to install
Enable the docker stable repo in the omv-extras first tab section. Go to the plugins sections and select openmediavault-docker-gui plugin.
The initial settings of the plugin consist of four main items.
- Enable: Turn on the docker daemon, this will also start current containers that are configured to do so.
- Port: this is the port where the docker daemon will be listening. The plugin works by using the docker api sending docker commands to the daemon socket to operate images and containers.
- Docker base path: This is the place where all images and containers are stored. You can select an OMV shared folder or leave it empty. An empty folder will use the default docker location (/var/lib/docker)
- Copy images: The third line with two fields is only used to move images and containers from an existing install, in case you were using docker before the plugin. Select the location by clicking on the explorer button to the right in the first field, and then choose the destination. If you don't select source, the default will be used (/var/lib/docker). Press the far right button to start copying. This can take a while depending on the amount of images and containers you have in your server. The original images location will still hold the data, so you need to manually remove if you want to save space.
The plugin presents in is main tab two panels. The first upper panel displays the available/downloaded images of docker. The lower panel displays containers. It also displays it current status (running, stopped, exited, etc) and mapped ports.
How can I get images?
If you know the repo name (usually maintainer/application_name, if they are OS ones from the official is just the name, ex: centos) you press the pull button and enter the repo name completely, you can add tags at the end if you want a specific one, and press start. Then you have to wait for the image to finish downloading
Some of the buttons explained in image section,
- Details: The detail button will display info about the image, exposed ports, variables, ID of the container volume in the filesystem, etc.
- Info: The info button will take you to the docker hub webpage, where you can find details about the particular image, and how to set it up running.
- Run: It will execute a container based on the image
Executing a container
Press the run button in the upper section selecting a single image. From there you'll be presented with dialog to assign parameters to the container.
Currently available parameters to config explained:
- Name: give a name to the container, otherwise docker will assign a random name to it. This helps if you want to fire multiple containers from the same image doing different tasks
- Reboot persistent (self explanatory)
- Privileged mode: Can give access to host resources, this can pass for example block devices to the container. Docker-Reference. This can be very useful for tvheadends containers.
- Networking mode:
- Bridge: packets will flow back and forward to the docker0 interface, you need to map the docker0 port to the main host one
- Host: the container will bind directly to the host interface, you won't need to forward the port
- Environment variables: Docker applications need some info from the host to work, credentials, PATH, terminal, localtime. The basic are usually predefined by the maintainer, in other cases you have to add the variable.
- Volumes and bind mounts: If the container needs to access host resources folders, this is the place where you link folders inside the container to folders in the host. For example torrent applications need an outside folder where to place downloads. At the container side you can place a :ro (example /config:ro) to present the mount as read only for the container. To the left side you have your current host machine (OMV), to the right is the path inside the container.
IMPORTANT NOTE: The plugin performs data validation once another field has being added. So for port forwarding, environment variables and bind mounts you NEED TO PRESS THE + BUTTON after entering data. Otherwise the parameters won't get passed to the run container command.
How do I fill all the information requested prior running the container?
Press the Info button, it will take you to the hub page where maintainers usually give a brief explanation of their container purpose, how to run it and what parameters to enter.
What is the search button for?
It performs a quick web search of images. You can search by name of the maintainer or application program
Currently Running Containers
Containers are fired from the downloaded templates images, most of them are designed to run with some custom parameters. Once entered the parameters and the image is running you cannot change them. If you need to change a port or map bind, you need to stop the container, remove it, and fire again the image with the new parameters.
When you remove a container it looses all data that generated inside, that's why most applications specify outside data folders to store moving data. So if you specify the same map bind in the a new container the application should display the same content. Take the Emby server for example it asks you a path for you media files and another folder for library metadata. After you remove the container, run again with different port but same volume binds, the application should display the same Library.
Containers can be stopped, started or restarted. No inside data will be lost, until the container is being removed. Containers can only be removed after they have been stopped. What a stop or restart do is kill all the inside running processes.
What is the copy button for?
Is to duplicate the execution of a running container with all its parameters. You'll be presented with run image dialog and the original container parameters. This is the point where you should change those parameters. For example you want to run a second instance of a kodi-watchdog for another MySql library, another emby server for a friend in the network, etc. Don't forget to change the port and folder bind, otherwise the application will conflict with the current one. Also change the name so you can identify properly if you want to stop it or restart it.
How can I see the current parameters of a currently running container?
Press the details button in the container section
What is the run cmd button for?
Just as it says, it executes commands inside the container environment
The docker repo is just images that have been selected by the plugin developer to be displayed and pulled down that are considered handy for OMV. Press the pull button and wait.
This is how to run the very popular docker container in OMV, the kodi watchdog. This runs a headless kodi server with watchdog. When a file is added to the kodi library folder it will retrieve all metadata and add the info to the MySQL library. This can help lowering the stress to update the whole library in small powered devices like the rpi running openelec. Below is the link from the maintainer on how to run the docker container.
Those instructions translate more or so into this one for the plugin
Notice the empty line after each parameter settings? Always leave an empty line, that way you ensure all of the settings are gonna get passed to the run command
Questions / Problems / Discussions