Ultimate QNAP Docker Compose and Container Station Guide [2023]

QNAP + docker compose, a great union made possible by QNAP Container Station. Today, I’ll show you how to use Container Station to build your QNAP Docker Compose stack.

We have previously covered Synology Docker topics in detail. Our objective with this QNAP Docker post is also to help QNAP NAS users to get started with building Docker Compose stacks.

The inclusion of Docker in NASes took brands like Synology and QNAP to the next level because, a whole new world of containerized applications could not be run on NASes. [Read: 60+ Best Docker Containers for Home Server Beginners]

In addition, QNAPs are one of the best NAS devices for Plex Media Server.

One is not just restricted to the limited set of apps available through the NAS maker or its community.

In the case of QNAP, Container Station is what allows you to jump into the world of Docker.

QNAP Container Station

Container Station is the official QNAP app for virtualization, supports LXD, Kata, and naturally Docker, has a very neat interface and is absolutely easy to use.

We can search, choose and download images or applications, directly from the Create menu, OR use the power and versatility of docker-compose and click Create Application to obtain a new ready-to-write YAML file.

The Create Tab, Used To Install New Container Or Create New Application
The Create Tab, Used To Install New Container Or Create New Application

The list used to retrieve the images and applications is nothing but a Github repository, that can be changed from the application Preferences.

Repository For Docker Images
Repository For Docker Images

Of course, it's possible to Export/Import containers, but for the sake of lazyness practicality, we're going to use only one YAML file to rule them all.

Last but not least, docker engine and compose are automatically installed with the app, so everything needed is packed together. This a great plus compared to Synology, which requires separately installing Compose using commandline.

Note: At the time of writing, QNAP Container Station 3 is still a beta version, so I'm going to use the latest version available.

1. Install Container Station

It's downloadable from the App Center, if not already installed.

Qnap Container Station App Install
Qnap Container Station App Install

After QNAP Container Station Download, during the first run, we'll be asked which folder will be used for storing application data. By default a shared folder named Container is automatically created, otherwise, we could choose or create another one. In this tutorial I used the default folder.

Qnap Container Stations Default Folder
Qnap Container Stations Default Folder

Start Now and Container Station is ready.

2. Check Container Shared Folder Permission

Quick check, just to verify that our user has permission to read/write inside the "Container" folder, from "Control Panel", "Shared Folder":

Qnap Shared Folder Permissions
Qnap Shared Folder Permissions

Click on the Edit shared folder permission button, of the Container folder, and check if our user is included in the user list and has correct permission:

Include User In The Permissions List
Include User In The Permissions List

As my user is in the administrator's group, I'm fine, but if not, we could add the user by pressing the Add button.

Add User To Folder Permissions
Add User To Folder Permissions

Then, select the user from a list, setting the right permission:

Select User To Give Privileges To The Shared Folder
Select User To Give Privileges To The Shared Folder

3. Enable SSH Access on QNAP

Now, we need to connect the NAS through SSH. If SSH has not been activated before, we need to do it from Control Panel->Telnet/SSH.

Qnap Ssh Access
Qnap Ssh Access

Tick "Allow SSH connection", then click on "Edit Access Permission" and select the user you want to use for the connections.

Remember that only users in the "administrators" group could be allowed for SSH.

We could also tick "Enable SFTP" to be able to manage files with clients like Filezilla. [Read: 30 Best SSH Clients for Windows [2022]: Free and Paid]

Enable Ssh On Qnap
Enable Ssh On Qnap

4. Upgrade Docker Compose (OPTIONAL)

Now that everything is ready, we can SSH into our NAS, move to the folder location of docker-compose and download its latest version from here, based on the CPU architecture:

# Show the CPU architecture
uname -m

# Move into docker-compose binary folder
cd /share/CE_CACHEDEV1_DATA/.qpkg/container-station/usr/bin/.libs/

# Download 
wget https://github.com/docker/compose/releases/download/vx.xx.x/docker-compose-linux-xxxxxx

Just to prevent things from going wrong, we'll make a backup copy of the actual docker-compose binary with another name, rename the new one and assign it the right owner, group and permission:

sudo bash

# Backup copy 
mv docker-compose docker-compose-old

# Rename new binary
mv docker-compose-linux-xxxxxx docker-compose

# Changing owner, group and permissions
chown admin:administrators docker-compose
chmod +x docker-compose
chmod 755 docker-compose

# Check compose version
docker-compose -v

The result should be something like this:

Qnap Docker Compose Version
Qnap Docker Compose Version

We can create, control and edit compose stack directly from command line, but QNAP NAS Container Station already does this job and lets us configure everything one time and forget about it - no worries about autostart configuration on boot, no complication with encrypted volumes, etc.

So, in my opinion, the best thing to do is letting Container Station do all this kind of works for us.

5. Create Folder Structure

To setup the folder structure used by Anand (Find it here), we first need to create an additional group, where the only member is the admin, and use it to set the right permissions for the secrets folder and the .env file.

FUN FACT: QNAP NASes don't have the root user, but they do have the admin user.

Different names, same functions.

We're gonna do it from the "Control Panel", "User Groups", because AFAIK there's no terminal command to create a new group:

Qnap Group Creation
Qnap Group Creation

Click on "Create" and fill the field with the group name, I used admindocker, assign ONLY admin user to the group and no assignation of folder is needed as the admin already has access to all the filesystem.

Create Group For Docker Containers On Qnap
Create Group For Docker Containers On Qnap

After this, SSH into NAS and go to the folder where "Application" (A.K.A compose stack) data are saved, and create a folder:

Note: write down the name of the folder we're going to create, as we need to use it for the name of the "Application" in Container Station.
# Move to data folder
cd /share/Container/container-station-data/application

# Create a new folder
mkdir FolderName
cd FolderName

# Create folder structure using Anand's tutorial
mkdir ...
touch ...

# Change .env file and "secrets" folder permission, owner and group
chmod 600 .env
chmod 600 secrets

sudo bash
chown admin:admindocker .env
chown admin:admindocker secrets

If we want to edit the file directly from SSH, VIM is an option (already installed on QNAP NAS but not really user friendly).

Other options, depending on the operating system used, are SCP/SFTP clients:

Populate the .env file and secrets folder with all the stuff that you need, and jump to the next step! You can follow Anand's Docker Guide as reference.

6. Change Default QNAP Ports

AND FINALLY, we're ready to create our compose stack.... Well, actually almost ready, because if we plan to include containers that need standard ports 80 (HTTP, QNAP Web Server) or 443 (HTTPS), like Traefik reverse proxy, we must edit QNAP settings, as these ports are already used:

In "Control Panel", "System", "General Settings", "System Administration", we have to change the "System port" (HTTP) from 80 to another free port number (8000 for example) and, if secure connection is enabled but I'm pretty sure it is, also change the "Port number" (HTTPS) from 443 to another free port number (4430 for example).

Change Qnap Nas Default System Ports
Change Qnap Nas Default System Ports

Same thing for the QNAP Web Server, if enabled, "Control Panel", "Application", "Web Server":

Change Qnap Nas Web Server Ports
Change Qnap Nas Web Server Ports

7. Create Compose Stack with Container Station

No more tricks, time to open Container Station, click on "Create" and "Create Application":

Build Docker Compose Stacks On Qnap
Build Docker Compose Stacks On Qnap

And >>BOOM<<, here it is our YAML file, ready to be written.

Did you remember the name of the folder we created moments ago?

Good, that's the name that goes in the "Application name" field, to be able to use the folder structure, .env file and secrets folder.

When a new "Application" is saved, Container Station creates a new folder inside "/share/Container/container-station-data/application" using the name given in the "Application name" field and stores there the docker-compose.yml file.

If the folder has already been created, it simply stores the YAML file inside it, and leaves its structure unaffected.

Qnap Docker Compose File
Qnap Docker Compose File

The "Sample" drop-down includes three already compiled YAML files:

  • WordPress
  • Redmine
  • PostgreSQL

Once we finish, we need to click "Validate YAML", "Create" and, if everything is fine, stack building should start:

Qnap Docker Stack Creation In Progress !
Qnap Docker Stack Creation In Progress !

Our compose stack has been created, we could see it from the "Container" tab: the green cubes icon means that the stack is up and running, the grey one that is stopped, we could stop, restart, edit and delete the stack using the menu on the right.

Qnap Docker Stack Status
Qnap Docker Stack Status

That's all for now with our QNAP docker compose journey.


I guess you all know what a bonus track is:

A bonus track (also known as a bonus cut or bonus) is a piece of music which has been included as an extra.

and like musicians, I want to add some extra to this tutorial, arguments that are not strictly related to the main topic, but could help reaching our goal easily.


! Installing nano as text editor on QNAP NAS !

Restricted Content

Additional explanations and bonus content are available exclusively for the following members only:

Silver - Monthly, Silver - Yearly, Gold - Monthly, Gold - Yearly, Diamond - Monthly, Diamond - Yearly, and Platinum Lifetime (All-Inclusive)

Please support us by becoming a member to unlock the content.
Join Now

! autorun.sh Edit !

I'm not crazy, I told you I wouldn't have covered the argument on the tutorial, and I'm not going to cover it, BUT if you really really really want, or need, to edit the autorun.sh, here's a link from QNAP with all the information.



Can QNAP run Docker?

Yes, most modern QNAP NASes can run Docker. The Docker package also include Docker Compose. But the versions can be slightly older.

Where are QNAP containers stored?

QNAP container data are stored in the default folder defined during Container Station Installation (e.g. /share/Container/container-station-data/application).

How to install container station on QNAP?

QNAP container station is a downloadable app from the App Center, if not already installed.

Final Thoughts on QNAP Docker Compose

I think that Container Station is the fastest solution for having a compose stack on QNAP NAS, without the risk of many headaches.

Couple of caveats I want to report are:

  1. When you create a new "Application" with a single container inside, you cannot edit the YAML file once saved.
  2. If you create and bring up your compose stack directly from command line, you'll be able to see it from Container Station but you cannot control from it, plus containers won't autostart upon reboot/shutdown (you need to edit the autorun.sh script, but I won't cover the process in this tutorial).

Otherwise, I hope that this QNAP Container Station and Docker Compose guide helps you get started. Don't forget to check out the Traefik Reverse Proxy guide.

Be the 1 in 200,000. Help us sustain what we do.
11 / 150 by Dec 31, 2024
Join Us (starting from just $1.67/month)