Koo Docs
View as Markdown

Deploy a container

You point a web service at an image reference, set the port, and Koo rolls it out as a new deployment. Prefer not to build the image yourself? Deploy from Git instead; deploys with AI Coming soon will follow.

What you need

  • An OCI image pushed to a registry (Docker Hub, GHCR, or any other registry), referenced as registry/name:tag — for example ghcr.io/acme/web:1.4.2.
  • The TCP port your server listens on inside the container.
  • An app to deploy into. If you don't have one yet, the quickstart walks through creating your first.

Image deploys skip the build step entirely: Koo's hosting layer pulls your image as-is and rolls it out.

Deploy from the console

  1. Open your app in the console.
  2. Add a web service, or select an existing one.
  3. Paste the image reference into the service's source.
  4. Set the port your container listens on.
  5. Deploy.

The deployment moves through deploying and reaches ready once the rollout is applied. The previous version keeps running until the new one is ready, and the live state of the service is always visible on its status. You can also trigger image deploys programmatically through the Deployments API.

Public and private images

Public image references work as-is — no credentials needed.

Private registries aren't supported yet. Private-image pull credentials will be managed like sensitive variables Coming soon — until then, the image must be publicly pullable.

Redeploying a new tag

To ship a new release, push the new tag to your registry, update the service's image reference, and deploy again. Every deploy creates a new immutable version — nothing is mutated in place, and you can roll back to any earlier version.

Prefer a unique tag per release (a version number or commit SHA) over reusing a mutable tag like latest, so each deployment maps to a known image.

Troubleshooting

Image not found. Check the reference for typos, confirm the tag exists in the registry, and confirm the image is public — private images fail to pull until private-registry support ships.

Wrong architecture. Koo runs linux/amd64 containers. An image built only for arm64 (the default on an Apple Silicon machine) will fail to start — rebuild with docker build --platform linux/amd64 . or publish a multi-arch image.

Crash loop. If the deployment reaches ready but the service isn't running, the container is likely exiting on boot. Check the service's logs for the startup error, confirm the port you set matches what the server actually binds, and confirm any required environment variables are set.

Still stuck? Reach out via support.