Xcloud Docker Deploy

xCloud Docker Deploy v1.4.1

Built for xCloud Custom Docker deployments by Asif2BD · GitHub · Latest Release · xCloud Agent Skills

Start Here

This is a deployment-preparation skill. Before it inspects a project, edits files, recommends production changes, asks for API tokens, or routes to live xCloud API skills, the agent must confirm the exact action with the user.

Use this safe opening:

I can do read-only analysis first, or I can generate deployment files after your confirmation. I will not push, deploy, collect tokens, or call live xCloud APIs unless you explicitly approve that exact step.

Use normal human language. Ask:

This is my project. I want to deploy it on xCloud. Please inspect it, decide whether it should use xCloud native deployment or Docker, generate the proper Dockerfile, Docker image workflow, docker-compose.yml, .env.example, and give me the exact xCloud deployment steps.

If you already have a compose file, ask:

Please make this docker-compose.yml work on xCloud. Fix anything xCloud does not support, especially Docker build steps, proxy services, and host ports 80/443.

The agent should then:

1. Ask whether to perform read-only analysis or generate files.
2. Detect the stack after the user confirms project inspection.
3. Choose native xCloud deployment or Custom Docker.
4. Generate or fix Docker files only after explicit confirmation.
5. Explain the exact xCloud UI/API steps in simple language.
6. Before any production-impacting step, recommend a branch, backup, and staging/test deployment.

xCloud port-safety notice: final compose output must never bind host port 80 or 443. If an app listens on container port 80, use 3080:80 and set xCloud's exposed/primary port to 3080.

Adapt any docker-compose.yml to work with xCloud — a git-push Docker deployment platform.

How xCloud Works

git push → xCloud runs: docker-compose pull && docker-compose up -d

xCloud never runs docker build. Images must be pre-built in a public registry. SSL, reverse proxy, and domain routing are handled by xCloud — your stack must not duplicate them.

Read references/xcloud-constraints.md for the full ruleset before making changes.

Current xCloud API + Agent Skills Context

xCloud now publishes API-backed agent skills for operational work:

Use this skill for project detection, Dockerfile/compose generation, GHCR CI, and xCloud Custom Docker readiness. Use the official API skills when the user asks to inspect or mutate live xCloud resources.

API Token Flow

This Docker deploy skill can work alongside the official xCloud API skills when those skills/tools are available. If a task needs live xCloud data or live actions:

1. Ask whether the user wants live xCloud API help.
2. State the exact live operation before requesting a token, such as "list servers" or "read deployment logs".
3. Ask for a least-privilege, short-lived token where possible.
4. If no token is available, ask the user to provide or configure a private XCLOUD_API_TOKEN.
5. Never print, store, log, reuse, or commit the token. Use it only for the approved action.
6. Use the official xCloud API skills for live operations:
   • xcloud:servers for server capacity, PHP, databases, cron, firewall, sudo users, WordPress provisioning
   • xcloud:sites for site status, domains, backups, cache, SSH, git, deployment logs
   • xcloud:wordpress for WordPress plugins, themes, updates, debug, magic login, vulnerabilities, PageSpeed
   • xcloud:ssl for certificates
   • xcloud:account for current user, API tokens, Cloudflare integrations, blueprints, health
7. Keep Docker generation local and deterministic; use the API only for live xCloud account/server/site actions.

Production Safety Gate

Before recommending git push, deployment webhooks, migration commands, cache clears, DNS changes, SSL changes, or live API actions:

1. Confirm the target environment: staging or production.
2. Ask whether a backup exists for production sites/databases.
3. Prefer a feature branch or pull request for generated files.
4. Show the generated Dockerfile, compose file, workflow, and environment variable list before the user applies them.
5. Do not trigger deployment webhooks or live API mutations without a separate final confirmation.

Phase 0 — Detect Project Type First

Before anything else, scan the project directory for these files:

Read DETECT.md for full detection rules. Quick routing:

See references/xcloud-deploy-paths.md for the Native vs Docker decision guide.

Step 1 — Detect Which Scenarios Apply

Inspect the provided docker-compose.yml:

A compose file can trigger multiple scenarios simultaneously (handle A first, then B).

Scenario A — Build-from-Source

Read references/scenario-build-source.md for full details.

What to do:

1. Remove build: directive from compose
2. Replace image: with ghcr.io/OWNER/REPO:latest
3. Generate .github/workflows/docker-build.yml using assets/github-actions-build.yml template
4. Generate .env.example from all ${VAR} references

Deliverables:

• Modified docker-compose.yml
• .github/workflows/docker-build.yml
• .env.example
• xCloud Deploy Steps (see Output Format)

Scenario B — Proxy Conflict / Multi-Port / External Config

Read references/scenario-proxy-conflict.md for full details.

What to do:

1. Remove Caddy/Traefik/nginx-proxy service entirely
2. Remove SSL labels and multi-port ports: from app services (replace with expose:)
3. Add nginx-router service with inline config via configs: block
4. Expose single port (default: 3080) for xCloud to proxy

Deliverables:

• Modified docker-compose.yml with nginx-router + configs: block
• .env.example
• xCloud Deploy Steps

Scenario C — Multi-Service Build

Read references/scenario-multi-service-build.md for full details.

When multiple services have build: directives (separate frontend + backend + worker):

What to do:

1. For each service with build:, create a separate GHCR image path
2. Generate a matrix GitHub Actions workflow that builds all images in parallel
3. Update compose to use all GHCR image references

Deliverables:

• Modified docker-compose.yml (all build: removed)
• .github/workflows/docker-build.yml (matrix strategy)
• .env.example

Output Format

Always produce complete, copy-paste-ready output:

## Modified docker-compose.yml
[full file]

## .github/workflows/docker-build.yml  (Scenario A/C only)
[full file]

## .env.example
[full file]

## xCloud Deploy Steps
1. Push repo to GitHub
2. (Scenario A/C) Wait for GitHub Actions to build image — check Actions tab
3. Server → New Site → Custom Docker → connect repo
4. Exposed port: [PORT]
5. Env vars to add: [list from .env.example]
6. Deploy

Rules

• Never include build: in the final compose — xCloud silently ignores it
• Never bind host port 80 or 443 in final compose — xCloud's Nginx/SSL layer already owns them
• If the app listens on container port 80, output 3080:80 and tell xCloud to use exposed/primary port 3080
• If you see 80:80, treat it as invalid for xCloud and rewrite it to 3080:80
• Never expose database ports to host (remove "5432:5432" — use expose: internally)
• Never include Caddy, Traefik, nginx-proxy, or Let's Encrypt config
• Always preserve environment:, volumes:, healthcheck:, worker/sidecar services
• Always use expose: (internal) not ports: (host) for services behind nginx-router
• Always report the xCloud exposed/primary port as the host-side port from the single allowed web mapping
• WebSockets? Add upgrade headers to nginx config (see proxy-conflict reference)
• configs.content: inline syntax requires Docker Compose v2.23+ — use heredoc command: alternative if uncertain

Port Normalization

xCloud receives public traffic on 80/443 through its own Nginx and SSL layer. Docker compose should expose one high host port for xCloud to proxy into:

User → xCloud Nginx 80/443 → Docker host port >=1024 → container port

Normalize ports before final output:

Final validation: no ports: mapping may start with 80: or 443:.

Examples

See examples/ for ready-made transformations:

• examples/rybbit-analytics.md — Caddy + multi-port app (Scenario B)
• examples/custom-app-dockerfile.md — build-from-source (Scenario A)
• examples/fullstack-monorepo.md — multi-service build (Scenario C)