Create a Compose App from YAML

Published · Last updated: May 2026 · 3 min read

Who this is for

Users who have an existing docker-compose.yml and want to run it on a server managed by CloudAIPilot.

Prerequisites

Server is running with SSH connectivity and Docker + Docker Compose installed.
You have a valid docker-compose.yml you want to deploy.

What a Compose App Is

A Compose App runs multiple Docker containers defined in a docker-compose.yml file as a single managed unit. This is suitable for applications with multiple services — for example, a web app container + a database container + a cache container.

docker-compose.yml is stored encrypted in CloudAIPilot and written to the server at deploy time.

How to Create a Compose App

Go to Servers → open the server.
Click the Apps tab → + Create App.
Select Compose App → Enter YAML manually.
Fill in the form:

Field	Description
App name	Internal label in CloudAIPilot
Compose YAML	Paste your full `docker-compose.yml` content
Port mappings	For each service port you want to expose: container port, host port, protocol, and service name
Environment variables	Key-value pairs to inject into the compose environment

Toggle Deploy now ON to start immediately.
Click Create.

Example Compose YAML

version: "3.9"
services:
  web:
    image: nginx:1.27
    ports:
      - "8080:80"
  app:
    image: myapp:latest
    environment:
      - DATABASE_URL=postgres://user:pass@db:5432/mydb
    depends_on:
      - db
  db:
    image: postgres:15
    volumes:
      - db_data:/var/lib/postgresql/data
    environment:
      - POSTGRES_USER=user
      - POSTGRES_PASSWORD=pass
      - POSTGRES_DB=mydb

volumes:
  db_data:

Port Mappings

For each service port in your compose file that you want CloudAIPilot to track and register:

Container port: the port inside the service container
Host port: the port on the server (must not conflict with other apps)
Protocol: tcp (default) or udp
Service name: the service in the compose file (e.g., web, app)

These are used for port conflict detection and firewall rule management.

Security Note: Compose YAML Encryption

Your docker-compose.yml may contain sensitive values (database passwords, API keys). CloudAIPilot encrypts the YAML content with AES-256-GCM before storing it. Environment variables should be passed via the Environment Variables section for better separation.

What Happens After Creation

CloudAIPilot SSH-es to the server.
Writes the compose YAML to a project directory.
Runs docker compose up -d.
Monitors service statuses.

The app appears in the Apps tab with status pending → running.

What Success Looks Like

App status shows running. All services defined in the compose file are up. Accessing any exposed port on the server returns the expected response.

Common Issues and Fixes

Issue	Likely cause	Fix
Compose parse error	Invalid YAML syntax	Validate YAML at yaml.org/validate before pasting.
Service fails to start	Image pull failed, env var missing, or port conflict	Check Logs tab — see KB-04-12: App Logs.
"PORT_CONFLICT"	Host port already in use	Check Port Mapping conflicts — see KB-04-14: Port Mapping.
Compose app shows "stopped"	All containers exited	Check logs. Common causes: missing env vars, bad config.