omv8:omv8_plugins:docker_compose

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revision Previous revision
Next revision		 Previous revision
omv8:omv8_plugins:docker_compose [2025/12/21 11:08] – [Add from example] chenteomv8:omv8_plugins:docker_compose [2026/01/11 09:06] (current) – [Usage in compose files] chente
Line 12: Line 12:
  
 ===== Summary ===== ===== Summary =====
-[[https://docs.docker.com/compose/|{{ ::omv7:omv7_plugins:compose7-1.png?direct&200|Go to -> Docker compose}}]]+[[https://docs.docker.com/compose/|{{ ::omv7:omv7_plugins:compose7-1.png?direct&300|Go to -> Docker compose}}]]
 Docker is a technology that enables the creation and use of Linux containers. A container is an isolated environment where one or more applications and their dependencies run using the same operating system kernel. Docker is a technology that enables the creation and use of Linux containers. A container is an isolated environment where one or more applications and their dependencies run using the same operating system kernel.
  
Line 67: Line 67:
 <html><center>Under <b>Services</b> > <b>Compose</b> > <b>Settings</b></center></html> <html><center>Under <b>Services</b> > <b>Compose</b> > <b>Settings</b></center></html>
  
-{{ :omv8:omv8_plugins:compose8-1.png?direct&600 |Settings}}+{{ :omv8:omv8_plugins:compose8-1.png?direct&1200 |Settings}}
 \\ \\
 This tab contains the general configuration options of the **openmediavault-compose** plugin. This tab contains the general configuration options of the **openmediavault-compose** plugin.
Line 80: Line 80:
 === Compose Files === === Compose Files ===
  
 +{{ :omv8:omv8_plugins:compose8-19.png?direct&600|Compose settings}}
 Define the folder where the plugin will store container configuration files, including Docker Compose files (''.yaml'') and environment files (''.env'').   Define the folder where the plugin will store container configuration files, including Docker Compose files (''.yaml'') and environment files (''.env'').  
  
Line 709: Line 710:
 ---- ----
  
-==== Usage in compose files ====+==== Usage in Compose Files ====
  
 Docker configs managed in this tab can be referenced inside compose files using the standard Docker Compose syntax. Docker configs managed in this tab can be referenced inside compose files using the standard Docker Compose syntax.
Line 715: Line 716:
 This allows configuration files to be mounted into containers at runtime without hardcoding their contents directly in the compose file. This allows configuration files to be mounted into containers at runtime without hardcoding their contents directly in the compose file.
  
-This functionality is recommended only for users familiar with Docker Compose and container configuration management.+**Workflow:** 
 + 
 +  * A config file is always associated with a specific Compose file. 
 +  * When you create or import a config in the GUI, it is stored in the same folder as the Compose file. 
 +  * In your Compose file, you can reference the config using its filename only, no absolute path needed. 
 +  * This allows you to keep all container configuration files in one place, simplifying management and avoiding repetitive CLI bind-mounting. 
 + 
 +**Example:** 
 + 
 +  * You create mosquitto.conf in the Configs tab and associate it with docker-compose.yml. 
 +  * The plugin stores mosquitto.conf in the same folder as the compose file. 
 +  * In docker-compose.yml, mount it like this: 
 + 
 +<code> 
 +services: 
 +  mosquitto: 
 +    image: eclipse-mosquitto 
 +    volumes: 
 +      - .mosquitto.conf:/mosquitto/config/mosquitto.conf:ro 
 + 
 +</code> 
 + 
 +**Key points:** 
 + 
 +  * Configs cannot be created outside the compose folder. 
 +  * This workflow saves CLI steps and keeps configuration files organized and easy to find. 
 +  * Recommended for users who want to manage container configs without hardcoding paths or moving files manually.
  
 ---- ----
Line 979: Line 1006:
   * **Driver**   * **Driver**
     * Choose the network driver type (bridge, overlay, macvlan, etc.).     * Choose the network driver type (bridge, overlay, macvlan, etc.).
 +      * **bridge** – standard network bridge.
 +      * **ipvlan** – network interface with minimal overhead, useful for assigning multiple IPs.
 +      * **macvlan** – assign a MAC address to each container; allows containers to appear as separate devices on the LAN.
 +      * **overlay** – network for multi-host container communication.
 +  * **Parent Network** (only for macvlan)
 +    * Select the physical network interface on the host that will act as the parent for the macvlan network.
   * **Subnet**   * **Subnet**
     * Define the subnet in CIDR notation (e.g., 172.20.0.0/16).     * Define the subnet in CIDR notation (e.g., 172.20.0.0/16).
Line 987: Line 1020:
   * **Aux Address**   * **Aux Address**
     * Optional static IP assignments in the format `name=ip`.       * Optional static IP assignments in the format `name=ip`.  
-      Comma separate multiple entries (e.g., `my-router=192.168.10.5,my-nas=192.168.20.6`).+    * Comma separate multiple entries (e.g., `my-router=192.168.10.5,my-nas=192.168.20.6`).
   * **Save**   * **Save**
     * Creates the network with the defined parameters.     * Creates the network with the defined parameters.
Line 1184: Line 1217:
 {{ :omv8:omv8_plugins:compose8-16.png?direct&1200 |Schedule}} {{ :omv8:omv8_plugins:compose8-16.png?direct&1200 |Schedule}}
  
-{{ :omv8:omv8_plugins:compose8-17.png?direct&400|Backup}}+{{ :omv8:omv8_plugins:compose8-17.png?direct&600|Backup}}
 By default, backups include all subfolders containing generated compose files. These subfolders are created automatically every time a compose file is generated via the GUI. By default, backups include all subfolders containing generated compose files. These subfolders are created automatically every time a compose file is generated via the GUI.
  
Line 1207: Line 1240:
  
 <html><body><table width="100%" border="0"><tr><td colspan="2" style="background-color:#69A5FF;height:30px;"><strong><span style="color:#FFFFFF;font-size:110%;">&#160; Note <html><body><table width="100%" border="0"><tr><td colspan="2" style="background-color:#69A5FF;height:30px;"><strong><span style="color:#FFFFFF;font-size:110%;">&#160; Note
-</span></strong></td></tr><tr><td style="background-color:#E6FEFF;height:25px;width:380px;">+</span></strong></td></tr><tr><td style="background-color:#E6FEFF;padding:10px;width:380px;">
 The advantage of the plugin's backup utility is that it stops containers before performing the backup, ensuring consistency. Afterward, you can use any specialized backup solution for versioning, deduplication, etc. Running backups while containers are active may produce inconsistent results. The advantage of the plugin's backup utility is that it stops containers before performing the backup, ensuring consistency. Afterward, you can use any specialized backup solution for versioning, deduplication, etc. Running backups while containers are active may produce inconsistent results.
 </tr></table></body></html> </tr></table></body></html>
Line 1215: Line 1248:
 === Create === === Create ===
  
-{{ :omv7:omv7_plugins:compose9.jpg?direct&400|Schedule}}+{{ :omv7:omv7_plugins:compose9.jpg?direct&600|Schedule}}
 Opens a dialog to schedule container backup and/or update jobs. Opens a dialog to schedule container backup and/or update jobs.
  
Line 1444: Line 1477:
  
 <html><body><table width="100%" border="0"><tr><td colspan="2" style="background-color:#69A5FF;height:30px;"><strong><span style="color:#FFFFFF;font-size:110%;">&#160; Note <html><body><table width="100%" border="0"><tr><td colspan="2" style="background-color:#69A5FF;height:30px;"><strong><span style="color:#FFFFFF;font-size:110%;">&#160; Note
-</span></strong></td></tr><tr><td style="background-color:#E6FEFF;height:25px;width:380px;">+</span></strong></td></tr><tr><td style="background-color:#E6FEFF;padding:10px;width:380px;">
 The authentication status affects the ability to pull or push images from/to private repositories. The authentication status affects the ability to pull or push images from/to private repositories.
 </tr></table></body></html> </tr></table></body></html>
Line 1492: Line 1525:
  
 This widget allows quick monitoring of active containers without entering the Compose interface. This widget allows quick monitoring of active containers without entering the Compose interface.
- 
----- 
- 
  
 ---- ----
Line 1500: Line 1530:
 ===== Usual procedures ===== ===== Usual procedures =====
  
----- +[[omv8:docker_in_omv#usual_procedures|{{ :omv7:dockeromv7-26.jpg?200|Go to -> 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**. +You can find several common procedures for creating and maintaining containers in the Docker documentation on OMV, in the Usual Procedures section.
-  * 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.+
  
----- +See -> [[omv8:docker_in_omv#usual_procedures|Usual procedures]]
- +
-=== 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. +
- +
- +
-<html><body><pre><code>services: +
-  pi-hole: +
-    container_name: "pi-hole" +
-    . +
-    . +
-    <FONT COLOR="red">networks: +
-      mynet: +
-        ipv4_address: 192.168.1.241 +
-networks: +
-  mynet: +
-    external: true</FONT></code></pre></body></html> +
- +
-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. +
- +
-<html><body><table width="100%" border="0"><tr><td colspan="2" style="background-color:#FFB663;height:30px;"><strong><span style="color:#FFFFFF;font-size:110%;">&#160;  +
-Warning  +
-</span></strong></td></tr><tr><td style="background-color:#FFE4A6;height:25px;width:380px;"> +
-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.<br> +
-If you have a suggestion to do this in a safe way you can post it in the forum. +
-</tr></table></body></html> +
- +
-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: +
- +
-<html><body><pre><code>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</code></pre></body></html> +
- +
-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: +
- +
-<html><body><pre><code>nano /etc/network/interfaces.d/99-mynet-host</code></pre></body></html> +
- +
-  * Copy into that file the following content: +
- +
-<html><body><pre><code>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</code></pre></body></html> +
- +
-  * 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. +
- +
-<html><body><table width="100%" border="0"><tr><td colspan="2" style="background-color:#69A5FF;height:30px;"><strong><span style="color:#FFFFFF;font-size:110%;">&#160; Note +
-</span></strong></td></tr><tr><td style="background-color:#E6FEFF;height:25px;width:380px;"> +
-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. +
-</tr></table></body></html>+
  
 ---- ----
  • omv8/omv8_plugins/docker_compose.1766315318.txt.gz
  • Last modified: 2025/12/21 11:08
  • by chente