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.
Create the app
Section titled “Create the app”- Open a project.
- Select New app.
- In Start from scratch, select Docker image.
- In Image, enter the image reference, such as
ghcr.io/org/app:latest. - In Name, enter a name for the app.
- Under Networking, confirm the port.
- Select a reach.
- 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.
orchard deploy create --image nginx:alpine --name web --port 80 --waitWithout --port, Orchard uses the port the image exposes, or port 80.
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.
Add private registry credentials
Section titled “Add private registry credentials”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.
- Open the project.
- Go to Settings.
- In Registry credentials, select Add.
- Select the Registry.
- Enter the Username and the token.
- Save the credential.
orchard project registry set ghcr.io --username octocat --password-stdin < token.txtorchard project registry listOrchard 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.
| Registry | Username | Token |
|---|---|---|
ghcr.io | Your GitHub username | A classic personal access token with read:packages |
docker.io | Your Docker Hub username | A Docker Hub access token |
registry.gitlab.com | A deploy token user (gitlab+deploy-token-…) or your username | The deploy token, or a personal access token with read_registry |
quay.io | A robot account name | The robot account token |
| Other registries | The username its basic or bearer authentication expects | The 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.
Update the image
Section titled “Update the image”- Open the app.
- Go to Settings > Source & build.
- In Image, enter the new reference.
- Select Save.
orchard deploy image set <id> ghcr.io/org/app:v2 --waitTo update the image from CI, you can also use a webhook token.
Orchard rolls the app onto the new image. Health checks and rollback history apply as they do for any deploy.
Set the pull policy
Section titled “Set the pull policy”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 policy | Behavior |
|---|---|
| Automatic | The 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 cached | Starts reuse the copy already on the node. |
| Always pull | Every 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.
Related resources
Section titled “Related resources”- Configure app networking - Set up ports, reach, and how traffic gets to an app.
- Review app security - Scan the image for known vulnerabilities and check the app’s settings.