Skip to content
sitesolide

Docs Concepts

How it works

sitesolide serves every project from one Debian server you own. Each project is a folder on that server, live at https://<slug>.<zone>.

  1. Your laptop

    sitesolide deploy

  2. over SSH, or with a token

    One server you own

    • Caddy

      HTTPS and company sign-in

    • Your apps

      one account and unit each

    • Helpers

      root, one job each

    • Dashboard

      shows state, holds no power

One machine, on purpose

Link to the section One machine, on purpose

There is no staging and no failover. What breaks the server breaks every site at once, and nothing repairs itself. That constraint keeps the system small enough to understand completely, so every change is verified rather than assumed.

A project is a folder

Link to the section A project is a folder

A project exists because /srv/sites/<slug> exists on the server. Caddy's wildcard block serves <slug>.<zone> from that folder by name. There is no database of projects, and adding one changes no shared file.

KindDeclares in sitesolide.jsonGets
Static sitepublicDir, no startFiles Caddy serves. Nothing runs.
Appstart, or servicesA systemd unit per service and a Caddy block. 8 to 40 MB of memory.

deploy generates the units and the block from the manifest every time, and validates the new block with every block in service. They live on the server alone. An app can also run workers and scheduled jobs.

Helpers with one job each

Link to the section Helpers with one job each

Changes on the server go through small root-owned helpers. Each one may do one job, and nothing more.

HelperIts one job
StewardJudges every change against the access registry, writes secrets and restarts services.
GatekeeperChanges one site's general access, reloads Caddy, probes the site and rolls back on failure.
InstallerDeploys one project for a token, reading its archive as the project's own account.
CollectorReads the server on a timer and leaves a snapshot for the dashboard.
Backup runStores the hourly snapshots that each project's own account hands it.

The dashboard holds no power

Link to the section The dashboard holds no power

The dashboard runs under its own unprivileged account. It cannot open another project's files or reach other projects' services. What it shows comes from the collector's snapshot, and every change it asks for goes to the steward, which judges it. A compromised dashboard leaks only what its pages already showed.

The server is the source of truth

Link to the section The server is the source of truth

A deployed project's general access and its secrets are what the server carries, not what the repository says. The CLI reads the server first, and refuses to contradict it. deploy never pushes a secret: it checks that each one exists, and points to the dashboard when one is missing.

Limits

Link to the section Limits
  • No zero-downtime deploys, no code rollback. See what a deploy costs.
  • No failover. When the server is down, every site is.
  • No automatic reboots. Security updates install every day, but a new kernel waits for you to reboot.
  • No offsite backups by default. Snapshots stay on the server's disk until you configure a bucket.

Related

Link to the section Related