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.

​
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.