Levelrail Pages: host static sites from git on your own server, with rollback

[thegdsks]

If you have pushed a folder of HTML to GitHub Pages or Cloudflare Pages, you know the workflow Levelrail Pages follows: point at a repo, get a site on a domain with TLS, undo a bad push. What changes is where it runs. Pages is served by the Caddy ingress embedded in your own control plane, on your own Linux box. There is no container, no registry and no build image involved.

Below: what a Page is, how to deploy one, what a deploy looks like, how rollback and delete behave, and a checklist for moving a site off GitHub Pages. The workflow is simple. You build the site in CI (or commit the output), and Levelrail publishes the finished files.

Contents

• What Pages is
• How it compares
• Deploy a site
• The deploy lifecycle
• Domains and TLS
• Rollback
• Deleting a Page
• Limits
• Migrating from GitHub Pages
• Troubleshooting
• Links and next steps

What Pages is

A Page is an app whose build.type is static. Levelrail fetches your repository, copies the directory you name into a folder on the control plane keyed by service and commit, and points your domains at it. Nothing runs per site. No container starts, no port gets allocated, no process needs watching. Caddy's file server, inside the same binary as the control plane, answers the requests.

In practice a static site costs disk and nothing else. TLS and domain routing work exactly as they do for container apps, and because every deploy lands in its own commit-named folder, keeping old versions around for rollback is cheap.

Note

The workflow: build the site wherever you like (CI, your laptop), put the finished HTML in a directory or branch, and let Levelrail publish that directory. There is no build step on the Levelrail side for static. Details under Limits.

How it compares

Every cell for GitHub Pages and Cloudflare Pages comes from their official docs, linked in the row. Where I did not confirm something, the cell says "see docs" rather than guessing.

	Levelrail Pages	GitHub Pages	Cloudflare Pages
Where it runs	Your own server, via embedded Caddy	GitHub's hosting	Cloudflare's hosting
Build step	None for static; deploy finished files	Optional build process (about); a custom Actions workflow is also possible (limits)	see docs
Custom domains	Listed under domains, automatic Let's Encrypt TLS	Supported (guide)	Up to 100 per project on Free (limits)
Site size	Disk on your server; no hard limit in the docs	Published site no larger than 1 GB (limits)	25 MiB per file, 20,000 files on Free (limits)
Bandwidth	Whatever your server and network give you	Soft limit of 100 GB per month (limits)	see docs
Rollback	Re-publish an earlier deploy, checked by content digest	see docs	Instant rollback to a previous production deployment (docs)
PR previews	Not documented for Pages	see docs	Unique URL per pull request (docs)
Custom headers	Not documented for Pages	see docs	_headers file, max 100 rules (limits)
SPA fallback	Not documented; the docs say rewrites are not configured	see docs	Serves / for unknown paths when there is no top-level 404.html (docs)

Cloudflare Pages is ahead on pull request previews, headers files and SPA routing. Levelrail Pages wins on placement: the site sits on hardware you control, next to your apps and databases, with the same dashboard, domains and rollback history as everything else you run.

Deploy a site

Put an app.yaml in the repo. For a site whose finished output lives in dist/:

version: 1
services:
  web:
    build:
      type: static
      path: ./dist
    domains:
      - example.com
      - www.example.com

path is optional and defaults to the repository root. It must be relative and point to a directory that exists in the repo. A static service cannot set port, host_port or bind_address, since there is no container to route to, and hooks, jobs and egress are rejected for the same reason. The full field list is in the app spec reference.

Validate locally with no API call, then create the app:

levelrail-cli apps validate --file app.yaml

levelrail-cli apps create --name my-site --file app.yaml --service web \
  --repo https://github.com/you/your-site.git --ref main

For build.type: static the CLI needs a repo and ref (--ref defaults to your current branch, then main) and refuses image-oriented flags such as a port or --image-repo. In the dashboard, open the New wizard and pick the Git repository card.

If your generator is Hugo, Vite, Jekyll or a Next.js static export, run it in CI, commit or push the output to a branch such as deploy, and give --ref that branch. Levelrail then publishes exactly the files you built.

• Add app.yaml with build.type: static to your repo
• Run levelrail-cli apps validate --file app.yaml
• Point your domain's DNS at the server
• Create the app and watch the first deploy
• Open the domain and check the padlock

The deploy lifecycle

A static deploy skips the container pipeline. It goes through these stages:

flowchart LR
  A[Push or manual deploy] --> B[Fetch source]
  B --> C[Publish to file server]
  C --> D[Route goes live in embedded Caddy]
  C --> E[Content digest recorded]
  E -.->|enables| F[rollback-to]

Loading

The dashboard shows two steps, Fetch source and Publish to file server. With no container there is no readiness gate or health check, so the deploy settles as soon as the files are published and the route points at them. The digest recorded on the deploy is what later makes rollback safe.

Inspect a deploy from the CLI:

levelrail-cli apps deploys list my-site
levelrail-cli apps deploys steps my-site <deploy-id>
levelrail-cli apps deploys logs my-site <deploy-id>

When a deploy fails, say because build.path does not exist in the repo, the previous version stays live until you fix it and push again.

Domains and TLS

Domains behave as they do for container apps. List them in the spec, or manage them from the CLI:

levelrail-cli apps domains list my-site
levelrail-cli apps domains add my-site docs.example.com

Each domain gets an automatic Let's Encrypt certificate, renewed by the ingress. A domain can belong to only one service across the spec. For verification, wildcards and running behind an existing proxy, see Domains and ingress.

Rollback

Each deploy records a hash of the published tree. To roll back to a past succeeded deploy:

levelrail-cli apps deploys rollback-to my-site <deploy-id>

Or click Rollback on an earlier deploy in the Deployments view. Rollback is a re-publish, not a rebuild: Levelrail checks the files still on disk against the digest that deploy recorded, points the site back at them and records a new succeeded deploy so the history shows what happened. It can refuse in two ways:

Response	Meaning	What to do
409 Conflict	The target is not a succeeded static deploy with a recorded digest, or the files on disk no longer match the recorded content (the tree changed)	Redeploy from source
410 Gone	The published files of that deploy are no longer on disk	Redeploy from source

Both messages tell you to redeploy from source. That is the point of the digest: a rollback restores exactly what that deploy served, or it refuses. It never serves a quietly different tree.

Deleting a Page

Deleting the app removes the site, its published files and its route right away:

levelrail-cli apps delete my-site

There is also a direct route for sites that outlived their app:

levelrail-cli static-sites list
levelrail-cli static-sites delete my-site
# same as: DELETE /api/v1/static-sites/my-site

static-sites delete removes a site's published files, domains and route. While the app still exists it answers 409, with the message to delete the app instead. An unknown name answers 404; success is 204 No Content.

A background sweep also removes static sites that have no app and no queued or running deploy, once they are older than a grace period. That protects a site whose app is still being created. The grace period defaults to 10 minutes. Set APP_STATIC_ORPHAN_GRACE to a Go duration such as 1h to change it. An empty, 0, unparseable or negative value falls back to the 10 minute default (the last two also log a warning).

Where this lives in the source

• Deploy: internal/deploy/static.go, static_publish.go, static_remove.go
• Rollback checks: internal/api/deploy_rollback_static.go
• Delete route: internal/api/static_sites_delete.go
• Sweep config: cmd/levelrail/preview_limits.go

Limits

• Build in CI, publish the output. build.type: static deploys finished files. Run Hugo, Jekyll, Vite or a Next.js static export in CI, commit or push the output, then point build.path (and --ref) at it.
• Port and container features. port, host_port, bind_address, hooks, jobs and egress are rejected on a static service, because nothing runs.
• Rewrites. The docs say URL rewrites and sophisticated routing are not configured on the file server. For an SPA fallback or redirects, test your routes before cutting over, or run a small container service for that site.
• Size. The docs set no hard limit. Trees over about 1 GB deploy and roll back more slowly, so keep an eye on disk under the data directory.

Migrating from GitHub Pages

• Commit built output, or have CI push it to the branch you will deploy
• Add app.yaml with build.type: static and the right build.path
• Stop relying on a CNAME file: domains now come from the domains list
• Check links that depended on a github.io project path prefix
• Test deep links and your 404 page, since rewrites are not documented
• Lower the DNS TTL, deploy, verify on the new server, then switch records
• Keep the old site up until the certificate is issued and a rollback has been rehearsed once

Troubleshooting

Symptom	Likely cause	Fix
Validation fails on port	A static service must omit port	Remove port, host_port and bind_address
Deploy fails at Fetch source	Bad repo URL, ref or credentials	Check --repo and --ref; read apps deploys logs
Deploy fails at Publish	build.path missing in the repo	Fix the path; the old version stays live
Rollback returns 410	Published files are gone	Redeploy from source
Rollback returns 409	Tree changed, or target was not a succeeded static deploy	Redeploy from source
static-sites delete returns 409	The app still exists	Run apps delete instead
Site files vanished while the app was being recreated	Orphan sweep ran after the grace period	Raise APP_STATIC_ORPHAN_GRACE

Links and next steps

• Pages docs: https://docs.levelrail.com/pages
• App spec reference: https://docs.levelrail.com/app-spec-reference
• Domains and ingress: https://docs.levelrail.com/domains-and-ingress
• CLI reference: https://docs.levelrail.com/cli-reference
• Install: https://docs.levelrail.com/installing
• Source and issues: https://github.com/glincker/levelrail

If you move a site over, tell me in the comments what you migrated and what tripped you up, especially anything you relied on in GitHub Pages or Cloudflare Pages that is missing here. A star on the repo helps other people find it.