• Get started

    • Getting started
    • Concepts
    • Tour
  • Using shpyrd

    • Deploying
    • shpyrd.yaml
    • Resources
    • Databases and caches
    • Domains and exposure
    • Sign-in for your app
    • Teams, roles and security
    • AI assistants (MCP)
    • Logs
    • Dashboard
    • CLI reference
  • Running it yourself

    • Installation
    • Oracle Cloud (OKE)
    • AWS (EKS)
    • Extensions and sign-in
    • Platform backups
    • Architecture guide
  • Project

    • Design principles
    • Roadmap
    • How to contribute
    • Support the project
  1. Get started
  2. Concepts
Sign in
Start free

Concepts

Projects, processes, builds, releases and config vars - what each one is in shpyrd.

On shpyrd cloud you work with projects, processes, builds, releases and config vars through the dashboard and the CLI; underneath, each maps onto Kubernetes objects, which you can inspect with kubectl on a cluster you run yourself.

Project and resources

A project is what you deploy to: a name, a domain, config vars and a set of resources. It has a display name ("My Shop") and a slug derived from it (my-shop) that names it everywhere precise: --project, shpyrd.yaml, the dashboard URL /projects/my-shop and its address. Both can change: shpyrd projects rename my-shop "My Store" --slug my-store; the old address redirects for 30 days. Underneath, a project has an id that never changes. Resource types are the app (your code with its process types), volumes (persistent disks), PostgreSQL databases and Redis-compatible stores (see Resources and Databases and caches). A project without a web process is a worker or an agent; no separate type is needed. Under the hood (what you see with kubectl on a cluster you run yourself) the project is a namespace named by its id, p-<id> (older projects: app-<slug>), labelled shpyrd.io/project=<slug>. It holds an App custom resource (shpyrd.io/v1alpha1), the Volume, Postgres and Redis resources and everything the controllers create for them. kubectl get apps,volumes.shpyrd.io -A lists them all; shpyrd projects info and the project's Resources page show the same list with status and what uses each resource.

apiVersion: shpyrd.io/v1alpha1kind: Appmetadata:  name: 0f8k2m...            # the project's id, short form  namespace: p-0f8k2m...  labels: { shpyrd.io/project: hello-world }spec:  source:    git: { url: https://github.com/shpyrd-io/shpyrd, revision: main }    subPath: examples/hello  processes:    web: { port: 8080, replicas: 3 }    worker: { replicas: 2 }  build:    env: [{ name: BP_GO_TARGETS, value: ./cmd/web:./cmd/worker }]status:  phase: Running  url: https://hello-world.127.0.0.1.nip.io   # a local cluster  releases: [...]

Projects without a web process (workers, agents, schedulers) work the same way; they just get no URL.

Processes

A process type is a way of running the build: web serves HTTP and receives PORT; anything else (worker, scheduler, agent) runs the command of the same name that the buildpacks recorded in the image. Each process type becomes a Deployment with its own instance count (shpyrd scale web=3 worker=1, or bounds the web process follows its load between, shpyrd autoscale shop --min 2 --max 10) and instance size (shpyrd resize web=shared-m): a named cpu/memory allocation from the cluster catalog.

Two size kinds exist:

  • shared: the cpu value is a ceiling the process may use; it is guaranteed a 1/16 share of it and borrows the rest from idle neighbours (Kubernetes burstable QoS). Many small shared instances fit on one node.
  • dedicated: requests equal limits — whole cores, Guaranteed QoS.

Memory is never overcommitted: requests equal limits for both kinds. The default size is shared-m (up to 0.5 CPU, 256 MiB) for Node.js, Ruby, Python and Java, and shared-s (up to 0.5 CPU, 64 MiB) otherwise. Databases and stores have lists of their own with the same names (Databases). shpyrd sizes list shows the full catalog.

Instances are named the way Heroku names dynos: web.1, web.2, worker.1, in creation order. Logs and the dashboard use these names.

Builds

A build compiles source into an OCI image inside the cluster, with one of two strategies: Cloud Native Buildpacks (Paketo, run by kpack), the default, or the repository's Dockerfile built by a rootless BuildKit Job, for what buildpacks cannot build (When a Dockerfile is justified). A build happens for every new source: an uploaded archive, or a new commit on a Git branch (kpack polls; Dockerfile builds from Git rebuild when the revision changes). Builds are numbered (#1, #2, ...) and identified by the image digest; the dashboard shows every step live (prepare, analyze, detect, restore, build, export for buildpacks; fetch and build for Dockerfiles).

Buildpacks detect the language from the repository (go.mod, package.json, pom.xml, requirements.txt, Gemfile, *.csproj, or static files) and produce one process type per entry point. A Procfile or buildpack-specific settings (BP_* variables in build.env) refine that, for example BP_GO_TARGETS to build several Go commands.

Releases

A release is a build plus the config vars in effect, numbered v1, v2, ... Anything that changes what runs creates one:

KindExample descriptionCreates a build?
deployDeploy 654f4925638eyes
configSet GREETING config var, Resize web to shared-mno, reuses the current build
rollbackRollback to v7no, reuses v7's build

Each release records its build (identified by REVISION, the git commit or archive digest), its config snapshot (a Secret <app>-release-vN), its process types and their sizes, and the resources attached to the app. Rollback re-releases an earlier release exactly: its build is pinned and its config vars, sizes and attachments are restored. REVISION follows the image that runs, so a rollback reports the older commit, not the newest one. Rolling back to a release whose build predates a process type (say, before worker existed) cannot start that process; the dashboard warns before and the failure is reported plainly after.

The next shpyrd deploy unpins the build and continues from the new source.

Release phase

When an image has a release process type (a Procfile line release: bundle exec rails db:prepare, or processes.release.command in shpyrd.yaml for Dockerfile images), the platform runs it as a one-off Job before the new release rolls out. The rollout waits; a failure leaves the previous release serving and marks the project Failed. Every kind of release — a new build, a config change, a rollback — triggers the phase. See Deploying › Release phase.

Config vars

Config vars are environment variables for every process. Four sources, in increasing priority:

  1. Global vars — set once by a workspace admin, on the workspace's Config vars page or with shpyrd globals set; every project of the workspace receives them.
  2. env: in shpyrd.yaml — plain, non-secret vars committed with the code (RACK_ENV, NODE_ENV). Travels with the deploy; wins over globals.
  3. Project variables and secrets — saved with shpyrd env set (visible values) or shpyrd secrets set (hidden values). Edits stay pending until deploy or redeploy; the active environment is stored in Secret <app>-env. Existing values remain secrets on upgrade.
  4. Bound vars — injected by attached resources (DATABASE_URL, REDIS_URL); win over secrets of the same name.

Changing any of these creates a release and rolls the processes. The platform also injects read-only variables (PORT, REVISION, RUNNING_IN_SHPYRD, SHPYRD_PROJECT, SHPYRD_PROJECT_ID, SHPYRD_PROJECT_NAME, SHPYRD_WORKSPACE, SHPYRD_PROCESS, SHPYRD_RELEASE, SHPYRD_RELEASE_VERSION, SHPYRD_REVISION, SHPYRD_PROJECT_REVISION, SHPYRD_ISSUER; SHPYRD_RELEASE_PHASE in the release phase) that cannot be overridden from shpyrd.yaml.

Domains and TLS

A project's web process is published at its own address - on shpyrd cloud, https://<workspace>-<slug>.shpyrd.app (the workspace itself is at https://<workspace>.shpyrd.cloud), or under the workspace's own domain when it brings one; on a cluster you run yourself, https://<slug>.<domain>. Additional domains can be declared. Certificates come from cert-manager: the development CA on the local profile, a public or private CA on cloud profiles.

Extensions

Self-hosted: optional capabilities are extensions, compiled into shpyrd, switched on per cluster with shpyrd extensions enable, each bringing its installer component, resource types and commands. Among them: auth-local (accounts for the dashboard), postgres, redis, object-storage, mail and sleep. See Extensions and sign-in.

Environment profile

Self-hosted: the profile chosen at install time (local, oci or aws) says how load balancing, DNS, TLS and the registry are provided; see Installation.

Phases

A project's phase summarises its state:

PhaseMeaning
Pendingno source or image yet
Buildinga build is running (a previous release may still be serving)
Deployingnew instances are rolling out; previous ones keep serving until they are ready
Runningevery process has its desired instances ready
Failedthe build failed, or new instances cannot start (the reason is shown, previous instances keep serving)

On this page

  • Project and resources
  • Processes
  • Builds
  • Releases
  • Release phase
  • Config vars
  • Domains and TLS
  • Extensions
  • Environment profile
  • Phases
Back to top
  • AI Community
  • Vibe Coders
  • Developers
  • Businesses
  • FDEs & Implementation Partners
  • Getting Started
  • Pricing
  • Docs
  • Changelog

© 2026. shpyrd. All rights reserved.LegalTerms of ServicePrivacy Policy