Skip to content

Image Builds

Build container images from Compose projects or a build workspace, locally or with Depot.

Arcane builds images from a Dockerfile on the local Docker host, or on Depot, a hosted build service.

  1. Mount a builds folder into the Arcane container at /builds. In Arcane’s compose.yaml, use a host folder such as /srv/arcane/builds:/builds, or a named volume such as arcane-builds:/builds declared under top-level volumes:.
  2. Open Settings → Builds and pick the agent. Build settings are per agent.
  3. Set the fields below, then save.
Setting What it does
Builds Directory Absolute path inside the Arcane container that the Build Workspace opens. Default: /builds.
Default Provider Local Docker or Depot.
Build Timeout Between 60 and 14,400 seconds.
Depot Project ID and Depot Token Set both to enable Depot. A blank Depot token on save keeps the saved one.

On the project page, use Build or Build & Deploy for Compose services with build:.

  1. Open Images → Builds.
  2. Under Source, pick the build context:
    • Workspace folder: a folder in the Builds Directory. Select Choose folder, or pick Use as build context on a folder in the Files tab.
    • Git repository: a Git URL. Add #ref or #ref:subdir to pick a branch, tag, or commit and a subfolder, such as https://github.com/owner/repo.git#main:docker/app.
  3. In Build Configuration, name the image.
  4. Optional: expand Advanced for Dockerfile path, target stage, platforms, build args, labels, cache, and runtime options.
  5. Pick a provider, and choose Push, Load, or both.
  6. Click Build and watch the live output.
  • A Git repository source uses the credentials of an enabled Git repository with the same URL. Otherwise Arcane clones it anonymously.
  • To add files to the workspace, upload them in the Files tab. Files of any size are accepted.
A finished build with its context files and output.
A completed local Docker image build with its context files and output.A completed local Docker image build with its context files and output.

A finished build with its context files and output.

Build History lists every build’s status, provider, time, and duration. Open a row for its configuration and output. Rebuild loads that configuration into the form.

Load-only builds use the free-form Image Tags field: full references, separated by commas or newlines.

With Push on (always on for Depot), choose:

  • Registry: one of your enabled container registries.
  • Repository name: one of the repository names saved on that registry.
  • Tag: free text, such as 1.0.0.

The resulting host/repository:tag shows as a read-only Image reference above the build button.

  • Changing the registry clears the repository.
  • Repositories not in the registry’s list are rejected.
Message What to do
No repository names configured for this registry Add repository names in your registry settings.
No enabled registries Add or enable a container registry.
No permission to list registries Ask an admin for registry read access.
Provider Where it builds Push and Load
Local Docker The Docker host running Arcane. You choose. With neither selected, the image is loaded.
Depot Depot’s hosted build machines. Push is always on and Load is always off.

Manual builds can override the agent’s default provider. If Depot isn’t configured, Arcane uses Local Docker.

Push sends the image to a registry. Load adds it to local Docker images. Unsupported options are rejected.

Option Meaning Local Docker Depot
Platforms Target CPU architectures, such as linux/amd64. One platform Many
Cache To Where to export the build cache, such as a registry ref. No Yes
Entitlements Extra BuildKit permissions, such as network.host. No Yes
Privileged Runs build steps with elevated privileges. No Yes
Network, Isolation, Shm size, Ulimits, Extra Hosts Runtime settings for RUN steps. Yes No