Barkstack

Barkstack is the control-plane CLI for Barkstack services. Its first backend is Docker Swarm.

Monorepo

The CLI, Barkfile schema, Console, PawSQL, TreatVault, shared UI foundation, and release automation live here and ship from one version tag:

apps/console/        Console HTTP server and Svelte shell
services/pawsql/     PostgreSQL router and plugin UI
services/treatvault/ encrypted secret service and plugin UI
packages/barkfile/   Barkfile parser and validation
packages/brand/      Canonical Barkstack logo asset
packages/ui-foundation/ shared host UI tokens

barkstack version identifies the CLI release. A tagged CLI defaults init to matching pawsql, treatvault, and Console image tags; development builds use the edge channel.

init validates the Barkfile, then ensures Docker Swarm, the barkstack overlay network, PawSQL, the Barkstack Console, and — when the Barkfile configures a treatvault block — TreatVault:

go run ./cmd/barkstack init --config ./Barkfile

init validates the Barkfile with the shared parser, then:

1. initializes Docker Swarm when this Docker node is inactive;
2. requires an active Swarm manager before proceeding;
3. with a treatvault block: creates the TreatVault identity Docker secret if it is absent, then provisions the barkstack-treatvault service; without one: verifies every Docker secret referenced by password_secret exists;
4. creates the attachable barkstack overlay network when it is absent;
5. pulls the PawSQL, Barkstack Console, and TreatVault images;
6. creates or refreshes the manager-constrained barkstack-pawsql service;
7. mounts referenced Docker secrets into PawSQL and publishes PostgreSQL port 5432 through Swarm ingress;
8. creates or refreshes the barkstack-console service with PawSQL registered at http://barkstack-pawsql:9090;
9. publishes console port 8080 through Swarm ingress.

PawSQL bind-mounts the Barkfile at /etc/barkstack/Barkfile and bind-mounts the configured TLS certificate and key at their configured paths. PawSQL is constrained to managers because those local files must be present where it runs. The console needs no host bind mounts and reaches PawSQL over the overlay network.

Managed PostgreSQL routes use a short password_secret reference. Without TreatVault, Barkstack prefixes the reference with barkstack_, verifies the Docker Swarm secret exists, and mounts it into PawSQL:

docker secret create barkstack_application_postgres_password /secure/path/application-postgres-password
barkstack init --config ./Barkfile

With a treatvault block, TreatVault manages the namespaced secrets instead: barkstack init provisions barkstack-treatvault with the encrypted source-of-truth file bind-mounted read-write, the Docker socket, and the identity secret, then labels PawSQL as a TreatVault consumer. TreatVault watches the encrypted file and creates, rotates, and mounts versioned Docker Swarm secrets at stable barkstack_<name> targets. The console gains a TreatVault page for creating, rotating, and deleting secrets; values are write-only and never displayed again.

On the first init, Barkstack creates the age identity directly as the barkstack_treatvault_identity Docker secret. TreatVault initializes a missing secrets.age from that mounted identity on service startup. No TreatVault CLI bootstrap is required:

barkstack init --config ./Barkfile

The encrypted secrets.age file is safe to commit and back up; only its Docker-secret identity must stay secret. The TreatVault image and service name can be overridden with --treatvault-image and --treatvault-service.

Secret values never belong in the Barkfile. With TreatVault, create and rotate values through the console's TreatVault page; consumers are re-mounted automatically on the next sync. Without TreatVault, Docker secrets are immutable, so rotate under a new secret name, update password_secret, and run barkstack init again.

Override defaults when necessary:

barkstack init \
  --config /srv/barkstack/Barkfile \
  --pawsql-image registry.campbellwireless.net/barkstack/pawsql:v0.8.0 \
  --console-image registry.campbellwireless.net/barkstack/barkstack:v0.8.0 \
  --docker-socket /var/run/docker.sock \
  --network barkstack \
  --service barkstack-pawsql \
  --console-service barkstack-console \
  --treatvault-image registry.campbellwireless.net/barkstack/treatvault:v0.8.0 \
  --treatvault-service barkstack-treatvault

PawSQL also bind-mounts /var/run/docker.sock. It must run managed postgres containers itself — creating, starting, and stopping them on idle timeouts — so it needs Docker Engine access. The Docker socket grants PawSQL root-equivalent control of the host; mount it only for trusted Barkfiles and administrators. Override the path with --docker-socket.

The Docker CLI must point to the intended Swarm manager. The current implementation uses bind mounts for PawSQL, so the Barkfile and TLS files must be available on that manager. After initialization, open http://<any-swarm-node>:8080; the Swarm routing mesh forwards the request to the console task.

Management Console

With TreatVault configured, register its write-only plugin the same way; barkstack init does this automatically for the Swarm deployment. The embedded Svelte console listens on plain HTTP and discovers independently shipped service UIs at runtime:

cd apps/console/ui && bun install && bun run build && cd ../../..
go build -tags uiassets -o barkstack ./cmd/barkstack
./barkstack console --listen :8080 \
  --plugin pawsql=http://localhost:9090 \
  --plugin treatvault=http://localhost:9090

Open http://localhost:8080. Repeat --plugin id=http://internal-service:port for additional plugins.

See docs/console.md for architecture, local and Swarm deployment, production builds, failure behavior, and future ingress compatibility. See docs/ui-plugin-api-v1.md for the versioned manifest, custom-element, styling, event, and trust contracts.