Skip to main content
Live. This area is documented as current, user-reliable behavior.

​
Goal

Deploy an image-backed application with the least ceremony.

​
Prerequisites

  • A healthy node
  • A Docker image URI
  • The runtime port and env vars the image expects

​
Workflow

1
Create a project and choose Docker image as the source type.
2
Provide the image URI, service type, workload type, and runtime settings.
3
Pick a resource preset, startup timeout, and optional persistent volume before deploy.
4
Configure domains, env vars, and placement preferences.
5
Deploy and validate the live URL, logs, and health state.

​
Simplified image review (pending API, worker and frontend release)

The updated flow uses Source → Review & Deploy for images too. Enter an immutable image URI ending in @sha256 plus its 64-character digest, then review the name, resource allocation, destination and environment values. Advanced contains port, process, resource and storage overrides. Image contents are not scanned for writable paths in this flow; configure image-specific storage and startup requirements there. Source-code storage defaults apply only to analyzed repositories and uploads.

​
Runtime choices that matter

  • Service type controls whether StackShift exposes public ingress. Web services get URL and domain behavior. Worker services do not.
  • Workload type classifies the repo or image shape as web, API, worker, or contract build.
  • Contract build is build-only. It produces artifacts but does not deploy a long-running runtime.

​
Resource presets and warmup

  • Standard: 512MB RAM and 0.5 CPU.
  • Web3 App: 2GB RAM and 1 CPU.
  • Worker: 4GB RAM and 2 CPU.
  • Heavy: 8GB RAM and 4 CPU.
  • Startup timeout is configurable from 30 to 600 seconds. Increase it for indexers, chain warmup, or slower boot paths.

​
Persistent volume behavior

  • Persistent volume can be disabled with size 0 or enabled from 1 to 100 GB.
  • Mount paths must start with / and cannot target /, /proc, /sys, /etc, /var/lib/docker, or /var/lib/stackshift.
  • Use persistent storage for chain caches, checkpoints, or data that should survive redeploys.

​
Expected result

The project is live from a Docker image and manageable through the project pages.

​
Common failures

  • The app does not listen on the configured port
  • Image startup requires env vars that were not set
  • Worker or build-only runtime was selected but a public URL was expected

Builds, deployments, and logs

Understand the project execution lifecycle: build output, deploy state, rollback behavior, and where to inspect logs.

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.