stackr

module
v0.4.2 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Sep 18, 2026 License: Apache-2.0

README

stackr

CI

stackr is a self-hosted deployment platform for Docker Swarm. It builds and runs applications, provisions shared infrastructure, manages routing and backups, and presents the whole system as a live dependency canvas.

Features

  • Git and image deployments with immutable registry artifacts.
  • Multiple environments, promotion, rollback and pull-request previews.
  • Reviewable stack and organization configuration as code.
  • Managed PostgreSQL and S3-compatible storage.
  • Logical database and bucket slices from shared instances.
  • Traefik routing, automatic TLS and environment-aware domains.
  • Scheduled jobs, one-shot functions and durable background work.
  • Multi-node placement, replicas, node agents and two-pass volume moves.
  • Backups for databases, volumes and the stackr control plane.
  • REST API, OpenAPI document and the stackr CLI.

Development

Requires Go 1.26 or newer, Docker, Node.js and the HAMR CLI.

make install
hamr dev

The development server watches Go, templ, CSS and static assets. Database migrations run automatically at startup.

Before submitting a change:

make test
make lint
make templint

Repository layout

Path Purpose
cmd/stackrd Control-plane server and node agent
cmd/stackr Command-line client
cmd/proxyrelay Local port-forward relay
internal/stackrd/handlers Web and API transport
internal/stackrd/config Config parsing, planning and apply
internal/stackrd/infra/cluster Boundary for Docker access across nodes
internal/stackrd/infra Deploy, proxy, backup, registry and node services
internal/stackrd/store SQLite persistence and audit records
internal/cli CLI commands and API client
frontend Tailwind source and browser assets
docs/features Feature contracts and design notes
docs/plans Active plans and compact implementation records

See AGENTS.md for project conventions and docs/host-setup.md for host requirements.

Status

Pre-release beta. The schema and operational contract may still change without a compatibility path.

License

Stackr is licensed under the Apache License 2.0.

Directories

Path Synopsis
cmd
proxyrelay command
The stackr-proxyrelay binary: pipes TCP from its listen port to one fixed target, and exits once idle.
The stackr-proxyrelay binary: pipes TCP from its listen port to one fixed target, and exits once idle.
stackr command
Command stackr is the command-line client for a stackr server.
Command stackr is the command-line client for a stackr server.
stackr-install command
Command stackr-install installs stackr on a fresh Docker host.
Command stackr-install installs stackr on a fresh Docker host.
stackrd command
internal
cli
Package cli implements the `stackr` command-line client.
Package cli implements the `stackr` command-line client.
cli/cmd
Package cmd is the cobra command tree for the stackr CLI.
Package cmd is the cobra command tree for the stackr CLI.
installer
Package installer is stackr-install: the form, the checks on every answer, and the docker commands that create the panel on a fresh host (docs/plans/49-installer-binary.md).
Package installer is stackr-install: the form, the checks on every answer, and the docker commands that create the panel on a fresh host (docs/plans/49-installer-binary.md).
netaddr
Package netaddr checks addresses typed by an operator.
Package netaddr checks addresses typed by an operator.
proxyrelay
Package proxyrelay is the entire brain of the stackr-proxyrelay container: a TCP pipe with an idle timeout.
Package proxyrelay is the entire brain of the stackr-proxyrelay container: a TCP pipe with an idle timeout.
stackrd/config/envcompare
Package envcompare answers "how do this stack's environments differ from the first one": one row per tile slug, one cell per environment, the keys that differ, and which of those someone has marked as on purpose.
Package envcompare answers "how do this stack's environments differ from the first one": one row per tile slug, one cell per environment, the keys that differ, and which of those someone has marked as on purpose.
stackrd/config/envops
Package envops holds environment lifecycle operations shared by the web UI and automation triggers (PR webhooks): config-only cloning and full teardown.
Package envops holds environment lifecycle operations shared by the web UI and automation triggers (PR webhooks): config-only cloning and full teardown.
stackrd/config/envutil
Package envutil parses KEY=VALUE env blobs shared by the deploy engine, databases, and the web Variables tab.
Package envutil parses KEY=VALUE env blobs shared by the deploy engine, databases, and the web Variables tab.
stackrd/config/orgconf
Package orgconf is org-level config-as-code (§6): one file from which a fresh stackr server can materialize the entire org, org vars/secrets, org-scoped shared managed instances, and the stacks themselves.
Package orgconf is org-level config-as-code (§6): one file from which a fresh stackr server can materialize the entire org, org vars/secrets, org-scoped shared managed instances, and the stacks themselves.
stackrd/config/runpolicy
Package runpolicy is the registry of runnable tile types: how each type's built artifact runs, and which config surface it accepts.
Package runpolicy is the registry of runnable tile types: how each type's built artifact runs, and which config surface it accepts.
stackrd/config/secrets
Package secrets encrypts sensitive values (app/db env blobs) at rest with AES-GCM.
Package secrets encrypts sensitive values (app/db env blobs) at rest with AES-GCM.
stackrd/config/settings
Package settings holds the cascading defaults: server -> organization -> stack -> environment -> tile.
Package settings holds the cascading defaults: server -> organization -> stack -> environment -> tile.
stackrd/config/sharelink
Package sharelink runs one-shot secret exchanges with people who have no account: a drop box they fill in (values land straight in the encrypted variables store) or a share link that shows them existing values once.
Package sharelink runs one-shot secret exchanges with people who have no account: a drop box they fill in (values land straight in the encrypted variables store) or a share link that shows them existing values once.
stackrd/config/stackconf
Package stackconf parses stackr-compose.yml, declarative stack config, and resolves it into per-environment tile definitions.
Package stackconf parses stackr-compose.yml, declarative stack config, and resolves it into per-environment tile definitions.
stackrd/config/staging
Package staging records pending UI edits into the staged_changes buffer so they apply as one reviewed transaction (see internal/stackconf/staging.go for how the buffer is drained).
Package staging records pending UI edits into the staged_changes buffer so they apply as one reviewed transaction (see internal/stackconf/staging.go for how the buffer is drained).
stackrd/config/varref
Package varref resolves ${{ ...
Package varref resolves ${{ ...
stackrd/envcolor
Package envcolor resolves the colour an environment is drawn in.
Package envcolor resolves the colour an environment is drawn in.
stackrd/handlers/api
Package api mounts the REST surface.
Package api mounts the REST surface.
stackrd/handlers/api/v1
Package v1 is the REST API.
Package v1 is the REST API.
stackrd/handlers/middleware
Package middleware holds this application's own Echo middleware, request logging with a propagated request id, the active-organization context, and the guard that keeps config-managed stacks read-only in the UI.
Package middleware holds this application's own Echo middleware, request logging with a propagated request id, the active-organization context, and the guard that keeps config-managed stacks read-only in the UI.
stackrd/handlers/notify
Package notify pushes "something changed" events to browsers over the hamr websocket hub, and records events in the in-app notification center.
Package notify pushes "something changed" events to browsers over the hamr websocket hub, and records events in the in-app notification center.
stackrd/handlers/stream
Package stream is an in-process pub/sub hub used to fan out log lines and status updates to SSE subscribers.
Package stream is an in-process pub/sub hub used to fan out log lines and status updates to SSE subscribers.
stackrd/handlers/web
Package web is the HTML surface: the full route table, the middleware groups behind it, and the shared error rendering.
Package web is the HTML surface: the full route table, the middleware groups behind it, and the shared error rendering.
stackrd/handlers/web/avatar
Package avatar handles the two uploaded images in stackr, a user's avatar and an organization's logo, from the multipart form to the <img> tag.
Package avatar handles the two uploaded images in stackr, a user's avatar and an organization's logo, from the multipart form to the <img> tag.
stackrd/handlers/web/components
templ: version: v0.3.1001
templ: version: v0.3.1001
stackrd/handlers/web/components/canvas
templ: version: v0.3.1001
templ: version: v0.3.1001
stackrd/handlers/web/components/form
templ: version: v0.3.1001
templ: version: v0.3.1001
stackrd/handlers/web/filebrowse
templ: version: v0.3.1001
templ: version: v0.3.1001
stackrd/handlers/web/graph
Package graph derives a project topology (nodes + edges) from apps and databases.
Package graph derives a project topology (nodes + edges) from apps and databases.
stackrd/handlers/web/handler/about
templ: version: v0.3.1001
templ: version: v0.3.1001
stackrd/handlers/web/handler/account
templ: version: v0.3.1001
templ: version: v0.3.1001
stackrd/handlers/web/handler/annotate
Package annotate is the HTTP half of canvas annotations: bind, validate and write one note against a canvas owner key the caller has already authorized.
Package annotate is the HTTP half of canvas annotations: bind, validate and write one note against a canvas owner key the caller has already authorized.
stackrd/handlers/web/handler/app
templ: version: v0.3.1001
templ: version: v0.3.1001
stackrd/handlers/web/handler/auth
Package auth holds web-layer auth helpers shared across the internal/web/handler/auth/* page packages (login, register, etc.).
Package auth holds web-layer auth helpers shared across the internal/web/handler/auth/* page packages (login, register, etc.).
stackrd/handlers/web/handler/auth/invite
Package invite handles org invite links: an existing session joins the org directly, a fresh visitor creates an account through the invite.
Package invite handles org invite links: an existing session joins the org directly, a fresh visitor creates an account through the invite.
stackrd/handlers/web/handler/auth/login
templ: version: v0.3.1001
templ: version: v0.3.1001
stackrd/handlers/web/handler/auth/register
templ: version: v0.3.1001
templ: version: v0.3.1001
stackrd/handlers/web/handler/backups
Package backups is the per-tile Backups tab: the schedules on one tile, their run history, and the buttons that run or restore them.
Package backups is the per-tile Backups tab: the schedules on one tile, their run history, and the buttons that run or restore them.
stackrd/handlers/web/handler/cli
templ: version: v0.3.1001
templ: version: v0.3.1001
stackrd/handlers/web/handler/container
templ: version: v0.3.1001
templ: version: v0.3.1001
stackrd/handlers/web/handler/db
templ: version: v0.3.1001
templ: version: v0.3.1001
stackrd/handlers/web/handler/deployment
templ: version: v0.3.1001
templ: version: v0.3.1001
stackrd/handlers/web/handler/notification
Package notification renders the in-app notification center and the live-updating rail bell badge.
Package notification renders the in-app notification center and the live-updating rail bell badge.
stackrd/handlers/web/handler/org
templ: version: v0.3.1001
templ: version: v0.3.1001
stackrd/handlers/web/handler/prhook
Package prhook turns GitHub pull_request webhooks into ephemeral environments: opened → clone the configured base env and deploy it, synchronize → redeploy the PR branch, closed → tear the env down.
Package prhook turns GitHub pull_request webhooks into ephemeral environments: opened → clone the configured base env and deploy it, synchronize → redeploy the PR branch, closed → tear the env down.
stackrd/handlers/web/handler/project
templ: version: v0.3.1001
templ: version: v0.3.1001
stackrd/handlers/web/handler/search
Package search is the global search palette's backend: one endpoint that substring-matches everything the viewer can navigate to and returns an HTML fragment of result rows.
Package search is the global search palette's backend: one endpoint that substring-matches everything the viewer can navigate to and returns an HTML fragment of result rows.
stackrd/handlers/web/handler/server
Package server renders the servers screen: host stats history, Docker daemon info, and the server-level default settings.
Package server renders the servers screen: host stats history, Docker daemon info, and the server-level default settings.
stackrd/handlers/web/handler/settings
templ: version: v0.3.1001
templ: version: v0.3.1001
stackrd/handlers/web/handler/sharepub
Package sharepub is the public face of a secret link: the pages someone with no account sees at /s/:token.
Package sharepub is the public face of a secret link: the pages someone with no account sees at /s/:token.
stackrd/handlers/web/wsproxy
Package wsproxy bridges a websocket to a plain TCP connection, the server half of `stackr forward`.
Package wsproxy bridges a websocket to a plain TCP connection, the server half of `stackr forward`.
stackrd/handlers/web/wsterm
Package wsterm bridges a browser websocket to a docker exec TTY, the one implementation behind both the container terminal and the db console.
Package wsterm bridges a browser websocket to a docker exec TTY, the one implementation behind both the container terminal and the db console.
stackrd/infra/agent
Package agent is the node agent: one task per swarm node, proxying the handful of docker calls Swarm's control plane does not forward.
Package agent is the node agent: one task per swarm node, proxying the handful of docker calls Swarm's control plane does not forward.
stackrd/infra/backup
Package backup writes database dumps, docker volumes, and the panel's own SQLite file to S3-compatible destinations, restores from them, prunes old archives, and runs the schedules that trigger all of it.
Package backup writes database dumps, docker volumes, and the panel's own SQLite file to S3-compatible destinations, restores from them, prunes old archives, and runs the schedules that trigger all of it.
stackrd/infra/cigate
Package cigate releases push deploys parked behind wait_for_ci: a janitor task polls GitHub's check runs + commit statuses for each waiting_ci deployment and turns green into a queued build, red into an error.
Package cigate releases push deploys parked behind wait_for_ci: a janitor task polls GitHub's check runs + commit statuses for each waiting_ci deployment and turns green into a queued build, red into an error.
stackrd/infra/cluster
Package cluster is the one door for every docker call the panel makes.
Package cluster is the one door for every docker call the panel makes.
stackrd/infra/deploy
Package deploy runs the build+release pipeline: fetch → build → run new → health-gate → retire old.
Package deploy runs the build+release pipeline: fetch → build → run new → health-gate → retire old.
stackrd/infra/envnet
Package envnet maps a tile to its environment's isolated Docker network and slug-based naming.
Package envnet maps a tile to its environment's isolated Docker network and slug-based naming.
stackrd/infra/forward
Package forward tracks live `stackr forward` tunnels in memory.
Package forward tracks live `stackr forward` tunnels in memory.
stackrd/infra/githubapp
Package githubapp implements the GitHub App manifest flow for "github" connectors: each connector creates its own private GitHub App in one click, then mints short-lived installation tokens for cloning private repos and validating webhooks.
Package githubapp implements the GitHub App manifest flow for "github" connectors: each connector creates its own private GitHub App in one click, then mints short-lived installation tokens for cloning private repos and validating webhooks.
stackrd/infra/gitlog
Package gitlog is a list of recent commits on one branch, from GitHub or a local clone, in one shape.
Package gitlog is a list of recent commits on one branch, from GitHub or a local clone, in one shape.
stackrd/infra/hostmetrics
Package hostmetrics reads one machine's own counters: CPU, memory, disk, network.
Package hostmetrics reads one machine's own counters: CPU, memory, disk, network.
stackrd/infra/imagewatch
Package imagewatch polls container registries for new image digests and drives the per-tile update policy (notify / auto-redeploy).
Package imagewatch polls container registries for new image digests and drives the per-tile update policy (notify / auto-redeploy).
stackrd/infra/jobs
Package jobs is the scheduler behind cron tiles: it fires them on their cron expression, runs each as a one-shot container from the tile's own image, and records the outcome in cron_runs.
Package jobs is the scheduler behind cron tiles: it fires them on their cron expression, runs each as a one-shot container from the tile's own image, and records the outcome in cron_runs.
stackrd/infra/mail
Package mail is stackr's outbound transactional email: one SMTP2GO adapter behind hamr's email.Sender, plus the dev inbox.
Package mail is stackr's outbound transactional email: one SMTP2GO adapter behind hamr's email.Sender, plus the dev inbox.
stackrd/infra/managedtiles
Package databases provisions and manages database containers: per-engine image/env/volume defaults plus dump & restore commands.
Package databases provisions and manages database containers: per-engine image/env/volume defaults plus dump & restore commands.
stackrd/infra/metrics
Package metrics samples container CPU/memory into a SQLite ring buffer for the per-service graphs, plus host CPU/mem/disk under "server:local" refs for the servers screen.
Package metrics samples container CPU/memory into a SQLite ring buffer for the per-service graphs, plus host CPU/mem/disk under "server:local" refs for the servers screen.
stackrd/infra/netpool
Package netpool hands out pre-created swarm overlays.
Package netpool hands out pre-created swarm overlays.
stackrd/infra/nodes
Package nodes keeps the servers table in step with the swarm, pings the nodes, and issues the one-time keys a node joins with.
Package nodes keeps the servers table in step with the swarm, pings the nodes, and issues the one-time keys a node joins with.
stackrd/infra/placement
Package placement decides which node a tile's task may run on.
Package placement decides which node a tile's task may run on.
stackrd/infra/proxy
Package proxy owns Traefik: it runs the Traefik container and writes its dynamic file-provider config.
Package proxy owns Traefik: it runs the Traefik container and writes its dynamic file-provider config.
stackrd/infra/registry
Package registry manages the Stackr-hosted Docker registry (registry:2 with htpasswd auth) and external registry records.
Package registry manages the Stackr-hosted Docker registry (registry:2 with htpasswd auth) and external registry records.
stackrd/infra/runtime
Package runtime is the single Docker boundary: no other package may import the Docker SDK or shell out to docker.
Package runtime is the single Docker boundary: no other package may import the Docker SDK or shell out to docker.
stackrd/infra/storagetiles
Package storagetiles implements §2.7 storage tiles: server-scoped shares (nfs/smb) and local pools, consumed through declared sub-paths, each backed by a docker local-driver volume.
Package storagetiles implements §2.7 storage tiles: server-scoped shares (nfs/smb) and local pools, consumed through declared sub-paths, each backed by a docker local-driver volume.
stackrd/infra/volmove
Package volmove moves every volume a tile mounts from one node to another.
Package volmove moves every volume a tile mounts from one node to another.
stackrd/infra/workqueue
Package workqueue is one durable runner for every long job (docs/plans/33-workqueue.md).
Package workqueue is one durable runner for every long job (docs/plans/33-workqueue.md).
stackrd/service
Package service holds business logic that outlives any one HTTP handler.
Package service holds business logic that outlives any one HTTP handler.
stackrd/store/audit
Package audit records reads and writes of secret variable values.
Package audit records reads and writes of secret variable values.
stackrd/store/db
Package db opens the SQLite connection and owns the embedded migrations, which run at startup.
Package db opens the SQLite connection and owns the embedded migrations, which run at startup.
stackrd/store/repo
Package repo is the data layer: the Store interface every handler talks to, the row structs behind it, and the slug rules shared by both.
Package repo is the data layer: the Store interface every handler talks to, the row structs behind it, and the slug rules shared by both.
stackrd/store/testdb
Package testdb spins up a migrated in-memory SQLite store for tests.
Package testdb spins up a migrated in-memory SQLite store for tests.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL