Merge pull request #368 from mkulina/fix/arm-mariadb-volume-detection

fix: auto-detect ARM architecture for MariaDB volume configuration

Author: dialmaster

docker-compose.arm.yml

@@ -0,0 +1,11 @@
+# Override file for ARM-based systems (Apple Silicon, Raspberry Pi, etc.)
+# This uses a named volume for MariaDB to work around virtiofs bugs on ARM
+
+services:
+  youtarr-db:
+    volumes:
+      - youtarr-db-data:/var/lib/mysql
+
+volumes:
+  youtarr-db-data:
+

docker-compose.yml

@@ -15,9 +15,10 @@
 # mkdir -p config jobs server/images /path/to/youtube_videos
 # sudo chown -R 1000:1000 config jobs server/images /path/to/youtube_videos
 #
-# 2) Database setup notes for Synology and Apple Silicon macOS users:
-# There are known issues with using bind mounts for MariaDB data directories due to permission and virtiofs bugs respectively.
-# It is highly recommended to use a named volume for the youtarr-db service instead of the bind mount.
+# 2) Database setup notes for Synology and ARM-based systems (Apple Silicon, Raspberry Pi):
+# There are known issues with using bind mounts for MariaDB data directories due to permission and virtiofs bugs.
+# The start scripts automatically detect ARM architecture and use docker-compose.arm.yml override to switch to named volumes.
+# For Synology or manual override, run: docker compose -f docker-compose.yml -f docker-compose.arm.yml up -d
 
 services:
   youtarr-db:
@@ -38,9 +39,6 @@ services:
       - "${DB_PORT:-3321}:${DB_PORT:-3321}"
     volumes:
       - ./database:/var/lib/mysql
-      # Synology and Apple Silicon macOS users:
-      # Uncomment the line below and comment out the line above to use named volume:
-      # - youtarr-db-data:/var/lib/mysql
     command: --port=${DB_PORT:-3321} --character-set-server=utf8mb4 --collation-server=utf8mb4_unicode_ci --innodb-file-per-table=1 --innodb-large-prefix=ON
     healthcheck:
       test: ["CMD", "mysqladmin", "ping", "-h", "localhost", "-P", "${DB_PORT:-3321}", "-u", "${DB_USER:-root}", "-p${DB_PASSWORD:-123qweasd}"]
@@ -98,7 +96,6 @@ networks:
   default:
     name: youtarr-network
 
-# Synology and Apple Silicon macOS users:
-# Uncomment the line below and comment out the line above to use named volume:
-# volumes:
-#   youtarr-db-data:
+# Named volume definition (used by docker-compose.arm.yml override for ARM systems)
+volumes:
+  youtarr-db-data:

docs/DOCKER.md

@@ -22,9 +22,12 @@ Youtarr uses Docker Compose with two containers:
 - **Image**: `mariadb:10.3`
 - **Port**: 3321 (both host and container)
 - **Volumes**:
-  - `./database:/var/lib/mysql` - Database persistence
+  - `./database:/var/lib/mysql` - Database persistence (default)
+  - `youtarr-db-data:/var/lib/mysql` - Named volume (required for ARM/Synology)
 - **Character Set**: utf8mb4 (full Unicode support)
 
+> **ARM Users**: See [ARM Architecture Notes](#arm-architecture-apple-silicon-raspberry-pi) below.
+
 ## ⚠️ Important: Do Not Mount the Migrations Directory
 
 Avoid adding a `./migrations:/app/migrations` volume. The production image already includes the migration files it needs.
@@ -48,6 +51,45 @@ volumes:
 
 If your automation creates a migrations directory, remove it from both directory creation and volume mounts.
 
+## ARM Architecture (Apple Silicon, Raspberry Pi)
+
+ARM-based systems (Apple Silicon Macs, Raspberry Pi, etc.) have known issues with MariaDB bind mounts due to virtiofs bugs. The start scripts automatically detect ARM and apply the fix.
+
+### Using Start Scripts (Recommended)
+
+The `./start.sh` script automatically detects ARM architecture and applies the correct configuration:
+```bash
+./start.sh
+```
+
+### Using Docker Compose Directly
+
+If you prefer running `docker compose` commands directly on ARM systems, use the override file:
+```bash
+docker compose -f docker-compose.yml -f docker-compose.arm.yml up -d
+```
+
+This uses a named Docker volume instead of a bind mount for MariaDB data, avoiding the virtiofs issues.
+
+### Manual Configuration
+
+Alternatively, edit `docker-compose.yml` directly:
+```yaml
+services:
+  youtarr-db:
+    volumes:
+      # Comment out bind mount:
+      # - ./database:/var/lib/mysql
+      # Use named volume:
+      - youtarr-db-data:/var/lib/mysql
+
+# Add at the bottom:
+volumes:
+  youtarr-db-data:
+```
+
+See [Troubleshooting](TROUBLESHOOTING.md#apple-silicon--arm-incorrect-information-in-file-errors) for more details on the underlying issue.
+
 ## Configuration Setup
 - **Create a .env file** to configure environment variables:
     ```bash

docs/INSTALLATION.md

@@ -81,6 +81,12 @@ If you prefer to use standard `docker compose up` commands:
    docker compose up -d
    ```
 
+   > **ARM Users (Apple Silicon, Raspberry Pi)**: Use the ARM override to avoid MariaDB volume issues:
+   > ```bash
+   > docker compose -f docker-compose.yml -f docker-compose.arm.yml up -d
+   > ```
+   > See [Troubleshooting](TROUBLESHOOTING.md#apple-silicon--arm-incorrect-information-in-file-errors) for details.
+
 5. **Access the web interface**:
    - Navigate to `http://localhost:3087`
    - If you set preset credentials in .env, use those to log in

docs/TROUBLESHOOTING.md

@@ -347,31 +347,48 @@ ERROR 1396 (HY000) at line 21: Operation CREATE USER failed for 'root'@'%'
 
 Tip: run with a named volume (see Apple Silicon/Synology sections) so filesystem corruption is less likely to recur.
 
-### Apple Silicon: `Incorrect information in file` errors
+### Apple Silicon / ARM: `Incorrect information in file` errors
 
-**Problem**: On Apple Silicon (M1/M2/M3/M4) running Docker Desktop, MariaDB logs errors like:
+**Problem**: On Apple Silicon (M1/M2/M3/M4) or other ARM systems running Docker Desktop, MariaDB logs errors like:
 ```
 ERROR 1033 (HY000): Incorrect information in file: './youtarr/videos.frm'
 ```
 This happens whenever MariaDB touches tables stored on a bind-mounted host directory (our default `./database:/var/lib/mysql`). Docker Desktop shares bind mounts over `virtiofs`, and MariaDB 10.3 cannot reliably reopen InnoDB tables on that filesystem ([MariaDB issue #447](https://github.com/MariaDB/mariadb-docker/issues/447), [#481](https://github.com/MariaDB/mariadb-docker/issues/481)). Linux and WSL users are unaffected.
 
-**Solution** (switch to a named Docker volume):
+**Solution A: Use the start scripts (Recommended)**
+
+The `./start.sh` and `./start-dev.sh` scripts automatically detect ARM architecture and apply the fix:
+```bash
+./start.sh
+```
+No manual configuration needed—the scripts use `docker-compose.arm.yml` as an override on ARM systems.
+
+**Solution B: Manual docker compose (if not using start scripts)**
+
+If you run `docker compose up` directly, use the ARM override file:
+```bash
+docker compose -f docker-compose.yml -f docker-compose.arm.yml up -d
+```
+
+Or manually edit `docker-compose.yml` to use a named volume:
+
 **NOTE:** Existing data will *not* be migrated!
-1. Stop the stack and remove the old volume `docker compose down -v`.
+1. Stop the stack: `docker compose down`
 2. Edit `docker-compose.yml`:
    ```yaml
    services:
      youtarr-db:
-       # Comment out the default bind mount line:
-       # - ./database:/var/lib/mysql
-       # And enable the named volume instead (charset tuning is built into the container command):
-       - youtarr-db-data:/var/lib/mysql
+       volumes:
+         # Comment out the bind mount:
+         # - ./database:/var/lib/mysql
+         # Use named volume instead:
+         - youtarr-db-data:/var/lib/mysql
 
-   # Ensure that the volume is defined
+   # Add at the bottom of the file:
    volumes:
      youtarr-db-data:
    ```
-4. Start Youtarr again (`./start.sh` or `docker compose up -d`). MariaDB will initialize inside `youtarr-db-data`, avoiding virtiofs entirely.
+3. Start Youtarr: `docker compose up -d`
 
 **Alternatives**:
 - Point Youtarr at an external MariaDB/MySQL instance via `./start-with-external-db.sh`.

scripts/_start_template.sh

@@ -30,11 +30,24 @@ fi
 # shellcheck source=scripts/_shared_start_tasks.sh
 source "$SCRIPT_DIR/_shared_start_tasks.sh" "$@"
 
+# Detect ARM architecture (Apple Silicon, Raspberry Pi, etc.)
+ARCH=$(uname -m)
+IS_ARM=false
+if [[ "$ARCH" == "arm64" || "$ARCH" == "aarch64" ]]; then
+  IS_ARM=true
+  yt_info "Detected ARM architecture ($ARCH) - using named volume for MariaDB"
+fi
+
 if [ "$USE_EXTERNAL_DB" == "true" ]; then
   # Only start the youtarr service.
   COMPOSE_ARGS="-f docker-compose.external-db.yml up -d"
 else
-  COMPOSE_ARGS="-f docker-compose.yml up -d"
+  if [ "$IS_ARM" == "true" ]; then
+    # Use ARM override to switch to named volume (works around virtiofs bugs)
+    COMPOSE_ARGS="-f docker-compose.yml -f docker-compose.arm.yml up -d"
+  else
+    COMPOSE_ARGS="-f docker-compose.yml up -d"
+  fi
 fi
 
 $COMPOSE_CMD $COMPOSE_ARGS