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.
Configure build settings
Section titled “Configure build settings”- Mount a builds folder into the Arcane container at
/builds. In Arcane’scompose.yaml, use a host folder such as/srv/arcane/builds:/builds, or a named volume such asarcane-builds:/buildsdeclared under top-levelvolumes:. - Open Settings → Builds and pick the agent. Build settings are per agent.
- 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. |
Build from a project
Section titled “Build from a project”On the project page, use Build or Build & Deploy for Compose services with build:.
Run a manual build
Section titled “Run a manual build”- Open Images → Builds.
- 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
#refor#ref:subdirto pick a branch, tag, or commit and a subfolder, such ashttps://github.com/owner/repo.git#main:docker/app.
- In Build Configuration, name the image.
- Optional: expand Advanced for Dockerfile path, target stage, platforms, build args, labels, cache, and runtime options.
- Pick a provider, and choose Push, Load, or both.
- 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.
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.
Name the image
Section titled “Name the image”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. |
Build providers
Section titled “Build providers”| 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.
Reference
Section titled “Reference”Build options
Section titled “Build options”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 |