Templates & Domains
1. Installing a Template
Go to the Templates tab on a device and click + Install.
The template catalog opens. Browse or search by name, tag, or description. Select a template to see its full description.
Review the template details and optionally set an instance name. Click Install.
The agent pulls the Docker image and starts the container. This takes 1–3 minutes depending on connection speed. Desired state shows installed, observed state updates as the agent reports in.
Once the container is up and healthy, the instance shows Running.
Use the configure icon on the instance row to edit settings (data directory, passwords, etc.) after installation. Saving recreates the container with the new values.
2. Adding a Domain
Go to the Hosting tab and click + Add domain. The wizard walks through four steps: Domain → Point DNS → Issue cert → Done.
Step 1 — Enter the domain. Type your domain and an optional SSL contact email, then click Add & continue.
Step 2 — Point DNS. Create an A record at your registrar:
| Field | Value |
|---|---|
| Type | A |
| Name | your domain |
| Value | gateway IP shown in wizard |
| TTL | 300 (or auto) |
Click Verify DNS. You can close the dialog and return later.
Step 3 — Issue cert. Once DNS is verified, Caddy requests a Let's Encrypt certificate. This takes 30–90 seconds.
Done. The wizard confirms Certificate active.
After the wizard closes, the domain appears in the Hosting tab. Use the bind controls to route traffic to a Template instance or a Local port. Click Bind to activate.
3. Connecting a Domain to a Template
Once a domain is verified and a template is running, go to the Hosting tab. The domain row shows a Template instance bind control. Open the dropdown and select the running template instance.
If your SSH key has a passphrase, a prompt appears.
Click Bind. The agent runs domain bind on the device and Caddy routes the domain to the template's web service.
The domain row updates to OBSERVED: BOUND and shows which service it is routed to.
4. Custom Docker Compose
To run an arbitrary container, search for Custom Docker Composition in the template catalog and select it.
The configure dialog opens. Paste your docker-compose.yml into the Docker Compose field. Use named volumes for persistence — bind mounts and host port mappings are not permitted. Reference environment variables with ${VAR} syntax.
Scroll down to set the Primary service (the service name whose HTTP port is exposed) and Primary port (the in-container port). Click Save & recreate.
