Architecture

How QuickStack works under the hood: k3s, Traefik, Longhorn, BuildKit, Railpack, the internal registry, and the deploy pipeline.

QuickStack is a control plane that turns a Linux server into a self-hosted platform. It runs on k3s, a lightweight Kubernetes distribution, and exposes a web UI on top of Kubernetes primitives. You never have to write manifests or run kubectl for day-to-day work.

This page explains what runs where and what happens when you click Deploy. For the task-oriented steps, see the tutorials and how-to guides.

Components

Component	Role
QuickStack control plane	A Kubernetes pod that serves the web UI and API and stores all configuration in a SQLite database (`storage/db/data.db`).
k3s	The Kubernetes distribution that schedules apps, databases, and build jobs.
Traefik	The reverse proxy and ingress controller. Terminates HTTP/HTTPS and provisions Let's Encrypt certificates.
Longhorn	Distributed block storage for volumes in multi-node clusters. Single-node installs use `local-path` by default.
BuildKit	The image builder that executes builds from Git sources.
Railpack	The zero-config builder QuickStack uses for Framework and Railpack builds; it detects the language and framework and produces an image via BuildKit. railpack.com
Internal registry	Stores images built from Git so deployments can pull them by immutable commit tag.

Technologies not bundled by QuickStack can be added as cluster add-ons (Longhorn, cert-manager, and, on the canary channel, the Kubernetes Agent Sandbox and gVisor).

How the pieces fit together

Cluster topology

Single node (default): one server runs the k3s control plane, QuickStack, and all workloads. Volumes use the local-path storage class.
Multi node: the first server is the master node; additional servers join as worker nodes. QuickStack schedules workloads across nodes and Longhorn replicates volumes. See Cluster Nodes.

What happens when you deploy

Build (Git sources only) — QuickStack clones the configured branch, builds an image with the selected build method (Framework and Railpack builds run on Railpack, which uses BuildKit), and pushes it to the internal registry. Each build is tagged with the short commit hash and a moving latest tag.
Backup — any volume backup schedule marked Backup before deployment runs first. See Volume Backups.
Apply configuration — staged settings (environment variables, volumes, domains, network policies, health checks, resource limits) are written to the workload.
Roll out — QuickStack creates or updates a Kubernetes Deployment and performs a rolling update: new pods start, and old pods terminate once the new ones are ready.

Image sources skip the build steps Apps that use a Docker image or a template pull the image directly instead of cloning and building. The backup, apply-config, and rollout steps are identical.

Configuration is staged until you deploy Editing settings only changes the stored configuration. Clicking Deploy is what applies it to the running workload. See Deploy & Redeploy.

Networking at a glance

External HTTP(S) traffic enters through Traefik on ports 80/443 and is routed to an app by its domain.
Internal traffic between workloads uses Kubernetes service hostnames of the form svc-<app-id>.<project-id>.svc.cluster.local and is deny-by-default. See Networking & Policies.
Non-HTTP traffic can be exposed directly on cluster nodes with Node Ports.
The QuickStack control panel is served on port 30000 for the initial setup. Once you assign it a domain, Traefik serves it with a Let's Encrypt certificate instead, and port 30000 is only needed for the initial configuration.

See Ports & Endpoints for the full list.

Where data lives

Data	Location
QuickStack configuration (projects, users, apps, secrets)	SQLite database inside the QuickStack pod
Application volumes	Kubernetes PersistentVolumes (`local-path` or `longhorn`)
Built images	Internal registry
Backups	S3-compatible object storage configured as an S3 target

The configuration database is backed up separately from application data as a system backup.