Get started

Before you begin

• A Linux or macOS machine that can run the Barkstack release binary.
• Docker Engine installed and available to the account running Barkstack.
• A Docker Swarm manager. Barkstack initializes a single-node Swarm when Docker is not already in one.
• A trusted local network: the Console currently serves plain HTTP on port 8080.

1. Install the CLI

Download the archive that matches your operating system and CPU from the Barkstack release page. Replace vX.Y.Z with an emitted release tag; the matching CLI selects the same PawSQL, TreatVault, and Console image version.

VERSION=vX.Y.Z
OS=linux       # linux or darwin
ARCH=amd64    # amd64 or arm64
curl -fLO "https://git.campbellwireless.net/barkstack/barkstack/releases/download/$VERSION/barkstack_${VERSION#v}_${OS}_${ARCH}.tar.gz"
tar -xzf barkstack_*.tar.gz
install -m 0755 barkstack /usr/local/bin/barkstack
barkstack version

2. Create a Barkfile

Create a directory owned by the operator, then save a Barkfile. PawSQL is cluster-wide; every project owns its PostgreSQL resources and an isolated overlay network. The password is a project-scoped Docker Swarm secret, never a Barkfile value.

docker secret create barkstack_garden_garden_postgres_password /secure/path/garden-password

pawsql {
  listen :5432
}

project garden {
  pawsql {
    database garden {
      postgres {
        image postgres:18
        volume garden-postgres-data
        password_secret garden_postgres_password
      }
    }
  }
}

Optional: compose projects from Barkfiles

Use include directives to compose project ownership boundaries in memory. Paths are relative to the including file. listen, tls, and treatvault remain cluster resources and may be declared only once. Each project has a non-attachable barkstack-project-<name> overlay; PawSQL joins the system overlay and every project overlay it serves, while PostgreSQL joins only its owning project overlay. Database IDs are canonicalized as database/<project>/<database>, so names may repeat across projects. Repeating an unqualified database name requires distinct SNI hostnames to route traffic.

# Barkfile
pawsql {
  listen :5432
}
include "Barkfile.garden"

# Barkfile.garden
project garden {
  pawsql {
    database main {
      hostname garden.pawsql.example
      postgres {
        image postgres:18
        volume garden-main
        password_secret main_password
      }
    }
  }
}

3. Initialize Barkstack

Run this on the Swarm manager with access to the Barkfile and every file it references. Re-running the command safely refreshes Barkstack services after configuration changes.

barkstack init --config /srv/barkstack/Barkfile

4. Open the Console

Barkstack publishes the Console through Docker Swarm ingress. Open the address of any Swarm node on port 8080 from your trusted network.

http://<swarm-node>:8080