seawall

seawall is a command-line tool and terminal dashboard for a Docker home server. It deploys, maintains and updates your stacks on Docker or rootless Podman. It also runs the monitoring and security around them.

In development. No tagged release. In daily use on one server.

seawall 0.1.0Rust

$ curl -fsSL seawall.sh | sh not yet
~ seawall
~ $ seawall status
> Alerts       ✓ nothing firing
> Stacks       ✓ 9 running, 4 stopped, none drifted
> Exposure     ✓ published ports match the allowlist
> Updates      ! web: app 6.65.0 → 6.67.0 (minor)
> Backups      ✓ 2 databases, restore-tested 8h ago
> Config repo  ✓ captured 05:00, pushed

~ $ seawall stack update web
web-app  app 6.65.0 → 6.67.0
dry run: add --yes to update

Hey. I'm Ollie.

seawall is a personal project of mine where I asked a simple question.

Do homelabs really need to be that hard?

seawall is in progress and not public yet. If you've ever asked the question about whether it's worth setting up a homelab, seawall is here to help you on that journey.

mail ollie at seawall dot sh

Monitoring and security

This is what runs on my server today. seawall init installs the same on yours. That's Prometheus, Grafana, cAdvisor and node-exporter, Loki and Alloy for logs, the alert rules, CrowdSec, auditd, the security facts and the encrypted config backup.

    • cAdvisor
    • Uptime Kuma
    stacks
    • Trivy
    • stack lint
    • Loki
    • Alloy
    docker
    • docker-socket-proxy
    • port allowlist
    • node-exporter
    host
    • ufw
    • CrowdSec
    • nftables
    • auditd
    • SOPS
    • age
PrometheusLokiGrafana
sev0sev1sev2sev3

Your channels, straight awayntfy

One summary at 09:00

Monitoring

Prometheus scrapes the host through node-exporter and every container through cAdvisor. Loki keeps 30 days of logs from the journal, Docker, the reverse proxy and auditd. Grafana runs the alert rules. sev0 and sev1 go out immediately. sev2 and sev3 arrive in one rollup at 09:00.

  • Every notification carries the first command to run and a link to its logs. seawall alerts <name> shows what fired it, read live.
  • A container that stops, restart-loops or turns unhealthy raises an alert with its exit reason.
  • A daily check finds image updates and counts the Critical and High CVEs they fix.
  • The Host tab shows each filling disk's days to full at the last six hours' rate. One under 25% free and due to fill within a day pages you.
  • Each night every running MySQL, MariaDB and Postgres database is dumped, then restored into a throwaway container. A failure raises an alert.
  • Pages and the rollup each go to ntfy, Pushover, Telegram, Discord, Slack, Matrix, Gotify or email, set in seawall config.
  • Every silence seawall sets ends on its own, after 30 days at most. None covers a sev0.
  • A heartbeat arrives at 09:00 every day. If it doesn't, alert delivery is broken.

Security

On the host, seawall relies on ufw, unattended security upgrades, CrowdSec and auditd. seawall init installs each one on request. Its ufw rules let in SSH, HTTP, HTTPS and metrics, and ufw stays off until you enable it. auditd watches SSH keys, cron, systemd units, passwd, shadow and sudoers. init reports sshd's settings and sets CIS's when asked. A change to sshd undoes itself unless a second login keeps it. For new containers, seawall new writes compose files that drop all capabilities, set no-new-privileges, limit memory and PIDs and run as non-root where the image allows. stack lint holds hand-written compose files to the same rules.

  • A container that publishes a port missing from the allowlist pages you. This was the alert seawall started with.
  • CrowdSec reads the SSH and reverse proxy logs. Its firewall bouncer bans attackers in nftables.
  • A change to a file auditd watches pages you, unless a package upgrade made it.
  • A deploy that adds a hardening error is refused.
  • Containers that need the Docker API go through a locked-down socket proxy. No app gets the raw socket.
  • Config and secrets go to a private Git repo every night, encrypted with age.
  • Every change seawall makes is logged with its origin (an SSH session, a timer or an agent). A change from anywhere else pages you.

Features

alerts and silence

Lists firing Grafana alerts. alerts <name> reads what fired it live (a listener's PID and command line, a container's last log lines and restart count, the CVEs an update fixes) and lists the seawall command that resolves it, if there is one. silence adds a Grafana silence. sev0 alerts can't be silenced.

seawall alerts · example data
$ seawall alerts

db backup

Dumps each MySQL, MariaDB and Postgres database with the client inside its own container. Each dump is restored into a throwaway container with no network. Its table count per schema is compared with the live database. The nightly timer keeps 14 dumps and raises an alert when a dump or restore test fails.

seawall db ls · example data
$ seawall db ls

game up

Starts and stops game server stacks. On a port clash it moves the new game to the next free port and prints the port players connect to. The running game is left alone. game down silences the game's alerts before it stops. The game's ports are added to and removed from the port allowlist.

seawall game ls · example data
$ seawall game ls

host

Graphs CPU, memory, disk and network from Prometheus, from the last hour up to 30 days with --since. Memory is split by stack, the Docker engine, system services, login sessions and page cache, from cgroup v2. It also shows the running and newest kernel, a pending reboot, RAID state and disk use. host mem ranks stacks by memory growth over the last day.

seawall host · example data
$ seawall host

images

Checks each running container's registry daily for a newer release in its major and for new majors. Trivy runs in a digest-pinned, locked-down container. It scans the running image and the candidate and counts the Critical and High CVEs the update fixes. A local build is checked against its base image. images ls lists the results. images explain <container> lists the CVEs by package. It never changes a stack. stack update takes the update.

seawall images ls · example data
$ seawall images ls

init

Sets up a new Ubuntu or Debian server, or links in with an existing one. Docker and Compose must be installed first. It adds Portainer or Compose, a reverse proxy (Nginx Proxy Manager, Traefik or Caddy), Prometheus, Grafana, cAdvisor, node-exporter, Loki, Alloy, CrowdSec, auditd, ufw rules and unattended security upgrades. Every image is pinned by digest. Each step is checked first and skipped if it's already in place. On a terminal it shows the plan and asks Carry out these steps? [y/N]. Off a terminal it prints the plan and takes no action. It ends with the ssh -L line and the login for each web UI.

new

A wizard for a new app, internal service or game server. It searches Docker Hub with the words as typed, hyphenated and joined, and flags look-alikes and images with few pulls. It reads the image's user, ports and volumes from the registry and its README. The compose file runs as a non-root user with capabilities dropped and a memory limit, and passes the lint. A non-root app's volumes are created and handed to its user before the first start.

seawall new · example data
$ seawall new

proxy hosts and proxy certs

proxy hosts reads every route from Nginx Proxy Manager (its database), Traefik (labels and file provider) or Caddy (its admin API). It flags routes without HTTPS, without an HTTP redirect or with a backend off the proxy network. proxy certs asks the proxy for each certificate it serves, so Cloudflare origin certificates show too. proxy certs install installs a Cloudflare origin certificate you paste in. It checks the key matches, switches every site the certificate names and confirms what the proxy serves.

seawall proxy hosts · example data
$ seawall proxy hosts

stack lint and stack harden

stack lint checks each compose file against 32 hardening rules. They include no-new-privileges, cap_drop: [ALL], memory and PID limits, pinned images, no Docker socket, no host root mount, databases off the proxy network and no relative bind mounts under Portainer. A deploy that adds an error is refused. A finding is accepted on purpose with a # seawall-lint: allow comment and an optional expiry date. stack harden writes the missing settings, with memory limits at twice the 14-day peak from Prometheus.

seawall stack lint web · example data
$ seawall stack lint web

stack migrate

Moves a running stack between Portainer and Compose under the same project name, so its volumes carry over. The stack's env moves with it, into a 0600 .env for Compose. It backs up the deployed compose first. If the stack doesn't come back healthy, it's moved back. It runs only after you type the stack's name.

seawall stack migrate api --to compose · example data
$ seawall stack migrate api --to compose

stack update

Bumps an image tag from the daily check, or to --to TAG, and redeploys through Portainer or Compose with the stack's env sent back unchanged. It backs up the deployed compose and pulls only the images it changes. It waits for every container to be running and healthy. If one doesn't settle, it offers stack rollback. Majors need --major. A database major also needs a restore-tested dump from the last 24 hours and the stack's name typed. Afterwards the update check runs again, so its alerts clear.

seawall stack update web · example data
$ seawall stack update web

status

One screen of what needs attention. Firing alerts and active silences, stacks that are stopped, restarting or drifted from their deployed compose, unexpected published ports, pending image updates with the CVEs they fix, apt updates, database backup age, the config repo and collector health. --brief prints one line for the SSH login banner. --json is for scripts. --check exits 1 when something needs attention.

seawall status · example data
$ seawall status

Screenshots

seawall tui shows the same information in eight tabs. Lists refresh every 30 seconds. Host graphs have a live view at one update a second. An action runs the same logic as its CLI command, as a dry run in a pane where the command has one. y runs it again with --yes. Each caption names the command that prints the same screen. Click it to run it in the demo below.

The overview tab
The overview tab lists what needs attention, one section per check.$ seawall statusFull size
The host tab, with a memory bar above four graphs
The host tab, with memory by owner above a day of CPU, memory, disk and network. [ and ] change the window from the live view up to a week.$ seawall hostFull size
The stacks tab
The stacks tab. The last column shows whether each compose file on disk matches the deployed one.$ seawall stack lsFull size
The alerts tab
The alerts tab. Enter is your shortcut to learn more about an alert or to take action on it. S silences it, for an hour up to a week.$ seawall alertsFull size
The backups tab, with two verified database dumps
The backups tab. Each nightly dump is restored into a throwaway database before it counts as verified.$ seawall db lsFull size
The new-stack wizard and the compose file it generated
The new-stack wizard, with the compose file it generated.$ seawall newFull size
A harden plan shown as a dry run
A harden plan as a dry run, waiting for y.$ seawall stack harden webFull size
The about page, with the seawall logo above a rolling sea
The about page. Press a on any tab to open it.$ seawall aboutFull size

Try it

A pretend terminal with example output. Type a seawall command or pick one below. Nothing here runs anything.

~ seawall demo
Loading the demo…

Memory

Per-stack figures come from the kernel's cgroup accounting. Together they add up to the whole machine. Stacks are drawn in blue and teal, the system in white and page cache in grey. Cache gets its own segment because the kernel reclaims it as soon as a process needs the memory.

in use4.3 GiB / 16.0 GiB (27%)

    Example figures from a 16 GiB server.

    Safety

    1. 1plan

      $ seawall stack update web
      seawall stack update web
        why  1 update waiting
      web-app  app 6.65.0 → 6.67.0
        steps  back up · pull app 6.67.0 · deploy · settle
      dry run: add --yes to update

      A command that changes something prints its plan and stops unless you add --yes, except the few that act at once. The plan shows the diff, the lint result, any ports it would open and any silences it would add.

    2. 2--yes

      $ seawall stack update web --yes
      …
      web updated  27s
        changed    web-app  6.65.0 → 6.67.0

      The riskiest changes need more than --yes. Moving a database to a new major version or moving a stack asks you to type the stack's name first.

    3. 3undo

      undo  seawall stack rollback web

      Every change is logged to the systemd journal along with where it came from (an SSH session, a systemd timer or an agent). A change from anywhere else sets off an alert.

    It's written in Rust with unsafe code forbidden. Subprocesses never go through a shell. Files are written atomically. Secrets are never printed.

    Roadmap

    The goal is a secure, monitored homelab from one command. seawall init sets up a fresh host to a documented hardening baseline, and seawall keeps it that way. The work below gets there.

    1. Now

      1. Seawall's own monitoring

        Seawall reads containers and the host itself and keeps their history. Prometheus and Grafana become optional.

      2. Alerts from seawall

        Seawall's own rules, silences and quiet hours. Alerts go straight to ntfy, Discord and the other channels.

    2. Later

      1. Every Linux distribution

        Debian and Ubuntu first, then Fedora and RHEL, then Arch and Alpine.

      2. macOS

        The CLI and TUI run on a Mac against a remote host.

    You are hereRunning one server every day.

    Journey

    How seawall was built.

    1. The config in git

      The host's config lives in a private repo with every secret encrypted. Drift is reported, and a host can be rebuilt from it.

    2. A user for every stack

      A stack runs as its own user with no login, or moves to rootless Docker or Podman and back.

    3. Security checks

      The kernel, accounts, sshd, AppArmor and file modes are checked against CIS and fixed from their row. Docker's own files are checked too. Origins reachable around Cloudflare and ports open past DOCKER-USER are found.

    4. Alerts that explain themselves

      Packs you pick by area. Each alert says what fired, how to check it and the fix, and goes to the channels you choose.

    5. The command centre

      A terminal dashboard. An action is a dry run first where its command has one, and a To do list says what needs you.

    6. Backups that restore

      Each database is dumped and restored into a throwaway copy every night. Volumes go to a local disk, S3 or SFTP. A restore is tested every week.

    7. A hardening baseline

      Compose files are checked against 32 rules. Harden and limits add what's missing, tried on a copy first.

    8. Deploys through your manager

      Portainer or Compose, the stack's environment kept. Updates are backed up first and rolled back when a stack doesn't come up.

    9. The allowlist alert

      A game server published two ports the host's allowlist didn't have. Seawall began as a safe way to edit that file.

    Seawall was going to be called bosun. The name was taken.