Skip to content
v31-devPublic

About

Single user micro-PaaS for running and managing Docker-based applications across a small set of machines.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

sage

Sage is a lightweight single-user micro-PaaS for running and managing Docker-based applications across a small set of machines. It uses Tailscale for node connectivity, Cloudflare for domains, DNS and public apps, Traefik for ingress, and a web UI for day-to-day operations.

Detailed technical and development-oriented material lives in docs/.

Table of Contents

Overview

Sage is built around a manager node that coordinates one or more worker nodes over a private Tailscale network.

  • The manager provides the API and web UI.
  • Workers run application containers and supporting edge services.
  • Cloudflare provides the domain: DNS, a tunnel on each worker for public apps, and the DNS-01 validation for Let's Encrypt certificates.
  • Traefik on each worker routes its names to its own containers.
  • Metrics and logs are collected centrally for visibility and troubleshooting.
  • Backups can be stored with S3-compatible object storage.

Sage is designed for small, practical self-hosted deployments rather than large-cluster orchestration.

Architecture

At a high level, Sage has three main layers:

  • A manager service that stores platform state, coordinates deployments, and exposes the UI and API
  • Worker nodes that run applications, ingress, and supporting runtime services
  • Shared platform integrations for networking, DNS, metrics, logs, and backups

The manager-to-workers model over Tailscale is the core operating pattern.

For deeper architecture details, see docs/architecture.md.

Features

  • Manage projects, applications, containers, domains, volumes, workers, settings, backups, and notifications
  • Deploy applications from Docker images or Git repositories (private repos via a GIT_AUTH_TOKEN build secret)
  • Stop and delete deployed workloads
  • Route public and internal traffic through generated Traefik configuration
  • Add workers from your tailnet and bootstrap them over Tailscale
  • Collect worker and container metrics
  • Ingest and search container logs
  • Create and restore platform and application backups

Usage

Manager

The manager is a single container image, ghcr.io/v31-dev/sage. It runs anywhere that runs a container with a persistent volume. It joins your tailnet as its own node, so it needs no published ports, public URL, host Tailscale or TUN device.

It needs:

  • TS_AUTH_KEY — a Tailscale auth key for the manager's node. Create it tagged (the tag becomes the manager's tag) and not ephemeral. It is only used while the node has no tailnet identity yet (first boot, or after its state is lost). If the node can't join the tailnet with it (an invalid or expired key), the container exits at once with a [CRITICAL] line.
  • TS_NAME — the manager's tailnet machine name, also its name inside Sage.
  • DOMAIN — a domain whose DNS is on Cloudflare: its zone must be active (the registrar lists Cloudflare's nameservers). Apps get addresses under it, and the UI is served only at https://<TS_NAME>.core.<DOMAIN>.
  • CLOUDFLARE_API_TOKEN — a user API token, created under My Profile › API Tokens (account-owned tokens are not supported), with Account › Cloudflare Tunnel › Edit and Zone › DNS › Edit, and nothing else. Limit it to the account and to the one zone of DOMAIN. It must see only one active zone for DOMAIN; Sage uses the account that holds that zone.
  • ENCRYPTION_KEY — encrypts secrets in the database, platform backups and volume backups. Generate one with openssl rand -base64 32 | tr '+/' '-_' and keep it with your S3 credentials: backups can't be restored without it. It can't change after the first boot: Sage refuses to start with a different key. To use another key, wipe the volume and start again. Restoring a backup needs the key it was made with, so recovering onto a new volume means starting with the original key.
  • A persistent volume at /app/data.
  • Exactly one running instance.
  • A stop grace period of a few minutes. On a stop signal Sage starts no new work and lets running tasks (a deploy, a backup) finish before it exits. Docker's default is 10 seconds before it kills the container.

.env:

TS_AUTH_KEY=tskey-auth-...
TS_NAME=sage
DOMAIN=example.com
CLOUDFLARE_API_TOKEN=...
ENCRYPTION_KEY=...

Leave the values unquoted: docker run --env-file keeps quotes as part of the value.

With docker run:

docker run -d --name sage --restart unless-stopped --stop-timeout 300 \
  --env-file .env \
  -v sage-data:/app/data \
  ghcr.io/v31-dev/sage:latest

With Docker Compose:

services:
  sage:
    image: ghcr.io/v31-dev/sage:latest
    restart: unless-stopped
    stop_grace_period: 5m
    env_file: .env
    volumes:
      - sage-data:/app/data

volumes:
  sage-data:

latest follows the newest release. Pin a release tag (ghcr.io/v31-dev/sage:<version>, see the GitHub releases) to control when you upgrade.

On start, before serving anything, Sage sets up Cloudflare (the platform's tunnel and the manager's DNS record) and gets the manager's certificate from Let's Encrypt. A first start can take a few minutes. If Cloudflare is unreachable or answers with a server error, Sage retries for about 20 minutes and then exits, and its log says why. A token Cloudflare rejects, or a domain the token can't use, exits at once with the reason. With a certificate from an earlier start, it serves even while the Cloudflare setup fails.

unless-stopped restarts Sage after a crash and after a host reboot, without limit. A start that keeps failing then loops, which Let's Encrypt tolerates: failed validations are capped at 5 per hour, Sage stops immediately once it is rate limited, and Let's Encrypt doesn't ban addresses. If you'd rather it give up, restart: on-failure:5 (--restart on-failure:5) stops after 5 failed starts, but Docker doesn't restart on-failure containers after a host reboot, so you then start Sage by hand.

Tailnet

Enable MagicDNS: the manager reaches workers by name. The UI's address, <TS_NAME>.core.<DOMAIN>, is a Cloudflare DNS record pointing at the manager's tailnet IP, so it only works from the tailnet. Plain http://<TS_NAME> redirects to it.

Sage has no login or access control of its own. Anyone who can reach the manager over the tailnet can use the UI and API, including reading the stored S3 keys and Discord webhook. The tailnet policy is the only gate: restrict who can reach the manager, and never expose it outside the tailnet (no published ports, no public URL).

In the tailnet policy, give the manager and the workers their own tags (the examples use tag:sage and tag:sage-worker) and allow the traffic Sage uses. Anything not allowed is unreachable; tailnet traffic reaches every port the manager container listens on.

{
  "tagOwners": {
    "tag:sage":        ["autogroup:admin"],
    "tag:sage-worker": ["autogroup:admin"]
  },
  "acls": [
    // Your devices → the manager UI (443; 80 only redirects to it)
    {"action": "accept", "src": ["autogroup:member"], "dst": ["tag:sage:80,443"]},
    // Workers → the manager: Telegraf's reports and Vector's logs
    {"action": "accept", "src": ["tag:sage-worker"], "dst": ["tag:sage:9001"]},
    // Manager → workers: SSH (Tailscale SSH)
    {"action": "accept", "src": ["tag:sage"], "dst": ["tag:sage-worker:22"]},
    // Internal and TCP app domains (*.<subdomain>.int) and internal discovery, served by workers
    {"action": "accept", "src": ["autogroup:member", "tag:sage-worker"], "dst": ["tag:sage-worker:443,8443"]}
  ],
  "ssh": [
    // Tagged sources must use "accept" (not "check")
    {"action": "accept", "src": ["tag:sage"], "dst": ["tag:sage-worker"], "users": ["root"]}
  ]
}

Workers

A worker is a Linux machine with Docker (including the Compose plugin) that joins the tailnet with Tailscale SSH enabled:

tailscale up --ssh --auth-key=tskey-auth-...   # a key tagged tag:sage-worker

The tag is for the tailnet policy above, which lets the manager reach the machine; Sage does not read it. Add the machine on the Workers page by its hostname or Tailscale IP: Sage checks that it answers, then sets it up over SSH. In Sage a worker has a subdomain, given when it is added, which its internal names are under (<name>.<subdomain>.int.<DOMAIN>). A new worker gets its own certificate and private key; changing its subdomain replaces only that certificate. Workers share a separate certificate for internal discovery. Certificates use 45-day validity and renew with seven days remaining. The worker's page shows each certificate's status and applied expiry separately; Settings → Cloudflare shows the full inventory and any issuance or retirement errors. See Certificate Lifecycle for cleanup and rate limits. Deleting a worker stops Sage's services on it and removes Sage's files from it. A worker with containers or internal domains can't be deleted: delete its containers and move or delete its domains first, even when it is offline. A worker that is offline is removed from Sage only; its VM has to be cleaned up by hand.

A worker records which Sage manages it. Several Sages can share a tailnet when each has its own domain, S3 path and workers: a machine that another Sage manages is refused, and has to be deleted from that Sage first. Give each Sage its own tags in the tailnet policy if one must not reach the other's workers.

Workers are meant to be dedicated to Sage: a hardened, bare VM with Docker and nothing else running on it. The manager has no such requirement; it needs only Docker and runs anywhere, on a laptop, a PaaS or a VM.

Sizing

Sage is meant for one domain with about 10 workers and 50 applications; another domain or landscape runs its own Sage. The smallest recommended machine, for the manager and for each worker, is 1 GB of memory and 1 core. Give a machine more as its applications and logs grow.

First steps

Once Sage is up, the UI is at https://<TS_NAME>.core.<DOMAIN>. S3 (backups) and notifications are optional and set in the UI.

An application is reached at the names you give its containers on the Domains page: a public name <name>.<DOMAIN>, or an internal one <name>.<subdomain>.int.<DOMAIN> (tailnet only, on its worker). Names that share a service are listed together for clients that choose one, at https://discovery.<DOMAIN>/?service=<service> (public) or https://discovery.int.<DOMAIN>/?service=<service> (internal), in the Sage-Endpoints header, with an online flag for each name; Domain Types has the details. Each HTTP Domain can allow frontend origins for browser API requests. The client guide shows how to discover a backend service, probe its replicas and choose one.

Sage lists the backups already in the S3 bucket and path when you save the S3 settings, at startup and from Discover backups on the Backups page. To recover onto a new volume, start with the original ENCRYPTION_KEY, set S3, then restore a platform backup; volume backups are listed once their application is back. A platform restore replaces the configuration with the backup's, keeps the S3 settings in use and starts the history empty. Containers are then stopped and show an error until they are deployed again, also when the workers kept serving while the manager was being recovered, and a container that isn't in the backup is removed from its worker with its volumes' data; see Platform Backup And Restore. Each backup can also be downloaded from the Backups page (platform) or a volume's Restore dialog (volume): a link that works for a minute, straight from S3. The files are encrypted; Settings → S3 shows how to open one.

To change TS_NAME or the Cloudflare details, edit the env and restart: Sage brings the workers in line on start. A new TS_NAME renames the manager's tailnet machine, and the manager's metrics history starts over. Records and tunnels of a previous domain, account or name stay in Cloudflare until you delete them; they are listed in Cloudflare Resources. See DNS and API limits for Cloudflare's quotas and how Sage reports failures.

Sage doesn't upgrade itself. The version in the footer opens Settings → Upgrade, with the release notes and the steps: take a backup, pause Sage and wait until it is safe to stop, then run the newer image against the same volume. Sage always starts unpaused. The backup comes first because a paused Sage refuses changes and starts no tasks.

The newer version migrates the data when it starts, from 0.1.3 or any later release; an older install runs 0.1.3 once first. If the migration fails, Sage stops and leaves the data as it was, so the previous version still runs on it, and Settings → Upgrade → Migration logs shows why. Once migrated, the data no longer opens in an earlier version: going back means restoring the backup, or putting back the copy of the database Sage took before migrating, data.db.migration-<version> in the data folder, kept 90 days.

The repo's docker-compose.yml and sample.env are for local development; see docs/development.md.

More Docs

About

Single user micro-PaaS for running and managing Docker-based applications across a small set of machines.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages