Deploying
Create a project, deploy it from a checkout or a Git URL, configure it, scale it, read its logs and roll back.
Signed in to your workspace with shpyrd login (see Getting started), the CLI speaks the workspace's API: on shpyrd cloud there is nothing else to set up. On a cluster you run yourself, a kubeconfig named on the command line (--context) makes it go through the cluster instead.
Create a project
shpyrd projects create "My Service" # slug my-service: a namespace of its own (p-<id>) + App resourceshpyrd projects create "My Service" --save # also writes shpyrd.yaml (project: my-service, plus what the directory's build profile implies)The name is free text. The slug derived from it (lowercase letters, digits and dashes, max 40 characters; --slug chooses it) becomes the address: on shpyrd cloud https://<workspace>-<slug>.shpyrd.app, such as https://acme-my-service.shpyrd.app; on a cluster you run, https://my-service.<domain>. shpyrd projects rename --slug changes it later; the old address redirects for 30 days.
A new project asks its visitors to sign in: only people with a role on it can open the app, and the app receives who they are. For a site anyone may open, create it with --public or switch later with shpyrd access set public. See Sign-in for your app.
From the catalog
A project can also be made from the catalog: applications ready to run, such as an agent framework or a CRM, each described by an entry that says where its code lives, how it runs and what it asks at install.
shpyrd catalog listshpyrd catalog show fluxyrshpyrd catalog install fluxyr --input OPENROUTER_API_KEY=sk-or-... # --slug, --name, --revision v1.2.0The install makes the project with what the entry says (processes, build settings, plain variables), its disks and resources, sets the inputs as config vars (secrets as secrets, a value marked generate made at install), and sets the source: the upstream repository on the entry's branch, which the project follows from then on as any git project does, or the tag --revision pins. An entry may lay files over the upstream checkout before the build, a Dockerfile for a project that has none; that goes with a Dockerfile build, since the buildpacks builder reads one source. The project is marked with the entry it came from (catalogEntry in its summary).
The catalog is a repository of entry folders (shpyrd-io/catalog), each a shpyrd.yaml with the keys of a project's own under a catalog block, published by its CI as an index over HTTPS. A server reads shpyrd's unless SHPYRD_CATALOG_URL names another, a fork or a private catalog, or off. shpyrd catalog validate <dir> checks a folder of entries and shpyrd catalog publish <dir> --out public writes the index.
Deploy
From inside your repository:
shpyrd deploy # app from shpyrd.yaml, or --project my-serviceWhat happens:
- Archive. The committed tree of the current directory (
git archive HEAD) is packed; run it from a subdirectory to deploy just that service of a monorepo. Uncommitted changes are not included unless you pass--working-tree(also chosen automatically when nothing in the directory is committed yet). Outside a Git repository the directory is tarred, without.gitandnode_modules. - Upload. The archive is sent to your workspace over its API (self-hosted, with
--context: through the Kubernetes API server). - Build. In the cluster, with the Paketo buildpacks (kpack), the default, or, when the directory has a
Dockerfile, with BuildKit (When a Dockerfile is justified); the CLI streams every step. - Release. The controller rolls the new image out process by process and prints the release number and URL.
==> Archiving HEAD:examples/hello (654f4925638e)==> Building with buildpacks==> Uploading source (2.6 KiB) archive 3f1c2a9b7d04==> Building===> prepare===> detect4 of 9 buildpacks participating===> build web (default): /layers/paketo-buildpacks_go-build/targets/bin/web worker: /layers/paketo-buildpacks_go-build/targets/bin/worker===> export==> Releasing Deploying: Releasing v3: web 1/3 updated · worker 0/1 updated Running: web 3/3 · worker 1/1Released v3: Deploy 654f4925638ehttps://acme-hello-world.shpyrd.appOther sources:
shpyrd deploy --git https://github.com/org/repo --ref main --path services/api # every push to the branch deploysshpyrd deploy --image ghcr.io/org/repo:1.4.2 # run a prebuilt image, no buildshpyrd deploy --no-wait # do not follow the buildDeploying from Git is also available in the dashboard (Deploy button, or when creating the project).
Private repositories
A build clones your repository. For a private one, give shpyrd access in one of two ways. Both need you signed in (shpyrd login).
On GitHub, the simplest way is to connect GitHub once for the workspace: no key or token per project. The two ways below work on any git host, and on GitHub too when a repository is not in a connected account.
A deploy key for the project. Works on any git host. It is read-only and opens one repository.
shpyrd git-auth deploy-key --project shopshpyrd makes the key for the host of the project's repository and prints its public half. A project with no git repository yet needs the host: shpyrd git-auth deploy-key --project shop --host github.com. Add it to the repository as a read-only deploy key (on GitHub: Settings, Deploy keys, Add deploy key, with write access off). Then build again with shpyrd redeploy --project shop: a shpyrd deploy of the same source sees nothing changed and does not build. A new deploy-key replaces the old one, and shpyrd git-auth deploy-key --project shop --remove deletes it. Remove it from the repository too.
A token for a host. Set once by a workspace admin; every project of the workspace that clones from that host uses it.
shpyrd git-auth set --host gitlab.example.com --token - # reads the token from stdinshpyrd git-auth list # hosts, never valuesshpyrd git-auth unset --host gitlab.example.comshpyrd sends a user name with the token. The default is x-access-token, oauth2 on gitlab.com and x-token-auth on bitbucket.org. Another host may want another one: pass --username.
Mind who can read a token. Every project of the workspace that clones from the host uses it, and project developers with cluster access can read its value from their project's namespace. Use a read-only token limited to the repositories the builds need, and prefer deploy keys for anything sensitive.
If a project has both, the deploy key wins, as long as it is for the repository's host. shpyrd git-auth show --project shop says which credential its builds use.
When the repository URL is not in the form the credential needs, shpyrd converts it: SSH for a deploy key, HTTPS for a token. A URL already in that form is used as given. A git URL it cannot parse, such as git://, builds as before, without credentials.
Values are write-only: shpyrd never shows a token or a private key again.
The host key. When the deploy key is made, shpyrd records the git host's SSH host key. Dockerfile builds check it and refuse a host that presents another. Buildpack builds clone with kpack, whose git client does not check the host key.
When access is refused. A clone that the host refuses for access fails the build, and the message names shpyrd git-auth. Once access is given, shpyrd redeploy builds the same source again.
Deploying on push
A project that deploys from a git branch deploys every push to it. shpyrd
reads the branch's latest commit and builds that commit, never the branch
itself, for buildpack and Dockerfile builds alike. Each release names its
commit: Push a1b2c3d by alice: fix login, or Commit a1b2c3d (head of main) when shpyrd read the branch itself.
With a webhook: within seconds. Each project has a webhook URL and a secret. Add them to the repository:
shpyrd git-hooks show --project shop # the URL, the secret, and where they goshpyrd git-hooks rotate --project shop # a new URL and secret; the old ones are refused- GitHub: the repository's Settings, Webhooks, Add webhook. Payload URL: the
URL; Content type:
application/json; Secret: the secret; "Just the push event". - GitLab: the project's Settings, Webhooks, Add new webhook. URL: the URL; Secret token: the secret; Trigger: Push events.
- Gitea: the repository's Settings, Webhooks, Add webhook, Gitea. Target
URL: the URL; Content type:
application/json; Secret: the secret; Trigger on: Push events.
The dashboard shows the same under the project's Summary, Deploy on push. Only people who may change the project see the secret.
Without one: pushes do not deploy. On a GitHub repository the shpyrd GitHub App covers, there is nothing to set up: see Connect GitHub. On another host, shpyrd does not check the branch on a timer: until the project's webhook is set up, a push deploys only when someone deploys (the dashboard's Deploy, or shpyrd deploy), which reads the branch and builds its latest commit. The Source block says which: "Pushes do not deploy until its webhook is set up. Deploy to build the branch's latest commit.", or "Deploys on push through its webhook (last delivery 3 days ago)." A repository shpyrd cannot read says why on the project, with the shpyrd git-auth command that fixes it, and shpyrd tries again by itself.
Skipping a commit. A commit whose message says [skip deploy] (or
[deploy skip], in any case) is recorded and not deployed, also when a
later check finds it at the head of the branch. The next commit deploys as
usual. This works when the push reaches shpyrd by webhook: a check of the
branch cannot read commit messages, so a project that relies on checking
deploys the commit anyway.
Auto-deploy off. To record pushes without deploying them:
shpyrd deploy --git https://github.com/org/repo --no-auto-deployor switch Auto-deploy off under the project's Summary. The project shows
the latest commit it has not deployed; a deploy deploys it, and so does
switching auto-deploy on again, at once and without waiting for the next
check: the release says Commit a1b2c3d (auto-deploy on). A commit that
asked to be skipped stays skipped. A deploy that names neither --auto-deploy nor
--no-auto-deploy keeps the project's setting.
What runs. A --ref that is a branch or a tag is followed; a tag's
commit is the one it points at. A --ref that is a commit (7 to 40
hexadecimal characters) is built as given, and nothing is followed. A
deploy reads the branch again at once. If the branch is deleted, what runs
keeps running, and the project says so.
The first time a project on a branch is built this way after an upgrade, it
builds once more, the same code: the build now names the commit instead of
the branch. A project already deployed from a branch that shpyrd cannot read
keeps building the branch as before, and says why it cannot read it. A URL
with a user name and password in it (https://user:pass@host/org/repo)
still works without a token: shpyrd reads the branch with them, and never
shows them.
Connect GitHub
A workspace connects GitHub once. Then anyone who makes projects picks a repository from a list: private ones build without deploy keys or tokens, and every push to a project's branch deploys, with no webhook to add.
Connect an account or organisation (workspace admins): in the dashboard, Workspace settings, Git, Connect GitHub. GitHub asks who you are, then shpyrd lists the installations of its App you own: Connect the one you want, and you are back on the workspace's page. To put the App on an account it is not on yet, use Install the App on another account, on the Git page or under that list: GitHub asks where to install it and which repositories it may read, then sends you back. From a terminal, shpyrd github connect opens that Git page and waits until the new connection appears; you press the button there.
shpyrd github connect # opens the Git page, waits for the connectionshpyrd github list # the workspace's connectionsshpyrd github disconnect acme # forget one; the App stays installed on GitHubOnly an owner of the GitHub account can connect it: an owner of the organisation, or, for a personal account, that account itself. Nobody else can connect it with a copied link. Several workspaces can connect the same account or organisation, each by an owner: a push deploys the projects on that repository in every one of them, and disconnecting it in one leaves the others connected. Manage on GitHub opens the installation's settings, where you add repositories, suspend it or remove it.
Link your GitHub account. Each person links their own GitHub account once, in a browser session. In New project, From GitHub shows Continue with GitHub: GitHub asks you to authorize the App in a small window, and the dialog keeps what you typed. While it waits, the dialog offers Not finished? Try again and Cancel. Once linked, the bottom of the picker shows GitHub: paezao with Unlink, which asks before it unlinks. From a terminal, shpyrd github link opens the browser and waits, shpyrd github unlink unlinks, and shpyrd whoami shows the account. An API token can read the link and unlink it, but cannot link: linking needs a browser. An API token acts as the person who made it, so an agent with your token picks what you can pick. The admin token is not a person and has no link.
Make a project from a repository: New project, From GitHub, pick the account (the workspace's accounts your GitHub account can see), filter the list, pick the repository and the branch (its default branch first). The list shows only the repositories you can read on GitHub; a list cut short says "Showing the first N. Filter to narrow." Can't find a repository? opens the account's installation on GitHub, where repositories are added; Add GitHub account or organisation connects another (workspace admins; others are told to ask one). Or find it with shpyrd github repos --filter shop and deploy it as any git repository:
shpyrd deploy --git https://github.com/acme/shop --ref main --project shopWho can pick what. For a private repository on github.com whose owner the workspace has connected through the GitHub App (a live installation, not a suspended one), making a project, deploying with a changed repository URL, and restoring an archived project check that you can read the repository on GitHub (for a token, the person who made it). If you cannot, shpyrd answers 403 "You can't read acme/shop on GitHub, or the GitHub App's installation on acme does not include it", or asks you to link your account first. If you can, but the installation does not include the repository, it answers 422 "The GitHub App's installation on acme does not include acme/vault: add it to the installation on GitHub, or give shpyrd a deploy key (shpyrd git-auth deploy-key)". A public repository needs no link, and neither does a private repository of an owner the workspace has not connected: that one builds with a deploy key or a token, which have their own access. The admin token, tokens it made, the operator's kubeconfig access, and a server run without sign-in are no person and are not checked. A redeploy of the same repository is not checked. While the project's Source block reads "Deploys on push through the GitHub App", it shows who connected it ("Connected by paezao"). Builds, webhooks, checks and Deployments go through the workspace's installation, never through your account: when you unlink or leave the workspace, your projects keep deploying.
What shpyrd keeps. GitHub's user token for the App can do only what both you and the App may do. Its access token lives in the platform's memory only. Its refresh token is stored encrypted (AES-256-GCM), under a key in the Secret shpyrd-token-key, apart from the database. Unlinking revokes the token on GitHub. A refresh token GitHub no longer accepts (unused for 6 months, or revoked) removes the link, and New project asks you to link again; so does a new token key. To rotate the key, an operator deletes that Secret and restarts every server replica together; people then link again. Linking needs the App's user tokens to expire: with "Expire user authorization tokens" off in the App's settings on GitHub, linking is refused and says so.
How builds reach it. For a repository on github.com whose owner the workspace has connected, every build and every check of the branch uses a token the App gives for that one repository, read-only, that lasts an hour; shpyrd renews it every 50 minutes. The App comes first, then the project's deploy key, then the workspace's token. shpyrd skips the App for a suspended installation, a repository the installation does not include, an installation that is gone, and while GitHub is failing (it asks again after a pause). A token already issued is kept through a short GitHub outage. shpyrd git-auth show --project shop says through the GitHub App (acme), and so does the Source block of the project's overview.
Pushes arrive through the App's own webhook, with nothing to set up per project: shpyrd git-hooks show says so. A repository the App covers is never checked on a timer. Every 5 minutes shpyrd asks GitHub to deliver again whatever push, CI result or installation event did not reach it (GitHub keeps deliveries three days), so a missed delivery deploys within about 5 minutes. A delivery GitHub never made is not caught: push again, or Redeploy. A suspended installation's pushes do not deploy. [skip deploy] and auto-deploy work as in Deploying on push.
When the App cannot read a repository. shpyrd tries the deploy key and the token. When nothing gives access, the project says why, starting with the App's reason ("The GitHub App's installation on acme does not include shop: add the repository to it on GitHub."), and what runs keeps running.
On shpyrd cloud the App is already set up; on a self-hosted platform an operator registers it once: see Installation.
Checks and Deployments on GitHub
For a repository the GitHub App covers, GitHub shows what shpyrd does with each commit. A check named shpyrd / <project> appears on the commit: Building, then Deploying, then Running at the app's address, or Failed with the last lines of the reason. Its Details link opens the project in the dashboard. A commit that waits for CI shows Waiting for CI. A commit that was not deployed, that asked to be skipped, that a newer commit overtook, that a newer pin replaced, or that a rollback or a deploy by image overtook before it was deployed shows a neutral check that says why ("Replaced by a1b2c3d", "Superseded by a1b2c3d", "Not deployed: rolled back to release 3").
Each release that changes the code is also a GitHub Deployment, in an environment named after the project, with a link to the app once it runs. A rollback to an older commit is a Deployment too. A Deployment that was still unfinished when a newer release replaced it is marked inactive. A release that only changes config vars or sizes gets no Deployment, and never changes a check that is finished. Two projects on one repository each get their own check and their own environment.
The check and the Deployment never hold a deploy back: when GitHub is down or refuses a write, shpyrd deploys as usual and sends what it owes later. A suspended or removed installation reports nothing. When shpyrd stops reporting on a project (it no longer follows a branch on github.com, for one), its unfinished checks and its unfinished Deployment are closed. When the App stops covering the repository, they are closed too while shpyrd still holds a token for it; otherwise they stay as they were.
An installation made before the App asked for checks, statuses and Deployments has to accept the App's updated permissions on GitHub; until it does, nothing is reported, and a commit that would wait for CI is not deployed (below).
Wait for CI
With Wait for CI on, a pushed commit deploys only once every other check and commit status on it passes, all except shpyrd's own. Switch it on under the project's overview, in the Source block, or:
shpyrd deploy --git https://github.com/acme/shop --wait-for-ci # --no-wait-for-ci switches it offThat command is your own deploy, and yours never waits: it deploys the branch's head now, and the setting applies from the next push. To switch it on without deploying, use the switch in the Source block.
The Source block says "Waiting for CI on a1b2c3d (since 2 min)" meanwhile, and shpyrd projects info prints Commit: a1b2c3d waits for CI (since 2m). Then:
- They pass: the commit deploys; its release says
Push a1b2c3d by alice: fix login (CI passed). - One fails: the commit is not deployed, and the project says which check failed: the Source block, "a1b2c3d not deployed: CI failed (test)";
shpyrd projects infoand the check on GitHub, "CI failed: test". Re-run it on GitHub: if it passes while the commit is still the branch's newest, it deploys. - None reports within a minute: the commit has no CI, and it deploys (
… (no CI)). A CI that reports later than a minute after the push may lose that race. - Still pending an hour later: the commit is not deployed ("CI did not finish within an hour"). It is not tried again by itself.
- A newer commit arrives: it replaces the waiting one at once.
- GitHub does not answer: the commit keeps waiting, and the hour keeps counting. It is never deployed unchecked.
- The App stops covering the repository: a waiting commit stays held and ends "CI could not be read: the GitHub App no longer covers the repository".
- The installation has not accepted the App's updated permissions: the commit is not deployed, at once: "CI could not be read: accept the GitHub App's updated permissions on GitHub". Accept them on GitHub; the next push waits for its CI again.
shpyrd learns of results through the App's webhook, and checks a waiting commit every 2 minutes in case a delivery is missed (the projects on one repository share what GitHub said for 90 seconds). A deploy by a person (shpyrd deploy, Redeploy, a rollback) and the first commit of a new project do not wait. Turning auto-deploy back on sends the commit that was waiting through watch paths and wait for CI like any other.
Watch paths
Watch paths deploy only the commits that change certain files: in a repository that holds several services, each project deploys its own. They are patterns from the repository root, one per line:
services/api!**/*.md* matches within one folder and ** across any number of folders. Patterns start at the repository root, with or without a leading /: *.md matches only Markdown files in the root, and **/*.md matches them anywhere. A pattern that names a folder (services/api) covers everything below it; services/api/ matches only what is below it. Character classes such as [a-z] work. A leading ! excludes. Patterns run in order and the last one that matches a file decides it: the two above deploy any change under services/api except Markdown. A project takes up to 20 patterns of up to 200 characters; a pattern shpyrd cannot read is refused when it is set.
Set them under the project's overview, in the Source block, or:
shpyrd deploy --git https://github.com/acme/monorepo --watch-path 'services/api' --watch-path '!**/*.md'shpyrd deploy --git https://github.com/acme/monorepo --no-watch-paths # every commit deploys againA commit that changes nothing in them is recorded, not deployed (the Source block and shpyrd projects info say "a1b2c3d not deployed: no changes in the watch paths"; the check on GitHub says "No changes in the watch paths"). The files counted are everything changed since the commit that runs, so a commit that was not deployed still counts once a later one matches, and a renamed file counts under its old name and its new one. When GitHub's list of changes cannot be trusted (300 or more files changed, the branch's history was rewritten, GitHub's compare failed, or GitHub is not answering), the commit deploys, and its release ends with "(watch paths not checked: …)", naming the reason.
Watch paths and wait for CI work through the GitHub App. On a repository the GitHub App doesn't cover (another host, an owner the workspace hasn't connected, or a repository the installation doesn't include) they are kept but do nothing: the dashboard says "Needs the GitHub App" and lets you only switch wait for CI off and clear the watch paths, and shpyrd deploy says so when it sets them.
Buildpacks: languages, stacks and system packages
The Paketo buildpacks detect the language from the repository and do the right thing for the common case. A few patterns need hints they cannot guess; the CLI recognises those patterns in the directory and fills the hints in before the build (build profiles), saying what it inferred and why:
==> Detected static site (public/index.html and no language files) build.buildpacks=[web-servers], BP_WEB_SERVER=nginx, BP_WEB_SERVER_ROOT=public (shpyrd.yaml values win; --save writes these there)| The CLI sees | It infers |
|---|---|
public/index.html and no language files | the web-servers buildpack on nginx serving public/ |
vite in package.json, a build script, no start script | the web-servers buildpack building with Node and serving dist/ with single-page routing |
next in package.json | BP_NODE_RUN_SCRIPTS=build, NODE_ENV=production for the build |
config.ru | RACK_ENV=production (Sinatra 4 only permits real hostnames in production) |
config/application.rb | RAILS_ENV=production, RAILS_LOG_TO_STDOUT=1, the /up health check when the app routes it |
public/index.php | the PHP buildpack with nginx in front of PHP-FPM serving public/ |
an Aptfile with libvips, ImageMagick, ffmpeg, GDAL, OpenCV, Tesseract, Chromium... | build.stack: full (their dependency trees need the full run image) |
Anything written in shpyrd.yaml wins over an inferred value; a Dockerfile build takes none of the buildpack hints. shpyrd deploy --save (or shpyrd projects create --save) writes the inferred values into shpyrd.yaml — a new file, or the missing keys added to the existing one with its comments kept — so what runs is what is committed. Detection reads the local directory: --git and --image deploys get none of it.
The sections below are what the profiles write, for when the pattern is not one of these.
Static sites
A directory with only static files (HTML, CSS, JS) needs BP_WEB_SERVER or the web-servers buildpack cannot detect it:
# shpyrd.yamlbuild: env: BP_WEB_SERVER: nginx # or httpd BP_WEB_SERVER_ROOT: public # directory that holds index.htmlSingle-page apps (React, Vite)
A Vite project with no start script in package.json is served as a static site after npm run build. The Node buildpack would win detection (there is a package.json) and produce an image with no process to start. Use build.buildpacks to compose explicitly:
build: buildpacks: [web-servers] # Paketo web-servers: builds with Node, serves with nginx env: BP_NODE_RUN_SCRIPTS: build BP_WEB_SERVER: nginx BP_WEB_SERVER_ROOT: dist BP_WEB_SERVER_ENABLE_PUSH_STATE: "true" # HTML5 routingBuildpacks and stacks
build.buildpacks pins the buildpack group the project uses (names in shpyrd.yaml); build.stack chooses the base image. The full stack (jammy-full) carries more system libraries than the base (jammy, default) and is useful when a language extension needs a C library that is present on Ubuntu but not in Paketo's minimal base image:
build: stack: full # base (default) or fullLanguage versions
The version of the language comes from the app's own files, as it would on a laptop: the go line of go.mod, engines.node in package.json (or .nvmrc), .python-version, the ruby line of the Gemfile, require.php in composer.json. Without one, the buildpack takes its own default, which is not always the newest version. To choose it in shpyrd.yaml instead, set the buildpack's variable in build.env, such as BP_GO_VERSION, BP_NODE_VERSION, BP_CPYTHON_VERSION or BP_MRI_VERSION (Ruby):
build: env: BP_GO_VERSION: "1.26.*"The versions on offer are the Paketo buildpacks'. A new version of a language reaches them some days or weeks after its release, and the platform takes up new buildpacks by itself: nothing to install or upgrade. Until then, a build that asks for the new version fails, and the failure names the versions on offer. Ask for one of those, or build with a Dockerfile, which brings its own toolchain.
System packages (Aptfile)
An Aptfile in the repository root lists Ubuntu packages to install into the image, one per line:
# Aptfilelibvips42The CLI translates it to the format the heroku/deb-packages buildpack reads and composes it in front of the language's buildpack. No project.toml or explicit build.buildpacks needed.
# shpyrd.yaml not required for an Aptfile — the CLI detects itshpyrd deployMonorepos and workspaces
An app that is one package of an npm, pnpm or Yarn workspace deploys from its own folder:
cd apps/web && shpyrd deployshpyrd deploy finds the workspace's root above the folder (a package.json with workspaces, or a pnpm-workspace.yaml, that lists it), uploads the whole workspace and builds that package in it:
==> Detected a pnpm workspace at the repository's root; building apps/web in it build.workspace=apps/web (shpyrd.yaml values win; --save writes it there)The build installs what the package needs (its workspace dependencies included), with the package manager the root's lockfile says and the version its packageManager names, runs the package's build script, and starts it with its start script. Dev dependencies, the root's included, are removed from the image once the build is done; BP_KEEP_DEV_DEPENDENCIES: "true" in build.env keeps them. If the package needs its workspace dependencies built first, its build script says so, as it would locally (pnpm --filter @acme/ui run build && next build, or turbo run build --filter web). A Procfile in the package's folder, or at the workspace's root, replaces the start script. An Aptfile in the package's folder brings its system packages, before the root's.
A workspace package builds with buildpacks, even when the workspace's root has a Dockerfile. A Dockerfile in the package's own folder, or build.strategy: dockerfile in shpyrd.yaml, keeps a Dockerfile build, and then no workspace is detected. build.workspace can be written by hand, as the package's path from the workspace's root.
Release phase
When the image has a release process type — the Procfile line release: bundle exec rails db:prepare — the platform runs it before every new release rolls out. The rollout waits; a failure leaves the previous release serving and marks the project Failed with the reason.
# Procfilerelease: bundle exec rails db:prepareweb: bundle exec puma -C config/puma.rb==> Releasing Deploying: release phase: running /cnb/process/release Running: web 1/1Released v2: Deploy abc123def456The command's output streams into the deploy (release | ...) and stays in shpyrd logs --process release. shpyrd projects info <project> lists the process types, including release, and a pending or failed release phase; the project page shows the phase while it runs and, when it fails, the reason, the output and a Run it again button (shpyrd redeploy does the same: with a failed release command, a redeploy runs the command again rather than restarting instances that never rolled out).
Before the command starts, the CLI and project page show what it is waiting for: room on a machine, a new machine being added, network setup, or the image download. The message includes elapsed waiting time and, when known, the download size for large images. The same diagnostics appear for new instances during a rollout. Adding a machine usually takes a few minutes; keeping the app's image small also reduces the download time on a new machine. Once the container starts, the status shows the command running and its output follows.
The release command runs at the web process's size unless processes.release sets its own. Like a build, it does not count against the workspace's memory and CPU ceiling: it is a step of the deploy, so it can run while the app is awake, bounded by that size's limits. For Dockerfile images without a Procfile, declare the command in shpyrd.yaml (for buildpack images, this replaces the Procfile's release: line):
processes: release: command: ["python", "manage.py", "migrate"]Dockerfile builds
Buildpacks are the default and the recommended way to build. A Dockerfile is one more file to maintain: its base image, its toolchain and its security updates are yours, where a buildpack image takes the platform's. Add one only when buildpacks cannot build what the app needs.
When a Dockerfile is justified
- A language or runtime the builder does not have: Rust, Elixir or Erlang, Deno, Bun, Crystal, Haskell, Swift, Zig, or C/C++ compiled from source. The builder has Go, Node.js, Java (and other JVM languages), Python, Ruby, PHP, .NET and static sites.
- A language version the buildpacks do not offer yet, when waiting for it is not an option (Language versions).
- A system package that is not in Ubuntu's archive: a vendor's installer, a PPA, a library compiled from source. A package Ubuntu ships goes in an Aptfile instead.
- A base image the app must run on, such as a vendor's image that comes with the software preinstalled.
- An existing project that already builds with a Dockerfile its team maintains: keep it rather than rewrite the build.
Not reasons for a Dockerfile, each has a buildpack answer: the start command or several processes (a Procfile), a language version (the app's own files, or build.env), an Ubuntu package or a C library (an Aptfile, build.stack: full), migrations (a release: line in the Procfile), a static site or a Vite build (the web-servers buildpack), a monorepo package (Monorepos and workspaces), build variables (build.env), or running as non-root (buildpack images already do).
How a Dockerfile build runs
When the deployed directory contains a Dockerfile, shpyrd deploy builds it instead of using buildpacks. A Dockerfile left over in the repository therefore wins: delete it, or set build.strategy: buildpacks in shpyrd.yaml, to build with buildpacks.
==> Archiving working tree (c26f84642501)==> Building with Dockerfile (Dockerfile)==> Uploading source (1.7 KiB)==> Building===> fetch===> build#8 importing cache manifest from 10.96.0.50:5000/apps/hello-docker:cache#9 CACHED...pushed 10.96.0.50:5000/apps/hello-docker@sha256:2a6749dc...==> ReleasingReleased v2: Deploy c26f84642501The build runs as a rootless BuildKit Job in the project namespace: a first step fetches your archive (or clones the Git revision), the second builds the context and pushes the image. Multi-stage builds, build arguments, .dockerignore and a layer cache between builds all work as with docker build.
A build is a step of a deploy, not something the workspace keeps running: it does not count against the workspace's memory and CPU ceiling, so an app that is awake never stops its own next deploy. Each build has a hard ceiling of its own instead: up to 4 GiB of memory and 2 CPUs while it builds (512 MiB and half a CPU while it fetches the source). A build that needs more memory stops and says so; lighten it with a multi-stage Dockerfile, fewer steps in parallel, or a smaller dependency install.
Processes, release steps, and one-off commands run as non-root. Prefer a numeric USER 1000 in the final Dockerfile stage, and give that user access to the files the app needs. For images built by shpyrd, named users such as USER node are resolved from the image’s /etc/passwd and run with that numeric uid/gid. If the name cannot be resolved, startup fails with a suggestion to use a numeric USER; root users remain disallowed.
Pin or tune it in shpyrd.yaml:
build: strategy: dockerfile # buildpacks | dockerfile; without it, auto-detected from the Dockerfile dockerfile: deploy/Dockerfile target: runtime # multi-stage target env: NODE_ENV: production # build argumentsprocesses: web: {} # runs the image CMD worker: command: ["node", "worker.js"] # Dockerfile images have one entrypoint: other process types name their commandFrom Git, detection is not possible; say so explicitly: shpyrd deploy --git https://github.com/o/r --dockerfile (optionally --dockerfile deploy/Dockerfile). The dashboard's Deploy dialog has the same choice. Git sources with a Dockerfile are rebuilt on every push to the branch, like buildpack builds (Deploying on push), and when the build settings change.
Failures show BuildKit's error in the CLI, the Activity panel and shpyrd projects info <project>; the previous release keeps serving. examples/hello-docker in the repository is a complete example.
Processes and sizes
Declare process types in shpyrd.yaml next to your code; shpyrd deploy applies it:
project: hello-worldprocesses: web: port: 8080 worker: cpu: "500m" memory: 256Mibuild: env: BP_GO_TARGETS: ./cmd/web:./cmd/worker # Go: one process per commandScale at any time; counts survive deploys:
shpyrd scale web=3 worker=2shpyrd autoscale my-service --min 2 --max 10 # web follows its load between the bounds (autoscale extension)shpyrd resize web=shared-l worker=dedicated-s # change the size; a releaseshpyrd sleep my-service --after 15m # scale web to zero when idle (sleep extension)With bounds, the web process gets another instance when one passes 70% of its size's CPU or carries more than 20 requests in flight (--cpu and --concurrency change the targets), and one fewer when the load has been lower for five minutes. shpyrd scale web=N then sets the minimum. Sleep and bounds go together: zero while asleep, the minimum on a wake, the bounds under load.
Without a size, a process gets shared-m for Node.js, Ruby, Python and Java, and shared-s for the rest. shpyrd sizes list shows the catalog.
Config vars
shpyrd secrets set DATABASE_URL=postgres://...shpyrd env set APP_URL=https://example.com LOG_LEVEL=debugshpyrd env list # names and values of plain variablesshpyrd env unset LOG_LEVELshpyrd secrets list # names and when each was last set; values are never shownChanges are saved without restarting the app. Run shpyrd redeploy (or deploy new source) when ready to apply them. On a project that deploys on push, the next push to the branch deploys them too, with its commit. Until then, running processes, replacement instances and one-off commands keep using the deployed configuration. The project's Config page shows a pending-changes notice and a save toast; it supports editing visible variables, replacing hidden secrets, and pasting .env files with a choice of kind.
Variables are readable by everyone who can view the project. New entries default to secrets, and existing secrets stay hidden on upgrade. Making a secret a variable requires confirmation; credential-looking names such as API_KEY or AUTH_TOKEN also require confirmation (shpyrd env set --confirm-plain in the CLI). Making a variable a secret hides its value without changing it. A name has one project-owned value: saving it as a secret takes precedence, while existing secrets cannot be converted back to visible variables. Attached-resource variables still override project configuration.
Rollback restores the selected release's deployed values and their visibility. Pending edits remain saved for a later deployment.
Plain, non-secret variables can also live in shpyrd.yaml under env: and travel with the code — useful for things like RACK_ENV, RAILS_ENV or NODE_ENV that belong in the repository rather than in the cluster's secret store:
env: RACK_ENV: production RAILS_LOG_TO_STDOUT: "1"env: is authoritative when present: an empty map (env: {}) removes every previously declared plain variable. Secret values — API keys, database passwords — always go through shpyrd secrets set, never here.
At build time
A buildpack build sees the same variables the app will run with: global config vars, the project's config vars, the variables of attached resources (DATABASE_URL, DATABASE_HOST, …) and env:, in that order (the later wins), with build.env from shpyrd.yaml above them all. That is what prisma generate, a Next.js page that reads the database while the build collects page data, NEXT_PUBLIC_* variables inlined into the assets and Rails' assets:precompile rely on. Attach the database before the first deploy and the first build already has DATABASE_URL.
A build reads the values current when it starts. Setting or changing a project config var does not start a build or restart processes. The next deploy builds with the saved values (shpyrd redeploy --rebuild, or Redeploy in the dashboard, builds the same source again).
The values stay secret on the way. They reach the build in a Kubernetes Secret mounted into the build alone, and shpyrd's buildpack, first in every builder, hands them to the buildpacks after it for the build only: they are not written into the image nor into the build cache. What the app's build does with them is its own: a variable it inlines on purpose, such as NEXT_PUBLIC_*, ends up in the image, as on Heroku. A secret value the build prints shows as *** in the build's log, in the dashboard and the CLI alike: the value whole, each line of a value of several lines, and the password of a URL on its own. A value shorter than 8 characters, or one printed in another form (base64, a part of it), shows as it is; and only the values current when the log is read are recognised. Two names cannot reach a build, type and provider; a project that names its own builder (build.builder) gets the variables only if that builder starts with shpyrd's buildpack.
A build can reach the project's database: it runs in the project's own network. Run migrations in the release phase, not in the build, so a build that fails never leaves the schema half changed. Dockerfile builds receive only build.env, as ARG values.
Global config vars
Settings every project should have (an OPENAI_API_KEY, a region) are set once by a workspace admin and injected into every process of every project of the workspace:
shpyrd globals set OPENAI_API_KEY=sk-... REGION=eushpyrd globals unset REGIONshpyrd globals list # names and when each was set; values are never shownGlobals come first in the environment: a project's own config var of the same name wins, and variables from attached resources win over both. A change is a Global config change release in every project that receives them (the workspace's Config vars page asks first and says how many). shpyrd secrets list and the project's Config page show them as provided by cluster and mark project vars that override one. A project opts out in shpyrd.yaml:
globals: false # none of themglobals: { exclude: [OPENAI_API_KEY] } # all but theseHealth checks
shpyrd configures probes automatically. No configuration is needed for the common case:
| Process type | Default probe |
|---|---|
web | HTTP GET / on PORT |
Any other process with port: set | TCP on that port |
| Workers and other processes without a port | None — relies on restart-on-crash |
The same check runs three ways: at start (the grace period), for readiness (3 failures take the instance out of rotation) and for liveness (6 failures in a row restart it). Defaults: every 10s, a 5s timeout per check, a 30s grace period (also the minimum) and a 5s shutdown delay.
The deploy waits for each new instance to pass its readiness probe before the old one is removed, so traffic is always served. If a new instance never becomes healthy the rollout stalls, the Activity panel shows the reason (exit code, probe error) and a rollback button; the old instances keep serving.
A size no machine can hold is refused before anything is stopped ("dedicated-m needs 2 cores; the largest machine in this cluster offers 1.83 cores"), and so is one the machine that holds a process's disk has no room for. An instance that still finds no room fails instead of waiting for ever: at once when no machine is large enough ("web cannot start: it asks for 2 cores; no machine here has more than 1.83 cores"), after five minutes when the cluster is not adding a machine. A process with a single-instance volume rolls out by stopping the old instance first; when the new one cannot start, the previous release runs again meanwhile and the page says so until you resize or roll back. The way back is never locked: a rollback or a resize over a rollout in progress asks for a confirmation (--force on the CLI) and cancels it.
HTTP checks reach the process directly, without the edge's sign-in, cookies or identity headers. Keep the health path outside your app's authentication middleware and return 2xx to a plain GET. A 401, 403, server error, timeout or failing redirect can leave the instance unready; repeated startup or liveness failures restart it even when its logs say it started successfully. Redirecting an unauthenticated check to /.shpyrd/signin cannot sign it in: that route belongs to the edge.
If / requires sign-in, add an unauthenticated /healthz route and set processes.web.healthCheck.path: /healthz. Alternatively, use processes.web.healthCheck.tcp: true to check only that the port accepts connections; this does not check the HTTP response or application dependencies. See Sign-in for your app.
Override the default or disable checking in shpyrd.yaml:
processes: web: healthCheck: path: /healthz # HTTP GET on PORT; replaces the default / interval: 5s timeout: 3s # per check gracePeriod: 60s # startup time before failures count shutdownDelay: 5s # drain time before SIGTERM worker: healthCheck: command: [python, -c, "import app; app.is_healthy()"] # custom command api: healthCheck: tcp: true # explicit TCP when port: is set batch: healthCheck: disabled: true # no probeshpyrd projects info <project> shows the health config per process. shpyrd.yaml changes take effect on the next deploy.
Shell and one-off commands
shpyrd shell # bash (or sh) in web.1shpyrd shell --instance worker.2 # a specific instanceshpyrd shell --process worker # the first instance of a process typeshpyrd shell -- cat /etc/os-release # run one command and return its exit codeshpyrd shell attaches to a running instance: what you see is the live process's filesystem and environment. Buildpack images get the same environment as the process (through the CNB launcher), so node, bundle or python are on the PATH.
A process that will not start has no instance to attach to. shpyrd shell --debug (with --process or --instance to name it) opens a shell in a new copy of the process: its image, config vars and volumes, on the machine that holds its disk, with the process's command replaced by the shell. Look at /data, run the fix, exit; the copy is removed.
shpyrd run rails db:migrate # a new instance of the current release, removed when the command exitsshpyrd run --size shared-l python manage.py import big.csvshpyrd run --detach ./nightly.sh # start and return; follow with shpyrd logs -p runshpyrd run starts a temporary instance (like heroku run) with the release's image and config vars, streams its output and exits with the command's exit code; piped input works (cat dump.sql | shpyrd run psql). A one-off instance stops after an hour at most; --detach leaves it running until then.
A one-off instance has no volumes unless you ask: shpyrd run --process web -- fluxyr migrate-storage mounts web's volumes at their paths, and runs on the machine that holds a single-instance disk right now, so the two instances share the attached disk. The release step can see them too: declare the volume on the release process in shpyrd.yaml (processes.release.volumes, the same entry as the process's) and the step runs with it, where the disk is. A data migration on a disk belongs there.
Maintenance mode
shpyrd maintenance on --message "Back at 15:00 UTC" # the page instead of the appshpyrd maintenance # on or off, since when, by whomshpyrd maintenance off # the app againWhile maintenance is on, every request at the project's addresses gets a 503 and a page with the project's name and your message; programs get a JSON answer with Retry-After, so crawlers and webhooks come back later rather than record an error. Nobody is let through, the team included, as on Heroku: the team works through the console. The processes keep running, and releases, scaling, shpyrd shell and shpyrd run go on underneath, so a migration runs behind the page, a deploy rolls out behind it, and off shows the result. Switching is instant and restarts nothing: the project's addresses point at the page, then at the app again.
The project's Overview has the same switch and message; the header, the project list and the launcher say Maintenance while the page is up, and the audit trail records who turned it on and off. An app that sleeps is kept awake while the page is up, since no request would wake it, and may sleep again afterwards. Shells, one-off commands and deploys are refused only during a move or a restore, which has its own page.
Volumes
Processes that need a disk mount a project volume:
shpyrd volumes create data --size 5Gi # a persistent disk of the project# shpyrd.yamlprocesses: web: volumes: - name: data path: /dataVolumes are persistent: they outlive deploys, scaling and crashes and are deleted only by shpyrd volumes delete (or the project's destruction). A volume is single-instance by default (block storage attaches to one node): the process mounting it runs one instance and rolls out with a stop-then-start (a few seconds of downtime per deploy, no data risk), and shpyrd scale web=3 is refused with that explanation. --shared volumes can be mounted by many instances and processes but need a provisioner that offers ReadWriteMany; they are unsafe for SQLite. See Resources for the details.
Logs
shpyrd logs --project shop -fThe project's Logs page streams every instance live. The Logs page covers the log agent, the on-node limits and drains to your log provider.
Releases and rollback
shpyrd releasesRELEASE CREATED DIGEST DESCRIPTIONv7 (current) 2026-09-21 22:44:30 2edf5661353b Rollback to v5v6 2026-09-21 22:44:18 2edf5661353b Set GREETING config varv5 2026-09-21 22:44:06 2edf5661353b Set GREETING config varv4 2026-09-21 21:53:52 2edf5661353b Deploy 654f4925638eshpyrd rollback # to the release before the current oneshpyrd rollback 4 # to a specific release: its build and its config varsA rollback is refused while another release is still rolling out (--force overrides). See Concepts for what a release contains.
When something fails
The project says what failed, in words, in the dashboard, the CLI (shpyrd projects info <project>) and the workspace's MCP server alike:
- A build: the script that was running and, when the build's output makes it plain, why - a variable the build reads and nobody set, a module that is not installed, a source no buildpack recognises. The output itself is the build's log:
shpyrd logs --build. - The release phase: that it failed, ran past its 30 minutes, or could not start. Its output is
shpyrd logs -p release. - Something that cannot start because of the workspace's ceilings: which ceiling (memory, CPU), what takes it - the database, the processes - and how much more was needed. Retrying does not help; a smaller size, fewer instances or a larger plan does.
The previous release keeps serving through all of these.
Redeploy
shpyrd redeploy # new instances of the current releaseshpyrd redeploy --rebuild # build the same source againRedeploy tries the current release again without creating a release. With a healthy or unhealthy release it starts new instances of it (a rolling restart: the fix for an instance stuck on a dependency that came back). When the last build failed - a registry hiccup, a flaky download - it builds the same source again instead, and the release that results is a normal deploy. The project page has the same button; after a failed build it reads Build the same source again.
Open and inspect
shpyrd open # opens https://acme-my-service.shpyrd.app (shpyrd cloud) or https://my-service.<domain>shpyrd projects info my-service # status, releases and every resource of the project (app, volumes...)shpyrd projects listDestroy
shpyrd projects destroy my-service # deletes the project's namespace (p-<id>; older projects: app-<slug>) and everything in itThe command warns about the data on the project's volumes before asking for confirmation. Images stay in the registry.