Modern Docker Management, Designed for Everyone
Go composecontainer-managementcontainersdockerdocker-composedocker-managementgoself-hostedsveltekittypescriptweb-ui
fix: container permissions and removed the need for DOCKER_GID
Kyle Mendelldde20c0cff5d
diff --git a/Dockerfile b/Dockerfileindex 49858fe4e..d2f38780b 100644--- a/Dockerfile+++ b/Dockerfile@@ -25,11 +25,9 @@ RUN delgroup ping && apk del iputilsWORKDIR /app# Set up environment variables early for better caching+# These will serve as defaults if not overridden in docker-compose.ymlENV DOCKER_GID=998 PUID=1000 PGID=1000-# Create necessary groups and users-RUN addgroup -g ${PGID} arcane && adduser -D -u ${PUID} -G arcane arcane && addgroup -g ${DOCKER_GID} docker && adduser arcane docker-# Set up directories and permissionsRUN mkdir -p /app/data && chmod 755 /app/data@@ -42,7 +40,8 @@ COPY --chmod=755 scripts/docker/entrypoint.sh /usr/local/bin/entrypoint.sh# Install only production dependenciesCOPY package*.json ./-RUN npm install --omit=dev && npm cache clean --force && chown -R arcane:arcane /app+# The chown part is removed as 'arcane' user might not exist here+RUN npm install --omit=dev && npm cache clean --force# Configure containerEXPOSE 3000diff --git a/docker-compose.yml b/docker-compose.ymlindex 3cc7644cd..2139aba9e 100644--- a/docker-compose.yml+++ b/docker-compose.yml@@ -2,19 +2,43 @@ services:arcane:image: ghcr.io/ofkm/arcane:latestcontainer_name: arcane- user: rootports:- - '3000:3000'+ - '3000:3000' # Exposes Arcane's web interface on port 3000 of the host.volumes:+ # Mount the Docker socket to allow Arcane to manage Docker.- /var/run/docker.sock:/var/run/docker.sock+ # Mount a volume for Arcane's persistent data (stacks, settings, etc.).+ # Replace './arcane-data' with your preferred host path.- ./arcane-data:/app/dataenvironment:- - APP_ENV=production- - DOCKER_GID=998 # Find using: getent group docker | cut -d: -f3- - PUBLIC_SESSION_SECRET=your-secure-random-32-character-string-here # Generate using: openssl rand -base64 32- # - PUBLIC_ALLOW_INSECURE_COOKIES=true # Uncomment only for local HTTP testing without SSL/TLS- restart: unless-stopped+ - APP_ENV=production # Sets the application environment to production.-# Optional: Define the volume if you want Docker to manage it+ # --- User and Group ID Configuration (Optional but Recommended for Volume Permissions) ---+ # These variables control the user and group Arcane runs as inside the container.+ # Matching these to your host user's UID/GID can help avoid permission issues+ # with the mounted /app/data volume.+ - PUID=1000 # User ID for the 'arcane' user inside the container. Defaults to 1000.+ - PGID=1000 # Group ID for the 'arcane' group inside the container. Defaults to 1000.++ # --- Docker Group ID (Usually Handled Automatically) ---+ # - DOCKER_GID=998 # GID for the 'docker' group inside the container.+ # The entrypoint script typically auto-detects and sets this based on the+ # GID of the mounted /var/run/docker.sock.+ # Only set this if you have a specific need or the auto-detection fails.++ # --- Session Configuration ---+ # Generate a strong secret using: openssl rand -base64 32+ - PUBLIC_SESSION_SECRET=your-secure-random-32-character-string-here++ # --- Advanced/Debugging (Uncomment if needed) ---+ # - PUBLIC_ALLOW_INSECURE_COOKIES=true # Uncomment only for local HTTP testing without SSL/TLS.+ # - LOG_LEVEL=debug # For more verbose logging from Arcane.+ # - NODE_ENV=development # For development-specific behaviors (not recommended for production).++ restart: unless-stopped # Ensures the container restarts automatically unless manually stopped.++# Optional: Define the volume if you want Docker to manage it explicitly.+# This allows for easier management with `docker volume` commands.# volumes:# arcane-data:+# driver: local # Or your preferred volume driverdiff --git a/docs/docs/getting-started/configuration.md b/docs/docs/getting-started/configuration.mdindex 35e2a2020..c48247faa 100644--- a/docs/docs/getting-started/configuration.md+++ b/docs/docs/getting-started/configuration.md@@ -5,156 +5,146 @@ title: Configuration# Configuring Arcane-Arcane offers several ways to configure its behavior, with the recommended approach being through the web UI. Configuration is stored securely using encryption.+Arcane is pretty smart and usually, the best way to change its settings is right in its web pages. It keeps all your settings safe and sound by encrypting them.-## Configuration Storage+## Where Arcane Keeps Its Secrets (Settings)-Arcane stores its configuration in an encrypted format in `settings.dat` located in the application's data directory (typically `/app/data/settings` inside the container). Due to the encryption, **directly editing this file is not possible or recommended**.+Arcane saves its settings in a special locked box (an encrypted file called `settings.dat`). This box is usually found at `/app/data/settings` inside the Arcane container. Because it's locked up tight, you can't (and shouldn't try to) open or edit this file directly.-## Recommended Configuration Method: Web UI+## Best Way to Change Settings: Use the Web UI-The recommended way to configure Arcane is through the built-in web interface:+Seriously, the easiest and safest way is:-1. Access the Arcane web interface-2. Navigate to the Settings page-3. Update your configuration as needed-4. Save your changes+1. Open Arcane in your web browser.+2. Go to the "Settings" page.+3. Make your changes.+4. Hit "Save."-This approach ensures all settings are properly validated and securely stored.+Done! Arcane makes sure everything is correct and keeps it secure.-## Configuration Options+## What You Can Configure (The Nitty-Gritty)-- **`dockerHost`** (`string`)+Here are some of the things you can tell Arcane to do:- - Specifies the Docker daemon socket or TCP address Arcane should connect to.- - **Default:** `"unix:///var/run/docker.sock"` (Connects via the standard Unix socket)- - **Examples:**- - Unix Socket: `"unix:///var/run/docker.sock"`- - Windows: `"npipe:////./pipe/docker_engine"`- - TCP Host: `"tcp://192.168.1.100:2375"` (Ensure your Docker daemon is configured to listen on TCP)+- **`dockerHost`**: Where your Docker "engine" lives.+ - Usually: `"unix:///var/run/docker.sock"` (like a special phone line to Docker on the same computer)+ - If Docker is on another computer: `"tcp://192.168.1.100:2375"` (but be careful with this!)+- **`autoUpdate`**: Should Arcane automatically update your running apps when a new version comes out?+ - Default: `false` (No)+- **`autoUpdateInterval`**: If auto-update is on, how often should it check (in minutes)?+ - Default: `60` (once an hour)+- **`pollingEnabled`**: Should Arcane keep asking Docker "Hey, what's up with the apps?"+ - Default: `true` (Yes)+- **`pollingInterval`**: How often to ask (in minutes)?+ - Default: `10`+- **`pruneMode`**: When cleaning up old Docker images, how much should it throw away?+ - `"all"`: Get rid of all unused images.+ - `"dangling"`: Only get rid of images that aren't tagged (like lost socks).+ - Default: `"all"`+- **`stacksDirectory`**: Where Arcane keeps the instruction manuals (Docker Compose files) for your app collections.+ - Default: `"/app/data/stacks"`+- **`auth`**: Settings for logging into Arcane.+ - `localAuthEnabled`: Can you log in with a username/password created in Arcane? Default: `true` (Yes)+ - `sessionTimeout`: How long before Arcane logs you out if you're not doing anything? Default: `60` minutes.+ - `passwordPolicy`: How strong do passwords need to be? Default: `"medium"`+- **`registryCredentials`**: (Heads up: This bit isn't fully working in version 0.4.0) For telling Arcane how to log into private places to get app images.-- **`autoUpdate`** (`boolean`)+## Setting Up Arcane with Docker (The Easy Way)- - Enables automatic updating of containers when new images are available.- - **Default:** `false`+If you're running Arcane in a Docker container (which is super common), here's how you tell it what to do:-- **`autoUpdateInterval`** (`number`)+### 1. Give Arcane a Place to Store Its Stuff (Mounting a Volume)- - Interval in minutes between checks for container updates when `autoUpdate` is enabled.- - **Default:** `60` (1 hour)- - **Range:** 5-1440 minutes (1 day)--- **`pollingEnabled`** (`boolean`)-- - Enables periodic polling of the Docker daemon for container status updates.- - **Default:** `true`--- **`pollingInterval`** (`number`)-- - Interval in minutes between Docker status polls.- - **Default:** `10`- - **Range:** 5-60 minutes--- **`pruneMode`** (`string`)-- - Controls how image pruning operates.- - **Values:** `"all"` (removes all unused images) or `"dangling"` (removes only untagged images)- - **Default:** `"all"`--- **`stacksDirectory`** (`string`)-- - Defines the directory where Arcane stores and manages Docker Compose stack files.- - **Default:** `"/app/data/stacks"`--- **`auth`** (object)-- - **`localAuthEnabled`** (`boolean`): Enables/disables local authentication.- - **Default:** `true`- - **`sessionTimeout`** (`number`): Session timeout in minutes.- - **Default:** `60`- - **`passwordPolicy`** (`string`): Password complexity requirements.- - **Default:** `"medium"`--- **`registryCredentials`** (array) (This is currently not actually working in 0.4.0)- - List of registry credentials for pulling private images.--## Configuration with Docker--When running Arcane using Docker or Docker Compose, you configure the application by:--### 1. Mounting the Data Directory--This is the recommended approach as it persists all application data, including the encrypted configuration.+This is the **most important part** for keeping your Arcane settings and app data safe. You tell Docker to give Arcane a folder on your computer to use.```yaml-# docker-compose.yml excerpt+# In your docker-compose.yml fileservices:arcane:- # ... other settings+ # ... other settings like image name ...volumes:- - /var/run/docker.sock:/var/run/docker.sock # Mount Docker socket- - arcane-data:/app/data # Mount data directory- # ... other settings+ - /var/run/docker.sock:/var/run/docker.sock # Lets Arcane talk to Docker+ - ./arcane-data:/app/data # IMPORTANT: Arcane stores everything here!+ # './arcane-data' on your computer becomes '/app/data' inside Arcane.+ # ... other settings ...```-With this setup, configuration changes made through the UI are persisted across container restarts.+When you do this, any settings you change in the Arcane web UI will be saved in that `arcane-data` folder and will still be there even if you restart Arcane.++### 2. Special Instructions for Arcane (Environment Variables)-### 2. Environment Variables+Think of these like sticky notes you give to Arcane when it starts up. Some are really important for it to work correctly in Docker.-While most application settings are configured via the UI, certain environment variables are crucial for initial setup, permissions, and security, especially when running via Docker.+#### Who Owns the Files? (`PUID` and `PGID`)-#### Permissions & Docker Socket Access+- **`PUID`**: This is like telling Arcane, "The person who owns the files inside your container should have User ID number X."+- **`PGID`**: And "Their group ID number should be Y."-- **`DOCKER_GID`**: **Required.** Set this to the group ID of the `docker` group on your host machine (or the group that owns `/var/run/docker.sock`). This grants Arcane permission to interact with the Docker daemon. Find the ID using `getent group docker | cut -d: -f3` or `stat -c '%g' /var/run/docker.sock` on Linux.+Why care? If Arcane saves files in that `arcane-data` folder (from the `volumes` part above), you want to make sure _you_ can still access those files on your computer. Setting `PUID` and `PGID` to _your_ user's ID numbers on your computer helps avoid "permission denied" headaches.-#### Application Environment+- **How to find your IDs (on Linux/Mac):**+ - Your User ID (PUID): Open a terminal and type `id -u`+ - Your Group ID (PGID): Open a terminal and type `id -g`+- **Defaults if you don't set them:** `PUID=1000`, `PGID=1000` (common for the first user on many Linux systems).-- **`APP_ENV`**: **Required for Docker.** Controls which file system paths Arcane uses for data storage. When running in Docker, this must be set to `production` to ensure all data is stored in `/app/data` where the volume is mounted. Without this setting, the application may incorrectly use development paths (`.dev-data`) resulting in data not being persisted across container restarts.- ```yaml- environment:- - APP_ENV=production # Ensures proper data paths in Docker- ```+#### Letting Arcane Talk to Docker (`DOCKER_GID`)-#### Session Security+- **`DOCKER_GID`**: Arcane needs permission to chat with your main Docker engine. This is usually handled by making sure Arcane is part of a special "docker" group.+- **Good news!** Arcane is pretty smart. When you connect it to `/var/run/docker.sock` (like in the `volumes` example), Arcane's entrypoint script usually figures out the right Group ID for this "docker" group automatically.+- **So, you often don't need to set `DOCKER_GID` yourself.**+- If, for some strange reason, it doesn't work, you _can_ set it. Find the ID by typing `getent group docker | cut -d: -f3` or `stat -c '%g' /var/run/docker.sock` in your terminal.-- **`PUBLIC_SESSION_SECRET`**: **Required.** This secret is used to sign and encrypt user session cookies, ensuring their integrity and confidentiality. You **must** provide a strong, unique, random string of at least 32 characters. Generate a suitable secret using:+#### Telling Arcane It's in "Production Mode" (`APP_ENV`)- ```bash- openssl rand -base64 32- ```+- **`APP_ENV=production`**: **Super important for Docker!** This tells Arcane, "You're running for real now, save all your important stuff in the `/app/data` folder." If you forget this, Arcane might try to save things in temporary spots, and you'll lose your settings when it restarts.- Replace the placeholder in your `docker-compose.yml` or environment setup with the generated secret. **Keep this secret confidential.**+#### Keeping Your Login Safe (`PUBLIC_SESSION_SECRET`)-- **`PUBLIC_ALLOW_INSECURE_COOKIES`**: **Optional (Use with Caution).** By default (`false` or not set), session cookies are marked `Secure`, requiring an HTTPS connection. For **local development or testing only** where you are accessing Arcane over HTTP (e.g., `http://localhost:3000`) and cannot use HTTPS, you can set this variable to `true`. This allows the session cookie to be sent over insecure HTTP connections.- **Warning:** Setting this to `true` in a production environment or any environment exposed to untrusted networks is **highly insecure** and strongly discouraged. Always use HTTPS in production.+- **`PUBLIC_SESSION_SECRET`**: **You MUST set this!** This is like a secret password Arcane uses to make sure nobody messes with your login session.+- **Make it strong and random!** Don't just type "password".+- **How to make one:** Open a terminal and run `openssl rand -base64 32`. Copy the crazy string it gives you.+- **Keep this secret safe!**-#### Example `docker-compose.yml` Environment Section+#### For Local Testing Only (`PUBLIC_ALLOW_INSECURE_COOKIES`)++- **`PUBLIC_ALLOW_INSECURE_COOKIES=true`**: **Warning! Only use this if you're testing Arcane on your own computer and can't use HTTPS (the secure web lock icon).**+- Normally, Arcane insists on using secure cookies. If you're just running `http://localhost:3000`, you might need to set this to `true` to log in.+- **Never use `true` if other people can access your Arcane.** It's like leaving your front door unlocked.++#### Example Sticky Notes for Arcane (`docker-compose.yml`):```yaml-# docker-compose.yml excerpt+# In your docker-compose.yml fileservices:arcane:- # ... other settings+ # ... image, ports, volumes ...environment:- # Application Environment- - APP_ENV=production # Required for Docker deployment+ # Tell Arcane it's running for real+ - APP_ENV=production # Required for Docker!++ # Who owns the files? (Change these to your computer's user/group IDs)+ - PUID=1000+ - PGID=1000++ # Letting Arcane talk to Docker (Usually figured out automatically)+ # - DOCKER_GID=998 # Only set if auto-detection fails. Replace 998 with your Docker group's GID.++ # Your secret login handshake+ - PUBLIC_SESSION_SECRET=put_your_super_long_random_secret_here # Replace this!- # Permissions- - DOCKER_GID=998 # Example GID, replace with yours- # Session Security- - PUBLIC_SESSION_SECRET=your-secure-random-32-character-string-here # Replace with generated secret- # - PUBLIC_ALLOW_INSECURE_COOKIES=true # Uncomment only for local HTTP testing- # ... other settings+ # For local HTTP testing ONLY (dangerous otherwise!)+ # - PUBLIC_ALLOW_INSECURE_COOKIES=true+ # ... other settings ...```-## Important Notes+## Quick Reminders-- **Direct file editing not supported:** Due to encryption, you cannot manually edit the `settings.dat` file.-- **First-run setup:** On first run, Arcane will create default settings and generate encryption keys.-- **Backup considerations:** When backing up your Arcane installation, ensure you include the entire data directory (e.g., `/app/data` inside the container) to preserve settings, stacks, users, sessions, and encryption keys.-- **HTTPS Recommended:** For security, especially if exposing Arcane beyond your local machine, running it behind a reverse proxy with HTTPS enabled is strongly recommended. This protects login credentials and session cookies.+- **Don't touch `settings.dat`!** Use the web UI.+- **First time you run Arcane?** It'll set itself up with some defaults.+- **Backups are your friend!** If you back up Arcane, make sure you grab that whole `arcane-data` folder.+- **HTTPS is good!** If Arcane is on a network, put it behind a web server that does HTTPS to keep things extra safe.-## Initial Setup+## Getting Started-When you first access Arcane, you'll be guided through a setup process where you can configure the essential settings. You can modify them later at any time through the Settings page in the web UI.+When you first open Arcane, it will walk you through setting up the main things. You can always change them later on the Settings page.diff --git a/scripts/docker/entrypoint.sh b/scripts/docker/entrypoint.shindex ead00ff74..fe3508dab 100644--- a/scripts/docker/entrypoint.sh+++ b/scripts/docker/entrypoint.sh@@ -8,26 +8,27 @@ if [ "$(id -u)" -ne 0 ]; thenexec "$@"fi-echo "Entrypoint: Running as root. Setting up user and permissions..."+echo "Entrypoint: Setting up user and permissions..."# Default PUID/PGID if not providedPUID=${PUID:-1000}PGID=${PGID:-1000}DOCKER_GID=${DOCKER_GID:-998}APP_USER="arcane"-APP_GROUP="arcane"+APP_GROUP_FALLBACK="arcane" # Fallback group name if PGID group exists with different nameAPP_DIR="/app"+DATA_DIR="${APP_DIR}/data"echo "Entrypoint: Using PUID=${PUID}, PGID=${PGID}, DOCKER_GID=${DOCKER_GID}"-# Create the arcane group if it doesn't exist-if ! getent group "$PGID" > /dev/null 2>&1; then+# Determine the group name for PGID+if getent group "$PGID" > /dev/null 2>&1; then+ APP_GROUP=$(getent group "$PGID" | cut -d: -f1)+ echo "Entrypoint: Group with GID ${PGID} already exists: ${APP_GROUP}"+else+ APP_GROUP="$APP_GROUP_FALLBACK"echo "Entrypoint: Creating group ${APP_GROUP} with GID ${PGID}..."addgroup -g "$PGID" "$APP_GROUP"-else- # If group with PGID exists, find its name- GROUP_NAME=$(getent group "$PGID" | cut -d: -f1)- echo "Entrypoint: Group with GID ${PGID} already exists: ${GROUP_NAME}"fi# Ensure the docker group exists with correct GID@@ -42,20 +43,30 @@ elsefifi-# Create the arcane user if it doesn't exist-if ! getent passwd "$PUID" > /dev/null 2>&1; then- echo "Entrypoint: Creating user ${APP_USER} with UID ${PUID}..."- adduser -D -u "$PUID" -G "$APP_GROUP" "$APP_USER"-else- # If user with PUID exists, find their name+# Create the arcane user if it doesn't exist or ensure it uses the correct PUID/PGID+if getent passwd "$PUID" > /dev/null 2>&1; thenUSERNAME=$(getent passwd "$PUID" | cut -d: -f1)echo "Entrypoint: User with UID ${PUID} already exists: ${USERNAME}"- # Don't try to rename the root user or if username already matches+ # Ensure existing user is part of the target APP_GROUP+ if ! id -nG "$USERNAME" | grep -qw "$APP_GROUP"; then+ echo "Entrypoint: Adding user ${USERNAME} (UID ${PUID}) to group ${APP_GROUP} (GID ${PGID})..."+ usermod -a -G "$APP_GROUP" "$USERNAME"+ fi+ # Ensure primary group is correct+ if [ "$(id -g "$USERNAME")" != "$PGID" ]; then+ echo "Entrypoint: Setting primary group for ${USERNAME} (UID ${PUID}) to ${APP_GROUP} (GID ${PGID})..."+ usermod -g "$PGID" "$USERNAME"+ fi++ # If username is not 'arcane', and not 'root', consider renamingif [ "$USERNAME" != "$APP_USER" ] && [ "$USERNAME" != "root" ]; then- echo "Entrypoint: Renaming user from ${USERNAME} to ${APP_USER}..."+ echo "Entrypoint: Renaming user from ${USERNAME} to ${APP_USER} (UID ${PUID})..."usermod -l "$APP_USER" "$USERNAME"fi+else+ echo "Entrypoint: Creating user ${APP_USER} with UID ${PUID} and GID ${PGID}..."+ adduser -D -u "$PUID" -G "$APP_GROUP" "$APP_USER"fi# Ensure arcane user is in the docker group@@ -66,53 +77,37 @@ fi# Fix permissions for the Docker socket if it existsif [ -S /var/run/docker.sock ]; then- # Get the GID of the docker socketSOCKET_GID=$(stat -c '%g' /var/run/docker.sock)-- # If we have a different GID than expected, recreate the docker group- if [ "${SOCKET_GID}" != "${DOCKER_GID}" ]; then- echo "Docker socket GID (${SOCKET_GID}) doesn't match configured DOCKER_GID (${DOCKER_GID})"- echo "Updating docker group to match socket GID"-- # Delete existing docker group+ if [ "${SOCKET_GID}" != "$(getent group docker | cut -d: -f3)" ]; then+ echo "Docker socket GID (${SOCKET_GID}) doesn't match configured docker group GID."+ echo "Updating docker group to match socket GID: ${SOCKET_GID}"delgroup docker >/dev/null 2>&1 || true-- # Create new docker group with socket GIDaddgroup -g "${SOCKET_GID}" docker-- # Add arcane user to the new docker group- adduser arcane docker+ adduser "$APP_USER" dockerfi-- echo "Docker socket accessible at /var/run/docker.sock (GID: ${SOCKET_GID})"+ echo "Docker socket accessible at /var/run/docker.sock (GID: $(getent group docker | cut -d: -f3))"elseecho "WARNING: Docker socket not found at /var/run/docker.sock"echo "Make sure to mount the Docker socket when running this container"fi-# Ensure data directory exists-mkdir -p /app/data+# Ensure data directory exists and set ownership+echo "Entrypoint: Ensuring data directory exists and setting ownership..."+mkdir -p "$DATA_DIR"+chown -R "${PUID}:${PGID}" "$DATA_DIR"# If settings don't exist, copy the default-if [ ! -f /app/data/app-settings.json ]; then- if [ -f /app/data/app-settings.json.default ]; then- cp /app/data/app-settings.json.default /app/data/app-settings.json+if [ ! -f "${DATA_DIR}/app-settings.json" ]; then+ if [ -f "${DATA_DIR}/app-settings.json.default" ]; then # Check if default is in data dir+ echo "Entrypoint: Copying default settings to ${DATA_DIR}/app-settings.json"+ cp "${DATA_DIR}/app-settings.json.default" "${DATA_DIR}/app-settings.json"+ chown "${PUID}:${PGID}" "${DATA_DIR}/app-settings.json"+ elif [ -f "${APP_DIR}/app-settings.json.default" ]; then # Check if default is in app dir (e.g. copied during build)+ echo "Entrypoint: Copying default settings from ${APP_DIR}/app-settings.json.default to ${DATA_DIR}/app-settings.json"+ cp "${APP_DIR}/app-settings.json.default" "${DATA_DIR}/app-settings.json"+ chown "${PUID}:${PGID}" "${DATA_DIR}/app-settings.json"fifi-# Ensure permissions-chmod 755 /app/data-chmod 644 /app/data/app-settings.json 2>/dev/null || true--# Change ownership of application directories-echo "Entrypoint: Setting permissions on critical directories..."-chown "$PUID":"$PGID" "$APP_DIR"-chown -R "$PUID":"$PGID" "$APP_DIR/data"--if [ "$PUID" = "0" ]; then- echo "Starting Arcane as root user (PUID=0 was specified)..."- exec "$@"-else- echo "Starting Arcane as user arcane ($(id -u arcane):$(id -g arcane))..."- exec su-exec arcane "$@"-fi+echo "Entrypoint: Setup complete. Executing command as user ${APP_USER} (UID: ${PUID}, GID: ${PGID})..."+exec su-exec "$APP_USER" "$@"