Docker deploys

Use Docker when your project already has a Dockerfile, needs system packages, or runs a language outside Bex's native build runtimes. Bex can build the image from Git or deploy an image you have already pushed to a registry.

Choose the source​

The workload type is independent of the source: use web, pserv, worker, or cron as appropriate. See Service types.

Build a Dockerfile​

services:
  - name: api
    type: web
    runtime: docker
    repo: https://github.com/your-org/api
    branch: main
    dockerfilePath: ./Dockerfile
    autoDeployTrigger: off

Replace the repository URL with yours. Keep files needed by COPY inside the build context and check any rootDir or Docker context settings for monorepos. Your Dockerfile's default command should start the service. For Dockerfile builds, dockerCommand can override the startup command; native runtime buildCommand/startCommand settings are a different workflow.

Where caching is enabled, unchanged Dockerfile layers are reused from the service's cache; see Build caching. If a rebuild keeps serving stale layers, clear the cache for one deploy as described in How deploys work.

Deploy an existing image​

services:
  - name: api
    type: web
    runtime: image
    image:
      url: ghcr.io/your-org/api:release-1
    numInstances: 1

Replace the image with one you can pull and run. Prefer an immutable release tag or digest so the manifest identifies the intended artifact. Follow the Blueprint guide to authenticate, validate, and apply either example. The examples deliberately omit a health-check path; configure one when your application provides a suitable endpoint.

Image-backed services are not affected by build caching: deploying a prebuilt image runs no build, so there is nothing to reuse and nothing to clear.

Use a private registry​

Create a registry credential in the target workspace through the dashboard or /v1/registrycredentials API. Creating a credential alone does not attach it to a service. Select it in the service creation form, or reference its name in the Blueprint:

services:
  - name: private-api
    type: web
    runtime: image
    image:
      url: ghcr.io/your-org/private-api:release-1
      creds:
        fromRegistryCreds:
          name: ghcr-readonly

ghcr-readonly must match a registry credential available in that workspace. For a Dockerfile that pulls private base images, use the service-level registryCredential.fromRegistryCreds.name reference instead. Store access tokens in the registry credential, not in the image URL or Git manifest.

Prepare the container for Bex​

HTTP services must listen on 0.0.0.0:$PORT; Bex defaults to port 3000. EXPOSE documents a port in an image but does not make the process listen or configure Bex's service port. If the image uses a separate setting, make it match the service listener. Use an unprivileged port: tenant containers drop Linux capabilities.

Keep required state outside the disposable container filesystem. Use a managed datastore or a persistent disk, and handle termination signals so requests or jobs can finish safely during a deployment.

Update an image​

For a Blueprint-managed service, update image.url, validate, and apply the manifest through Bex. Follow the resulting deployment until it completes. Updating a source setting and starting a deploy are distinct API operations; when changing the image through service settings, use the deployment action to release the saved source.

Changing an upstream mutable tag does not by itself submit a Bex deployment. For a predictable release, publish a new versioned image and deploy that reference. To promote the exact image CI tested (immutable digest) from GitHub Actions, see CI deploys a tested image digest. Avoid patching API-managed Kubernetes resources directly: the control plane owns their desired configuration.

Troubleshoot​

Check build logs for Dockerfile/context errors. For image pull failures, verify the image name, tag or digest, registry access, and attached credential. If the image pulls but the process fails, inspect runtime logs, architecture support, its startup command, listener port, and required environment variables. If a Dockerfile rebuild at the right commit still serves old behavior, suspect stale cached layers and work through My change did not ship.

See Web services, Secrets, and Rollbacks.