{{ :omv6:omv6_plugins:compose5.jpg?direct&600 |Stats}}
----
=== Inspect ===
Docker inspect provides detailed information about builds controlled by Docker.
Activated when selecting a container.
----
=== Logs ===
Allows you to view the log of the selected container.
Activated when selecting a container.
----
=== Follow Logs ===
It will display logs for the selected container and will continue to display new logs if any occur.
Activated when selecting a container.
----
===== Images =====
Shows existing images on the system. Allows you to manage these images.
----
=== Delete ===
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.
----
=== Inspect ===
Displays the result of inspecting the selected image.
----
===== Networks =====
Shows existing networks on the system. Allows you to manage these networks.
----
=== Create ===
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.
----
=== Delete ===
Deletes the selected network interface.
----
=== Inspect ===
Inspects the selected network interface and lists its properties.
----
===== Volumes =====
Shows existing volumes on the system. Allows you to manage these volumes.
----
=== Delete ===
Deletes the selected volume.
----
=== Inspect ===
Inspects the selected volume and lists its properties.
----
===== Containers =====
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.
\\
\\
Under Services > Compose > Containers
{{ :omv6:omv6_plugins:compose4.jpg?direct&600 |Containers}}
----
=== Restart ===
Allows you to restart the selected container.
Activated when selecting a container.
----
=== Logs ===
Allows you to view the log of the selected container.
Activated when selecting a container.
----
=== Follow logs ===
Shows the continuous output of the container logs.
Activated when selecting a container.
----
===== Dockerfiles =====
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.
Under Services > Compose > Dockerfiles
{{ :omv6:omv6_plugins:compose3.jpg?direct&600 |Dockerfiles}}
----
=== Create ===
{{ :omv6:omv6_plugins:compose10.jpg?direct&400|Create Dockerfile}}
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.
----
=== Edit ===
Allows you to edit the //Dockerfile//, //script// and //conf// files of the selected Dockerfile.
The operation of this tab is similar to the [[omv6:omv6_plugins:docker_compose#create|Create]] button already seen.
Triggered by selecting a //Dockerfile//.
----
=== Delete ===
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//.
----
=== Build ===
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//.
----
=== Pull and build ===
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//.
----
===== Schedule (Updates and Backups) =====
{{ :omv6:omv6_plugins:compose12.jpg?direct&400|Backup}}
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.
| Note
|
|
The advantage of the plugin's backup utility is that it stops the containers before doing the backup, which is actually a simple rsync. After that is when you should use whatever specialized backup utility you want, with deduplication, versioning, etc., to backup that folder copied with rsync. If you use any backup application directly with the containers running you can get an inconsistent backup.
|
----
=== Create ===
{{ :omv7:omv7_plugins:compose9.jpg?direct&400|Schedule}}
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.
----
=== Edit ===
Opens the edit dialog for the selected task.
----
=== Delete ===
Deletes the selected task.
----
=== Run ===
Now executes the selected task. You will not receive an email if you run the scheduled job in this way.
----
===== Dashboard =====
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.
----
===== Usual procedures =====
----
=== 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** > **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.
----
=== 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 **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.
----
=== How to generate a composition yaml file with Autocompose ===
\\
* 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.
----
=== How to Create a VLAN (Pi-hole, Adguard, ...) ===
\\
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.
----
== Creation and use of the VLAN network interface with IP in our LAN ==
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: [[https://jodies.de/ipcalc|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.
----
== Assigning this network interface in a container ==
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.
----
== Reduce the IP range of the DHCP server (usually the router) ==
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.
----
== If we need communication between the containers and the host ==
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.
|
Warning
|
What follows from now on is a procedure that creates a binding interface for communication with the host via /etc/network/interfaces when OMV uses netplan. This can generate some conflict in certain circumstances. Do it at your own risk.
If you have a suggestion to do this in a safe way you can post it in the forum.
|
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.
| Note
|
|
If for some reason you need to create many different IPs keep in mind that macvlan uses different MAC addresses for each IP. This can be a problem if your hardware has a limit on the maximum number of MACs for the same physical interface. In that case you can change the configuration to ipvlan. Consult the official docker documentation in this regard to solve other possible configuration problems with ipvlan.
|
----
===== Source Code =====
-> [[https://github.com/OpenMediaVault-Plugin-Developers/openmediavault-compose|openmediavault-compose]]
----
===== A Closing Note =====
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**
\\
\\
\\
**Venmo: ryecoaaron** \\