release-only downloads, autocomplete

Author: terion-labs

.github/workflows/release.yml

@@ -74,8 +74,10 @@ jobs:
 
       - name: Package release bundle
         run: |
+          cp -a ansible release/ansible
+          rm -rf release/ansible/.ansible
           cd release
-          zip -rq "../terrarium-linux-${{ matrix.arch }}.zip" dist
+          zip -rq "../terrarium-linux-${{ matrix.arch }}.zip" dist ansible
 
       - uses: actions/upload-artifact@v4
         with:

.github/workflows/validate.yml

@@ -19,6 +19,7 @@ jobs:
           bun install
           bun run build
           bun run docs:build
+          cd ansible
           for attempt in 1 2 3 4; do
             if ansible-galaxy collection install -r requirements.yml; then
               break
@@ -34,4 +35,6 @@ jobs:
           test -x dist/terrariumctl
           bun run tests/integration/index.ts --help
       - name: Ansible syntax
-        run: ansible-playbook -i ansible/inventory.ini ansible/site.yml --syntax-check
+        run: |
+          cd ansible
+          ansible-playbook -i inventory.ini site.yml --syntax-check

.gitignore

@@ -3,5 +3,6 @@ node_modules/
 bun.lockb
 docs/.vitepress/cache/
 docs/.vitepress/dist/
+ansible/.ansible/
 tests/integration/output/
 tests/integration/.env

ansible.cfg ansible/ansible.cfgansible.cfg renamed to ansible/ansible.cfg

@@ -1,6 +1,6 @@
 [defaults]
-inventory = ansible/inventory.ini
-roles_path = ansible/roles
+inventory = inventory.ini
+roles_path = roles
 collections_path = .ansible/collections:~/.ansible/collections:/usr/share/ansible/collections
 host_key_checking = False
 retry_files_enabled = False

requirements.yml ansible/requirements.ymlrequirements.yml renamed to ansible/requirements.yml

@@ -28,7 +28,7 @@
     - "{{ terrarium_state_dir }}/restore"
     - /usr/local/lib/terrarium
 
-- name: Assert Terrarium compiled binaries are staged in the repo checkout
+- name: Assert Terrarium compiled binaries are staged in the install bundle
   ansible.builtin.stat:
     path: "{{ terrarium_repo_dir }}/dist/terrariumctl"
   register: terrarium_compiled_cli
@@ -75,6 +75,88 @@
       and terrarium_trm_alias.stat.lnk_source == "/usr/local/bin/terrariumctl"
     )
 
+- name: Create shell completion directories
+  ansible.builtin.file:
+    path: "{{ item }}"
+    state: directory
+    mode: "0755"
+  loop:
+    - /usr/share/bash-completion/completions
+    - /usr/local/share/zsh/site-functions
+    - /usr/share/fish/vendor_completions.d
+
+- name: Generate terrariumctl bash completion
+  ansible.builtin.command: /usr/local/bin/terrariumctl completion bash
+  register: terrariumctl_completion_bash
+  changed_when: false
+
+- name: Generate terrariumctl zsh completion
+  ansible.builtin.command: /usr/local/bin/terrariumctl completion zsh
+  register: terrariumctl_completion_zsh
+  changed_when: false
+
+- name: Generate terrariumctl fish completion
+  ansible.builtin.command: /usr/local/bin/terrariumctl completion fish
+  register: terrariumctl_completion_fish
+  changed_when: false
+
+- name: Install terrariumctl bash completion
+  ansible.builtin.copy:
+    content: "{{ terrariumctl_completion_bash.stdout }}\n"
+    dest: /usr/share/bash-completion/completions/terrariumctl
+    mode: "0644"
+
+- name: Install terrariumctl zsh completion
+  ansible.builtin.copy:
+    content: "{{ terrariumctl_completion_zsh.stdout }}\n"
+    dest: /usr/local/share/zsh/site-functions/_terrariumctl
+    mode: "0644"
+
+- name: Install terrariumctl fish completion
+  ansible.builtin.copy:
+    content: "{{ terrariumctl_completion_fish.stdout }}\n"
+    dest: /usr/share/fish/vendor_completions.d/terrariumctl.fish
+    mode: "0644"
+
+- name: Install trm bash completion alias
+  ansible.builtin.file:
+    src: /usr/share/bash-completion/completions/terrariumctl
+    dest: /usr/share/bash-completion/completions/trm
+    state: link
+    force: true
+  when: >-
+    not terrarium_trm_alias.stat.exists
+    or (
+      terrarium_trm_alias.stat.islnk | default(false)
+      and terrarium_trm_alias.stat.lnk_source == "/usr/local/bin/terrariumctl"
+    )
+
+- name: Install trm zsh completion alias
+  ansible.builtin.file:
+    src: /usr/local/share/zsh/site-functions/_terrariumctl
+    dest: /usr/local/share/zsh/site-functions/_trm
+    state: link
+    force: true
+  when: >-
+    not terrarium_trm_alias.stat.exists
+    or (
+      terrarium_trm_alias.stat.islnk | default(false)
+      and terrarium_trm_alias.stat.lnk_source == "/usr/local/bin/terrariumctl"
+    )
+
+- name: Install trm fish completion alias
+  ansible.builtin.file:
+    src: /usr/share/fish/vendor_completions.d/terrariumctl.fish
+    dest: /usr/share/fish/vendor_completions.d/trm.fish
+    state: link
+    force: true
+  when: >-
+    not terrarium_trm_alias.stat.exists
+    or (
+      terrarium_trm_alias.stat.islnk | default(false)
+      and terrarium_trm_alias.stat.lnk_source == "/usr/local/bin/terrariumctl"
+    )
+
 - name: Ensure root has a local password for Cockpit
   ansible.builtin.user:
     name: root

ansible/roles/base/tasks/main.yml

@@ -29,7 +29,7 @@ Most users should use the interactive installer. Just run this single command:
 curl -fsSL https://github.com/terion-name/terrarium/releases/latest/download/install.sh | bash
 ```
 
-The published `install.sh` is intentionally thin. It downloads the matching compiled `terrariumctl` bundle from GitHub Releases, stages it into `/opt/terrarium`, and runs the real installer there. Default and tag-like release installs fail closed if the release cannot be resolved or downloaded; source builds require an explicit branch-like `--ref`, for example `main`.
+The published `install.sh` is intentionally thin. It downloads the matching release bundle from GitHub Releases, unpacks the compiled `terrariumctl` binary plus the Ansible provisioning assets into `/opt/terrarium`, and runs the real installer there. Default and tag-like release installs fail closed if the release cannot be resolved or downloaded; source builds require an explicit branch-like `--ref`, for example `main`.
 
 If you want to pin a specific release instead of `latest`, use the tagged asset directly:
 
@@ -120,7 +120,7 @@ For non-interactive automation, use generated or file-based secret inputs so sec
 
 Terrarium keeps:
 
-- the repo checkout at `/opt/terrarium`
+- the installed Terrarium bundle at `/opt/terrarium`
 - the canonical config in LXD's dqlite-backed `terrarium-system` project after LXD is initialized
 - a local config export at `/etc/terrarium/config.yaml`
 

docs/getting-started/installation.md

@@ -52,7 +52,7 @@ If you ever need to dig into the server's internals, here is where everything li
 | `/etc/terrarium/config.yaml` | Your human-readable configuration backup. |
 | `/etc/terrarium/secrets/` | Generated passwords (like your Cockpit root login). |
 | `/var/lib/terrarium/` | General state files, S3 backup manifests, and OAuth proxy configs. |
-| `/opt/terrarium/` | The Terrarium source code repository. |
+| `/opt/terrarium/` | The installed Terrarium bundle: compiled `terrariumctl` and Ansible provisioning assets. |
 
 *Note: The **canonical** configuration is actually stored inside LXD's `dqlite` database. Do not edit `/etc/terrarium/config.yaml` by hand; always use `terrariumctl set` commands.*
 
@@ -70,4 +70,4 @@ If you link multiple Terrarium servers into a cluster, they communicate over a h
 - **`6641/tcp` & `6642/tcp`**: OVN database traffic (which Terrarium secures with mutual TLS certificates).
 - **`6081/udp`**: OVN overlay traffic (container-to-container communication).
 
-You never need to open these internal ports on your hosting provider's firewall. Terrarium handles all the complex routing securely through the single WireGuard connection.
+You never need to open these internal ports on your hosting provider's firewall. Terrarium handles all the complex routing securely through the single WireGuard connection.

docs/reference/services-and-endpoints.md

@@ -39,14 +39,15 @@
 | `terrariumctl set idp local|oidc` | mode plus optional flags | n/a | Switches between self-hosted ZITADEL and external OIDC, verifies external OIDC settings when applicable, and reconfigures oauth2-proxy plus LXD management auth together. |
 | `terrariumctl set s3` | optional flags | keeps current enable/disable state unless `--enable` or `--disable` is passed | Updates S3 backup settings, verifies the target with a real test operation, and can enable or disable S3 exports. |
 | `terrariumctl set syncoid` | optional flags | keeps current enable/disable state unless `--enable` or `--disable` is passed | Updates syncoid replication settings and can enable or disable syncoid. |
+| `terrariumctl completion` | `bash`, `zsh`, or `fish` | n/a | Prints a shell completion script. Installed hosts register completion for both `terrariumctl` and `trm` automatically. |
 
 ## install
 
 | Flag | Argument | Required | Default | Meaning |
 | --- | --- | --- | --- | --- |
 | `--non-interactive` | none | no | interactive mode if omitted | Disables prompts and requires all needed config through flags. |
 | `--yes` | none | no | prompt before destructive actions | Auto-confirms destructive or confirmation prompts. |
-| `--ref` | git branch or tag | no | `main` | Checks out a specific Terrarium ref in `/opt/terrarium`. |
+| `--ref` | git branch or tag | no | `main` when invoking `terrariumctl` directly; release-selected tag when run through `install.sh` | Installs a specific Terrarium release tag, or builds from a branch-like source ref such as `main`. |
 | `--email` | email address | yes in non-interactive mode; no in interactive mode | prompted in interactive mode | Sets the Terrarium contact/admin email and default ZITADEL bootstrap admin email. |
 | `--acme-email` | email address | no | falls back to `--email` | Sets the ACME account identity for Traefik and LXD certificate automation. |
 | `--domain` | root domain | no | service domains default to `<service>.<dashed-public-ip>.traefik.me` when omitted | Sets the root domain used to derive service subdomains. |

docs/reference/terrariumctl.md

@@ -53,7 +53,16 @@ ensure_os() {
 ensure_bootstrap_deps() {
   export DEBIAN_FRONTEND=noninteractive
   apt-get update -y
-  apt-get install -y ca-certificates curl unzip git python3
+  apt-get install -y ca-certificates curl unzip python3
+}
+
+ensure_git() {
+  if command -v git >/dev/null 2>&1; then
+    return
+  fi
+  export DEBIAN_FRONTEND=noninteractive
+  apt-get update -y
+  apt-get install -y git
 }
 
 ensure_bun() {
@@ -138,7 +147,7 @@ download_release_bundle() {
   curl -fsSL "${asset_url}" -o "${bundle_dir}/terrarium.zip" || return 1
   unzip -q "${bundle_dir}/terrarium.zip" -d "${bundle_dir}"
   [[ -x "${bundle_dir}/dist/terrariumctl" ]] || return 1
-  TERRARIUM_BUNDLE_DIR="${bundle_dir}" TERRARIUM_REPO_URL="${REPO_URL}" "${bundle_dir}/dist/terrariumctl" install --ref "${resolved_ref}" "${FORWARD_ARGS[@]}"
+  run_terrariumctl_install "${bundle_dir}" "${bundle_dir}/dist/terrariumctl" "${resolved_ref}" "${FORWARD_ARGS[@]}"
 }
 
 build_from_source() {
@@ -152,6 +161,7 @@ build_from_source() {
     mkdir -p "${build_dir}/repo"
     cp -a "${source_path}/." "${build_dir}/repo/"
   else
+    ensure_git
     git clone --depth 1 --branch "${source_ref}" "${REPO_URL}" "${build_dir}/repo"
   fi
   ensure_bun
@@ -160,7 +170,37 @@ build_from_source() {
     /opt/bun/bin/bun install --frozen-lockfile || /opt/bun/bin/bun install --no-progress
     /opt/bun/bin/bun scripts/build.ts
   )
-  TERRARIUM_BUNDLE_DIR="${build_dir}/repo" TERRARIUM_REPO_URL="${REPO_URL}" "${build_dir}/repo/dist/terrariumctl" install --ref "${source_ref}" "${FORWARD_ARGS[@]}"
+  run_terrariumctl_install "${build_dir}/repo" "${build_dir}/repo/dist/terrariumctl" "${source_ref}" "${FORWARD_ARGS[@]}"
+}
+
+is_non_interactive_install() {
+  local arg
+  for arg in "${FORWARD_ARGS[@]}"; do
+    case "${arg}" in
+      --non-interactive|--help|-h)
+        return 0
+        ;;
+    esac
+  done
+  return 1
+}
+
+run_terrariumctl_install() {
+  local bundle_dir="$1"
+  local terrariumctl="$2"
+  local ref="$3"
+  shift 3
+
+  if [[ -r /dev/tty ]]; then
+    TERRARIUM_BUNDLE_DIR="${bundle_dir}" TERRARIUM_REPO_URL="${REPO_URL}" "${terrariumctl}" install --ref "${ref}" "$@" </dev/tty
+    return
+  fi
+
+  if ! is_non_interactive_install; then
+    die "interactive install requires a TTY; run this from an interactive shell or pass --non-interactive with full configuration"
+  fi
+
+  TERRARIUM_BUNDLE_DIR="${bundle_dir}" TERRARIUM_REPO_URL="${REPO_URL}" "${terrariumctl}" install --ref "${ref}" "$@"
 }
 
 main() {