Skip to main content

Template Deployment

Template deployment is the simplest way to deploy a service. Select a template from the catalog, fill in the variables, and the panel handles everything else.

How It Works​

Step 1: Select Template​

Navigate to Deploy > Template Deploy to open the catalog. Browse by category or search by name. Click a template to see its details, including:

  • Description and documentation link
  • Minimum resource requirements (CPU, memory, storage)
  • Security profile
  • Configurable variables

Step 2: Configure Variables​

Each template defines a set of variables. Some are required (like SERVICE_NAME), others are optional with sensible defaults. Common variable types:

TypeBehavior
stringFree-text input field
passwordMasked input, auto-generated if left blank
numberNumeric input with validation
selectDropdown with predefined options
booleanToggle switch

The SERVICE_NAME determines the subdomain: a service named my-app will be accessible at https://my-app.panel.example.com.

Step 3: Resource Validation​

Before deploying, the panel checks that sufficient resources are available:

  • CPU cores >= template minResources.cpu
  • Available memory >= template minResources.memoryMB
  • Available storage >= template minResources.storageMB

If resources are insufficient, the deploy is blocked with a message showing what is needed.

Step 4: Compose Generation​

The panel generates a Docker Compose file from the template spec:

  1. Substitutes variable values into the compose definition
  2. Adds Traefik labels for routing and SSL: 
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.${SERVICE_NAME}.rule=Host(`${SERVICE_NAME}.${PANEL_DOMAIN}`)"
      - "traefik.http.routers.${SERVICE_NAME}.tls.certresolver=letsencrypt"
      - "traefik.http.services.${SERVICE_NAME}.loadbalancer.server.port=${EXPOSE_PORT}"
  3. Adds resource limits based on plan quotas
  4. Connects all services to the aiadminpanel Docker network
  5. Removes any ports: directives (all traffic routes through Traefik)

Step 5: Container Deployment​

The panel executes the deployment:

  1. Creates the Docker Compose project
  2. Pulls container images
  3. Creates volumes for persistent data
  4. Starts containers
  5. Monitors health check endpoint

Progress updates stream to the UI in real time via WebSocket.

Step 6: DNS and SSL​

If Cloudflare DNS integration is configured:

  1. Panel creates an A record for {SERVICE_NAME}.{PANEL_DOMAIN} via Cloudflare API
  2. Traefik detects the new route and provisions an SSL certificate
  3. Service is accessible via HTTPS within seconds

Without Cloudflare, the wildcard DNS record (*.panel.example.com) handles routing automatically.

Step 7: Health Check​

The panel polls the template's health check endpoint until it returns a success response:

healthcheck:
  path: /
  port: 3001
  interval: 30s
  timeout: 10s

Once healthy, the service status changes to Running and the deploy is marked as successful.

Post-Deploy​

After deployment, you can:

  • View logs — real-time container log streaming
  • Start/Stop/Restart — lifecycle management
  • Monitor resources — CPU, memory, and network usage
  • Update variables — reconfigure and redeploy
  • Delete — stops containers, removes volumes, cleans up DNS

Troubleshooting​

Service stuck in "Deploying" state​

Check container logs for startup errors:

docker logs {service-container-name}

Common causes: missing environment variables, port conflicts within the compose file, image pull failures.

Health check failing​

Verify the health check endpoint is correct for the service. Some services take longer to initialize (especially database-backed services that run migrations on first start). The panel will retry health checks for up to 5 minutes before marking a deploy as failed.

SSL certificate not issued​

Ensure DNS resolves to your server. Check Traefik logs for ACME errors:

docker logs aiadminpanel_traefik | grep -i acme