sitectl

sitectl is the LibOps command-line tool for managing Docker Compose-backed application sites. It keeps contexts, Compose lifecycle commands, service helpers, component changes, local image overrides, validation, health checks, and deployment entrypoints in one consistent CLI.

Documentation: https://sitectl.libops.io

Requirements

• Docker with the Compose v2 plugin for local application contexts.
• Go 1.26.1 when building sitectl from source.
• Application plugins such as sitectl-drupal, sitectl-isle, sitectl-wp, sitectl-ojs, sitectl-omeka-classic, sitectl-omeka-s, or sitectl-archivesspace for app-specific create flows and helpers.

Quick Start

Install sitectl, install the app plugin for the template you want to run, then create a local site:

sitectl create wp/default \
  --template-repo https://github.com/libops/wp \
  --path ./my-wordpress-site \
  --type local \
  --checkout-source template \
  --default-context

Start the site with the context-aware Compose wrapper:

sitectl compose up --remove-orphans -d

See Managed applications for the Compose, local image build, HTTPS, and development override contract.

Template provenance and downstream ownership

When a plugin creates a project from a template, sitectl resolves the cloned template's exact Git commit before discarding its Git history. It then initializes a fresh repository for the site owner and atomically writes .libops/template.lock.yaml. The lock has a versioned TemplateLock envelope and records:

• the template repository and full Git object ID;
• the sitectl and plugin package versions and build revisions when the binaries expose valid build metadata;
• the component-defaults revision when the template declares one; and
• the SHA-256 digest of .libops/template-contract.yaml when that contract is present.

This file is retained provenance, not an update mechanism or an attestation. Downstream owners can commit it with their fork and compare it during future sitectl component operations without giving the original template control of their Git history.

Template contracts use this minimal envelope; additional application fields belong under spec:

apiVersion: sitectl.libops.io/v1alpha1
kind: TemplateContract
schema: 1
spec:
  componentDefaults:
    revision: components-v3

A template may instead provide the same value as a single safe line in .libops/component-defaults.revision. If both declarations exist, they must match. Malformed or multi-document contracts, oversized metadata, symlinked .libops metadata paths, and conflicting revisions stop creation before the template history is removed. A source template must never contain .libops/template.lock.yaml; that file is owned and generated by the create operation for the downstream site.

Repository URLs written to the lock must not contain user information, inline passwords or tokens, query strings, or fragments. Use an SSH agent or Git credential helper for private templates; never put a credential in --template-repo.

Common Operations

Compose lifecycle is documented in sitectl compose:

sitectl compose ps
sitectl compose logs -f
sitectl compose down

Context and site checks are documented in sitectl healthcheck and sitectl validate:

sitectl healthcheck
sitectl validate

Local image overrides are documented in sitectl image:

sitectl image set --tag wp=nginx-1.30.3-php84

Component changes are applied immediately with sitectl set. Use sitectl converge later to inspect or repair drift:

sitectl set ingress enabled --mode https-mkcert --domain app.localhost
sitectl set ingress enabled --trusted-ip 203.0.113.10/32 --max-upload-size 2G --upload-timeout 10m
sitectl converge --report

License

sitectl is licensed under the MIT License.

Attribution

• The config commands for setting contexts were heavily inspired by kubectl.
• Adding a TUI was inspired by 37signals' once CLI.