Merge pull request #313 from DialmasterOrg/docs/apple-mariadb

docs: add Apple Silicon troubleshooting for MariaDB virtiofs corruption

Author: dialmaster

README.md

@@ -154,6 +154,8 @@ Youtarr reads the `TZ` environment variable to determine when cron-based downloa
 - Already running MariaDB/MySQL elsewhere and do not want to use bundled internal DB?
 - See [docs/EXTERNAL_DB.md](docs/EXTERNAL_DB.md)
 
+> **Apple Silicon note:** Docker Desktop’s `virtiofs` bind mounts can corrupt MariaDB’s bundled database and cause `Incorrect information in file: './youtarr/videos.frm'` errors. See [Troubleshooting → Apple Silicon](docs/TROUBLESHOOTING.md#apple-silicon-incorrect-information-in-file-errors) for the named-volume workaround.
+
 ### Deploying on Unraid
 
 See [docs/UNRAID.md](docs/UNRAID.md) for instructions on Unraid setup.

docker-compose.yml

@@ -18,6 +18,8 @@ services:
       - "${DB_PORT:-3321}:${DB_PORT:-3321}"
     volumes:
       - ./database:/var/lib/mysql
+      # macOS (Apple Silicon): comment the line above and use the named volume example below to avoid the MariaDB+virtiofs bug (see README/Troubleshooting)
+      # - youtarr-db-data:/var/lib/mysql
       - ./config/mariadb.cnf:/etc/mysql/conf.d/charset.cnf:ro
     command: --port=${DB_PORT:-3321} --character-set-server=utf8mb4 --collation-server=utf8mb4_unicode_ci
     healthcheck:
@@ -75,3 +77,8 @@ services:
 networks:
   default:
     name: youtarr-network
+
+# When switching the DB service to a named volume (Apple Silicon workaround),
+# remember to define it here:
+# volumes:
+#   youtarr-db-data:

docs/TROUBLESHOOTING.md

@@ -285,6 +285,41 @@ or
 
 3. Verify database credentials in environment
 
+### Apple Silicon: `Incorrect information in file` errors
+
+**Problem**: On Apple Silicon (M1/M2/M3/M4) 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):
+1. Stop the stack: `./stop.sh` or `docker compose down`.
+2. Remove the old host directory (`./database`) so MariaDB can recreate a clean datadir inside the named volume:
+   ```bash
+   sudo rm -rf ./database
+   ```
+3. 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:
+       - youtarr-db-data:/var/lib/mysql
+       - ./config/mariadb.cnf:/etc/mysql/conf.d/charset.cnf:ro
+
+   volumes:
+     youtarr-db-data:
+   ```
+4. Start Youtarr again (`./start.sh`). MariaDB will initialize inside `youtarr-db-data`, avoiding virtiofs entirely.
+
+**Alternatives**:
+- Point Youtarr at an external MariaDB/MySQL instance via `./start-with-external-db.sh`.
+- Run the stack on Linux/WSL, which uses a native filesystem for bind mounts.
+
+Once migrated, back up the database using `mysqldump` or `docker cp` instead of copying files from `./database`, since the named volume lives inside Docker’s VM.
+
 ## Download Issues
 
 ### Videos Not Downloading