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
apiscope.
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
repoandadmin: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 servingpublic/, 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 hasoutput: "standalone"(a much smaller image), elsenext startover the whole build. - astro: the same install and build, then port 4321: the
@astrojs/nodeadapter's server (modestandalone) when the build made one, elsedist/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 pathindex.htmlfor the app's router. The template setsVITE_APP_URLfrom 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.