Image Builds

Build images from a Dockerfile, for a Compose project’s build: services or by hand in the Build Workspace, on the local Docker host or on Depot, a hosted build service.

Configure build settings

Build settings are per environment, under Settings → Builds:

1. Builds Directory: absolute path inside the Arcane container that the workspace opens.
2. Default Provider: Local Docker or Depot.
3. Build Timeout: between 60 and 14,400 seconds.
4. Depot Project ID and Depot Token: set both to enable Depot.

Tip

A blank Depot token on save keeps the saved one.

The Build Workspace reads contexts from Builds Directory (/builds by default) in the Arcane container. In Arcane’s compose.yaml, mount a host folder such as /srv/arcane/builds:/builds, or a named volume such as arcane-builds:/builds declared under top-level volumes:.

Build from a project

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

Note

Depot builds and pushed builds need an explicit image: name on each service. Generated local-only tags can’t be pushed.

Run a manual build

Build an image from a workspace and follow the build output in Arcane.

×

Build an image from a workspace and follow the build output in Arcane.

1. Open Images → Builds and choose a context folder in the left panel.
2. In Build Configuration, name the image.
3. Optional: expand Advanced for Dockerfile path, target stage, platforms, build args, labels, cache, and runtime options.
4. Pick a provider and choose Push, Load, or both.
5. Click Build and watch the live 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.

Name the image

Load-only builds use the free-form Image Tags field: full references separated by commas or newlines. With Push on (always 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

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 environment’s default provider. If Depot isn’t configured, Arcane uses Local Docker.

Reference

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