deploy-from-template

Deploy from a template

Templates are pre-built Docker images bundled with sensible defaults (resources, ports, env-var slots) for common workloads. One CLI call provisions, configures env, and deploys end-to-end.

Step 1 — auth check

af whoami --json

Unauthenticated? Run the af-setup skill.

Step 2 — find the right template

If the user named one (e.g. "ollama", "postgres"):

af templates list | grep -i <name>
af templates info <templateId>          # shows resources, ports, required env vars

If they didn't:

af templates list                       # browse by category
# Categories: AI_ML, GAME_SERVER, DATABASE, DEVTOOLS, WEB_SERVER, STORAGE

Pick the template id (typically slugged like postgres-16, ollama, comfyui-stable).

Step 3 — collect required env vars

af templates info <id> lists envVars with a required: true flag. Anything required must be passed via --env KEY=VALUE in -y mode — otherwise the deploy throws with a clear list of missing keys.

Typical patterns:

Template type	Common required env
Database (postgres, mysql)	POSTGRES_PASSWORD / MYSQL_ROOT_PASSWORD
AI inference (ollama, vllm)	usually none required (model loaded on first request)
Auth-protected service	ADMIN_PASSWORD, JWT_SECRET, etc.

Platform-injected env vars (generatedAccessKey, generatedSecret, orgId, apiKey) are filled in automatically by the backend — don't pass them.

Step 4 — deploy

af services create \
  --kind template \
  --template <templateId> \
  --name <your-name> \
  --env KEY1=value1 \
  --env KEY2=value2 \
  -y

Adjust resources / region if the template defaults don't fit:

... --cpu 4 --memory 16Gi --storage 100Gi --region us-east

GPU-bearing templates (e.g. ComfyUI, vLLM) — if the template defaults already include a GPU, no flag needed. To override:

... --gpu --gpu-model h100 --gpu-count 1

For confidential / TEE deploys:

... --confidential        # routes to Phala

Composite templates

If af templates info <id> shows components: [...] (a multi-service bundle — e.g. app+db+cache), the CLI refuses with a clear error and points at the dashboard. Composite templates need per-component provider routing that the CLI doesn't prompt for yet. Tell the user to deploy from https://app.alternatefutures.ai and circle back.

Step 5 — verify + connect

af services info <your-name>
af services logs <your-name> --tail 100

The deploy poller prints connection details when ACTIVE:

• Web/API templates → public URL
• Database templates → internal hostname + port (use af ssh or af services link to wire to another service)
• SSH-only templates → ssh root@<ip> -p <port>

Example: Postgres

af services create --kind template --template postgres-16 \
  --name app-db \
  --env POSTGRES_PASSWORD="$(openssl rand -base64 24)" \
  --env POSTGRES_DB=app \
  --memory 4Gi --storage 50Gi \
  -y

Then link your app service to it:

af services link my-app app-db --alias DB
# DB_HOST / DB_PORT / DB_USER / DB_PASSWORD show up in my-app's env
af services deploy my-app   # redeploy to materialize the new env keys

Example: Ollama (GPU)

af services create --kind template --template ollama \
  --name local-llm \
  --gpu --gpu-model h100 \
  --region us-east \
  -y

Pull a model after it's live:

af ssh local-llm --command "ollama pull llama3"

Common pitfalls

• "Template not found" with --template → the id is wrong. Run af templates list and copy the exact id (templates are slug-cased, e.g. postgres-16, not postgres:16).
• "Missing required template env vars" under -y → the template requires keys you didn't pass. The error lists them; add each as --env KEY=VALUE.
• "Composite templates need per-component provider routing" → use the dashboard, not the CLI.
• Server-side resource validation: if the template declares a minMemory higher than your --memory override, the deploy will reject. Check af templates info <id> for floors.