Skip to content
Install

Deploy from an image

Deploy from an image when something else already builds it, such as your CI pipeline or a vendor that publishes one. Orchard skips the build and pulls the image directly, so the app starts as fast as the registry can serve it. Private registries work too, with a credential stored once per project or organization.

  1. Open a project.
  2. Select New app.
  3. In Start from scratch, select Docker image.
  4. In Image, enter the image reference, such as ghcr.io/org/app:latest.
  5. In Name, enter a name for the app.
  6. Under Networking, confirm the port.
  7. Select a reach.
  8. Select Deploy.

When the image exposes a port, Orchard sets the first port for you and shows the value below Image. If the image exposes no port, the form uses port 80. Set the port your process listens on.

An app with no port does not get a URL. To run a worker or a queue consumer with no URL, set the reach to Internal.

To pull a private image, add a credential for its registry. Orchard stores one credential per registry for each project. It checks the credential against the registry when you save it.

  1. Open the project.
  2. Go to Settings.
  3. In Registry credentials, select Add.
  4. Select the Registry.
  5. Enter the Username and the token.
  6. Save the credential.

Orchard attaches the credential to every app and job in the project whose image is on that registry. Those pods restart to pick it up. ghcr.io/org/app uses the ghcr.io credential. user/app and docker.io/user/app use the Docker Hub credential.

You can also add credentials for a whole organization under Organization settings > Registry credentials. Every project uses them unless it sets its own.

RegistryUsernameToken
ghcr.ioYour GitHub usernameA classic personal access token with read:packages
docker.ioYour Docker Hub usernameA Docker Hub access token
registry.gitlab.comA deploy token user (gitlab+deploy-token-…) or your usernameThe deploy token, or a personal access token with read_registry
quay.ioA robot account nameThe robot account token
Other registriesThe username its basic or bearer authentication expectsThe matching password or token

For ghcr.io, use a classic token. GitHub fine-grained tokens cannot read packages. If an organization owns the package, also authorize the token for SSO in that organization.

  1. Open the app.
  2. Go to Settings > Source & build.
  3. In Image, enter the new reference.
  4. Select Save.

Orchard rolls the app onto the new image. Health checks and rollback history apply as they do for any deploy.

Orchard does not watch your registry. If you push a new image to the same tag, nothing changes until the app restarts. The pull policy decides whether the restart fetches the new image.

Pull policyBehavior
AutomaticThe default. A tag that can move, such as latest, main, or a major version like 17, uses Always. A pinned tag or a digest uses IfNotPresent.
Use cachedStarts reuse the copy already on the node.
Always pullEvery start fetches the image again. The new app form calls this option Always re-pull.

To change the policy on an existing app, go to Settings > Source & build > Pulling, or run orchard deploy pull-policy set <id> --policy always. The flag accepts auto, always, or ifnotpresent.

Where you control the build, tag images by commit or version. Rollbacks then point at a fixed image. Apps built from a repository get a unique tag for every build.