deploy-api
Workflow Reference

How it works

Each deployment is a deployments/{client_id}/{deployment_id}/ directory containing Terraform files generated from the database.

The core loop is: edit the database → regenerate files (Get) → apply. The database is the source of truth; Terraform files are always regeneratable.

Apply on an already-applied deployment is a safe no-op that also re-syncs IPs from DNS.

Workflows

Create a new VM
1
+ VM Fill in provider, region, plan, OS, tags → Create
2
Get Generates providers.tf, inventory.tf, cloud-init files, runs terraform init
3
Plan Optional — review what will be created before committing
4
Apply ▶ Provisions the VM. Async — output streams as it runs.
Update a VM
1
Click the pencil on the VM row → edit fields → Update
2
Get Regenerates config with updated values
!
Plan Run Plan before Apply. Some attribute changes force a VM replacement (destroy + recreate). The Apply button turns red if replacements are detected.
4
Apply ▶ Applies the change. If the button is red, a confirmation listing affected VMs is required.
Get → Plan → edit → Get → Plan → Apply is always safe to repeat as many times as needed.
Remove a VM from a deployment
1
Click the trash on the VM row — removes from the database and releases its IPs back to the pool
2
Get Regenerates inventory.tf without the deleted VM
3
Plan Confirm the VM appears in the destroy list
4
Apply ▶ Destroys the cloud resource
Tear down a deployment
Destroy recoverable

Runs terraform destroy. Deprovisions all cloud resources. Database records and the deployment directory are kept — you can re-apply later.

Purge irreversible

Destroy + deletes all database records + removes the deployment directory. Nothing remains. Requires typing the deployment ID to confirm.

Notes

· Get is idempotent. Run it any time to regenerate files from current database state.
· Red Apply button means Plan detected VM replacements for this deployment. Investigate the reason (cannot update usually means an immutable attribute changed — common cause is a new catalog template in VCD). Confirm by typing the deployment ID.
· VM names are auto-generated after creation: vm{id}-{provider_id}-{region_prefix}. They cannot be changed.
· VCD IPs are pre-allocated from the pool at VM creation. DigitalOcean / Vultr IPs are unknown until after apply and are resolved from DNS.
· Tags are plain strings in two formats: flag (role/label) and key:value (used as Ansible variables). Click a tag chip to filter by it.
· ansible-inventory returns the current Ansible inventory in INI format, suitable for use with -i.
deploy-api workflow reference