Deploy a container image

Deploy an image you built yourself, in CI or on your machine, and Unkey pulls and runs it. There’s no build step and no repository connection, so you decide exactly when a version ships. By the end of this guide you have a , an that runs your image, and a production live on a unkey.app domain. To have Unkey build and deploy on every push instead, see Deploy from GitHub. Before you start, make sure that:

The image is pullable without credentials.
Your container listens on the port in the PORT environment variable, which is 8080 by default.
The reference has a tag (ghcr.io/acme/api:v1.2.3) or a digest (ghcr.io/acme/api@sha256:...). A reference with neither pulls latest at deploy time.

You need a Compute plan before you can deploy. If you don’t have one yet, the dashboard asks you to pick one the first time you try (the dialog is titled Choose a Compute plan), and the CLI rejects the deployment until you do. Only a workspace admin can pick a plan. See Compute plans for what each plan includes.

Dashboard
CLI

Create a project

Open Projects in the dashboard and choose Create project. Enter a Project Name, and Unkey fills in a Slug from it. You’ll use the slug to refer to the project in the API and the CLI. You can change it, as long as it’s unique in your workspace and isn’t default.The dashboard then opens the new-app flow. To add an app to a project later, open the project and choose Create app.

Pick the image

On Deploy a new app, pick Container image. Enter the Image reference and choose Continue to create the app, named after the last part of the image path (with -2, -3, and so on if the project already has an app by that name).

Run a container image card with ghcr.io/acme/storefront-worker:v1.4.2 in the Image field and a Continue button

Check app configuration

The default configuration is enough to run most images without changes:

Build: the image reference. An image app has no build step, and you can’t connect a repository to it later.
Scaling: 0.25 vCPU, 256 MiB of memory, and one instance in us-east-1. See Runtime settings.
Environment variables: mark secrets as sensitive to make them write-only. See Environment variables.

Build and scaling settings you save here apply to both the production and preview . The port can be changed for each environment individually later by navigating to App settings > Environments, selecting the environment, and clicking Configure on the Runtime card.Leaving before you deploy asks you to discard the app.

Deploy

Choose Deploy. The dashboard deploys the image to production and opens the deployment page. The deployment moves through pending, starting, building, deploying, network (shown as Assigning Domains), and finalizing to ready. The building step has nothing to build, so it’s short. If another deployment in the workspace is running, it waits its turn.At ready the app is live. For project payments, app api, and workspace acme, production answers on payments-api-acme.unkey.app (or payments-acme.unkey.app if the app slug is default). The deployment page lists every domain.If the deployment ends failed, the page shows the failed step and an error code. Deployments lists the codes and how to fix them.

Ship a new version

Push a new image to your registry. Then open the app’s Deployments page and choose Create deployment. Pick the Environment and enter the Image Reference, or pick an image you deployed before.A production deployment that reaches ready becomes the live deployment and the production domains move to it, unless the app is rolled back. A preview deployment gets its own domains.

Set up the CLI

Install the CLI and store a root key with unkey auth login, or set UNKEY_ROOT_KEY. See CLI authentication.The root key needs permission to create projects, apps, and deployments, and to read deployments. See the Permission reference.

Create a project

The slug is what you pass to later commands. It must be unique in your workspace, and default is reserved.

unkey projects create --name=Payments --slug=payments

Create the app

Pass the image with --oci. It becomes the app’s default image, and you can’t connect a repository to the app later.

unkey apps create \
  --project=payments --name=API --slug=api \
  --oci='{"image":"ghcr.io/acme/api:v1.2.3"}'

The app gets production and preview , and starts with 0.25 vCPU, 256 MiB of memory, and one instance in one region. See Runtime settings.

Deploy

With no source flag, the app deploys its default image. The command returns the deployment ID right away, and the rollout runs in the background.

unkey deployments create \
  --project=payments --app=api --environment=production

Check its status with the ID it returned:

unkey deployments get --deployment-id=d_... --output json

The deployment moves through pending, starting, building, deploying, network, and finalizing to ready. The building step has nothing to build, so it’s short. If another deployment in the workspace is running, it waits its turn.At ready the app is live. For project payments, app api, and workspace acme, production answers on payments-api-acme.unkey.app (or payments-acme.unkey.app if the app slug is default). The deployment page in the dashboard lists every domain.If the deployment ends failed, error.code says why. Deployments lists the codes and how to fix them.

Ship a new version

Push a new image to your registry, then deploy it with --oci. A tag such as :latest is pinned to the exact image it points to at deploy time, so the deployment doesn’t change when the tag moves.

unkey deployments create \
  --project=payments --app=api --environment=production \
  --oci='{"image":"ghcr.io/acme/api:v1.2.4"}'

unkey deployments create \
  --project=payments --app=api --environment=production \
  --deployment='{"deploymentId":"d_..."}'

A production deployment that reaches ready becomes the live deployment and the production domains move to it, unless the app is rolled back. A preview deployment gets its own domains.

Next steps

Production and preview

Promote a deployment, roll back, and redeploy.

Deploy from GitHub

Let Unkey build and deploy on every push instead.

Instances and autoscaling

What the runtime defaults mean. Change them on Runtime settings.

Environment variables

Give the image its configuration and secrets.

Add API key authentication later

When you want the gateway in front of this app to check API keys before requests reach it, create a keyspace and keys in API Management, then attach a key-auth policy to the environment. Nothing in this guide depends on it.

Get started

Concepts

Build

Configure

Networking

Gateway

Observe

Deploy a container image

Create a project

Pick the image

Check app configuration

Deploy

Ship a new version

Set up the CLI

Create a project

Create the app

Deploy

Ship a new version

Next steps

Production and preview

Deploy from GitHub

Instances and autoscaling

Environment variables

Add API key authentication later