Run a prebuilt image (BYOI)

Goal: run an image you’ve already built and pushed elsewhere — your own CI, a vendor image, a base you maintain. The platform skips the build entirely and pulls the image as-is, then runs it like any Ignite app. This is “bring your own image” (BYOI).

This applies the image — BYOI branch of Code & Runtimes. There’s no build step and no --build-arg/--dockerfile-path — the image is final.

You own the HTTP server. The image runs as-is, so your container must listen on $PORT and answer POST /. The platform threads the x-ignite-* request headers into the pod just like the other image paths.

Shape:

   pushed image    ──►  app create  ──►  draft save                ──►  draft publish  ──►  invoke
   (in your             (no runtime)     (--image-ref <ref>             (no build —          (your
    registry)                             [--registry-secret-ref s])     pull image →         container
                                                                         version 1)           serves it)

Prerequisites

• The dodil CLI installed and authenticated — dodil ignite config set token <token> and dodil ignite config set api_endpoint rpc.dev.dodil.io:443 (or export DODIL_TOKEN=<token>). See CLI Basics.
• Your org name for the org:name ID form. We use acme-corp.
• An image that listens on $PORT and answers POST /. We use `ghcr.io/acme-corp/greeter:1.0.0`.

1. Create the app

No --runtime — image-mode apps are defined by their source:

dodil ignite app create greeter --description "Prebuilt greeter image"

The app id is now acme-corp:greeter.

2. Save — public image

For BYOI the source flag is --image-ref (a fully-qualified image reference; pin a digest or tag). For a public image that’s all you need:

dodil ignite draft save acme-corp:greeter \
  --image-ref ghcr.io/acme-corp/greeter:1.0.0

The source flags are mutually exclusive. --image-ref runs a prebuilt image — it does not take --build-arg or --dockerfile-path (there’s no build). To build from a local context use --code (Build an image from your code); to build from a repo use --git-url (Deploy from a git repo).

3. Save — private registry

For a private registry (private ghcr.io, Docker Hub private, ECR, …), the platform needs credentials to pull. Create a registry Secret first, then reference it with --registry-secret-ref:

dodil ignite secret create greeter-registry \
  --type registry \
  --server ghcr.io \
  --username "$REGISTRY_USER" \
  --password "$REGISTRY_TOKEN"

dodil ignite draft save acme-corp:greeter \
  --image-ref ghcr.io/acme-corp/greeter-private:1.0.0 \
  --registry-secret-ref greeter-registry

See Secrets for the exact registry-secret fields your account supports.

The platform’s own admin registry uses mTLS and needs no secret — --registry-secret-ref is only for external private registries.

4. Publish

There’s no build to wait on — publishing validates the image is pullable (using the registry secret if set) and cuts an immutable version pointing at it:

dodil ignite draft publish acme-corp:greeter

After the first publish the app gets a direct FQDN — `greeter-acme-corp.ignite.dodil.cloud` (port 80). Verify:

dodil ignite app get acme-corp:greeter -o json | jq '{active_version, public_urls}'

5. Invoke

dodil ignite invoke acme-corp:greeter -p '{"name": "ada"}'

{ "greeting": "Hello, ada!", "execution_id": "01J..." }

Cold start note

BYOI runs your container, so the cold start includes pulling the image on a cold node — the heaviest of the paths if the image is large, and there’s no compile step to slim it down for you. Pin small base images, or keep pods warm with ScalingConfig.reserved_capacity > 0. See API Reference → Cold starts vs warm pods.

Iterating

Push a new image (a new tag or digest), then draft save with the updated --image-ref and draft publish to cut a new version. Pin a digest (@sha256:...) rather than a moving tag so a version always resolves to the same bits. Roll back with dodil ignite version rollback acme-corp:greeter <version>.

Common gotchas

See also

• Code & Runtimes — the image vs compile branches
• Build an image from your code — let the platform build the image for you
• Deploy from a git repo — build from a repo
• Secrets — registry and git credentials
• API Reference → Cold starts vs warm pods — image pulls vs warm pods