> ## Documentation Index
> Fetch the complete documentation index at: https://docs.shardcloud.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Custom Docker Images

> Deploy apps from your own Dockerfile instead of Shard Cloud's auto-detected language containers.

<CardGroup cols={2}>
  <Card title="Bring Your Own Dockerfile" icon="docker" href="#what-is-a-custom-docker-image">
    Full control over your runtime — no auto-detected language container
  </Card>

  <Card title="Auto-Rebuild on Push" icon="github" href="#auto-rebuild-on-github-push">
    Link a GitHub repo so every push rebuilds your image
  </Card>
</CardGroup>

<Note>
  Custom Docker Images require a **Core plan or higher**.
</Note>

## What Is a Custom Docker Image

For most apps, the [supported languages](/apps#production-optimized-containers) auto-detect your
project and run it in a production-hardened container for you. A **Custom Docker Image** is the
alternative for when you need full control: you upload a build context — a `.zip` containing a
`Dockerfile` at its root — and Shard Cloud builds it and pushes it to an internal image registry.

Unlike a normal app, a custom image has **no language, version, entrypoint, or custom command**
settings. Whatever your image's own `ENTRYPOINT`/`CMD` runs is what runs — the image is the
complete definition of how your app starts.

## Building an Image

<Steps>
  <Step title="Prepare your build context">
    Zip up your project with a `Dockerfile` at the root of the archive.
  </Step>

  <Step title="Upload">
    Upload the zip from the dashboard, along with a name for the image. The zip must be no larger
    than **100MB**.
  </Step>

  <Step title="Build">
    Shard Cloud stores the image immediately and kicks off the build in the background — builds
    can take several minutes, so you don't wait around for it.
  </Step>
</Steps>

### Watching the Build

The image goes through a simple status lifecycle:

| Status     | Meaning                                                  |
| ---------- | -------------------------------------------------------- |
| `building` | Upload/build is in progress                              |
| `success`  | Build completed and the image was pushed to the registry |
| `failed`   | Build or upload failed (the dashboard shows why)         |

You can watch the build's live output from the dashboard while it's running, or review the log
from the last completed build afterward.

## Rebuilding an Image

Uploading a new build context for an existing image triggers a fresh build in place — same
size/type limits as creating one. The image keeps the same identity throughout its life, so
anything referencing it (like an app deployed from it) doesn't need to change.

<Warning>
  Rebuilding only updates the image in the registry — it does **not** automatically restart or
  redeploy apps currently running from that image. They keep running whatever version they last
  deployed until you restart or redeploy them yourself.
</Warning>

A rebuild is rejected if the image is already building, and an image can't be deleted while a
build is in progress either.

## Deploying an App From an Image

Once an image has built successfully, you can deploy it as an app directly from the dashboard —
give it a name, RAM, and optional description/subdomain/environment variables. This is the same as
creating a normal app, minus the file upload and minus language/version/entrypoint/custom command
— those come from the image itself.

Deploying multiple apps from the same image is fine; the dashboard shows every app currently
running from a given image alongside it.

## Auto-Rebuild on GitHub Push

Just like [Git integration](/tutorials/platform/git-integration) for regular apps, you can link a
GitHub repository to a custom image so every push triggers a fresh build automatically.

<Steps>
  <Step title="Connect GitHub">
    Go to **Config** → **Integrations** in the dashboard and connect your GitHub account, if you
    haven't already.
  </Step>

  <Step title="Link the repository">
    From the image's page in the dashboard, choose the repository to link. Shard Cloud registers a
    push webhook on the repository for you.
  </Step>

  <Step title="Push">
    Every push to the linked repository starts a rebuild the same way a manual rebuild would —
    same "does not auto-redeploy running apps" behavior applies.
  </Step>
</Steps>

You can unlink the repository at any time from the image's page to stop auto-rebuilding. This only
clears the link on Shard Cloud's side — it doesn't remove the webhook from the GitHub repository
itself.

## Deleting an Image

Deleting an image removes it from the registry entirely. This is blocked while a build is in
progress. Deleting an image also deletes **every app currently deployed from it** — there's
nothing left for those apps to run once the image is gone.

## Limits

| Limit                      | Value                                                |
| -------------------------- | ---------------------------------------------------- |
| Build context size         | 100MB, `.zip` only, `Dockerfile` at the archive root |
| Custom images — Core       | 2                                                    |
| Custom images — Pro        | 6                                                    |
| Custom images — Enterprise | 20                                                   |

Limits apply to how many images you can have at once, regardless of their build status.