(Docker) Compose Plugin For OMV7

• Docker is a technology that enables the creation and use of Linux containers. A container is a closed environment where one or more applications and their dependencies are installed, grouped and isolated from each other, running on the same operating system kernel.
• Docker allows you to install, uninstall, modify, update applications as many times as you want without causing damage to the system.
• The openmediavault-compose plugin provides a tool in the openmediavault GUI to create and manage containers using docker compose.
• Through compose files you can manage containers from images.
• Through Dockerfiles you can create your own images. Containers will be created from these images.
• All generated files (compose files, Dockerfiles, …) are stored in a user-defined folder.
• The plugin will only manage containers created from the OMV interface. Any containers created in CLI will not exist for the plugin. Only some generic functions will be usable in this case.

Docker in OMV 7 is a document that establishes a method to successfully install any application on OMV using Docker.

It is recommended to read it before installing Docker or openmediavault-compose. Go to → Docker in OMV 7

• OMV-Extras must be pre-installed.
• A 64-bit system is desirable to run docker. If your system only supports 32-bit you will be able to run some containers, many others will be inaccessible to you. In addition, there are many other incompatibilities for 32-bit systems.

In OMV7's GUI:
Under SYSTEM > OMV-EXTRAS Click on the DOCKER REPO button and click on the SAVE button. Now the docker repository is activated and you can install the compose plugin and docker.
Under SYSTEM > PLUGINS find and highlight openmediavault-compose 7.X, and click the INSTALL button.

• Installing the openmediavault-compose plugin will also install the openmediavault-sharerootfs plugin as a dependency.

This is the plugin's general settings tab. We can define the necessary parameters for the operation of the plugin, as well as install, uninstall or restart docker.

• If you are configuring the plugin for the first time you can configure all the parameters and then press the Save button and accept the changes. If you are simply modifying a parameter do so and press the Save button below.
• Since the openmediavault-sharerootfs plugin is a dependency of the openmediavault-compose plugin, you can create the different shared folders in the root of the OMV system disk if necessary.

• The container configuration files are stored in this folder. The plugin will create subfolders for each container where it will store yaml files and env files respectively.
• If you set volumes with relative paths (through the expression ./ for example ./config) in your compose files those folders will be created inside the subfolder corresponding to that compose file.
• To define this folder do the following:
  • In the Shared Folder field select a shared folder.
    • You can choose a shared folder if you have already created it or create it directly by pressing the “+” button on the right.
  • By default these folders and files will be created with permissions restricted to root only. If you need to customize these permissions you can do so through the rest of the available fields. These permissions will not affect subfolders belonging to volumes with relative paths.
  • Click the Save button if you have already finished configuring the parameters in this tab.

• In this field we can define a folder already created where we have the user data.
• The plugin will use this path if we use the CHANGE_TO_COMPOSE_DATA_PATH string in any compose file. This behavior is similar to that of a global environment variable.
• If you are not going to use the CHANGE_TO_COMPOSE_DATA_PATH variable you can leave this field unconfigured.
• To define this folder do the following:
  • In the Shared Folder field select a shared folder.
    • You can choose a shared folder if you have already created it or create it directly by pressing the “+” button on the right.
  • Click the Save button if you have already finished configuring the parameters in this tab.

• The plugin has a schedulable Backup feature. By default, all subfolders that exist in the folder defined in the Compose Files section are included, this includes compose files (file and env) and container volumes defined by relative paths. Also included are all volumes in each composition file that are not set to :ro (read only) in the composition file. By default, any volume larger than 1GB is excluded.

• The Shared Folder field in this section will define the destination folder of the backup.
• The Max Size field in this section will define the maximum size allowed for a volume to be included in the backups. By default it is 1GB.
  • You can customize any volume within a compose file to be included or excluded in the backup:
    • Typing # BACKUP at the end of the line that defines a volume will include that volume in the backup.
      • Volumes of type :ro will never be included regardless.
    • Typing # SKIP_BACKUP at the end of the line that defines a volume will exclude that volume in the backup.
• Click the Save button if you have already finished configuring the parameters in this tab.

• In this section you can define the docker installation folder. This is useful for getting docker off the OMV system disk. The default path is /var/lib/docker.
• If you are using nvidia drivers in your docker containers (e.g. for Plex or Jellyfin hardware transcoding) you have to leave the path blank. If not, the nvidia driver settings are getting corrupted each time you reconfigure the OMV settings. You can see more details in the chris_kmn's guide.

• In the Docker Storage field define the path of the folder you want to use to install Docker and accept the changes.
  • Avoid using symlinks in this field.
• Click Reinstall Docker button. If you are on OMV6 and the configuration throws an error, simply press the Reinstall Docker button, if there is no error you are done.

Files is the yaml and env file management window, for configuring containers with docker-compose.

In this tab you can perform any action necessary to manage these files, including creating, modifying, deleting, starting or stopping containers, updating images, etc.

The files generated here will be stored in subfolders within the folder configured in Compose Files in the previous point.

The tab displays a list of existing files and a top bar with buttons to perform various actions.

Selecting a file activates the buttons on the top bar.

Allows you to act on the container or containers defined in a yaml file simultaneously. Actions executed in this tab will be applied to all containers defined in the yaml file.

Allows you to create the yaml and env configuration files of a container. Pressing the button will open a dialog box with the following fields:

• Name
  • Name with which this file will be designated in the system.
• Description
  • Description of the file to help identify it.
• File
  • Here you can create (or copy and paste) the configuration yaml file for the container(s).
• Environment
  • Here you can create (or copy and paste) the environment variable env file of the container(s).
• Save
  • It will store the created yaml and env files in a subfolder of the compose folder, this subfolder will be given the name written in the name field.
  • You will exit the dialog box.
  • The created file will now appear on a line with the name on the left and the description on the right. Selecting this line will activate all the buttons to apply actions to this file.
• Cancel
  • Exit without saving changes.

Allows you to create example containers from preconfigured yaml files in the plugin. In this list you will find numerous examples of yaml files ready to be adapted to your system configuration and implemented next.

• Example
  • You can select a yaml file from the list.
• Name
  • Name with which this file will be designated in the system.
• Description
  • Description of the file to help identify it.
• Save
  • Will set up the sample yaml and env files so that they can be edited and adapted to the server environment.
• Cancel
  • Exit without saving changes.

It allows you to download a file from a URL and create a configuration file from it.

• URL
  • Enter the URL from which to download the file.
• Name
  • Name with which this file will be designated in the system.
• Description
  • Description of the file to help identify it.
• Save
  • It will create the file according to the defined parameters.
• Cancel
  • Exit without saving changes.

Allows you to create yaml configuration files from containers running on the system that have not been created with compose. Use only when necessary, the generated file will be much larger than necessary to deploy a container. Useful if you have lost the configuration data of a container created in the CLI.

• Container
  • A list of working containers that can be imported into the compose plugin will appear.
• Name
  • Name with which this container will be designated in the system.
• Description
  • Description of the container functions to help identify it.
• Version
  • The version of the docker yaml composition files that will be used to create the configuration file.
• Create
  • It will generate the yaml and env files and store them in the compose folder inside the corresponding subfolder.
• Cancel
  • Exit without saving changes.

Allows you to import existing compose files into the plugin.

• In the dialog box enter the path to the folder containing the yaml files.
• The import will succeed if you have your yaml files in a subfolder with the yaml file and subfolder having the same name:
  • compose_files
    • compose1
      • compose1.yml
      • compose1.env
    • compose2
      • compose2.yml
      • compose2.env
    • …
• Click on Create button.

Allows you to edit the yaml and env files of the selected file.

The window is the same as the Create button already seen.

Activates when selecting a file.

Allows you to delete a file.

The corresponding subfolder in compose folder along with the yaml and env configuration files will also be removed.

Activates when selecting a file.

Allows you to define global environment variables.

These variables will be available to be used in the compose file that we are interested in doing.

Example of variable in this file:

MYPUID=1000

Usage in a compose file:

- PUID=${MYPUID}

When that container is run docker will run this:

- PUID=1000

It will check the configuration of a file and report possible errors if they are detected.

Util before launching the defined container or containers.

Any error that appears in a red box can be copied to the clipboard from the notifications button in the top bar of OMV to read it in its entirety.

Activates when selecting a file.

Allows you to start the containers belonging to the selected yaml file.

If this is the first start, the container images will be downloaded, then the containers defined in the file will be put into operation.

Activates when selecting a file.

Allows you to stop the containers defined in the selected file. Useful if some monitoring needs to find the container and see the output message.

Activates when selecting a file.

Allows you to stop and remove the containers defined in the selected file.

Activates when selecting a file.

Allows you to download the latest images available on the internet from the containers defined in the selected file.

Previous images are still on the system. To remove old images you can use the prune button.

Activates when selecting a file.

Allows you to see in a pop-up window the status of the containers defined in the selected file.

Activated when selecting a file.

Allows you to clean the system of images, containers, volumes or networks that are no longer needed and recover space.

• System
  • Removes from the system any images, containers, volumes, or networks generated for containers that no longer exist in the openmediavault-compose GUI or are not used. It does the same as all the following buttons simultaneously.
• Image
  • Removes downloaded container images from the system that no longer exist in the openmediavault-compose GUI or are not used.
• Container
  • Removes from the system containers that no longer exist in the openmediavault-compose GUI or are not used.
• Volume
  • Removes from the system volumes that no longer exist in the openmediavault-compose GUI or are not used.
• Network
  • Removes container network interfaces from the system that no longer exist in the openmediavault-compose GUI or are not used.

Link to this document.

This tab shows you the running services generated by docker containers.

Allows you to perform some actions on them.

The Ports column shows links that you can click to access the webui generated by each service.

It will download the latest image corresponding to the selected service.

It will restart the selected service using the last downloaded image.

It will restart the selected service.

It will display the logs of the selected service up to this point and stop.

It will display logs for the selected service and will continue to display new logs if any occur.

Shows a list of running containers displaying the usage status of the resources used.

Selecting a container activates the buttons on the top bar.

Docker inspect provides detailed information about builds controlled by Docker.

Activated when selecting a container.

Allows you to view the log of the selected container.

Activated when selecting a container.

It will display logs for the selected container and will continue to display new logs if any occur.

Activated when selecting a container.

Shows existing images on the system. Allows you to manage these images.

Deletes the selected image if it is not currently in use. If it is in use it will return an error and will not be removed.

Displays the result of inspecting the selected image.

Shows existing networks on the system. Allows you to manage these networks.

Opens a dialog that allows you to create a custom network interface.

• Name: Type the name of the network interface you want to create.
• Driver: Choose from the available types of drivers the one that interests you for the new network interface.
• Rest of fields: Defines the characteristics of the network interface according to the previously chosen driver.

Deletes the selected network interface.

Inspects the selected network interface and lists its properties.

Shows existing volumes on the system. Allows you to manage these volumes.

Deletes the selected volume.

Inspects the selected volume and lists its properties.

Shows a list of running containers displaying the basic execution data.

Selecting a container activates the buttons on the top bar.

It allows acting on the containers individually. Actions executed in this tab will be applied only to the selected container, regardless of whether the yaml file defines one or more containers.

The Ports column will display a link that provides access to the GUI of each container via its port and the domain the server uses, opening a new tab in the web browser. Your router has to allow DNS registration of the other domain names and the client with the browser has to be able to look up that fqdn in dns. How that is done depends on the router/DHCP/DNS system you are using.

Allows you to restart the selected container.

Activated when selecting a container.

Allows you to view the log of the selected container.

Activated when selecting a container.

Shows the continuous output of the container logs.

Activated when selecting a container.

This is the Dockefiles management tab for creating images.

Dockerfiles are managed in this tab to perform any action on them. here the Dockerfiles are created, modified, deleted, etc.

The generated Dockerfiles will be stored in the folder configured in settings, using subfolders generated by the plugin.

The tab shows a list of generated Dockerfiles and a top bar of buttons that allow executing the actions required in each case.

Selecting a Dockerfile activates the action buttons.

In this tab you can create a Dockerfile to generate your own container images.

• Name
  • Name with which this Dockerfile will be designated in the system.
• Description
  • Description of the Dockerfile functions to help identify it.
• Dockerfile
  • Here you can create (or copy and paste) the Dockerfile for image creation.
• Script filename
  • Name of the file with the script.
• Script
  • Optionally here you can create (or copy and paste) a file with a script that will call Dockerfile when run.
• Conf filename
  • Name of the file with the environment parameters.
• Conf file
  • Optionally here you can create (or copy and paste) a configuration file to be included within the image.

Allows you to edit the Dockerfile, script and conf files of the selected Dockerfile.

The operation of this tab is similar to the Create button already seen.

Triggered by selecting a Dockerfile.

Allows you to delete a Dockerfile.

It will also remove the corresponding subfolder along with the Dockerfile configuration, script and conf files.

Triggered by selecting a Dockerfile.

Allows you to deploy Dockerfile with the defined configuration. The first image will be pulled from the internet if it is not available on the host. A modified image will be created from the instructions defined in the Dockerfile.

Triggered by selecting a Dockerfile.

It will do the same as the Build button but the initial image will always be downloaded from the internet in its most updated version even if it exists on the host.

Triggered by selecting a Dockerfile.

This tab manages the utility that allows you to perform plugin backups and/or container image updates. Displays a list of scheduled jobs.

By default, backups will be created of all the subfolders that contain the generated compose files. These subfolders are what the plugin generates every time we create a compose file in the GUI.

In addition, the volumes defined in each container that have a size of less than 1GB will be added to this backup. This size can be customized in the Settings tab.

You can customize any volume within a compose file to be included or excluded in the backup:

• To force a volume to be included in the backup, type # BACKUP at the end of the line that defines that volume. If the volume is less than 1 GB (or the custom value), you don't need to write anything.
  • Volumes of type :ro will never be included regardless.
• To force a volume to be excluded from the backup, type # SKIP_BACKUP at the end of the that defines that volume. If the volume is greater than 1 GB (or the custom value), you do not need to type anything.

The backup performs the following process:

• Stops running containers.
• Make a copy via rsync to the folder defined in the Settings tab for this purpose.
  • The previous backup is overwritten.
  • If you want to have several versioned backups over time, you must make a copy later with another specialized application for this purpose.
• The containers that were running when the process started are started again. Those who were detained will continue to be detained.

The update task performs the following process:

• Download the container images included in the compose file.
• Recreate the containers with the new image if they were running.

Opens a dialog box to schedule container backup and/or update jobs.

• Settings
  • Enabled: Enable automatic execution of the task. If it is unchecked, the task can be executed manually.
  • Filter: Allows you to select the compose files to be included in this backup job.
    • Leaving this field blank will cause all compose files to be included.
    • Filter can be a partial match with use of wildcard (*). e.g. asd* or *asd* or *asd.
    • You can add multiple filters separated by commas.
• Action Type
  • Backup: If enabled, a backup task will be executed.
  • Update: If enabled, an update task will be executed for the selected containers. If the backup task is also checked, the backup will be performed first and then the update. Will recreate containers after update if running.
  • Prune: If enabled, prune all dangling images. It does not use a filter, so all existing dangling images will be removed. Will run the docker image prune -f command.
  • Pre-backup script field: Allows you to set the path of a custom script that will be executed before the execution of the scheduled task.
  • Post-backup script field: Allows you to set the path of a custom script that will be executed after the execution of the scheduled task.
• Schedule
  • Schedule the time of execution using the date and time options.
    • For example, the attached screenshot will backup all containers on Sundays at 8:36 AM. and will send an email with the result of the backup.
  • Select if you want to receive an email with the output of the work, the header will show what you write in the Comment field.

Opens the edit dialog for the selected task.

Deletes the selected task.

Now executes the selected task. You will not receive an email if you run the scheduled job in this way.

There are three widgets on the dashboard that provide docker container information:

• Services Grid
  • Shows if docker is enabled and running by a green button.
• Services Table
  • Shows in a list if docker is enabled and running.
• Container Table
  • Shows a list with the name of each container that is running, the image used by that container, and the time it has been running. Stopped containers do not appear in this table.

• If you have not already done so, define the folder where to store the configuration files. Go to Services > Compose > Settings In the dropdown choose a shared folder and click Save.
• Go to Services > Compose > Files Click on Create.
• Copy and paste your configuration yaml file into the File window.
• Fill in the Name field with a name for the file.
• Optionally type a description of the file in the Description field.
• Optionally copy and paste your environment parameter file into the Environment window.
• Press Save.
• Press the Up button. The image(s) of the container(s) defined in the yaml file will be downloaded and those containers will be put into operation.

• Go to Services > Compose > Services and select the container you want to update.
• Press the Pull button. This will download the latest available image from that container.
• Now go to Services > Compose > Files and select the file where that container is defined.
• Click Up. The containers defined in the yaml file will start with the latest available image downloaded. Your container is already updated.
• Press Prune and then press Image. Old images will be deleted.

• Go to Services > Compose > Files and select the yaml file that defines the containers you want to update.
• Press the Pull button. This will download the latest images available from all containers defined in the yaml file.
• Click Up. The containers defined in the yaml file will be started with the latest available image downloaded from each container. Your containers are already up to date.
• Press Prune and then press Image. Old images will be deleted.

• Go to Services > Compose > Files and select the yaml file that defines the containers you want to remove.
• Click Down to stop the containers defined in that yaml file.
• Press Prune and then press System. All data generated by those containers will be removed from the system.
• If you want to delete the yaml file, click Delete. This will remove the yaml file.

• If you have not already done so, define the folder where to store the configuration files. Go to Services > Compose > Settings In the dropdown choose a shared folder and click Save.
• Create the dockerfile composition file: Go to Services > Compose > Dockerfiles Click on Create.
  • Copy and paste your configuration dockerfile into the dockerfile window.
  • Fill in the Name field with a name for the dockerfile.
  • Optionally type a description of the dockerfile in the Description field.
  • Optionally copy and paste your script file into the Script window so that the dockerfile can execute it. Write the name of this file in the Script filename field.
  • Optionally copy and paste your environment parameter file into the Conf file window so that it is included in the generated image. Write the name of this file in the Conf filename field.
  • Press Save.
• Create the container and run it:
  • Select the dockerfile and press the Up button. The container will be created with the dockerfile commands and that container will be put into operation.

• Go to Services > Compose > Files and press the + and then the Autocompose button
• Expand the Container field. A list of all running containers will appear, select the container you want to generate a yaml file for.
  • In the Name field, type the name you want to use for the generated file.
  • In the Description field you can write a reminder summary of the file content.
  • In the Version field, select the version of docker-compose that will be used to generate the yaml file.
  • Press the Create button. The generated file will appear on a line in the Files tab list.
• Select this file and press the Edit button to view the content of the generated file.
  • There will probably be more information than necessary to define the container, it would be advisable to clean up all the unnecessary lines.
    • If you remember roughly what the original yaml file looked like, you can clean up the extra information.
    • You can search the internet for existing information about this container. If there is an example yaml file you can try to adapt yours to be as similar as possible.
    • Press the Save button.
  • Select the file again and press the check button.
    • The output can show you possible errors. If you detect any, go back to the previous step.
  • Select the file and press the Up button.
    • If the container is deployed without any problems the generated yaml file works. Otherwise you should keep checking for errors until it works.

This is useful if you need a container to have an IP within your LAN that is different from your server's.

The most common use case for this procedure is installing pi-hole in docker on an OMV server. The reason in this case is that both pi-hole and OMV need the same port to function correctly, port 53. Therefore we need pi-hole to use a different IP on our network to be able to use that port without affecting OMV. There may be other use cases besides pi-hole, depending on the needs of the container you're setting up.

Note that containers using this network will expose all their ports on the LAN, just like any other IP, eg OMV. Docker provides an additional layer of security through port mapping (similar to a firewall). Through this procedure we lose that additional security layer. This does not have to be a problem, it is normal operation in any network, but it is convenient to be aware of this circumstance. Logically it will be useless to map ports in those containers, so you can save that part.

We must create the network previously to be able to define the parameters we need and use it later in the containers. We will call it mynet and we will create it as follows:

• In the OMV GUI go to Services > Compose > Networks Press the Add button.
  • Choose the name for your network and write it in the Name field. For example mynet.
  • In the Driver field, drop down the menu and choose macvlan.
  • In the Parent Network field, drop down the menu and choose your OMV network interface. You can check it in the GUI under Network > Interfaces.
  • In the Subnet field write the IP range of your local network. Usually it can be 192.168.1.0/24 Adapt it to your network.
  • In the Gateway field write the gateway of your network, normally your router, something like this 192.168.1.1 Adapt it to your network.
  • In the IP range field write 192.168.1.240/29 Adapt it to your network.
    • This network range is equivalent to the IP addresses between 192.168.1.241 to 192.168.1.246 This will allow us to assign IP addresses up to 6 containers, you can expand it if you need more. Any such website can help with this: IP calculator
    • So that this is not a problem with the IP assignment of your DHCP server (your router in general) you can reduce the assignment range, instead of letting it assign from 1 to 254, we can reduce it from 1 to 235 for example. This is how we make sure we have those free IPs for docker.
  • In the Aux address field you can optionally define an IP address to reserve for the host. In this case it would be host=192.168.1.247
    • This will be useful only if you need the host and the container to communicate with each other.
  • Press the Save button. At this moment the network is already created and you can use it in the configuration of any container.
    • You can inspect the network by selecting it and clicking the Inspect button to view its current values. When some container is using it, it should appear in this configuration.

In order for a container to use the created network interface you need to add the following lines to the end of your compose file, assuming docker-compose is version 3 or higher. See the documentation for older versions of docker-compose.

services:
  pi-hole:
    container_name: "pi-hole"
    .
    .
    networks:
      mynet:
        ipv4_address: 192.168.1.241
networks:
  mynet:
    external: true

This sets up the mynet interface for that container and assigns it the IP value 192.168.1.241 within our network, which was the first available. We will still be able to use up to 246 in other containers.

When we start the container we will be able to access its interface from the assigned IP and the usual port.

Once the above is done, in order to avoid overlapping assignable IP ranges, it would be advisable to reduce the IP range of the network's DHCP server. In the case of the previous configuration it could be set to:

• From 192.168.1.2
• Up to 192.168.1.239

This way addresses from 192.168.1.240 onwards will always be available, since the router will not assign any of these IPs if a device requests an IP assignment.

If you use the container itself as a DHCP server, for example with pi-hole, you must disable the DHCP server on your router and adapt the DHCP range in pi-hole accordingly.

What has been applied so far is enough to use pihole, but in the case of other different containers it may be necessary for the container and the host to communicate with each other. Vlans have a limitation, by design they cannot communicate with the host. To overcome this setback and allow communication between the containers and the host, if necessary, we can create a network interface that will act as a bridge between the two.

Running the following commands would create this interface, but this configuration would not be persistent in OMV. On the first server restart it would disappear:

ip link add mynet-host link eno1 type macvlan mode bridge
ip addr add 192.168.1.239/32 dev mynet-host
ip link set mynet-host up
ip route add 192.168.1.224/28 dev mynet-host

This would create a macvlan network interface called mynet-host in bridge mode that would use the IP 192.168.1.239. The host would use this network interface thanks to the static route set in the 192.168.1.224/28 network range to communicate with the containers.

To make this configuration persistent in OMV we must do it as follows:

• Create a network interface configuration file:

nano /etc/network/interfaces.d/99-mynet-host

• Copy into that file the following content:

auto mynet-host
iface mynet-host inet static
    pre-up ip link add mynet-host link eno1 type macvlan mode bridge
    address 192.168.1.239/32
    up ip link set mynet-host up
    up ip route add 192.168.1.224/28 dev mynet-host

• Replace eno1 with your network interface. You can see it in the GUI under Network > Interfaces.
• Save changes and exit the editor. Ctrl+X and Yes
• Restart the service or the server.

From now on those settings will be set every time the server is started.

→ openmediavault-compose

We, who support the openmediavault project, hope you’ve found this guide to be useful and that you’ll find your openmediavault server to be efficient, easy to use, and enjoyable.

If you found this plugin guide to be helpful, please consider a modest donation to support the hosting costs of this server.

OMV-Extras.org