A guide for configuring Docker containers on QNAP devices with Container Station
This project is as yet unfinished, which means there can and will be issues. Getting this HomeLAB enviornment working in your QNAP will probably require tweaking and troubleshooting. I will help when and if I can, but I can not be held responsible for issues created while following this guide or performing any suggestions I make.
WARNING: This guide is incomplete, and as such will contain errors.
Please read the disclaimer at the end of this document.
Thanks for checking out this guide. If it ends up being useful for your setup, please consider donating!
PREREQUISITES:
- A QNAP device that supports the Container Station application. We have not yet figured out how to manually install Docker on a QNAP device, therefore must still rely on the default installation of Docker.
- A desire to learn Docker and some basic Terminal commands.
Consider joining and contributing to the QNAP Unofficial Discord, a community built around advice on everything QNAP. We have helpful members, FAQs, CI/CD, community Docker images, and cookies (well, maybe not cookies).
- QNAP Docker HomeLAB Setup Instructions
- Contributors
- DISCLAIMER
- All actions in this section will be performed in the QNAP QTS operating system web-portal GUI.
-
Ports 80, 443, and 8080 must be unused by your NAS.
- NOTE: This step may be unnecessary if you can get double port forwarding to work when getting Traefik to recognize your domain and register a certificate. YMMV.
- By default, QTS assigns ports 8080 and 443 as the default HTTP and HTTPS ports for the QNAP Web Admin Console, and assigns 80 as the default HTTP port for the native "Web Server" application. Each of these must be updated to be successful with this guide.
-
Modify these ports as follows to ensure there will be no port conflicts with docker stacks:
- Change default System ports: In QNAP Web GUI
Control Panel >> System >> General Settings
- Change the default HTTP port to
8480
, and the default HTTPS port to8443
. - NOTE: This will change the LAN address from which you access your QTS web-gui, requiring you to add the port at the end of your NAS LAN IP (e.g. https://192.168.1.100:8443)
- Change default Web Application ports: In QNAP Web GUI
Control Panel >> Applications >> Web Server
- Change the default HTTP port to
9480
, and the default HTTPS port to9443
. - TIP: Unless currently in use, consider disabling the MySQL application in the QNAP GUI Settings.
- WARNING: DO NOT disable the Web Server application, leave this active on the new port. There is a bug in QTS where the Web Server will re-acquire the default port if it is disabled.
- Change default System ports: In QNAP Web GUI
-
Ports 80 and 443 must be forwarded from your router to your NAS.
- This is possible using UPNP in the QNAP GUI, but is not recommended!
- Instead, disable UPNP at the router and manually forward ports 80 and 443 to your NAS.
- NOTE: There are too many possible routers to cover how to forward ports on each, but there are some good guides here if you don't know how to do it for your router:
Ports Overview:
- QTS System ports should be:
- HTTP :
8480
- HTTPS:
8443
- HTTP :
- QTS Web Server application ports should be: - HTTP : `9480` - HTTPS: `9443`
-
Create a new user called
dockeruser
-
Create the following folder shares using the QTS web-GUI
ControlPanel >> Privilege >> Shared Folders
- Give
dockeruser
Read/Write permissions for each of the below folders: /share/docker/
- This is the main "docker" folder inside which we will place swarm and compose config files, in their own subfolders. The remaining folders listed below should be created using the Terminal, when logged in using the default QTS
admin
account.
- This is the main "docker" folder inside which we will place swarm and compose config files, in their own subfolders. The remaining folders listed below should be created using the Terminal, when logged in using the default QTS
- NOTE: The
swarm
,compose
,common
, andsecrets
folders (created using the terminal) can be added as shares in the QTS Control Panel, but that is entirely unnecessary as the/share/docker/
parent folder is already shared out.
- Install the
entware-std
package from the third-party QNAP Club repository appstore. This is necessary in order to setup the shortcuts/aliases used when controlling docker via command line by editing a permanent profile.-
The preferred way to do this is to add the QNAP Club Repository to the App Center. Follow the walkthrough instructions here.
-
Note that I use the English translation of the QNAP Club website, but you may change languages (and urls) in the upper right language dropdown.
-
If you don't need the walkthrough, add the repository. (For English, go to App Center, Settings, App Repository, Add,
https://www.qnapclub.eu/en/repo.xml
). -
If you cannot add the QNAP Club store to the App Center, you may manually download the qpkg file from that link and use it to manually install via the App Center, "Install Manually" button. This is not preferred as QNAP cannot check for and notify you of updates to the package.
-
Search for
entware-std
and install that package.- If you have trouble locating the correct package, the description begins with
entware-3x and entware-ng merged to become entware.
The working link (as of publication) is here: https://www.qnapclub.eu/en/qpkg/556.
- If you have trouble locating the correct package, the description begins with
-
IMPORTANT: DO NOT CHOOSE either the
entware-ng
orentware-3x-std
packages. These have merged and been superceded byentware-std
.
-
-
Backup what you have running now (if you don't have anything running yet, skip to Step 3 or 5)
-
Shutdown and remove all Containers:
- Open an SSH terminal session to your NAS and run:
docker system prune
- To ensure the network topography is reset, run:
docker network prune
- To be sure you don't have a swarm left hanging around, run:
docker swarm leave --force
- Open an SSH terminal session to your NAS and run:
-
Remove Container Station:
-
Reboot the NAS
-
Install Container Station from the QNAP Appstore.
- Launch CS once installed
- Accept and create the
/Container
folder suggested when CS is launched for the first time.
- All actions in this section will be performed via SSH Terminal connection to your QNAP NAS.
-
Open/Connect an SSH Terminal session to your QNAP NAS.
- NOTE: Alternatively you can use BitVise because this also has an SFTP remote file browser interface.
- TIP: I switched to using WinSCP and Cmder because they have dark themes. Windows Terminal Preview is turning out to be a good Terminal as well.
- TIP: Connecting to the NAS using SFTP allows me to edit the docker config files using
Notepad++
orVSCodium
(open source Visual Studio Code clone). - TIP: I also map the
/share/docker/
folder as a Network drive on my Windows desktop, which makes viewing and editing Docker config files very easy.
-
Install nano or vi, whichever you are more comfortable with (only one needed)
- RUN:
opkg install nano
- RUN:
opkg install vim
- NOTE: You must have installed the
entware-std
package as detailed in Section 1.4 to be able to use the "opkg" installer.
- RUN:
-
This section is a continuation of the QNAP QTS folder creation steps from the previous section. Here we will create the sub-folders required for
scripts
,swarm
,compose
, andsecrets
files.-
These folders should all individually be created using this example terminal command:
mkdir -pm 600 /share/docker/scripts
OR create all the below listed folders using a single command:
mkdir -pm 600 /share/docker/{common,scripts,secrets,compose/{appdata,configs,runtime},swarm/{appdata,configs,runtime}}
/share/docker/swarm
- this is the "docker swarm" config files folder/share/docker/swarm/appdata
- Here we will add folders named
< stack name >
. This is where your application files live... libraries, artifacts, internal application configuration, etc. Think of this directory much like a combination ofC:\Windows\Program Files
andC:\Users\<UserName>\AppData
in Windows.
- Here we will add folders named
/share/docker/swarm/configs
- Here we will also add folders named
< stack name >
. Inside this folder, we will keep our actual stack_name.yml files and any other necessary config files used to configure the docker stacks and images we want to run. This folder makes an excellent GitHub repository. NOTE: Do not save sensitive information in your.yml
files if you are sharing this folder as a git repository.
- Here we will also add folders named
/share/docker/swarm/runtime
- This is a shared folder on a volume that does not get backed up. It is where living DB files and transcode files reside, so it would appreciate running on the fastest storage group you have or in cache mode or in Qtier (if you use it). Think of this like the
C:\Temp\
in Windows.
- This is a shared folder on a volume that does not get backed up. It is where living DB files and transcode files reside, so it would appreciate running on the fastest storage group you have or in cache mode or in Qtier (if you use it). Think of this like the
/share/docker/compose
- this is the "docker-compose" config files folder/share/docker/compose/appdata
- Here we will add folders named
< stack name >
. This is where your application files live... libraries, artifacts, internal application configuration, etc. Think of this directory much like a combination ofC:\Windows\Program Files
andC:\Users\<UserName>\AppData
in Windows.
- Here we will add folders named
/share/docker/compose/configs
- Here we will also add folders named
< stack name >
. Inside this folder, we will keep our actual stack_name.yml files and any other necessary config files used to configure the docker stacks and images we want to run. This folder makes an excellent GitHub repository. NOTE: Do not save sensitive information in your.yml
files if you are sharing this folder as a git repository.
- Here we will also add folders named
/share/docker/compose/runtime
- This is a shared folder on a volume that does not get backed up. It is where living DB files and transcode files reside, so it would appreciate running on the fastest storage group you have or in cache mode or in Qtier (if you use it). Think of this like the
C:\Temp\
in Windows.
- This is a shared folder on a volume that does not get backed up. It is where living DB files and transcode files reside, so it would appreciate running on the fastest storage group you have or in cache mode or in Qtier (if you use it). Think of this like the
/share/docker/secrets
- This folder contains secret (sensitive) configuration data that should NOT be shared publicly. This could be stored in a PRIVATE Git repository, but should never be publicized or made available to anyone you don't implicitly trust with passwords, auth tokens, etc.
- This folder contains secret (sensitive) configuration data that should NOT be shared publicly. This could be stored in a PRIVATE Git repository, but should never be publicized or made available to anyone you don't implicitly trust with passwords, auth tokens, etc.
/share/docker/common
- This is where you can store general config files, or shared files bothcompose
andswarm
mode containers might use.
-
Once all required folders are created, you must update ownership and permissions so the
dockeruser
account has the proper access level for Docker operations:chown dockuser:dockgroup -cR /share/docker && chmod 600 -cR /share/docker
-
This is what your folder heirarchy should look similar to after creating the above folder structure:
-
-
Next you need to download the custom
docker scripts
from the QNAP HomeLAB Docker Scripts repository to your/share/docker/scripts/
directory.Alternatively, if you trust my installation script to run as root on your system, you can run thisThis feature is not finished, please download and install the scripts manually.curl
command that will automatically download and install the scripts for you:- TIP: Read through and understand what a script does before executing possibly malicious code on any device.
OR
# install the docker_scripts_setup.sh using wget without downloading the file wget -sO - https://raw.githubusercontent.com/QNAP-HomeLAB/Docker-Scripts/master/docker_scripts_setup.sh | sh
# download and install the docker_scripts_setup.sh using cURL curl -fsSL https://gitlab.com/qnap-homelab/docker-scripts/docker_scripts_setup.sh | sh
-
Type the below lines into the QNAP command line:
printf "alias profile='source /opt/etc/profile" >> /opt/etc/profile
printf "source /share/docker/scripts/docker_commands_list.sh -x" >> /opt/etc/profile
- NOTE: Adding the above lines to your
profile
automates the loading of the custom helper-scripts in the/share/docker/scripts/
sub-folder. - If you prefer to enter the text manually, this is the line that needs to go at the bottom of the
profile
file:source /share/docker/scripts/docker_commands_list.sh -x
- NOTE: Adding the above lines to your
-
OPTIONAL: The below steps accomplish the same thing as above, but add notification messages whenever you reload or log into the qnap cli.
-
NOTE: If you use a Windows client to save the profile (or the scripts below), they will be saved with the
CR LF
end of line sequence, and will error. You MUST set the end of line sequence to UNIXLF
in order for the profile and scripts to work correctly.VSCodium EOL Settings
-
EDIT the
profile
file vianano /opt/etc/profile
orvi /opt/etc/profile
-
NOTE: I prefer to use VSCodium to edit this file as it provides syntax highlighting.
source /share/docker/scripts/docker_commands_list.sh -x && echo " >> '.../docker_commands_list.sh' successfully loaded" || echo " -- ERROR: could not import '.../docker_commands_list.sh'"
-
NOTE: You will need to restart your ssh terminal session, or execute the
profile
alias (a shortcut to reloadprofile
), in order to make the changes effective.
-
-
Once the
profile
and/share/docker/scripts
are set up, use the below section as a reference for Docker shortcut commands.-
In general, this is the scheme for how the shortcut acronyms are composed:
dc...
refers to "Docker Compose" commands, for use outside of a swarm setupdl...
refers to "Docker List" commands (i.e. docker processes, docker networks, etc)ds...
refers to "Docker Stack" commands (groupls of containers in a swarm setup)dv...
refers to "Docker serVice" commands (mostly error and logs related)dw...
refers to "Docker sWarm" initialization/removal commands (the whole swarm)dy...
refers to "Docker sYstem" commands for showing info and cleaning remnants
-
NOTE: Individual script descriptions have been removed from this
readme.md
. Please refer to the docker_commands_list.sh file for an updated list with descriptions.
-
- This setup relies on several environment variable files to properly configure and set up your Docker containers.
- The
.script_vars.conf
file has variables used by both Swarm and Compose containers. - Ensure this file is located here:
/share/docker/scripts/.script_vars.conf
- Read through this file, and fill in YOUR NETWORK, NAS, OR PERSONAL INFORMATION.
- Pay special attention to these variables, as they are REQUIRED:
var_nas_ip
- this is the Local Area Network IP address of your QNAPvar_usr
- userid from commandid dockeruser
var_grp
- groupid from commandid dockeruser
var_tz
- time zone in standardRegion/City
formatvar_domain0
- main, or only, domain name used by Traefikvar_dns_provider
- DNS provider (e.g. Cloudflare, Namecheap, etc)var_certresolver
- Certificate Resolver (e.g. Cloudflare, Namecheap, etc)
- The
- You are now ready to customize the
Traefik
and other Docker app configuration files found in the repositories below. Your next step is to chooseDocker Compose
orDocker Swarm
(or a combination of both!) and then download and modify the desired Docker container config files, or write your own. - Example container configuration files from the QNAP HomeLAB repository:
If you have questions or issues, please join the community here: QNAP Unofficial Discord.
- Thanks to the late
gkoerk
(RIP) for starting this community and project. Without his efforts, none of this would have been possible. - Funky Penguin at funkypenguin.co.nz provided a lot of the inspiration and docker config examples which started this QNAP specific project.
- Several articles from smarthomebeginner.com were used as reference for the Traefik and Cloudflare configuration steps contained in this guide.
- Many helpers and members on the QNAP Unofficial Discord community.
- WARNING: This guide is incomplete, and as such will probably contain errors.
- NOTE: Effort has been made to provide accurate instructions tailored for QNAP NAS devices, but no guarantee can be made that this guide will work on your specific device.
- YOU accept all liability for loss or damage or inconvenience arising from using the information contained in this guide.
- All responsibility and risk for properly verifying the validity of anything written in this guide lies with the user. Contributors have composed the steps contained herin to the best of their ability, but nobody is infallible nor can all situations be accounted for. If you have questions or concerns, please join us on the QNAP Unofficial Discord community and request help.