Compose Pre-Deploy Check

Validate docker-compose.yml and Docker build configuration before deploying to a Phala Cloud CVM.

When to Run

Full Checklist

Run every check in order. Stop and report the first failure. Mark each as PASS/FAIL in output.

1. Single-File Constraint

Phala Cloud accepts one docker-compose.yml — no external file references.

FAIL if any of these appear:

PASS if:

• •build with inline Dockerfile (multi-line dockerfile_inline) — allowed but check Step 2
• •image references only — preferred pattern
• •Named volumes — fine (data:/var/lib/db)

Inline build is allowed but discouraged for large builds. The entire inline content counts toward the 200KB size limit.

2. File Size

Combined size of docker_compose_file + pre_launch_script must be ≤ 200KB (200 × 1024 = 204,800 bytes).

Measure in UTF-8 bytes, not characters (CJK characters = 3 bytes each).

If close to limit: Inline Dockerfiles and long scripts are the usual culprits. Move the Dockerfile out — pre-build and push the image to a registry, then reference by image: tag.

3. Architecture — amd64 Only

Phala Cloud CVMs run on Intel TDX hardware (x86_64/amd64). ARM images will not work.

Check Dockerfile / build config:

Recommendation: Always build with explicit platform:

docker buildx build --platform linux/amd64 -t myimage:latest .

Or in docker-compose.yml inline build:

services:
  app:
    build:
      dockerfile_inline: |
        FROM --platform=linux/amd64 node:20-slim
        ...

If user builds on Apple Silicon (M1/M2/M3): They MUST use --platform linux/amd64 or docker buildx. Default build produces arm64 images that crash on CVM boot with no obvious error message — serial logs may show exec format errors.

4. Image Accessibility

Every image: in the compose file must be pullable from the CVM at boot time.

Registry credentials go in the env file (phala deploy -e .env), NOT in docker-compose.yml. They are encrypted client-side before transmission.

5. Secrets Leakage

Scan docker-compose.yml for hardcoded secrets. FAIL if any found.

Fix: Move all secrets to the env file and deploy with phala deploy -e .env. Environment variables are encrypted client-side before reaching the API. The docker-compose.yml itself is stored as plaintext in the backend.

Acceptable in compose: variable references like ${DB_PASSWORD} (resolved from env file at runtime).

6. TEE Volume Mount

If the application needs TEE capabilities (key derivation, attestation quotes, TDX info), it must mount the dstack socket.

Check: Does any service have this volume?

volumes:
  - /var/run/dstack.sock:/var/run/dstack.sock

Both sockets are available on the CVM. The dstack SDK tries dstack.sock first, falls back to tappd.sock. But the volume must be mounted for the container to access either.

7. Port and Network Sanity

Quick checks:

• •ports: with host binding (e.g., "8080:80") — fine, CVM maps these
• •network_mode: host — works but unusual for CVM
• •Multiple services exposing same host port — FAIL, port conflict at runtime

Output Format

After running all checks, report:

## Compose Pre-Deploy Check

| # | Check | Result | Detail |
|---|-------|--------|--------|
| 1 | Single-file constraint | PASS | No external file references |
| 2 | File size | PASS | 12KB (limit: 200KB) |
| 3 | Architecture | WARN | No --platform specified, verify build host is amd64 |
| 4 | Image accessibility | PASS | All images are public Docker Hub |
| 5 | Secrets leakage | FAIL | Line 15: hardcoded `PRIVATE_KEY=0x...` |
| 6 | TEE volume mount | PASS | dstack.sock mounted on service "app" |
| 7 | Port/network | PASS | No conflicts |

### Actions Required
- **[FAIL] Secrets leakage:** Move `PRIVATE_KEY` to env file, use `${PRIVATE_KEY}` reference in compose

Only list Actions Required for FAIL and WARN items. Skip if all PASS.

Gotchas