templating (cloud-init, ansible, compose) support

Author: terion-name

docs/.vitepress/config.mts

@@ -73,6 +73,7 @@ export default defineConfig({
           { text: "OpenClaw", link: "/guides/openclaw" },
           { text: "Hermes", link: "/guides/hermes" },
           { text: "VSCodium Web IDE", link: "/guides/vscode" },
+          { text: "Templating Containers with trm launch", link: "/guides/templating" },
           { text: "Isolated Docker Compose deployments", link: "/guides/compose" },
           { text: "Dokploy", link: "/guides/dokploy" },
           { text: "Coolify", link: "/guides/coolify" },

docs/getting-started/creating-first-instance.md

@@ -26,7 +26,7 @@ You can choose whether you want to work through the browser or the terminal. Bot
 If you prefer the terminal, you can create the exact same container in one command. SSH into your Terrarium host and run:
 
 ```bash
-lxc launch ubuntu:24.04 my-first-app
+trm launch ubuntu:24.04 my-first-app
 ```
 
 *(By default, Terrarium automatically applies its secure container profile, which puts the container on the private `terrarium-ovn` network and gives it its own isolated ZFS storage.)*
@@ -43,7 +43,7 @@ For this example, let's just run a tiny, temporary web server.
 
 **From the CLI:**
 ```bash
-lxc exec my-first-app -- bash
+trm exec my-first-app
 ```
 
 Once you are inside the container's shell, run this command to start a simple Python web server on port `8080`:
@@ -82,6 +82,12 @@ On the Terrarium host terminal (not inside the container), run:
 lxc config set my-first-app user.proxy "https://my-app.example.com:8080"
 ```
 
+You can also set the route during launch:
+
+```bash
+trm launch ubuntu:24.04 my-first-app --proxy https://my-app.example.com:8080
+```
+
 ## 4. Applying the Change
 
 Terrarium scans your containers for new proxy labels automatically every 60 seconds. If you don't want to wait a minute for your new site to come online, you can force it to sync immediately.

docs/guides/README.md

@@ -19,7 +19,8 @@ You can run databases, internal APIs, and experimental AI agents without worryin
 - **[VSCodium Web IDE](vscode.md):** The absolute best way to code in the cloud. Spin up a browser-based editor that is completely isolated and secured by SSO.
 - **[OpenClaw](openclaw.md):** Give the powerful autonomous AI agent a safe, disposable sandbox to execute code in.
 - **[Hermes](hermes.md):** Run agent-driven background services and expose only the user interface to the web.
+- **[Templating Containers with `trm launch`](templating.md):** Use Ansible, Galaxy roles, Docker Compose, variables, and proxy labels to launch ready-to-use containers in one command.
 - **[Docker Compose Stacks](compose.md):** The cleanest way to run multi-container apps (like a web server + Postgres + Redis) without making a mess of your host machine.
 - **[Dokploy](dokploy.md):** Turn your Terrarium containers into an automated, UI-driven deployment platform (like Heroku or Vercel).
 - **[Coolify](coolify.md):** Another excellent, self-hosted Heroku alternative that runs perfectly inside a single Terrarium LXC.
-- **[Protecting Services with OIDC](auth-protection.md):** The magic label that forces users to log in before they can see your published web apps.
+- **[Protecting Services with OIDC](auth-protection.md):** The magic label that forces users to log in before they can see your published web apps.

docs/guides/index.md

@@ -19,7 +19,8 @@ You can run databases, internal APIs, and experimental AI agents without worryin
 - **[VSCodium Web IDE](vscode.md):** The absolute best way to code in the cloud. Spin up a browser-based editor that is completely isolated and secured by SSO.
 - **[OpenClaw](openclaw.md):** Give the powerful autonomous AI agent a safe, disposable sandbox to execute code in.
 - **[Hermes](hermes.md):** Run agent-driven background services and expose only the user interface to the web.
+- **[Templating Containers with `trm launch`](templating.md):** Use Ansible, Galaxy roles, Docker Compose, variables, and proxy labels to launch ready-to-use containers in one command.
 - **[Docker Compose Stacks](compose.md):** The cleanest way to run multi-container apps (like a web server + Postgres + Redis) without making a mess of your host machine.
 - **[Dokploy](dokploy.md):** Turn your Terrarium containers into an automated, UI-driven deployment platform (like Heroku or Vercel).
 - **[Coolify](coolify.md):** Another excellent, self-hosted Heroku alternative that runs perfectly inside a single Terrarium LXC.
-- **[Protecting Services with OIDC](auth-protection.md):** The magic label that forces users to log in before they can see your published web apps.
+- **[Protecting Services with OIDC](auth-protection.md):** The magic label that forces users to log in before they can see your published web apps.

docs/guides/templating.md

@@ -0,0 +1,292 @@
+# Templating Containers with `trm launch`
+
+`trm launch` is the fastest way to turn a fresh LXD container into a real application environment.
+
+It wraps `lxc launch`, so simple containers still feel familiar. When you add provisioning flags, Terrarium generates a small cloud-init template for the container, embeds or fetches the files you asked for, and runs the setup inside the new instance.
+
+Use it when you want a container to come up already shaped like an app server, agent sandbox, Docker Compose stack, or Ansible-managed machine.
+
+## 1. Start with a Normal Container
+
+The simplest form launches an Ubuntu container with Terrarium's default profile:
+
+```bash
+trm launch ubuntu:24.04 web-01
+```
+
+You can still pass normal LXD sizing options:
+
+```bash
+trm launch ubuntu:24.04 web-01 --disk 40G --memory 4G --cpu 2
+```
+
+For development containers, use the `dev` profile. It includes Terrarium's Docker-friendly defaults and passwordless sudo for the normal `terrarium` user:
+
+```bash
+trm launch ubuntu:24.04 devbox --profile dev
+```
+
+## 2. Run an Ansible Playbook
+
+If you already have an Ansible playbook, pass it directly:
+
+```bash
+trm launch ubuntu:24.04 web-01 --playbook ./site.yml
+```
+
+Terrarium embeds the local playbook into generated cloud-init, installs Ansible inside the container, and runs:
+
+```bash
+ansible-playbook -i localhost, -c local site.yml
+```
+
+A small real-world playbook might install Nginx and publish a static page:
+
+```yaml
+---
+- hosts: localhost
+  connection: local
+  become: true
+  tasks:
+    - name: Install Nginx
+      ansible.builtin.apt:
+        name: nginx
+        state: present
+        update_cache: true
+
+    - name: Write landing page
+      ansible.builtin.copy:
+        dest: /var/www/html/index.html
+        content: "{{ app_name }} is live\n"
+```
+
+Launch it with a variable and a public route:
+
+```bash
+trm launch ubuntu:24.04 landing-01 \
+  --playbook ./site.yml \
+  --var app_name=Landing \
+  --proxy https://landing.example.com:80
+```
+
+## 3. Add Galaxy Requirements
+
+If your playbook depends on Galaxy roles or collections, pass the requirements file too:
+
+```bash
+trm launch ubuntu:24.04 app-01 \
+  --requirements ./requirements.yml \
+  --playbook ./site.yml
+```
+
+Requirements can contain `roles:`, `collections:`, or both. Terrarium installs them before running the playbook.
+
+For a quick role-only container, use `--role`:
+
+```bash
+trm launch ubuntu:24.04 docker-01 --role geerlingguy.docker
+```
+
+You can repeat `--role` when you want several roles:
+
+```bash
+trm launch ubuntu:24.04 ops-01 \
+  --role geerlingguy.security \
+  --role geerlingguy.nginx
+```
+
+## 4. Run Docker Compose
+
+For Compose apps, pass one or more Compose files:
+
+```bash
+trm launch ubuntu:24.04 my-stack \
+  --profile dev \
+  --docker-compose ./docker-compose.yml
+```
+
+Terrarium installs Docker inside the container, starts the Docker service, and runs:
+
+```bash
+docker compose -f docker-compose.yml up -d
+```
+
+Here is a simple app stack:
+
+```yaml
+services:
+  web:
+    image: nginx:alpine
+    ports:
+      - "8080:80"
+```
+
+Publish it during launch:
+
+```bash
+trm launch ubuntu:24.04 nginx-stack \
+  --profile dev \
+  --docker-compose ./docker-compose.yml \
+  --proxy https://nginx.example.com:8080
+```
+
+Remember that Compose ports are still inside the LXD container. Terrarium routes public traffic to the container port you put in the `--proxy` route.
+
+## 5. Use Variables
+
+Variables keep the same template reusable across staging, production, and one-off test containers.
+
+Pass variables inline:
+
+```bash
+trm launch ubuntu:24.04 app-01 \
+  --playbook ./site.yml \
+  --var APP_NAME=hello \
+  --var APP_PORT=8080
+```
+
+Or keep them in a dotenv file:
+
+```dotenv
+APP_NAME=hello
+APP_PORT=8080
+POSTGRES_DB=app
+```
+
+Then launch with:
+
+```bash
+trm launch ubuntu:24.04 app-01 \
+  --vars ./app.env \
+  --playbook ./site.yml \
+  --docker-compose ./docker-compose.yml
+```
+
+Variables are made available in three places:
+
+- As shell environment variables for generated provisioning commands.
+- As Ansible extra vars through `--extra-vars`.
+- As Docker Compose variables through `--env-file`.
+
+Inline values override dotenv files:
+
+```bash
+trm launch ubuntu:24.04 app-staging \
+  --vars ./app.env \
+  --var APP_NAME=staging \
+  --docker-compose ./docker-compose.yml
+```
+
+The dotenv parser supports normal `KEY=value` lines, quoted values, `export KEY=value`, blank lines, and comments. Variable names must use shell-safe names such as `APP_NAME`, `POSTGRES_DB`, or `PORT_8080`.
+
+## 6. Fetch Templates from Git
+
+Local files are embedded into cloud-init. Git assets are cloned by the new container during first boot.
+
+Use this format:
+
+```text
+git+https://github.com/org/repo.git//path/inside/repo.yml?ref=v1.0.0
+```
+
+For example:
+
+```bash
+trm launch ubuntu:24.04 app-01 \
+  --requirements git+https://github.com/example/infra.git//ansible/requirements.yml?ref=v1.2.0 \
+  --playbook git+https://github.com/example/infra.git//ansible/site.yml?ref=v1.2.0
+```
+
+Compose files work the same way:
+
+```bash
+trm launch ubuntu:24.04 plausible \
+  --profile dev \
+  --vars ./plausible.env \
+  --docker-compose git+https://github.com/example/stacks.git//plausible/docker-compose.yml?ref=main \
+  --proxy https://analytics.example.com:8000@auth:admins
+```
+
+Pin `ref` to a tag or commit when you want repeatable launches.
+
+## 7. Combine Multiple Templates
+
+You can combine the provisioning shortcuts. Terrarium runs them in this order:
+
+1. Install packages needed for provisioning.
+2. Clone Git assets.
+3. Install Galaxy requirements.
+4. Install and run Galaxy roles.
+5. Run Ansible playbooks.
+6. Start Docker and run Compose stacks.
+
+A practical full launch might look like this:
+
+```bash
+trm launch ubuntu:24.04 customer-portal \
+  --profile dev \
+  --disk 80G \
+  --memory 6G \
+  --cpu 4 \
+  --vars ./portal.env \
+  --var APP_ENV=production \
+  --requirements ./ansible/requirements.yml \
+  --playbook ./ansible/base.yml \
+  --playbook ./ansible/hardening.yml \
+  --docker-compose ./compose/portal.yml \
+  --docker-compose ./compose/worker.yml \
+  --proxy https://portal.example.com:8080@auth:admins \
+  --proxy https://api.example.com:8081@auth:admins
+```
+
+This creates one isolated container, prepares it with Ansible, starts two Compose stacks, and publishes two authenticated HTTPS routes.
+
+## 8. Use Raw Cloud-Init When You Need Full Control
+
+If you already have a complete cloud-init file, pass it directly:
+
+```bash
+trm launch ubuntu:24.04 raw-01 --cloud-init ./user-data.yml
+```
+
+Raw cloud-init replaces Terrarium's generated template. Because of that, it cannot be combined with `--requirements`, `--playbook`, `--role`, `--docker-compose`, `--var`, or `--vars`.
+
+You can still combine it with normal launch options and proxy labels:
+
+```bash
+trm launch ubuntu:24.04 raw-01 \
+  --cloud-init ./user-data.yml \
+  --disk 40G \
+  --proxy https://raw.example.com:8080
+```
+
+## 9. Debugging a Launch
+
+Cloud-init runs after LXD reports that the container was created. If the instance exists but your app is not ready yet, open a shell:
+
+```bash
+trm exec app-01
+```
+
+Useful logs inside the container:
+
+```bash
+sudo cloud-init status --long
+sudo tail -n 200 /var/log/cloud-init-output.log
+sudo journalctl -u docker --no-pager -n 100
+```
+
+For Compose apps:
+
+```bash
+sudo docker compose ps
+sudo docker compose logs --tail=100
+```
+
+If the app is running but the public route does not respond, check that the service listens on `0.0.0.0` inside the container and then sync the proxy from the host:
+
+```bash
+terrariumctl proxy sync
+```
+
+For the full route label grammar, including authenticated routes and wildcard domains, see [Domains and Authentication](../getting-started/domains-and-auth.md#published-app-route-labels).