Compose Plugin For OMV6

• 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.
  • docker-compose
• Two management methods are provided, via yaml files or via dockerfiles.
• All generated files (yaml, env, dockerfiles, …) are stored in a user-defined folder.

• OMV-Extras must be pre-installed.

In OMV6's GUI:
Under System > Plugins find and highlight openmediavault-compose 6.X, and click the Install button.

• Installing openmediavault-compose will also install docker on the system if it was not already installed.

Under Services > Compose > Settings

Shared folder

Select a shared folder where to store the files generated by the user in the plugin (for didactic purposes in this guide we will call it “compose”).

A common practice for creating docker containers is to use a yaml composition file to define the parameters and docker-compose will generate the container(s) defined in this file.

Many container builders will provide composition yaml files to implement the container. This file must be adapted to the characteristics of your server. Consult the documentation of the creator of the container in each case to know how to do it.

In the same way you can define an env file where environment variables are included.

Files Lists the yaml and env configuration files created, whether the containers are running or stopped.

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.

Under Services > Compose > Files

Create

Allows you to create the yaml and env configuration files of a container. Pressing the button will open a dialog window 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 window. 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.

Add from example

Allows you to create example wrappers from preconfigured yaml files in the plugin.

• 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.

Autocompose

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.

Edit

Triggered by selecting a yaml file. Allows you to edit the yaml and env files of the selected file. The window is the same as the Create button already seen.

Delete

It is activated when selecting a file. Allows you to delete a file. The corresponding subfolder in “compose” along with the yaml and env configuration files will also be removed.

Check

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.

Up

Triggered by selecting a yaml file. Allows you to display the containers belonging to the selected yaml file. If this is the first time, the container images will be downloaded, then the containers defined in the file will be put into operation.

Down

Activates when selecting a file. Allows you to stop the containers defined in the selected file.

Pull

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.

ps

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

Prune

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.

Docs

Link to this guide.

Containers can be created using a dockerfile. This dockerfile defines the image that the container will use and will execute a series of commands that will lead to the generated container running.

Dockerfiles lists the configuration dockerfiles generated to create containers, whether they are running or stopped.

Selecting a dockerfile activates the buttons on the top bar.

The operation is similar to Files, but the containers are created using dockerfiles.

Under Services > Compose > Dockerfiles

Create

Popup window to create a container using a dockerfile.

• 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 container 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.

Edit

Triggered by selecting a dockerfile. Allows you to edit the dockerfile, script, and conf files of the selected container. The window is the same as the Create button already seen.

Delete

Triggered by selecting a dockerfile. Allows you to delete a container. The corresponding subfolder in “compose” along with the dockerfile, script and conf configuration files will also be removed.

Build

Activated by selecting a dockerfile. It allows deploying the container following the dockerfile already configured.

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.

Under Services > Compose > Containers

Pull

Activated by selecting a container. Allows you to download the latest image of the selected container available on the internet. The behavior is the same as in Files but only the image of the selected container is downloaded, not all the containers that have been generated by the yaml file.

Up

Activates when selecting a container. Allows you to display the selected container. The behavior is the same as Files but only the selected container will be started, not all the containers that have been generated by the yaml file.

Restart

Activated when selecting a container. Allows you to restart the selected container.

Logs

Activated when selecting a container. Allows you to view the log of the selected container.

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

Selecting a container activates the buttons on the top bar.

Under Services > Compose > Stats

Inspect

Docker inspect provides detailed information about builds controlled by Docker.

Logs

Activated when selecting a container. Allows you to view the log of the selected container.

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.

How to implement a container using a 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.
• 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.

How to update a single docker-compose container

• Go to Services > Compose > Containers 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.
• Press Down. Containers defined in the yaml file will be stopped.
• 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.

How to update multiple containers defined in a single docker-compose yaml file

• 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 Down to stop the containers defined in that 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.

How to delete containers from a yaml file

• 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.

How to deploy a container using a dockerfile

• 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.

SYSTEM DESIGN

Starting from a system with OMV installed, to use Docker we need a SPACE, a USER and a DATA FILE SYSTEM :

• A SPACE in our file system to store the containers. Making docker independent of the operating system is a good decision in most situations, using a dedicated disk, preferably a fast drive, SSD or similar, formatted in EXT4. Other formats or systems may cause problems or be incompatible with docker (mergerfs, ZFS,..). The capacity of this disk will depend on the number and type of containers that are going to be used, 60GB is a good start. PROGRAM FILES and CONFIGURATION FILES will be stored in this space:
  • PROGRAM FILES
    • They are expendable files.
    • They will be stored in the docker folder of the SSD drive.
    • Docker takes care of downloading these files from the internet and configuring them automatically.
    • Docker containers are updated by downloading the latest version of these files and replacing the old one. There are some exceptions, check the documentation for each container you install to find out how it works.
  • CONFIGURATION FILES
    • They are irreplaceable files.
    • They will be stored in the appdata folder of the SSD drive.
    • They are created, modified and customized during the operation of the application with passwords, personal settings, databases, etc. depending on the use case.
    • We'll also use the compose folder to store docker-compose's composition stacks.
    • We must keep them if we want to keep the application in the same state or restore it after a reinstallation of OMV. It is a good idea to make regular backup copies of these two folders.

• A USER who will be in charge of executing the container.
  • Docker applications execute the actions on the system from the container by means of a user. The permissions that we grant to this user will be the permissions that the container has. This will be the control mechanism to prevent the application from doing something on our system that we don't want it to do.
  • For security, it is convenient to create a user and grant only the necessary permissions for the application to work. In this guide this user is called appuser.
  • The containers should write/read in the docker and appdata folders. The way to give permissions to the container is to give them to the user who runs it. Therefore, we need to give appuser write permissions on these folders. Also, if we want the app to use data from our shared folders, appuser must have access to those folders as well.
  • For simplicity this guide uses a single user for all docker containers, appuser. Normally this will suffice. If you need to further adjust the security you can create a user for each container and further adjust the permissions.

• A DATA FILE SYSTEM where the data to be used by the application that we are installing is stored.
  • For simplicity, in this guide we limit ourselves to a single shared folder called DATA. You will probably have called it something else, name it your real folder instead of DATA.
  • These folders will store the data used by each application. In the case of Jellyfin, for example, we are referring to the movies, photos, etc. Which could be in DATA/media/films DATA/media/photos …
  • The file system used to store this data is irrelevant. We just need OMV to recognize it and be able to create a shared folder in it and grant the necessary permissions to the user appuser.

PREPARING AND INSTALLING DOCKER

• 1. Previous steps.
  • Install a dedicated drive (preferably SSD) in the server, format to EXT4 and mount to the file system. New User Guide
  • Install openmediavault-omvextrasorg.

• 2. Create symlinks /SSD and /DATA
  • Creating symlinks will avoid using long paths and will make it easier to replace disks by avoiding redoing all the containers. The use of symlinks is not mandatory, the objective is ease of use. If you prefer to use complete paths you can skip this point.
  • Install openmediavault-symlinks.
    • In the OMV GUI go to System > Plugins find and select the plugin, then click Install on the top menu.
  • Create symlink /SSD pointing to the dedicated drive.
    • In the OMV GUI go to Storage > File Systems open the Mount Point column (box icon on the top right) and press the button to copy the SSD disk mount point to the clipboard.
    • Go to Services > Symlinks and click on +Create.
      • In the Source field, copy the SSD disk mounting path from the clipboard (or find the path in the tree). It should look something like /srv/dev-disk-by-uuid-385245af-f180-4977-acg5-5847f908e48g/
      • In the Destination field type /SSD
      • Press the lower Save button.
  • Create symlink /DATA pointing to userdata folder.
    • Following the same procedure, now create the symlink /DATA (use your actual folder name). Find the mount path of your data folder in Storage>Shared Folders> open the Absolute Path column and copy your folder path to clipboard by pressing the button.
    • Go to Services>Symlinks> and click on +Create.
      • In the Source field copy from the clipboard the mount path of the data folder (or find the folder in the tree).
      • In the Destination field write /DATA (use the name of your actual folder)
      • Press the lower Save button.

• 3. Create folders for Docker files.
  • Create docker, appdata and compose shared folders on the dedicated disk. SSD or the one you have chosen.
    • Go to the OMV GUI Storage > Shared Folders Click on +Create In the Name field write docker. In the File system field select the SSD disk. Press Save.
    • Repeat the procedure for the appdata and compose folders.

• 4. Install Docker and openmediavault-compose plugin.
  • In the OMV GUI, go to the System > omv-extras > Docker and in the Docker storage field replace the value with the path of the docker folder created earlier, and press the Save button.
    • Warning: A symlink like /SSD/docker may not work here, it is preferable to use the full path. Example: /srv/dev-disk-by-uuid-861acf8c-761a-4b60-9123-3aa98d445f72/docker You can copy the path as in point 2 and add /docker at the end.
    • Warning: Once the route has been entered, press the lower Save button. Otherwise the changes will not be saved and if you continue, docker will be installed in the default path /var/lib/docker, that is, on the system disk, which is what we want to avoid.
  • Install Docker: In the bottom menu, click the Save button. Then click the Install button.
    • Now in the Status field the message should appear: Installed and running
  • Install openmediavault-compose. (In the OMV GUI go to System > Plugins find and select the plugin, then click Install on the top menu.
    • Warning: If you install openmediavault-compose before changing the docker installation path, docker will be installed to the default path /var/lib/docker.
  • In the OMV GUI, go to Services > Compose > Settings and select the compose folder to store the yaml composition file. Press Save.

• 5. Create the user “appuser”.
  • In the OMV GUI go to Users > Users click on the +Create button, define appuser name and assign password, in the groups field we add it to the docker and users groups. Click on Save.
  • Open the UID and GID columns and make a note of the values that the appuser user has. Example UID=1002 GID=100 If you already had one user, appuser UID will be 1001. If you had 2 users, appuser UID will be 1002, etc. This may vary on your system.

EXAMPLE OF INSTALLING AN APPLICATION (JELLYFIN)

• 6. Choose a stack

• On the dockerhub there are thousands of containers ready to configure. Try to choose containers from reputable publishers (linuxserver is very popular) or with many downloads and current ones. Check that the container is compatible with your server's architecture x86-64 arm64… When choosing one read the publisher's recommendations before installing it.
• As an example we are going to install Jellyfin. Many results appear in the search engine, we chose the one for linuxserver linuxserver jellyfin
• We fetch the docker-compose stack and copy it to a text file. In this case:

(Note: Verify on the official page that this stack has not changed before installing it)

  version: "2.1"
  services:
    jellyfin:
      image: lscr.io/linuxserver/jellyfin:latest
      container_name: jellyfin
      environment:
        - PUID=1000
        - PGID=1000
        - TZ=Europe/Madrid
        - JELLYFIN_PublishedServerUrl=192.168.0.5 #optional
      volumes:
        - /path/to/library:/config
        - /path/to/tvseries:/data/tvshows
        - /path/to/movies:/data/movies
      ports:
        - 8096:8096
        - 8920:8920 #optional
        - 7359:7359/udp #optional
        - 1900:1900/udp #optional
      restart: unless-stopped

• 7. Customize the stack.
  • It's always a good idea to read the editor's comments to familiarize yourself with the options and to check that the container is valid for your architecture (x86, arm …).
  • We customize our stack to fit our system. In this example, we remove all the optional lines and keep the essentials.
  • Let's assume as an example that inside /DATA we have the media folder that contains other subfolders with movies, photos, etc.
  • We adjust the stack as follows:

  version: "2.1"
  services:
    jellyfin:
      image: lscr.io/linuxserver/jellyfin:latest
      container_name: jellyfin
      environment:
        - PUID=1002  # See Comment 1
        - PGID=100   # See Comment 1
        - TZ=Europe/Madrid   # See Comment 2
      volumes:
        - /SSD/appdata/Jellyfin:/config   # See Comment 3
        - /DATA/media:/media   # See Comment 3
      ports:
        - 8888:8096   # See Comment 4
      restart: unless-stopped

• Comment 1: See point 5 of this guide and adjust the correct values.
• Comment 2: Adjust it to your location. You can see it by typing cat /etc/timezone in a terminal.
• Comment 3: In the volumes section we map folders from the container to the host. This means that when the container writes to an internal folder, it will actually be writing to the folder we want outside the container. The syntax means that to the left of the “:” we define the actual path of the folder in our file system and to the right will be the equivalent path within the container.
  • So in the first line we tell the app that the config files are written to and read from our SSD in the appdata folder plus another subfolder called Jellyfin. It is not necessary to create the Jellyfin folder beforehand, docker can create up to one level of subfolders when the container is started.
  • In the second line we tell the application where the data to use is, movies, etc. The container will access our /DATA/media shared folder and mount it inside the container by naming it /media.
    • For this to work we must GIVE PERMISSIONS to the userapp on our /DATA/media shared folder. Otherwise the container (using the appuser permissions) will not be able to access this folder and the application will not start, it will show an error. We can give appuser permissions from the GUI by editing the user's privileges.
    • Note: In Jellyfin it is enough to map the DATA/media folder. Within Jellyfin we can configure the libraries of movies, music… by choosing the folders /media/films or /media/music…
• Comment 4: In the “ports” section we define the ports for the application to communicate with the system.
  • The syntax is the same as in the previous point, to the left of “:” we define the port of our nas that we want to use to access the application; on the right we define the port that the application uses internally.
  • Docker will communicate both ports. In this case we decided to change the real port to 8888, so we change the one on the left and keep the one used internally by the 8096 container.
• It's a good idea to keep this text file with the docker stack for future reference or reinstallation. If we have this file and the appdata folder, reinstalling the application on another system takes two minutes.

• 8. Deploy the Docker stack and access the application
  • In the OMV GUI, go to Services > Compose > Files and click on the +Create button. Copy in the File box the contents of the text file that we have created in point 7. In the Name field write the name of the container, in this case Jellyfin. Click the Save button and apply the changes.
    • Note: If you need to set environment variables you can do so in the lower Environment box.
  • Select (yellow) the created row corresponding to your container and press the Check button.
    • If there are no errors your stack can be executed. Otherwise you should review the values entered.
  • Press the Up button.
    • This will download the container image and install it.
    • At this point you should be able to access your application by typing the IP of our server followed by “:” and the access port defined in the previous point. In this case, if the IP of our server were 192.168.1.100 we would write http://192.168.1.100:8888 to access Jellyfin.

• 9. Stack Modification.
  • To modify parameters in a stack:
    • In the OMV GUI go to Services > Compose > Files, select the container row and press the Down button. This will stop the container.
    • Press the Edit button. Modify the desired parameters in the File box and press Save.
    • Select the container row again and press the Up button. The container will now be running with the modified parameters.
  • To restore the container to its initial state, this will remove any configuration we have made to the container.
    • Stop the execution of the container. Down button.
    • Delete the config folder corresponding to the container. (in the example /SSD/appdata/Jellyfin)
    • Start the container. Up button.

→ 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