Documentation

Project environment, domains, and previews

Configure the project surfaces that most often decide whether a deployment works after it builds, including runtime shape, domains, previews, and storage.

Try StackShiftRead the overview

Projects

Project environment, domains, and previews

Live

Configure the project surfaces that most often decide whether a deployment works after it builds, including runtime shape, domains, previews, and storage.

Goal

Understand the runtime settings that matter after the app image exists.

Current status

Live

This area is documented as current, user-reliable behavior.

Workflow

  1. 1Set environment variables and confirm whether the project should expose public ingress at all.
  2. 2Review service type, workload type, resource preset, timeout, and storage settings.
  3. 3Attach and manage domains for the project.
  4. 4Use preview-related surfaces when they are available for your project flow.

Environment variable behavior

  • Project variables are encrypted at rest.
  • Saving edits triggers a new deployment so the runtime picks up the changes.
  • Project-level variables override global variables with the same key.

Advanced runtime settings

  • Service type decides whether the project behaves as a web service or worker service.
  • Worker services do not expose public ingress, so URL and custom-domain expectations should be adjusted accordingly.
  • Workload type can be web, API, worker, or contract build. Contract build means build-only with no deployed runtime.
  • Resource preset controls baseline RAM and CPU sizing.
  • Startup timeout ranges from 30 to 600 seconds and should be raised for chain sync, indexers, or slow boot paths.
  • Web3 enabled is auto-detected when possible but remains user-overridable.

Persistent storage rules

  • Persistent volume is disabled at size 0 and enabled from 1 to 100 GB.
  • Mount paths must begin with `/` and cannot target reserved system directories.
  • When editing an existing project, resizing storage requires redeploy, but retained data is preserved.

Preview deployment behavior

  • Preview deployments are tied to GitHub-backed projects rather than raw image projects.
  • Preview availability is plan-gated and the UI calls that out directly when locked.
  • Preview rows expose branch, PR number, live URL, expiry timing, and build-log entry points.

Custom domains in practice

Domains can be attached from the project side or from the domains product area. After attachment, DNS propagation and SSL activation may still take time even when the connection action itself succeeds.

If the project is configured as a worker service, domains can still exist in inventory but they should not be treated as active public ingress for that runtime.

Expected result

The project is configured beyond just “it deployed once”.