Prebuilt image packaging references an existing container image from any registry — Docker Hub, Amazon ECR, GitHub Container Registry, or a private registry. Stacktape skips the build step entirely and deploys the image directly. Use this when your image is already built by an external CI/CD pipeline, or when you want to run a third-party image like Nginx, Redis, or Prometheus.
This packaging type applies to web services, private services, worker services, multi-container workloads, and batch jobs.
Container packaging types
Stacktape has four container packaging types. Each targets a different workflow:
| Type | When to use |
|---|---|
js-bundle | A JavaScript or TypeScript service with one entry file. Stacktape bundles it and builds a small image. |
buildpack | Any other language or framework. Stacktape detects the project and builds the image without a Dockerfile. |
dockerfile | You need full control over the build. Provide your own Dockerfile and build context. |
prebuilt-image (this page) | The image already exists in a registry. Stacktape skips building entirely. |
Use prebuilt-image if your image already exists. Use one of the other three types if you want Stacktape to build and push the image during deployment.
When to use
Use prebuilt image packaging when:
- Your CI/CD pipeline already builds images. If GitHub Actions, GitLab CI, or another pipeline pushes tagged images to a registry, reference them directly instead of rebuilding inside Stacktape.
- You're running third-party software. Images like
nginx,redis,postgres, orgrafana/grafanaare ready to use from Docker Hub or other public registries. - You share images across multiple services. A single image built once can be referenced by several Stacktape resources without redundant builds.
- You need full control over the build environment. Build externally with any tooling (Bazel, Nix, Kaniko) and hand the final image to Stacktape.
When NOT to use
Skip prebuilt image packaging when:
- You want Stacktape to handle the entire build. The
js-bundle,buildpackanddockerfiletypes build an image from source and upload it to a managed ECR repository. - You don't have an external image pipeline yet. Setting up a separate registry and build system adds operational overhead. Letting Stacktape build the image from source is simpler when you don't already have container build infrastructure.
- You want the image version to be derived from source. With prebuilt-image, the documented input is the
imagestring. Prefer changing that value when you want a new image version to be visible in config review. Build-based modes produce a new image from your source on each deploy.
Basic example
The smallest valid configuration references a public image by name and tag:
The image property accepts any valid container image reference: a Docker Hub short name (httpd:latest), a full registry URL (123456789012.dkr.ecr.us-east-1.amazonaws.com/my-repo:v1.2.3), or a GitHub Container Registry path (ghcr.io/my-org/my-app:main).
Private registry images
To pull from a private registry that requires authentication, store your credentials in AWS Secrets Manager and reference the secret ARN via repositoryCredentialsSecretArn. The secret must be a JSON object with username and password keys.
Create the secret using the Stacktape CLI secret set command. The command accepts --secret-name to set the secret name and --value to provide the JSON credentials inline. See the CLI reference for the full list of flags (including --file and --region).
Then reference the secret ARN in your config:
The repositoryCredentialsSecretArn property accepts the ARN of an AWS Secrets Manager secret containing username and password keys. Underneath, AWS ECS uses these credentials when pulling the image from the private registry.
Amazon ECR does not need repositoryCredentialsSecretArn — underneath, AWS ECS authenticates to ECR via the task execution role. Use repositoryCredentialsSecretArn for non-ECR registries that require explicit username/password credentials.
Overriding startup behavior
You can override the image's default startup instructions without rebuilding it. The command and entryPoint properties map directly to Docker's CMD and ENTRYPOINT concepts.
Command override
The command property overrides the image's CMD instruction. Use this to pass different arguments or run an alternative script:
The command property accepts a string array. Each element becomes a separate argument — this matches Docker's exec-form CMD ["arg1", "arg2"] behavior.
Entrypoint override
The entryPoint property overrides the image's ENTRYPOINT instruction. This is useful when you need to wrap the default process with an init script or switch the executable entirely:
When both entryPoint and command are specified, entryPoint sets the executable and command provides its arguments — matching Docker's ENTRYPOINT + CMD composition model.
The container-workload packaging variant (PrebuiltImageCwPackagingProps) supports image, command, entryPoint, and repositoryCredentialsSecretArn. The batch-job packaging variant (PrebuiltImageBjPackagingProps) supports only image and command.
Multi-container workloads
When using prebuilt images in a multi-container workload, each container specifies its own packaging independently. This lets you combine prebuilt third-party images (like a sidecar proxy) with application containers built from source:
This pattern is common for adding observability sidecars (Datadog agent, OpenTelemetry collector), reverse proxies (Envoy, Nginx), or log forwarders alongside your application container.
Batch jobs
Batch jobs accept prebuilt-image packaging with a reduced property set: only image and command are available. The entryPoint and repositoryCredentialsSecretArn properties are not supported on batch jobs, so private registries that require username/password credentials are not usable from a batch-job prebuilt image.
If a batch job needs to pull from a private registry, use dockerfile packaging instead, or push the image to Amazon ECR first — underneath, AWS ECS authenticates to ECR via the task execution role without needing repositoryCredentialsSecretArn. See the batch job page for full configuration examples.
Image tagging strategy
The image property value is the image reference that Stacktape configures for the container resource. Prefer immutable tags for production so the config clearly identifies the image version being deployed.
| Strategy | Example | Tradeoff |
|---|---|---|
| Immutable tags (recommended) | my-app:v1.2.3 or my-app:abc1234 | Every deploy is deterministic. You always know exactly which code is running. |
latest tag | my-app:latest | Convenient for dev, but non-deterministic — the same tag can point to different image content. |
| Branch-based tags | my-app:main | Good for staging environments that track a branch. Still mutable. |
Use immutable tags (semantic versions or commit SHAs) for production. Mutable tags like latest are non-deterministic — the same tag can resolve to different image content over time. Immutable tags ensure every deploy references a specific, known image.
Set image to the registry reference you want the container resource to use. For production, prefer immutable tags so the configured image version is explicit in review. For details on how the underlying compute resource rolls out a change, see the relevant compute resource page (web service, worker service, etc.).
Prebuilt Image FAQ
When should I use prebuilt image vs letting Stacktape build the image?
Use prebuilt image when the image already exists — built by your CI pipeline, pulled from a public registry, or shared across services. Use js-bundle, buildpack or dockerfile when you want Stacktape to build from source during deployment. Prebuilt image is faster to deploy (no build step) but requires external infrastructure to produce and push images, and the deployed version is only as explicit as the tag you put in the image string.
How do I pull from a private registry?
Store the registry credentials in AWS Secrets Manager as a JSON object with username and password keys, then pass the secret ARN via repositoryCredentialsSecretArn. Public registries (Docker Hub, GitHub Container Registry) need no credentials, and Amazon ECR is authenticated automatically through the task execution role — only non-ECR private registries need repositoryCredentialsSecretArn. Note that batch jobs don't support repositoryCredentialsSecretArn, so for a private batch-job image push it to ECR first or use dockerfile packaging.
What's the difference between command and entryPoint?
The command property overrides the image's Docker CMD instruction — typically the arguments passed to the main process. The entryPoint property overrides the Docker ENTRYPOINT instruction — the executable itself. When both are set, entryPoint is the executable and command provides its arguments. Most users only need command to pass different flags or scripts to the existing entrypoint.
How do I debug startup failures with a prebuilt image?
Check container logs using stacktape logs with the resource name (and --container for multi-container workloads). Common causes of startup failures: the image doesn't expose the expected port, the command override has a typo, required environment variables aren't set, or the process exits immediately instead of staying alive. Verify your entryPoint and command produce a long-running process for always-on resources (web services, private services, worker services).
Can I use the same prebuilt image across multiple Stacktape resources?
Yes. Multiple resources can reference the same image tag, and each pulls independently. This is useful when a single base image serves different roles (API server, worker, migration runner) differentiated only by the command override — build once, deploy many times with different startup arguments.
API reference
PrebuiltImageCwPackagingProps