Deploy an app from an image
Create an app from a public or private container image — source, ports, size, temporary space, environment, health checks and advanced settings.
To deploy an app, open Public Cloud → Apps, select Create app, enter the image's repository and tag, choose its ports and size, and select Create and deploy. Every deploy pins the exact image (its digest) that the tag points to at that moment, so a later push to the same tag does not change a running app until you deploy again.
What does my image need?
| Requirement | Why |
|---|---|
A linux/amd64 build | The platform runs amd64 instances |
| A non-root user | Images that run as root are not allowed. The platform runs your image as user 10001 unless you set another |
| A numeric user, if it sets one | Set USER 1001 rather than a user name, so the platform can check it |
| A listening port | For a website or an API: the port your server listens on, HTTP for a public port |
Check image warns you about each of these before you create the app.
Step 1: Source
- Registry: Public image — no credential, or a connected registry.
- Repository: for example
docker.io/library/nginxorghcr.io/your-org/api. Browse lists a connected registry's repositories. - Tag: letters, digits,
_,.and-, up to 128 characters. Tags lists the available tags. - Select Check image to fill in the name, ports, health checks and user from the image.
Step 2: Basics
- Name: 2 to 80 characters, shown in the console. You can change it later.
- Short name: up to 40 lowercase letters, digits and hyphens, starting with a letter. Permanent: it names the app's public address and its private address in the project.
- Description (optional): up to 280 characters.
Step 3: Networking
List the ports your image listens on: a Name (lowercase, up to 15 characters), the Port (1 to 65535) and the Protocol (HTTP, gRPC or TCP). An app has 1 to 10 ports; one HTTP port can be public. The public port gets an HTTPS address on the internet; every port is reachable from the project. See Ports and addresses.
Step 4: Size & scaling
Choose a size and the number of Instances, or turn on Autoscale. See Sizes and scaling.
Step 5: Storage
Temporary space per instance is writable space that is emptied when an instance restarts: 1, 2, 5, 10 or 20 GB, with 1 GB included. For data that must survive restarts, add a volume.
Step 6: Environment
Add environment groups shared with other apps, and the app's own variables, each a Plain value or a Secret. See Environment variables and secrets.
Step 7: Health checks
- Readiness: the app receives traffic only while this passes.
- Liveness: an instance that keeps failing it is restarted.
- Startup: gives a slow-starting app time before the other checks begin.
Each check is an HTTP path, a TCP connection or a command.
Step 8: Pre-deploy job and advanced settings
- Run a job before each deploy: runs with the new release's image and environment before it goes live — for example database migrations. It is skipped when the image does not change. Timeout 0.5 to 60 minutes (default 10), retries 0 to 3.
- Advanced: override the image's Command, Arguments and Working directory (an absolute path), and set Run as user ID (1 or more; never 0).
Step 9: Create
The summary shows the estimated monthly cost before GST and credits. Select Create and deploy, or Save as draft to deploy later. The first deploy shows each step the platform works through.
Why did my deploy fail?
The app's page says why in plain words. The most common reasons:
| Message | What to do |
|---|---|
| The image couldn't be pulled | Check the repository and tag, and for a private image the registry connection |
| The app ran out of memory | Choose a larger size or lower the app's memory use |
| The deploy didn't finish within 10 minutes | Check the logs and the readiness check: the app must start answering |
| The project's resource quota is used up | Free up resources or raise your limits |
Last updated on