Deploying

Apps built from git

stackd builds apps from a GitHub or GitLab repo (gitlab.com or self-hosted) and deploys each build, on every push if you like. A repo with its own Dockerfile is built as it is; one without uses a build template for Laravel, Next.js, Astro or Vite.

Pull requests can get their own preview apps too (Preview environments).

Connecting an account

Settings → Builds connects an account, two ways. Either way its access is kept sealed, and an account can't be removed while apps are built from it.

OAuth, with a click. An admin registers an OAuth application once per provider (GitHub, gitlab.com, each self-hosted GitLab):

  • on GitHub, an OAuth app, under your account or an organization;
  • on GitLab, an application (user, group or instance), confidential, with the api scope.

Its callback URL is the panel's /git/callback; Settings shows it. Enter its ID and secret in Settings → Builds (POST /api/git/oauth-apps; posting again replaces them). Then click "Connect with GitHub" (or GitLab) and approve on the provider's page, which asks for repo and admin:repo_hook (GitHub) or api (GitLab).

GitHub's OAuth tokens last until revoked; GitLab's are renewed by stackd as needed. If the provider refuses (the app was revoked or its secret changed), the account shows a token error and Settings offers to reconnect it. An organization restricting OAuth apps must approve the app before its repos show.

An access token. POST /api/git/accounts with the token, checked before it's kept:

  • GitHub: a fine-grained token with Contents and Metadata read, Webhooks read/write and Commit statuses read/write, or a classic one with repo and admin:repo_hook.
  • GitLab: api.

Adding a token for an account connected with OAuth replaces its OAuth access.

Where images go

Builds need an object store, set in Settings → Builds (PUT /api/settings/builds). stackd makes a bucket there, stackd-registry, and runs a registry on every online server that every server pulls built images from. It listens on 127.0.0.1:5443 only, so servers need no configuration and nothing outside the server can reach it. A built image is deployed only to servers whose registry is up.

An app's repo

An app is built from a repo when it has a source: account, repo, branch, directory (for a repo holding several apps), Dockerfile path, and optionally a build template. POST /api/apps takes it as source (and no image), checks the branch can be read, and starts the first build; PUT /api/apps/{id}/source changes it, DELETE stops building (the app keeps its last image).

The repo's own Dockerfile is used when it exists. Otherwise the build template's:

  • laravel: Composer packages (no dev), Vite assets when there's a package.json, nginx with PHP-FPM 8.5 serving public/, with the extensions Laravel hosts ship (pdo_mysql, pdo_pgsql, redis, intl, gd, imagick, exif, zip, bcmath, pcntl, opcache). Logs go to stderr. Port 80. laravel-octane has the same extensions on FrankenPHP.
  • nextjs: the packages with the repo's package manager, picked by its lockfile (npm, pnpm or Yarn through Corepack, or Bun), npm run build (or that manager's), and on Node 24, port 3000: the standalone server when next.config has output: "standalone" (a much smaller image), else next start over the whole build.
  • astro: the same install and build, then port 4321: the @astrojs/node adapter's server (mode standalone) when the build made one, else dist/ served as a static site (clean URLs, 404.html).
  • vite: the same install and build, then dist/ on port 8080 as a single-page app: files that exist as they are, any other path index.html for the app's router. The template sets VITE_APP_URL from the domain.

They run any other command as it is (processes, a release command), and bake the app's VITE_*, NEXT_PUBLIC_* or PUBLIC_* variables in at build time (Processes and release commands). There are app templates for each of them too.

Builds

POST /api/apps/{id}/builds builds the branch's head (or a commit), deploying it once built unless deploy: false. A build runs on one of your servers, the app's previous builder when it can (an unchanged rebuild then takes seconds), and goes through cloning, building and pushing before it succeeds and is deployed. Repo Dockerfiles can use BuildKit features (cache mounts, ADD --chmod, # syntax=).

The build's output (its last megabyte) is shown on the build, with the token masked.

A newer build of the app cancels one still running; POST /api/builds/{id}/cancel stops one. A build whose server's agent restarted is marked failed after a minute.

What's kept

An app keeps its newest 50 builds (what its builds list shows), every build from the last 30 days, its newest succeeded one, any still running, and any whose image is still in use or a rollback's target. Older ones are pruned hourly, their output with them. The images stay in the registry either way.

On each server, images stackd built or pulled from its registry are cleaned up every six hours: those past a week old, beyond the newest three of each repository (kept for rollbacks).

Freeing disk now

A server's Danger zone can purge unused images (POST /api/servers/{id}/purge-images): every image no container there uses, running or stopped, goes, rollback ones and images stackd didn't make too, then dangling ones. An image made or pulled in the last hour stays, since a deploy may be about to start it, and one in use by a container is never removed. A rollback then pulls its image from the registry again. The answer says how many images went and the disk freed. The panel waits 50 seconds; a purge still going then finishes on the server. Agents before 0.13.9 don't support it.

Deploy on push

With a public URL (STACKD_PUBLIC_URL) and deploy on push, stackd adds a push webhook to the repo pointing at POST /api/hooks/apps/{id}, with a secret of its own. A push to the app's branch starts a build that deploys; other branches, tags and pings are ignored. Removing the source or the app removes the webhook.

Commit statuses

Each build's commit shows how it went on GitHub or GitLab, as a status named stackd: <app> (a pull request's checks, the commit list), linking to the app in the panel when STACKD_PUBLIC_URL is set:

Build Status Description
queued, building pending (GitLab: running) Queued, Building
failed failure Build failed: why
cancelled error (GitLab: canceled) Cancelled: why
succeeded, not deploying success Built
succeeded, deploying pending Built; deploying
its deploy up success Deployed
its deploy failed failure Built, but the deploy failed
its deploy unsettled after 30 minutes error Built, but the deploy didn't finish

A build whose deploy never starts (a template's app waiting on its databases) shows Built after ten minutes. A preview's builds report under the preview app's name. A token without permission to write statuses only logs a warning; the build carries on.

Limitations

  • Builds run on the servers that run apps; a large build competes with them for CPU and memory.
  • One registry bucket per panel; changing the object store leaves earlier images in the old one, so apps need a new build.
  • No build-time secrets or variables yet.