Portainer and Docker Compose on NAS: A Practical Guide

Portainer is a browser-based Docker management interface that makes running containers on a NAS significantly more approachable. It provides a visual UI for managing containers, images, volumes, and networks, and acts as the control plane for Docker Compose stacks. This guide covers installing Portainer on both Synology (Container Manager) and QNAP (Container Station), using Docker Compose to deploy applications, and the key concepts (volumes, networks, environment variables) that determine whether your containers keep running reliably after a NAS reboot. These skills underpin every other Docker how-to guide on this site.

Why Portainer on a NAS?

Both Synology Container Manager and QNAP Container Station have their own Docker UIs. Portainer adds value because:

• Compose stack management: Portainer's Stacks view is the cleanest interface for managing multi-container applications defined in docker-compose.yml files. Synology Container Manager's Compose support (Projects) is improving but less mature. QNAP Container Station's Application view is functional but can be unintuitive for complex stacks
• Platform-agnostic skills: Portainer works identically on Synology, QNAP, or any Linux machine. Skills transfer between platforms
• Environment variable management: Portainer provides a clean interface for setting and editing environment variables for each stack. Cleaner than editing .env files via SSH
• Container health monitoring: At-a-glance view of running containers, CPU/RAM usage, logs, and restart history

Step 1: Install Portainer CE

Portainer is itself a Docker container. Bootstrap it with Docker on the command line (SSH into your NAS) or via your NAS Docker UI:

docker volume create portainer_data

docker run -d \
  -p 8000:8000 \
  -p 9443:9443 \
  --name portainer \
  --restart=always \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v portainer_data:/data \
  portainer/portainer-ce:latest

On Synology, SSH in with admin credentials: ssh admin@[NAS-IP]. On QNAP, use SSH via QTS Settings → Network → SSH. The /var/run/docker.sock mount gives Portainer access to the Docker daemon. This is how it can manage all containers on the host.

After deployment, access Portainer at https://[NAS-IP]:9443. On first access, create an admin password. Connect to the local Docker environment when prompted.

Step 2: Understanding Docker Compose Files

A Docker Compose file (docker-compose.yml) defines one or more containers as a stack. Their images, ports, volumes, environment variables, and inter-container networking. Key concepts:

Services: Each application component is a service. A typical Nextcloud stack has two services: app (Nextcloud) and db (MariaDB).

Volumes: Mount points that persist data between container restarts. Always define volumes for any data you want to keep. Container filesystems are ephemeral. Example: - ./config:/config mounts the config folder in the current directory to /config inside the container.

Environment variables: Configuration passed to containers at runtime. Database passwords, admin usernames, domain names. Sensitive values should be in a .env file referenced in the Compose file, not hardcoded.

Networks: By default, all services in a Compose file share a network and can reach each other by service name. A Nextcloud container can connect to its MariaDB at hostname db because they are in the same Compose network.

Restart policy: Always include restart: unless-stopped for services you want to survive NAS reboots automatically.

Step 3: Deploy a Stack via Portainer

To deploy an application as a Compose stack in Portainer:

1. In Portainer, go to Stacks → Add Stack
2. Give the stack a name (e.g. nextcloud)
3. In the web editor, paste your docker-compose.yml content
4. Under Environment variables, add any variables your Compose file references (database passwords, domain names, etc.). These are passed as a .env file to Compose
5. Click Deploy the stack

Portainer pulls the images, creates networks and volumes, and starts the containers. The stack appears in the Stacks list with running/stopped status for each container. Click the stack name to see individual container status, logs, and stats.

To update a stack (e.g. after pulling a new image version): go to the stack in Portainer, click Pull and redeploy. Portainer pulls the latest images and recreates the containers, preserving your volumes.

Step 4: Volumes, Paths, and Bind Mounts

The most common issue with containers on NAS hardware is incorrect volume paths. Two approaches:

Bind mounts (recommended for NAS): Mount a specific folder on the NAS filesystem into the container. - /volume1/docker/nextcloud/data:/var/www/html maps the NAS path /volume1/docker/nextcloud/data to /var/www/html inside the container. You can browse and access these files from your NAS file manager.

Named volumes: Docker manages the storage location internally. Data is accessible only through Docker commands. Less convenient for NAS use since you cannot browse the files through your NAS UI.

For NAS deployments, use bind mounts with NAS paths. This means your application data is stored in visible, accessible NAS folders. You can include them in NAS backup jobs and inspect them without Docker commands.

🇦🇺 Australian Users: NAS Recommendations for Docker

Minimum recommended NAS for running Portainer + 3-5 containers: QNAP TS-464 (~$989) or Synology DS423+ (~$980). Both have Intel CPUs and 8GB RAM. This headroom allows Portainer, a reverse proxy (NGINX Proxy Manager), Nextcloud with MariaDB, and 2-3 lightweight containers (Vaultwarden, Pi-hole, Home Assistant) to coexist comfortably.

ARM NAS models (TS-233, DS223) run Docker but with meaningful constraints: 4GB RAM limits how many containers run simultaneously, and ARM CPU performance makes some ML-heavy containers (Immich ML, Nextcloud Recognize) impractically slow. For homelab Docker use, an Intel NAS with 8GB+ RAM is strongly recommended.

See the QNAP Container Station guide for QNAP-specific Docker setup, or the NAS Sizing Wizard to estimate resource requirements for your planned container stack.

Related reading: our NAS buyer's guide.

Related reading: our NAS explainer.