diff --git a/content/configuration/environment.md b/content/configuration/environment.md index a8ebd909..10a68faf 100644 --- a/content/configuration/environment.md +++ b/content/configuration/environment.md @@ -31,6 +31,12 @@ Replace each placeholder with the real value from your database. - ``: the port Postgres uses - ``: 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 diff --git a/content/guides/gpu-setup.md b/content/guides/gpu-setup.md index 2f4d6687..547a2235 100644 --- a/content/guides/gpu-setup.md +++ b/content/guides/gpu-setup.md @@ -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 diff --git a/content/setup/installation.md b/content/setup/installation.md index 2a9870e0..5622df10 100644 --- a/content/setup/installation.md +++ b/content/setup/installation.md @@ -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. diff --git a/content/setup/next-images.md b/content/setup/next-images.md index 2f70d793..1166b6b4 100644 --- a/content/setup/next-images.md +++ b/content/setup/next-images.md @@ -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) diff --git a/static/config.json b/static/config.json index 1f4febab..442b5fb0 100644 --- a/static/config.json +++ b/static/config.json @@ -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" + }, { "env": "AUTO_LOGIN_PASSWORD", "field": "AutoLoginPassword",