Create a Container App from an Image

Published · Last updated: May 2026 · 4 min read

Who this is for

Users who want to run a pre-built Docker image (from Docker Hub, GitHub Container Registry, or any registry) on a server managed by CloudAIPilot.

Server is running with SSH connectivity and Docker installed.
You know the Docker image reference (e.g., nginx:1.27, myuser/myapp:latest).
If using a private registry: the server can authenticate to it (see note on private registry auth below).

Field	Description	Example
App name	Internal label in CloudAIPilot	`my-api`
Image reference	Docker image + tag	`nginx:1.27` or `ghcr.io/user/myapp:v2`
Host port	Port on the server to expose	`8080`
Container port	Port the app listens on inside the container	`80`
Health path	HTTP path for healthcheck (optional)	`/health`
Restart policy	When to restart the container	`unless-stopped` (default)
Command	Override Docker CMD (optional)
CPU limit	Max CPU cores (optional)	`1.0`
Memory limit	Max RAM in MB (optional)	`512`
Environment variables	Key-value pairs passed to the container	`NODE_ENV=production`

Policy	Behavior
`unless-stopped` (default)	Restarts automatically unless explicitly stopped
`always`	Restarts on any exit, including manual stop
`on-failure`	Restarts only on non-zero exit codes
`no`	Never restarts automatically

Use unless-stopped for most production apps. Use no for one-off jobs.

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

Progress is visible in the Activity Center.

Add a custom domain to expose the app via Nginx — see KB-04-09: App Domains and SSL.
Set up port forwarding rules if direct port access is needed — see KB-04-14: Port Mapping.

If your image is in a private registry, you must authenticate Docker on the server first:

SSH into the server or use the Terminal tab.
Run: docker login ghcr.io -u your-username --password-stdin (then paste your token).
Or for Docker Hub: docker login -u your-username

CloudAIPilot does not yet manage Docker registry credentials directly.

Status	Meaning
`pending`	App created, deploy triggered or queued
`running`	Container is running
`stopped`	Container is stopped (no auto-restart active)
`failed`	Container exited with an error
`deleting`	App is being cleaned up

App status shows running. If you set a host port, curl http://: returns a response from the container.

Issue	Likely cause	Fix
"PORT_CONFLICT" error	Host port already used by another app or site	Use a different host port, or check the Port Check feature.
App status stays "pending"	Docker pull failed or SSH issue	Check Activity Center logs. Verify image name and registry auth.
App status "failed" after deploy	Container exited — app crash	Check logs via the Logs tab — see KB-04-12: App Logs.
"NAME_CONFLICT" error	App name already used on this server	Use a different name.