Skip to main content

Adding an App

diagram

Checklist​

1. Create <appname>/docker-compose.yml​

Connect to traefik-net and add Traefik labels. Use ${COMPOSE_PROJECT_NAME} and ${TRAEFIK_HOST} from .env:

networks:
  traefik-net:
    external: true

services:
  myapp:
    image: example/myapp:latest
    container_name: myapp
    restart: unless-stopped
    networks:
      - traefik-net
    labels:
      - traefik.enable=true
      - traefik.http.routers.${COMPOSE_PROJECT_NAME}.rule=Host(`${COMPOSE_PROJECT_NAME}.${TRAEFIK_HOST}`)
      - traefik.http.routers.${COMPOSE_PROJECT_NAME}.entrypoints=websecure
      - traefik.http.routers.${COMPOSE_PROJECT_NAME}.tls.certresolver=letsencrypt
      - traefik.http.services.${COMPOSE_PROJECT_NAME}.loadbalancer.server.port=8080

2. Create <appname>/.env.example​

TRAEFIK_HOST=ops4life.com
COMPOSE_PROJECT_NAME=<appname>

Add any other app-specific variables that will be stored in Ansible Vault.

3. Store secrets in Ansible Vault​

Add the app's secrets to ansible/secrets.yml. All variables must be prefixed with the app name to prevent collisions (e.g., myapp_db_pass).

To edit the encrypted vault:

ansible-vault edit ansible/secrets.yml

Alternatively, use the helper script:

./scripts/vault-set.sh KEY VALUE

4. Update the provisioning playbook​

Add a task to ansible/playbook.yml under §6 "Write all app .env files" to generate the app's .env from your vault variables:

    - name: Write myapp/.env
      ansible.builtin.copy:
        dest: "{{ repo_dest }}/myapp/.env"
        mode: "0600"
        content: |
          TRAEFIK_HOST={{ traefik_host }}
          COMPOSE_PROJECT_NAME=myapp
          MYAPP_SECRET={{ myapp_secret }}

Then add the deployment task to Section §7 "Deploy apps in order" using the unified HA deployment wrapper:

    - name: Deploy myapp (HA wrapper)
      ansible.builtin.command: bash scripts/deploy-app.sh "{{ repo_dest }}/myapp"
      args:
        chdir: "{{ repo_dest }}"
      tags: [deploy, myapp]

Adding it to Section §7 ensures proper sequencing, zero-downtime Blue-Green swaps, and synchronization with configure/routing steps. Public apps are also deployed automatically via CI/CD.

5. Add a Kuma monitor​

Instead of manual SQL, add the monitor definition to scripts/configure-kuma.sh. This ensures the monitor is recreated correctly during provisioning.

# In scripts/configure-kuma.sh
upsert_monitor "MyApp" "https://myapp.${TRAEFIK_HOST}"

6. Update DNS​

DNS is managed via Terraform in the terraform/ directory. Add the new subdomain to terraform/main.tf if it's not covered by a wildcard.

7. Update the docs​

Add a row to the Apps table.