Start here
Docker images
Run a public container image, in any language, without building anything on OceanLaunch.
Create the app
In your workspace choose New app, then Docker image, and give the image's name and tag, like
ghcr.io/acme/api:1.4 or nginxinc/nginx-unprivileged:1.29-alpine. Without a tag,
latest is used. You can also give a digest (@sha256:…).
Before anything is deployed, OceanLaunch reads the image from its registry and checks it:
- On a known registry: Docker Hub,
ghcr.io,quay.io,registry.gitlab.com,public.ecr.awsormcr.microsoft.com. Private images work on the first four, see below. - linux/amd64: multi-platform images are fine; that version is the one that runs.
- Up to 2 GB (compressed).
- Not root. The image must run as an unprivileged user, set with a
USERline in its Dockerfile. Many official images run as root; most have an unprivileged sibling, such asnginxinc/nginx-unprivilegedfor nginx.
Port and health check
Leave the port empty to use the one the image exposes (EXPOSE), or 8080 if it exposes none. Any port
works, including 80. PORT and SERVER_PORT are set to it, for apps that read them.
A new version gets traffic once something listens on the port, or, if you set a health check path, once that path answers with a 2xx status. This works even in images without a shell or curl. Changing the port or the path in Settings rebuilds the app on the next deploy, which takes a little longer than usual.
Private images
Turn on Private image and give the registry's username and a read-only access token:
| Registry | Username | Token |
|---|---|---|
| ghcr.io | Your GitHub username | A personal access token with only read:packages |
| Docker Hub | Your Docker Hub username | A personal access token with Read-only access |
| quay.io | A robot account's name | Its token, with read permission on the repository |
| registry.gitlab.com | A deploy token's username | The deploy token, with read_registry |
The token is checked against the image before anything is saved, then stored encrypted and never shown again (only its last four characters). It's used only to read this image: OceanLaunch's build service copies the image into OceanLaunch's own private registry for each deploy, and your app runs from that copy. Change the image, the username or the token on the app's Settings tab; leave the token empty to keep the stored one, or clear the username to make the image public again.
Versions
Each deploy runs the exact image that was checked: OceanLaunch pins the tag to its digest, and the app page shows it. So a restart, a stop and start, or adding a domain runs the same version, even if someone pushed a new one to the tag in the meantime.
- Deploy latest reads the tag again and runs whatever it points to now.
- To run another tag (or another image), change it on the app's Settings tab. It's checked, saved and deployed straight away.
How it runs
- The image runs as it is: its user, entrypoint, command and files. OceanLaunch adds one small file (a static
busybox, at
/ol/busybox) for the health check. - No Linux capabilities, your plan's memory and CPU, and your workspace's private network, like every app. Your variables and secrets are set when it runs.
- Docker Hub limits how often images can be pulled. If a deploy says the registry is limiting requests, wait a few minutes and deploy again.