mooring

module

v0.9.0 Latest Latest Go to latest Published: Jul 27, 2026 License: Apache-2.0

Details

Valid go.mod file
Redistributable license
Tagged version
Stable version
Learn more about best practices

Repository

github.com/daboss2003/mooring

Links

Open Source Insights

README ¶

Mooring

Website · Documentation · Install

Run your apps on your own server — automatic HTTPS, live monitoring, and one clean dashboard — without the DevOps grind.

Mooring is a single small binary you install on a Linux server that has Docker. It owns the public edge (Caddy + automatic HTTPS), watches your apps' health, and gives you a dashboard and CLI to deploy and manage everything — so a plain server becomes a place you can ship to in minutes. Each app is defined by a mooring.yaml in its Git repo: you describe the services, domains, and config there, connect the repo, and Mooring runs it — generating and owning the Compose file and Dockerfile for you. You never hand-write either, hand-edit a proxy config, or run certbot.

Think of it as your own small Heroku or Netlify, running on a server you own. It's secure by default, and built around one rule: hosting Mooring should never be the thing that gets your server hacked.

What it is: Mooring is a lightweight, self-hosted PaaS / application control plane for Docker — a self-hosted alternative to Heroku/Railway and to CapRover, Coolify, and Dokploy, without Docker Swarm or Kubernetes. You describe a multi-service app in one typed mooring.yaml; Mooring generates and owns the Compose file and Dockerfile, provisions HTTPS at the edge, and deploys, monitors, scales, and self-heals it.

Most tools either put a UI on top of Docker (Portainer) or layer a PaaS on Swarm/Kubernetes (CapRover, Coolify). Mooring is a control plane, not another Docker dashboard:

typed YAML  →  Mooring control plane  →  Docker Engine

The Compose and Dockerfile underneath are generated implementation details you never hand-edit.

Why Mooring

	Mooring	CapRover	Coolify	Dokploy
No Docker Swarm required	✅	❌	✅	✅
No Kubernetes	✅	✅	✅	✅
Multi-service apps from one file	✅	⚠️ limited	✅	✅
Generates & owns Compose + Dockerfile	✅	❌	❌	❌
Automatic HTTPS at the edge	✅	✅	✅	✅
Built-in alerting + dead-man's switch	✅	⚠️ basic	⚠️ partial	⚠️ partial
Documented security / threat model	✅	⚠️ partial	⚠️ partial	⚠️ partial
Single static binary (no extra DB/services)	✅	❌	❌	❌

Comparisons are best-effort as of 2026, based on each project's public docs — corrections via PR are welcome.

Features

Automatic HTTPS — give an app a domain and Mooring issues and renews the certificate and routes traffic to it. No proxy to run, no certbot.
A real dashboard — health for every app and the host (with live CPU/memory/disk charts), logs, and start / stop / restart / redeploy per app or service.
Safe deploys — straight from a Git repo's mooring.yaml. Every change is checked before it goes live, with automatic rollback on failure.
Deploy from Git, one click — connect a repo (including one-click Connect with GitHub, which installs a read-only deploy key for you). Mooring watches for new commits and shows you what changed; you click Deploy. Access is fetch-only — Mooring never pushes to your repo.
Several apps from one repo — keep mooring.yaml plus variants like mooring.staging.yaml and mooring.prod.yaml in the same repo, and Mooring deploys each as its own app (you pick which on connect). One mooring.yaml? Nothing changes.
Secrets, done right — passwords and API keys are stored encrypted and referenced by name, never sitting in plain text in your files, repo, or logs.
Incidents in one place — open alerts, unhealthy apps, and recent failures roll up onto a single screen.
Alerting — optional email / webhook / Slack / Discord / Telegram, with quiet hours and an external dead-man's switch. Off until you turn it on.
Scaling & self-healing — optional, conservative automation that keeps stateless services responsive and recovers crashed ones (and pages you when it can't).
Backups — encrypted snapshots of your whole Mooring setup, with a safe restore onto a fresh server.
Single static binary — no external services, no asset pipeline, no build step. Runs as its own systemd unit.

Install

Mooring is third-party, so (like Docker or Tailscale) apt needs to know where to find it. Two ways:

Quickest — grab the .deb from the latest release and install it directly:

sudo apt install ./mooring_<version>_amd64.deb

For automatic apt upgrade updates — add the signed APT repo once, then install:

curl -fsSL https://daboss2003.github.io/mooring/gpg.key | sudo gpg --dearmor -o /usr/share/keyrings/mooring.gpg
echo "deb [signed-by=/usr/share/keyrings/mooring.gpg] https://daboss2003.github.io/mooring stable main" | sudo tee /etc/apt/sources.list.d/mooring.list
sudo apt update && sudo apt install mooring

A matching .rpm and standalone binaries are on every release. Full setup — generating your login + key, the config file, and starting the service — is in the installation guide.

Quickstart

Install it and generate your login + master key over SSH.
Open the dashboard at your admin.hostname.
Deploy your first app — connect its Git repo (its mooring.yaml defines the app), set its secrets, and give it a domain.

After install, you work entirely in the dashboard. To change an app's structure, edit its mooring.yaml and deploy — see The mooring.yaml file.

What you can do in the dashboard

Overview & Apps — every app's status at a glance; open one to see services, logs, and lifecycle controls.
Repository & updates — for repo-backed apps: what changed, and Deploy / Redeploy.
Edge & TLS — see the routes declared in an app's mooring.yaml; Mooring handles the certificate and routing.
Env & secrets — set your apps' secret values and non-secret env (the mooring.yaml declares secret names; the values live encrypted, never in the file). Config files and cert bindings are editable here too (and can be seeded from the file).
Incidents & Alerts — see what needs you, and configure how you're notified.
Audit log, API tokens, Backups — review privileged actions, manage machine tokens, and snapshot your setup.

Command line

The dashboard is the day-to-day surface. The CLI is for installation and the occasional power-user task:

Command	What it does
`mooring serve`	Run the dashboard + managed edge.
`mooring gen-key` · `hash-password` · `gen-totp` · `verify-key`	Generate the master key, password hash, and 2FA secret over SSH (the root of trust).
`mooring validate` · `init`	Check a `mooring.yaml`, or scaffold a starter one (read-only, CI-safe).
`mooring secret import`	Import an existing `.env` into an app's encrypted store.
`mooring token mint` · `list` · `revoke`	Manage scoped API tokens.
`mooring restore`	Restore Mooring's database from an encrypted backup.

Full reference: docs/cli.md.

Security

Mooring is secure out of the box, with no tuning required: the dashboard is private (loopback + IP allowlist), traffic is HTTPS, secrets are encrypted at rest, a push can't deploy itself, and an unsafe configuration makes it refuse to start rather than run insecure. If you're evaluating it, the security model covers the threat model and design in full.

Mooring runs the write plane (docker compose up/pull/build) on servers with ≥ 1 GB RAM; monitoring and HTTPS run fine on a smaller box.

Documentation

📖 Read the docs → — start with the three-page on-ramp: Introduction → Install → First steps.

Guides: Deploy from Git · Edge & TLS · Secrets & config files · Import a .env · Scaling & self-healing · Alerts · Backups · Many apps on one server · The mooring.yaml file. For internals: Architecture · Security.

License & contributing

License — Apache License 2.0 (see also NOTICE).
Contributing — see CONTRIBUTING.md. Because safety is the paramount requirement, changes to security-sensitive areas re-trigger the project's security checks before merge.
Security reports — please report vulnerabilities privately (see docs/security.md) rather than opening a public issue.

Directories ¶

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

Path	Synopsis
cmd
mooring command Command mooring is the single static binary: the admin server and the root-of-trust CLI (plan §2, §5.1).	Command mooring is the single static binary: the admin server and the root-of-trust CLI (plan §2, §5.1).
internal
alert Package alert is Mooring's read-and-notify alert engine (plan §8): ONE evaluator that reads the poller's snapshot (zero network I/O, zero docker writes, side-effect-free) and drives a per-(rule,target) state machine, and a SEPARATE rate-limited notifier that drains an outbox.	Package alert is Mooring's read-and-notify alert engine (plan §8): ONE evaluator that reads the poller's snapshot (zero network I/O, zero docker writes, side-effect-free) and drives a per-(rule,target) state machine, and a SEPARATE rate-limited notifier that drains an outbox.
alertengine Package alertengine runs the alert engine's goroutines (plan §8): ONE evaluator (reads the poller's snapshot, drives the state machine, enqueues the outbox — never sends), a SEPARATE globally-rate-limited notifier (drains the outbox, so a hung SMTP/bot can't stall evaluation or spam the box), and an externalized dead-man's-switch heartbeat.	Package alertengine runs the alert engine's goroutines (plan §8): ONE evaluator (reads the poller's snapshot, drives the state machine, enqueues the outbox — never sends), a SEPARATE globally-rate-limited notifier (drains the outbox, so a hung SMTP/bot can't stall evaluation or spam the box), and an externalized dead-man's-switch heartbeat.
alertstore Package alertstore persists the alert engine's channels (AES-256-GCM encrypted config), rules, per-(rule,target) state, and the outbox (plan §8/§9).	Package alertstore persists the alert engine's channels (AES-256-GCM encrypted config), rules, per-(rule,target) state, and the outbox (plan §8/§9).
apitoken Package apitoken is the scoped API-token model (plan §17.1): the keystone integration primitive — a new front DOOR, never a new trust PATH.	Package apitoken is the scoped API-token model (plan §17.1): the keystone integration primitive — a new front DOOR, never a new trust PATH.
appbackup Package appbackup is the app-data backup ENGINE: it produces encrypted snapshots of an app's stateful data — a logical database dump (pg_dump / mysqldump / mongodump) or a raw data-volume tar — by running a THROWAWAY sidecar container (`docker run --rm …`) on the write plane, piping its stdout through gzip and the tamper-evident AES-256-GCM stream from internal/backup, to a sink (a local .mbk file and/or an off-box object store).	Package appbackup is the app-data backup ENGINE: it produces encrypted snapshots of an app's stateful data — a logical database dump (pg_dump / mysqldump / mongodump) or a raw data-volume tar — by running a THROWAWAY sidecar container (`docker run --rm …`) on the write plane, piping its stdout through gzip and the tamper-evident AES-256-GCM stream from internal/backup, to a sink (a local .mbk file and/or an off-box object store).
audit Package audit appends to the append-only events table (plan §5.8).	Package audit appends to the append-only events table (plan §5.8).
backup Package backup is the app data backup/restore core (plan §7.10, §16).	Package backup is the app data backup/restore core (plan §7.10, §16).
backupsched Package backupsched is the scheduled app-data backup loop.	Package backupsched is the scheduled app-data backup loop.
backupstore Package backupstore manages Mooring's own-state backups: a consistent snapshot of the SQLite database (via VACUUM INTO), AES-256-GCM-encrypted with the master key (the chunked, tamper-evident stream from internal/backup), written under the data dir and recorded in a catalog.	Package backupstore manages Mooring's own-state backups: a consistent snapshot of the SQLite database (via VACUUM INTO), AES-256-GCM-encrypted with the master key (the chunked, tamper-evident stream from internal/backup), written under the data dir and recorded in a catalog.
builder Package builder is Mooring's build subsystem: it turns a declarative build spec (from mooring.yaml's compose.services[].build) into a hardened, multi-stage Dockerfile.	Package builder is Mooring's build subsystem: it turns a declarative build spec (from mooring.yaml's compose.services[].build) into a hardened, multi-stage Dockerfile.
cfgfile Package cfgfile implements managed config files (plan §7.4): a SELECTIVE, single-pass renderer that fills ONLY Mooring's own `{{hm.<key>}}` delimiter and copies everything else — the app's `${…}`, `$VAR`, Go `{{ }}`, and even `{{hmFoo}}` (no dot) — byte-identical.	Package cfgfile implements managed config files (plan §7.4): a SELECTIVE, single-pass renderer that fills ONLY Mooring's own `{{hm.<key>}}` delimiter and copies everything else — the app's `${…}`, `$VAR`, Go `{{ }}`, and even `{{hmFoo}}` (no dot) — byte-identical.
cfgstore Package cfgstore persists managed config files (templates + bindings) and cert bindings (plan §7.4/§7.5, M5b).	Package cfgstore persists managed config files (templates + bindings) and cert bindings (plan §7.4/§7.5, M5b).
clockskew Package clockskew detects system wall-clock steps by comparing the wall clock against a monotonic source (plan §5.9 / §6.3).	Package clockskew detects system wall-clock steps by comparing the wall clock against a monotonic source (plan §5.9 / §6.3).
compose Package compose is the §5.6 allowlist validator — the ONE chokepoint every compose document passes before it can reach `docker compose` (plan §5.6).	Package compose is the §5.6 allowlist validator — the ONE chokepoint every compose document passes before it can reach `docker compose` (plan §5.6).
config Package config loads and validates /etc/mooring/config.yaml — the root of trust (plan §5.1).	Package config loads and validates /etc/mooring/config.yaml — the root of trust (plan §5.1).
cronstore Package cronstore persists the last-run time + outcome of each app's scheduled tasks, so the scheduler knows when a task is next due and a restart doesn't re-fire everything.	Package cronstore persists the last-run time + outcome of each app's scheduled tasks, so the scheduler knows when a task is next due and a restart doesn't re-fire everything.
crypto Package crypto holds the password (argon2id), TOTP, and random/constant-time primitives for the security spine (plan §5.1, §5.3).	Package crypto holds the password (argon2id), TOTP, and random/constant-time primitives for the security spine (plan §5.1, §5.3).
definition Package definition is the mooring.yaml definition file (plan §7.7): the declarative source of truth for an app's Mooring-managed surface.	Package definition is the mooring.yaml definition file (plan §7.7): the declarative source of truth for an app's Mooring-managed surface.
diskgc Package diskgc is the disk-pressure auto-reclaim loop.	Package diskgc is the disk-pressure auto-reclaim loop.
docker Package docker is a thin, READ-ONLY Docker Engine API client that talks to the loopback docker-socket-proxy (plan §3) — never the raw socket.	Package docker is a thin, READ-ONLY Docker Engine API client that talks to the loopback docker-socket-proxy (plan §3) — never the raw socket.
dockerexec Package dockerexec is the write-plane exec wrapper: it shells out to `docker compose` with STATIC ARGV only — never a shell, never string interpolation, always a `--` terminator before service names (plan §3, §5.6).	Package dockerexec is the write-plane exec wrapper: it shells out to `docker compose` with STATIC ARGV only — never a shell, never string interpolation, always a `--` terminator before service names (plan §3, §5.6).
edge Package edge owns the managed edge (plan §6): Mooring supervises a child Caddy and is the SINGLE SOURCE OF TRUTH for its config via the admin API.	Package edge owns the managed edge (plan §6): Mooring supervises a child Caddy and is the SINGLE SOURCE OF TRUTH for its config via the admin API.
envimport Package envimport is the env import-and-own pipeline (plan §7.9).	Package envimport is the env import-and-own pipeline (plan §7.9).
envstore Package envstore is the per-app encrypted environment store (plan §5.5, M5).	Package envstore is the per-app encrypted environment store (plan §5.5, M5).
git Package git is the HARDENED git read/fetch layer (plan §7.6 + §15).	Package git is the HARDENED git read/fetch layer (plan §7.6 + §15).
github Package github implements the optional "Connect with GitHub" flow: a standard OAuth web flow plus the small slice of the GitHub API Mooring needs to make connecting a (private) repo a one-click affair — list the operator's repos and install a READ-ONLY deploy key — so nobody ever pastes a key by hand.	Package github implements the optional "Connect with GitHub" flow: a standard OAuth web flow plus the small slice of the GitHub API Mooring needs to make connecting a (private) repo a one-click affair — list the operator's repos and install a READ-ONLY deploy key — so nobody ever pastes a key by hand.
gitstore Package gitstore persists per-app repo-path GitOps config (plan §7.6): the repo URL/ref/paths, the FSM state (deployed/staged commit, update_state), and the secret material (PAT/deploy-key, webhook HMAC secret) AES-256-GCM at rest.	Package gitstore persists per-app repo-path GitOps config (plan §7.6): the repo URL/ref/paths, the FSM state (deployed/staged commit, update_state), and the secret material (PAT/deploy-key, webhook HMAC secret) AES-256-GCM at rest.
hostmon Package hostmon samples host CPU/RAM/disk for the read plane (plan §4).	Package hostmon samples host CPU/RAM/disk for the read plane (plan §4).
imagescan Package imagescan runs Trivy against a deployed app's images + dependency manifests to surface known CVEs, WITHOUT ever handing Trivy the Docker socket (Mooring's core read-only-socket invariant): upstream `image:` refs are scanned from the REGISTRY (`trivy image`), and build-service checkouts are scanned as a filesystem (`trivy fs`) for language deps.	Package imagescan runs Trivy against a deployed app's images + dependency manifests to surface known CVEs, WITHOUT ever handing Trivy the Docker socket (Mooring's core read-only-socket invariant): upstream `image:` refs are scanned from the REGISTRY (`trivy image`), and build-service checkouts are scanned as a filesystem (`trivy fs`) for language deps.
l4 Package l4 generates the config for Mooring's managed Layer-4 (TCP/UDP) load balancer — an nginx `stream {}` proxy that fronts a fixed public port (e.g.	Package l4 generates the config for Mooring's managed Layer-4 (TCP/UDP) load balancer — an nginx `stream {}` proxy that fronts a fixed public port (e.g.
monitor Package monitor is the read-plane poller (plan §4): it discovers apps (one per Docker Compose project), builds the normalized BASIC health record for each service (plan §4.3), samples host metrics, holds the latest snapshot in memory for the UI, and persists metric samples.	Package monitor is the read-plane poller (plan §4): it discovers apps (one per Docker Compose project), builds the normalized BASIC health record for each service (plan §4.3), samples host metrics, holds the latest snapshot in memory for the UI, and persists metric samples.
ntfy Package ntfy lets Mooring MANAGE a self-hosted ntfy server so an operator can get push alerts without depending on the public ntfy.sh or hand-running a container.	Package ntfy lets Mooring MANAGE a self-hosted ntfy server so an operator can get push alerts without depending on the public ntfy.sh or hand-running a container.
ops Package ops implements the App Ops Interface contract v1 (plan §4): discovery, the versioned descriptor, Terminus-style health normalization, queues, the pluggable adapter seam, and the per-app prober.	Package ops implements the App Ops Interface contract v1 (plan §4): discovery, the versioned descriptor, Terminus-style health normalization, queues, the pluggable adapter seam, and the per-app prober.
opsclient Package opsclient is the SSRF-safe outbound HTTP client for the App Ops Interface (plan §4.1, §15 §6.3).	Package opsclient is the SSRF-safe outbound HTTP client for the App Ops Interface (plan §4.1, §15 §6.3).
provision Package provision is the app provisioning core (plan §7): a typed form spec (mooring.yaml under the hood) deterministically GENERATED into a safe compose.	Package provision is the app provisioning core (plan §7): a typed form spec (mooring.yaml under the hood) deterministically GENERATED into a safe compose.
provstore Package provstore persists the registry of Mooring-provisioned apps (plan §7): the compose path and the typed form spec (mooring.yaml under the hood) that is the source of truth for regenerate/drift.	Package provstore persists the registry of Mooring-provisioned apps (plan §7): the compose path and the typed form spec (mooring.yaml under the hood) that is the source of truth for regenerate/drift.
retention Package retention bounds Mooring's own audit/events table so it can never become the disk-wedge that kills the write plane (plan §16.1).	Package retention bounds Mooring's own audit/events table so it can never become the disk-wedge that kills the write plane (plan §16.1).
s3 Package s3 is a MINIMAL, standard-library-only S3 client for pushing encrypted backup blobs to S3-compatible object storage (AWS S3, MinIO, Cloudflare R2, Backblaze B2).	Package s3 is a MINIMAL, standard-library-only S3 client for pushing encrypted backup blobs to S3-compatible object storage (AWS S3, MinIO, Cloudflare R2, Backblaze B2).
sandbox Package sandbox is the Mode-3 setup-script jail (plan §7/§9) — the single most dangerous feature in Mooring, so it is built assuming the script IS hostile.	Package sandbox is the Mode-3 setup-script jail (plan §7/§9) — the single most dangerous feature in Mooring, so it is built assuming the script IS hostile.
scale Package scale is the opt-in, host-aware process auto-scaler (plan §8A).	Package scale is the opt-in, host-aware process auto-scaler (plan §8A).
secret Package secret holds the two secrecy primitives the whole binary depends on: the Redacted type (a value that refuses to serialize itself in the clear) and the AES-256-GCM Cipher used for secrets at rest (plan §5.5).	Package secret holds the two secrecy primitives the whole binary depends on: the Redacted type (a value that refuses to serialize itself in the clear) and the AES-256-GCM Cipher used for secrets at rest (plan §5.5).
secretgen Package secretgen mints values for `spec.secrets[].generate` — the declarative "auto-generate this secret on first deploy" field.	Package secretgen mints values for `spec.secrets[].generate` — the declarative "auto-generate this secret on first deploy" field.
security Package security holds the in-repo, dependency-free pieces of the §15 Security Assurance Program (milestone M12) — the parts that run as plain `go test ./...` on every machine and in CI, with no external tooling required.	Package security holds the in-repo, dependency-free pieces of the §15 Security Assurance Program (milestone M12) — the parts that run as plain `go test ./...` on every machine and in CI, with no external tooling required.
selfheal Package selfheal is the bounded self-healing supervisor (plan §8.5): it restarts crashed/stuck services and ESCALATES to a Mooring-originated infra alert (§8.4) when it gives up — designed so that on a constrained box it can only REDUCE pressure or hold steady, NEVER manufacture an OOM (worst case: it declines to act and pages you).	Package selfheal is the bounded self-healing supervisor (plan §8.5): it restarts crashed/stuck services and ESCALATES to a Mooring-originated infra alert (§8.4) when it gives up — designed so that on a constrained box it can only REDUCE pressure or hold steady, NEVER manufacture an OOM (worst case: it declines to act and pages you).
serverinfo Package serverinfo backs the read-only "Server" tab: it sizes Mooring's own on-disk footprint, lists release artifacts for cleanup, and serves an allow-listed, read-only file view.	Package serverinfo backs the read-only "Server" tab: it sizes Mooring's own on-disk footprint, lists release artifacts for cleanup, and serves an allow-listed, read-only file view.
session Package session implements server-side opaque sessions (plan §5.3): a 256-bit random id handed to the browser, only its SHA-256 hash stored; rotated on login; idle + absolute timeouts that cannot be reopened by a backward wall clock step — even across a process restart (plan §5.9; review #1).	Package session implements server-side opaque sessions (plan §5.3): a 256-bit random id handed to the browser, only its SHA-256 hash stored; rotated on login; idle + absolute timeouts that cannot be reopened by a backward wall clock step — even across a process restart (plan §5.9; review #1).
setupstore Package setupstore persists per-app setup scripts (encrypted at rest) and the run ledger (plan §9).	Package setupstore persists per-app setup scripts (encrypted at rest) and the run ledger (plan §9).
socketproxy Package socketproxy lets Mooring MANAGE its own read-only docker-socket-proxy (plan §3) so the operator never runs a docker command — they only ever write mooring.yaml.	Package socketproxy lets Mooring MANAGE its own read-only docker-socket-proxy (plan §3) so the operator never runs a docker command — they only ever write mooring.yaml.
store Package store opens the SQLite database (pure-Go modernc driver, CGO-free) and runs embedded migrations transactionally (plan §2, §9).	Package store opens the SQLite database (pure-Go modernc driver, CGO-free) and runs embedded migrations transactionally (plan §2, §9).
updatecheck Package updatecheck periodically asks GitHub whether a newer Mooring release exists and — critically — whether the RUNNING version is affected by a published security advisory, so the operator is told to update (and paged, for a security advisory) even when nobody is watching the dashboard.	Package updatecheck periodically asks GitHub whether a newer Mooring release exists and — critically — whether the RUNNING version is affected by a published security advisory, so the operator is told to update (and paged, for a security advisory) even when nobody is watching the dashboard.
web Package web implements the HTTP control plane: the fail-closed request pipeline (plan §5), the auth/session handlers, and the admin UI shell.	Package web implements the HTTP control plane: the fail-closed request pipeline (plan §5), the auth/session handlers, and the admin UI shell.