Differences
This shows you the differences between two versions of the page.
Both sides previous revision Previous revision Next revision | Previous revisionLast revisionBoth sides next revision | ||
omv6:omv6_plugins:compose [2023/05/07 01:41] – chente | omv6:omv6_plugins:compose [2023/05/07 04:40] – chente | ||
---|---|---|---|
Line 1: | Line 1: | ||
- | {{indexmenu_n> | + | {{indexmenu_n> |
\\ | \\ | ||
< | < | ||
Line 11: | Line 11: | ||
===== Summary ===== | ===== Summary ===== | ||
+ | * 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. | * The openmediavault-compose plugin provides a tool in the openmediavault GUI to create and manage containers using docker-compose. | ||
* [[https:// | * [[https:// | ||
Line 274: | Line 276: | ||
* Select the // | * Select the // | ||
+ | ===== Best practices for using docker in OMV ===== | ||
+ | |||
+ | **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 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 **// | ||
+ | * 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 **// | ||
+ | * 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 **// | ||
+ | * The containers should write/read in the **// | ||
+ | * For simplicity this guide uses a single user for all docker containers, **// | ||
+ | |||
+ | * **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 **// | ||
+ | * 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/ | ||
+ | * 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 **// | ||
+ | |||
+ | **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. [[omv6: | ||
+ | * Install [[: | ||
+ | |||
+ | * 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 / | ||
+ | * 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> | ||
+ | * Go to Services> | ||
+ | * 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 **// | ||
+ | * 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 **// | ||
+ | |||
+ | * 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**: | ||
+ | * **Warning**: | ||
+ | * 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**: | ||
+ | * In the OMV GUI, go to **Services** > **Compose** > **Settings** and select the **// | ||
+ | |||
+ | * 5. Create the user " | ||
+ | * In the OMV GUI go to **Users** > **Users** click on the **+Create** button, define **// | ||
+ | * Open the UID and GID columns and make a note of the values that the **// | ||
+ | |||
+ | **EXAMPLE OF INSTALLING AN APPLICATION (JELLYFIN)** | ||
+ | |||
+ | * 6. Choose a stack | ||
+ | |||
+ | * On the [[https:// | ||
+ | * As an example we are going to install Jellyfin. Many results appear in the search engine, we chose the one for linuxserver [[https:// | ||
+ | * 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: " | ||
+ | services: | ||
+ | jellyfin: | ||
+ | image: lscr.io/ | ||
+ | container_name: | ||
+ | environment: | ||
+ | - PUID=1000 | ||
+ | - PGID=1000 | ||
+ | - TZ=Europe/ | ||
+ | - JELLYFIN_PublishedServerUrl=192.168.0.5 #optional | ||
+ | volumes: | ||
+ | - / | ||
+ | - / | ||
+ | - / | ||
+ | ports: | ||
+ | - 8096:8096 | ||
+ | - 8920:8920 #optional | ||
+ | - 7359: | ||
+ | - 1900: | ||
+ | restart: unless-stopped | ||
+ | |||
+ | |||
+ | * 7. Customize the stack. | ||
+ | * It's always a good idea to read the editor' | ||
+ | * 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: " | ||
+ | services: | ||
+ | jellyfin: | ||
+ | image: lscr.io/ | ||
+ | container_name: | ||
+ | environment: | ||
+ | - PUID=1002 | ||
+ | - PGID=100 | ||
+ | - TZ=Europe/ | ||
+ | volumes: | ||
+ | - / | ||
+ | - / | ||
+ | ports: | ||
+ | - 8888: | ||
+ | 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 / | ||
+ | * **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 ":" | ||
+ | * So in the first line we tell the app that the config files are written to and read from our SSD in the **// | ||
+ | * 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 / | ||
+ | * **Comment 4:** In the " | ||
+ | * The syntax is the same as in the previous point, to the left of ":" | ||
+ | * 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 **// | ||
+ | |||
+ | * 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 ":" | ||
+ | |||
+ | * 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 / | ||
+ | * Start the container. **Up** button. | ||
===== Source Code ===== | ===== Source Code ===== |