Adding a Stack

Adding a Stack

How to add a new Docker stack to the NAS.

Steps

1. Create the Stack Directory

Create a new folder at the repo root named after your stack:

my-new-stack/
├── docker-compose.yml
└── .env              (optional — if you need secrets/variables)

2. Write the Compose File

Standard docker-compose.yml — nothing special required. Just follow these conventions:

• Always set container_name — makes logs and management clearer
• Always set restart: always — containers should survive reboots
• Use ${VARIABLE} syntax in compose for values from .env
• Use network assignments appropriate to the service (see below)

services:
  my-app:
    container_name: MyApp
    hostname: myapp
    image: author/my-app:latest
    restart: always
    networks:
      IoT:
        ipv4_address: 10.1.11.XX   # If LAN-accessible
    volumes:
      - ${DOCKERDIR}/myapp:/config
    labels:
      # Traefik
      - traefik.enable=true
      - traefik.http.routers.myapp.rule=Host(`myapp.${DOMAIN}`)
      - traefik.http.routers.myapp.entryPoints=websecure
      # AutoKuma
      - kuma.myapp.http.name=My App
      - kuma.myapp.http.url=https://myapp.${DOMAIN}
      - kuma.myapp.http.parent_name=my-new-stack

3. Add Secrets (if needed)

If your stack needs secrets (API keys, passwords, etc.):

1. Add the secret to Azure KeyVault: az keyvault secret set --vault-name <name> --name "myapp-api-key" --value "the-value"
2. Create a .env file in your stack directory with the token reference:

   MYAPP_API_KEY=#{MYAPP_API_KEY}#

3. Reference it in your compose file: ${MYAPP_API_KEY}

See Adding a Secret for more detail.

4. Networking Decision

Scenario	Network	Notes
Needs direct LAN access	IoT with static IP	Pick an unused IP in 10.1.11.x
Only accessed via Traefik	Stack-specific bridge	Traefik routes to it internally
Needs to talk to other stacks	Add shared network	e.g. media, monitor

5. Commit and Push

git add my-new-stack/
git commit -m "Add my-new-stack"
git push origin main

The deployment pipeline will automatically:

• Replace any #{TOKEN}# values in your .env
• Run docker compose up -d in your new stack directory
• Sync the files to /config/stacks/my-new-stack on the NAS

6. Verify

Check the GitHub Actions run, then verify on the NAS:

• Portainer should show the new containers
• AutoKuma should register any monitoring labels
• Traefik should pick up routing labels automatically

Conventions

• Stack directory names are lowercase, hyphenated (e.g. home-automation)
• One docker-compose.yml per stack — don't nest further
• Persistent data goes in ${DOCKERDIR}/container-name
• Media/storage mounts use ${NAS_MEDIADIR} or direct /mnt/storage paths