Core Concepts

A mental model for how StackBlaze organises and runs your applications.

Projects

A Project is the top-level organisational unit in StackBlaze. It groups related services together and defines a shared region, team members, and billing boundary. Most teams create one project per product or application stack.

Projects have isolated networking: services within the same project can talk to each other over private DNS. Services in different projects cannot reach each other privately, you'd need to expose a public endpoint or use StackBlaze's private networking feature.

Services

A Service is a single deployable unit, a web app, a worker process, a cron job, a static site, or a managed database. Services belong to a project and run in the project's region.

Web Services

Web services expose an HTTP(S) endpoint to the internet. StackBlaze provisions an Ingress with a TLS certificate, balances traffic across replicas, and routes requests to your container on the configured port (default: 8080, read from the PORT environment variable).

Background Workers

Workers run continuously but receive no inbound traffic. They share the same build pipeline as web services and have access to all environment variables. Use them for queue consumers, event processors, or any async workload.

Cron Jobs

Cron jobs run on a schedule you define using standard cron syntax. Each run spins up a fresh container, executes your command, and terminates. Runs do not overlap by default (the concurrency policy is Forbid).

Static Sites

Static sites are built from a framework like Next.js (static export), Vite, or Gatsby. The build output is uploaded to a CDN. There is no server process, requests are served entirely from the edge.

Databases

Managed databases (PostgreSQL, MySQL, Redis, MongoDB) are provisioned by StackBlaze and accessible via private DNS within the project. Connection strings are automatically injected as environment variables into any service you link to the database.

Environments

Each project has one Production environment and optionally one or more Preview environments.

Environment	When created	Lifespan
Production	When you create the project	Permanent
Preview	Automatically on pull request open	Deleted when PR is merged or closed

Preview environments are isolated copies of your stack: they get their own databases, environment variables (with overrides), and URLs. They share no state with production.

Note

Preview environments are available on Team and above plans. Each open PR creates one environment automatically, no configuration needed.

Deployments

A Deployment is an immutable build artifact: a specific Docker image (tagged with the commit SHA) plus the environment variables that were active at the time of the deploy. Deployments are versioned, you can roll back to any previous deployment in one click.

Deployments are triggered by:

• A push to the configured branch (auto-deploy)
• A manual deploy from the dashboard or CLI
• A deploy hook (external HTTP trigger)
• An environment variable change that requires a restart

Internal Networking

Services within the same project communicate using stable private DNS names, no IPs, no service discovery configuration needed. The hostname pattern is:

<service-name>.internal

For example, if you have a web service named api and a Redis service named cache, your API can connect to Redis at redis://cache.internal:6379. This DNS name resolves to the ClusterIP of the Kubernetes Service object, it never leaves the cluster.

Tip

Use internal hostnames in your environment variables rather than hardcoding IPs. StackBlaze injects <SERVICE_NAME>_HOST and <SERVICE_NAME>_PORT automatically when you link services.

Environment Variables vs. Secret Files

StackBlaze provides two mechanisms for injecting sensitive configuration into your services:

Environment Variables

Key-value pairs injected into the container environment at runtime. Suitable for database URLs, API keys, feature flags, and any configuration that can be represented as a string. Values are encrypted at rest using AES-256 and are never logged or exposed in build output.

Secret Files

Arbitrary file content (certificates, JSON service account keys, .env files) that is mounted into the container at a path you specify. Useful when your application reads configuration from a file rather than environment variables.

Both environment variables and secret files are scoped per service and per environment - production and preview environments have independent sets of values.

Regions

A project is pinned to a single region. All services and databases in the project run in that region. Cross-region communication is not supported over private networking, if you need multi-region redundancy, you would create separate projects in each region and put a global load balancer in front.

See the Introduction for the list of available regions.