Documentation

Deploy a Docker image

Run a raw container image through the project flow when you already have an image and need runtime configuration, resource sizing, storage, domains, and placement.

Try StackShiftRead the overview

Projects

Deploy a Docker image

Live

Run a raw container image through the project flow when you already have an image and need runtime configuration, resource sizing, storage, domains, and placement.

Goal

Deploy an image-backed application with the least ceremony.

Current status

Live

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

Workflow

  1. 1Create a project and choose Docker image as the source type.
  2. 2Provide the image URI, service type, workload type, and runtime settings.
  3. 3Pick a resource preset, startup timeout, and optional persistent volume before deploy.
  4. 4Configure domains, env vars, and placement preferences.
  5. 5Deploy 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