Skip to content

Towlion Platform

Deploy Prompt

towlion/platform

Towlion Platform

towlion/platform

Getting Started
Getting Started
- Home
- Scope
- Tutorial
Architecture
Architecture
Deployment
Deployment
- Pipeline
- Self-Hosting
- Preview Environments
- Deploy Prompt Deploy Prompt
  Table of contents
- Self-Hosted Runners
Project
Project
- Ecosystem
- Governance

Deploy Prompt Template

A reusable Claude Code session prompt for spinning up a new Towlion application deployment. Copy this prompt, replace the placeholders, and paste it into a Claude Code session.

Placeholders

Placeholder	Description	Example
`<app-name>`	Repository name for the new app	`todo-app`
`<your-domain.com>`	Domain or subdomain for the app	`todo.example.com`
`<server-ip>`	IP address of the target server	`203.0.113.42`

Prompt

I want to deploy a new Towlion app called <app-name> to <your-domain.com> on server <server-ip>.

Walk me through these 5 phases:

### Phase 1: Create repository
- Create a new repo from the towlion/app-template GitHub template
- Clone it locally
- Run setup-repo.sh to configure governance (branch protection, labels)

### Phase 2: Build the app
- Implement the application logic in app/main.py
- Add any new dependencies to requirements.txt (at repo root)
- Ensure the /health endpoint returns {"status": "ok"}
- Commit with conventional commit messages (feat:, fix:, etc.)

### Phase 3: Provision server
- Run `bootstrap-server.sh` on a fresh Debian server (installs Docker, creates directories, starts platform services)
- Set up DNS A record: <your-domain.com> -> <server-ip>
- Generate a deploy SSH key pair for the `deploy` user
- Run `verify-server.sh` to confirm the platform is healthy

### Phase 4: Deploy
- SSH to server: create /opt/apps/<app-name>, clone the repo, create deploy/.env from deploy/env.template using credentials from /opt/platform/.env
- Configure GitHub Actions secrets (SERVER_HOST, SERVER_USER, SERVER_SSH_KEY, APP_DOMAIN)
- Push to main to trigger the deploy workflow
- The workflow will: verify .env exists, auto-create the app database, build containers, run migrations, health check, generate Caddyfile, reload Caddy
- Verify with: curl https://<your-domain.com>/health

### Phase 5: Configure CI/CD
- Confirm the deploy.yml workflow runs on push to main
- Confirm the validate.yml workflow runs on PRs
- Test by pushing a small change and watching the Actions tab

Important notes:
- The app-template already includes all deployment fixes (correct migration ordering, __init__.py, PYTHONPATH, alembic -c flag)
- Multi-app mode uses deploy/docker-compose.yml which joins the shared `towlion` network (platform provides postgres, redis, minio, caddy)
- The deploy workflow auto-creates a per-app database (e.g., todo_app_db) — no manual DB setup needed
- Caddyfile is generated by the workflow (not symlinked) with the literal domain and project-prefixed container name
- deploy/.env must exist on the server before the first push — the workflow fails fast if missing
- requirements.txt must be at repo root (not app/) for the Dockerfile build context

See also

Tutorial — step-by-step walkthrough with detailed commands
Deployment — pipeline internals and deploy behavior
Self-Hosting — fork model and infrastructure overview