Skip to content

docs: add dhi image docs #407

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
kmendell wants to merge 1 commit into
base: main
Choose a base branch
from
+25 −4
Open

docs: add dhi image docs #407

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 6 additions & 0 deletions content/configuration/environment.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -31,6 +31,12 @@ Replace each placeholder with the real value from your database.
- `<postgres_port>`: the port Postgres uses
- `<postgres_db_name>`: the database name to connect to

## Container runtime user

Official Arcane images set `ARCANE_DEFAULT_NONROOT=true`, so the process drops to the built-in non-root user (`65532:65532`) when `PUID` and `PGID` are not set.

Use `PUID` and `PGID` if mounted files should be owned by a specific host user and group. If you use a custom Unix Docker socket with `DOCKER_HOST`, Arcane uses that socket path when adding the runtime user to the socket group.

## Environment Variables

<EnvTable />
Expand Down
4 changes: 3 additions & 1 deletion content/guides/gpu-setup.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,9 @@ order: 3
---

> [!IMPORTANT]
> This guide assumes GPU drivers are already installed and configured on your host system. Refer to the respective vendor documentation for driver installation.
> This guide assumes GPU drivers are already installed and configured on your host system. Refer to the respective vendor documentation for driver installation.
>
> Official Arcane images use a minimal hardened runtime base and do not bundle vendor GPU utilities. NVIDIA monitoring relies on `nvidia-smi` being injected by the NVIDIA container runtime. AMD monitoring reads `/sys/class/drm` directly. Intel monitoring requires an image/runtime that provides `intel_gpu_top`.

## NVIDIA GPU Setup

Expand Down
3 changes: 3 additions & 0 deletions content/setup/installation.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -65,6 +65,9 @@ volumes:

## 2. Understand the folders Arcane uses:

> [!NOTE]
> Official Arcane manager and agent images start as root only for startup preparation, then drop to a non-root runtime user by default. Set `PUID` and `PGID` when you want Arcane-created files to use a specific host UID/GID. If you omit them, Arcane uses its built-in non-root user (`65532:65532`).

**_/var/run/docker.sock_**: Gives Arcane access to Docker.

**_arcane-data_**: Arcane's data folder, which stores things like the database and project data.
Expand Down
6 changes: 3 additions & 3 deletions content/setup/next-images.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -19,11 +19,11 @@ Arcane provides "next" builds that contain the latest features and improvements

## Docker Images

Each Image has 3 variants, `next`, `next-static`, and `next-distroless`.
Each image has 3 variants: `next`, `next-static`, and `next-distroless`.

Both the `next` (based on alpine) and the `next-distroless` (based on distroless-static) are built with static binaries. These builds may not contain the required functionality for some external monitoring tools like GPU's etc.
The normal `next` tag uses Arcane's hardened Debian-based runtime image and is the fully featured preview build for the manager and agent.

The normal `next` tag is the fully complete build of Arcane and the Agent, all features should be available.
The `next-static` and `next-distroless` variants use static binaries and smaller runtime images. They are useful for minimal deployments, but they may not include host-provided tooling or shared-library behavior needed by some integrations.

### Arcane Manager (Next)

Expand Down
10 changes: 10 additions & 0 deletions static/config.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -74,6 +74,16 @@
"sourceFile": "backend/internal/config/config.go",
"sourceSymbol": "config.Config.BackupVolumeName"
},
{
"env": "ARCANE_DEFAULT_NONROOT",
"field": "DefaultNonRoot",
"type": "bool",
"defaultValue": "false",
"description": "Enable the official images to drop from root to the default non-root runtime user when PUID/PGID are not set.",
"source": "config.Config",
"sourceFile": "backend/internal/config/config.go",
"sourceSymbol": "config.Config.DefaultNonRoot"
},
Comment on lines +78 to +86
Copy link
Copy Markdown
Contributor

@greptile-apps greptile-apps Bot May 16, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P1 defaultValue contradicts documented official-image behavior

config.json records "defaultValue": "false" for ARCANE_DEFAULT_NONROOT, so the generated <EnvTable /> on the Environment Variables page will show users that this setting defaults to false. However, environment.md (added in this same PR) explicitly states "Official Arcane images set ARCANE_DEFAULT_NONROOT=true", and installation.md says images "drop to a non-root runtime user by default."

A user reading the env table alongside the prose will encounter contradictory signals about what the actual default behavior is. If official images hardcode ARCANE_DEFAULT_NONROOT=true in the Dockerfile or entrypoint, that distinction should be surfaced — either by noting in the description that the code default differs from the image default, or by adjusting defaultValue to reflect the shipped-image default and documenting the code-level fallback separately.

Prompt To Fix With AI 
This is a comment left during a code review.
Path: static/config.json
Line: 78-86

Comment:
**`defaultValue` contradicts documented official-image behavior**

`config.json` records `"defaultValue": "false"` for `ARCANE_DEFAULT_NONROOT`, so the generated `<EnvTable />` on the Environment Variables page will show users that this setting defaults to `false`. However, `environment.md` (added in this same PR) explicitly states "Official Arcane images set `ARCANE_DEFAULT_NONROOT=true`", and `installation.md` says images "drop to a non-root runtime user by default."

A user reading the env table alongside the prose will encounter contradictory signals about what the actual default behavior is. If official images hardcode `ARCANE_DEFAULT_NONROOT=true` in the `Dockerfile` or entrypoint, that distinction should be surfaced — either by noting in the description that the code default differs from the image default, or by adjusting `defaultValue` to reflect the shipped-image default and documenting the code-level fallback separately.

How can I resolve this? If you propose a fix, please make it concise.

Fix in Codex Fix in Claude Code

{
"env": "AUTO_LOGIN_PASSWORD",
"field": "AutoLoginPassword",
Expand Down