Projects
A project is a deployed application on PandaStack. Every project maps to one build-and-serve pipeline and gets a public URL. You create a project by connecting a Git repository (or uploading static files), PandaStack builds it, and it goes live at https://{name}.pandastack.app — or at a custom domain you attach.
The three deploy types
Section titled “The three deploy types”PandaStack keys each project on a slug column with one of three deploy types. The type decides how the project is built, where it is served from, and what it costs.
| Type | How it serves | Runs a pod? | Cost | Best for |
|---|---|---|---|---|
static | Published to the global CDN | No | Free | SPAs, static site generators, plain HTML/CSS/JS |
container | Kubernetes pod fronted by the gateway | Yes | Free (scale-to-zero) or paid (always-warm) | APIs, servers, SSR apps, anything with a backend |
auto | Classified at create time, then persists as static or container | Depends on classification | Depends | ”Just connect a repo and pick nothing” |
auto is not a lasting type: it is a create-time convenience. After PandaStack classifies your repo, the project persists as either static or container. See Auto-detect deploys for the classification rules.
When each type is chosen
Section titled “When each type is chosen”- Static — you have a pure client-side app (Create React App, Vue CLI, a Vite SPA, Gatsby without SSR, Astro without an SSR adapter) or you upload pre-built files. There is no server process; the build output is published to the CDN and served with no pod. This is the cheapest option and it is free on every plan. See Static sites.
- Container — you have a server: an Express/Fastify/NestJS API, a Next.js/Nuxt/SvelteKit SSR app, or anything that listens on a port. It runs as a pod on Kubernetes and is reached through the gateway. See Container apps.
- Auto — you would rather not decide. PandaStack inspects the repository, ships a pure static SPA to the CDN when it can prove that is safe, and otherwise falls back to a container so the first deploy always works. See Auto-detect deploys.
Project names and URLs
Section titled “Project names and URLs”A project name is the public subdomain. The default URL is:
https://{name}.pandastack.appBecause the name is a public subdomain, it is globally unique across all organizations — not just unique within your org. If another organization already owns a project called blog, you cannot create one with the same name; PandaStack rejects the clash at create time.
The name must be a valid RFC 1123 DNS label:
- lowercase alphanumeric characters and hyphens only
- must start and end with an alphanumeric character
- at most 63 characters
The Deploy to PandaStack button works around the global-uniqueness constraint by appending a random 8-character suffix to the name, so two people clicking the same badge never collide.
The project lifecycle
Section titled “The project lifecycle”Every deploy follows the same path:
- Create — you connect a repo (or upload files) and pick a type (or
auto). PandaStack writes theProjectandDeploymentrows plus a transactional outbox row in one database transaction (topicdeploy.requested). - Queue — an outbox relay publishes the request to Google Pub/Sub. The deployment status is
queued. - Build — the worker picks up the message. For container and Git-static builds it runs a source scan (to reject malware/abuse kits), then builds. Static builds run in a microVM; container builds use Railpack or a Dockerfile. Status is
running. - Deploy — static output is published to the CDN; a container image is rolled out as a pod and a gateway service is created. The routing manifest is built and stored.
- Live — the project serves traffic at its URL. Status is
succeeded(orfailedif the build or rollout failed).
Deployment status
Section titled “Deployment status”| Status | Meaning |
|---|---|
queued | Deploy request accepted, waiting for the worker |
running | Building and/or rolling out |
succeeded | Live and serving traffic |
failed | Build or rollout failed — check the build logs |
Custom domains, routing, and analytics at a glance
Section titled “Custom domains, routing, and analytics at a glance”Every project shares the same gateway feature set. Some features are free; some require a paid plan.
| Feature | What it does | Free? | Details |
|---|---|---|---|
| Default URL | {name}.pandastack.app on every project | Free | — |
| Custom domains | Point your own domain at the project (Cloudflare SSL-for-SaaS) | Paid (402 for free orgs) | Domains |
| Redirects & rewrites | URL rules applied at the gateway | Free (MEMBER+ to set) | Routing |
| Response headers | Global header rules on all paths | Free (MEMBER+ to set) | Routing |
| Analytics | Audience data (visitors, referrers, devices) captured at the gateway | Paid feature + per-project toggle | Analytics |
| Metrics | Performance (requests, latency, errors, bandwidth) | See metrics docs | Metrics |
| Autoscaling / scale-to-zero | HPA (paid) vs KEDA scale-to-zero (free) | Mixed | Scaling |
Plan limits
Section titled “Plan limits”Free organizations can run up to 5 container apps and 5 static sites. Paid plans (pro, premium, enterprise) allow unlimited projects of both types. Creating a project past the free limit returns a 402 quota_exceeded error. See Plans & limits.
In this section
Section titled “In this section”- Auto-detect deploys — how Railpack classifies static vs container and the smart paid defaults
- Static sites — CDN hosting, build directory, clean URLs, SPA fallback
- Container apps — pods on Kubernetes,
PORT, health checks, scaling - Build & buildpacks — Railpack, supported frameworks, Dockerfile override, build logs
- Environment variables & secrets — build-time vs runtime,
NEXT_PUBLIC_*, reserved vars - Custom domains — bring your own domain
- Redirects, rewrites & headers — the routing manifest
- Autoscaling & scale-to-zero — HPA and cold starts
- Deploy to PandaStack button — one-click deploys and
pandastack.json