---
title: Build challenge images
description: Upload a Docker build context and let the platform build and store your challenge images.
---

Container challenges run from Docker images that Athena builds for you: you upload a zipped build context, the platform builds and stores the image, and the result becomes selectable in the challenge editor. You never push to a registry yourself.

This guide covers the build workflow itself. For wiring a built image into a challenge end to end, follow the [container challenge tutorial](/organizers/tutorials/run-a-container-challenge).

:::note
Image builds aren't available on **Extra Small** events, which are static-challenges-only, and the **Image builds** page doesn't appear in their dashboard. Pick **Small** or larger when creating an event that needs containers.
:::

1. **Prepare your build context**

    Zip up a folder with a `Dockerfile` at its root, not inside a
    subfolder. Everything else in the archive is the build context, so any
    language or stack works:

    - Dockerfile
    - app/
      - server.py
      - requirements.txt
    - flag.txt

    The zip must stay under **100 MB**, and it can't contain symlinks. If
    the Dockerfile isn't at the root, the build fails with *"archive must
    contain a Dockerfile at its root"*.

2. **Upload and start the build**

    Open **Image builds** in your event's dashboard and click **New build**.
    In the dialog:

    - **Name** the image, e.g. `my-challenge`, using lowercase letters and
      digits, with dashes, dots, and underscores allowed.
    - Drag your zip onto the **build context** dropzone (or **Browse
      files**).
    - Optionally click **Add** to pass build args as key/value rows; these
      are handed to Docker at build time, up to 32 of them.

    Click **Upload and build**. After the upload progress completes you'll
    see **Build started.** and the build appears in the table.

3. **Watch the build**

    The **Builds** table tracks each build through **Queued**, **Building**,
    and finally **Succeeded** or **Failed**, refreshing itself every few
    seconds while a build is running. A failed build shows its error message
    under the status badge.

    A build that's taking too long, or that you started by mistake, can be
    stopped with the **Cancel** button while it's queued or building. The
    build stops immediately, the row moves to **Cancelled**, and no image is
    published. Minutes already spent still count against your build-minute
    allowance, and the uploaded context is discarded, so starting again means
    uploading the zip a second time.

    There's no log viewer or retry: to try again after a failure, fix the
    context and upload a new build. Delete (trash icon) removes a finished
    build's row and its stored image.

4. **Use the image in a challenge**

    Every successful build is pinned to its exact content digest. The
    **Image** column shows a truncated `sha256:` digest, and clicking it
    copies the digest. Rebuilding under the same name creates
    a new entry with a new digest, so a challenge keeps serving exactly the
    image you picked until you change it.

    In the challenge editor's **Runtime setup** section, each service's
    **Image** dropdown lists your successful builds as `name (sha256:…)`.
    If you delete an image a challenge still references, the dropdown shows
    it as *no longer available*; select a current build before saving.

## Quotas

The **Build quota** card at the top of the page tracks two meters for the event, each shown as a used/limit bar:

- **Docker storage**: the space your built images occupy. Only successful builds count against it, and deleting an image frees its space. If your storage is exhausted, starting a build fails with *"docker storage quota exhausted; delete an existing image first"*, and a build whose result wouldn't fit fails rather than pushing.
- **Build minutes**: build time consumed by every run, successful or not, rounded up to whole minutes. When they run out you'll see *"build minutes for this event are exhausted"*.

Both limits scale with the event size you picked at creation, so budget your experimenting: failed builds don't take storage, but they do burn minutes.
