v1.0.1

Author: CoderLuii

README.md

@@ -102,6 +102,7 @@ services:
       - "4096:4096"
     volumes:
       - ./data/opencode:/home/opencode
+      - ./local-cache/opencode:/home/opencode/.cache/opencode
       - ./workspace:/workspace
     environment:
       - PUID=1000
@@ -119,6 +120,8 @@ Open http://localhost:4096. You're in.
 
 > The shipped `docker-compose.yaml` uses `${ANTHROPIC_API_KEY}` syntax which reads from your shell environment or a `.env` file. Copy `.env.example` to `.env` and fill in your API key.
 
+> Keep `./local-cache/opencode` on local disk. If this project folder lives on NAS/CIFS/SMB storage, change that cache mount to an absolute local host path instead.
+
 <p align="right">
   <a href="#top">back to top</a>
 </p>
@@ -226,6 +229,7 @@ services:
       - "4096:4096"           # OpenCode web UI
     volumes:
       - ./data/opencode:/home/opencode
+      - ./local-cache/opencode:/home/opencode/.cache/opencode
       - ./workspace:/workspace  # Your project files
     environment:
       - PUID=1000
@@ -260,7 +264,10 @@ services:
 
     volumes:
       # --- Persistent state (all OpenCode data under home dir) ---
-      - ./data/opencode:/home/opencode   # Config, sessions, plugins, cache, all XDG paths
+      - ./data/opencode:/home/opencode   # Config, sessions, plugins, all XDG paths
+
+      # --- Cache path (keep this on local disk; if this folder lives on NAS/CIFS, replace with an absolute local path) ---
+      - ./local-cache/opencode:/home/opencode/.cache/opencode
 
       # --- Workspace ---
       - ./workspace:/workspace   # Your project files
@@ -549,19 +556,27 @@ docker exec -it holycode bash -c "opencode providers login"
 
 ## 💾 Data and Persistence
 
-All OpenCode state lives in a single bind mount at `./data/opencode`. The container is stateless. The bind mount holds everything that matters.
+Most OpenCode state lives in `./data/opencode`. Plugin cache is mounted separately at `./local-cache/opencode` by default so you can keep that path on local disk.
 
 | Host Path | Container Path | What's in it |
 |-----------|---------------|-------------|
 | `./data/opencode/.config/opencode` | `/home/opencode/.config/opencode` | Settings, agents, MCP configs, themes, plugins |
 | `./data/opencode/.local/share/opencode` | `/home/opencode/.local/share/opencode` | SQLite sessions database, MCP OAuth tokens |
 | `./data/opencode/.local/state/opencode` | `/home/opencode/.local/state/opencode` | Frecency data, model cache, key-value store |
-| `./data/opencode/.cache/opencode` | `/home/opencode/.cache/opencode` | Plugin node_modules, auto-installed dependencies |
+| `./local-cache/opencode` | `/home/opencode/.cache/opencode` | Plugin node_modules, auto-installed dependencies |
 
 Rebuild the container anytime. Run `docker compose pull && docker compose up -d` and your sessions, settings, and configs come back automatically.
 
 **SQLite WAL note.** The sessions database uses Write-Ahead Logging. Don't copy the `.db` file while the container is running. Stop the container first if you need to back up or migrate the database file.
 
+**Network storage note.** If `./data/opencode` is on a CIFS/SMB network mount (NAS, Synology, TrueNAS), you need two mount options:
+- `nobrl` — SQLite WAL mode requires this (byte-range locking workaround)
+- `mfsymlinks` — plugin installation requires this (symlink support for node_modules)
+
+Keep `./local-cache/opencode` on local disk. If your whole HolyCode folder lives on network storage, change that cache mount to an absolute local host path such as `/var/lib/holycode-cache/opencode:/home/opencode/.cache/opencode`.
+
+See the Troubleshooting section below.
+
 <p align="right">
   <a href="#top">back to top</a>
 </p>
@@ -703,6 +718,42 @@ security_opt:
 
 </details>
 
+<details>
+<summary><strong>SQLite WAL or plugins fail on CIFS/SMB network mounts (NAS)</strong></summary>
+
+If your `./data/opencode` directory lives on a CIFS/SMB network share (e.g. NAS, Synology, TrueNAS), OpenCode may fail with:
+
+```
+Failed to run the query 'PRAGMA journal_mode = WAL'
+```
+
+OpenCode uses SQLite with Write-Ahead Logging (WAL) for its sessions database. WAL requires byte-range locking, which CIFS/SMB doesn't support by default.
+
+HolyCode detects this at startup and prints a warning with the fix instructions.
+
+**Fix:** Add `nobrl,mfsymlinks` to your CIFS mount options in `/etc/fstab`:
+
+```
+# Before
+//192.168.1.100/share /mnt/share cifs credentials=/etc/smbcreds,uid=1000,gid=1000 0 0
+
+# After — add nobrl and mfsymlinks
+//192.168.1.100/share /mnt/share cifs credentials=/etc/smbcreds,uid=1000,gid=1000,nobrl,mfsymlinks 0 0
+```
+
+Then remount:
+
+```bash
+sudo umount /mnt/share
+sudo mount /mnt/share
+```
+
+Restart HolyCode: `docker compose up -d --force-recreate`
+
+If you are using the default HolyCode Compose files, the cache mount is `./local-cache/opencode:/home/opencode/.cache/opencode`. Keep that path on local disk. If your entire HolyCode folder lives on network storage, replace it with an absolute local host path.
+
+</details>
+
 <p align="right">
   <a href="#top">back to top</a>
 </p>

docker-compose.full.yaml

@@ -14,7 +14,10 @@ services:
 
     volumes:
       # --- Persistent state (all OpenCode data under home dir) ---
-      - ./data/opencode:/home/opencode   # Config, sessions, plugins, cache, all XDG paths
+      - ./data/opencode:/home/opencode   # Config, sessions, plugins, all XDG paths
+
+      # --- Cache path (keep this on local disk; if this folder lives on NAS/CIFS, replace with an absolute local path) ---
+      - ./local-cache/opencode:/home/opencode/.cache/opencode
 
       # --- Workspace ---
       - ./workspace:/workspace   # Your project files

docker-compose.yaml

@@ -12,6 +12,7 @@ services:
       - "4096:4096"
     volumes:
       - ./data/opencode:/home/opencode
+      - ./local-cache/opencode:/home/opencode/.cache/opencode
       - ./workspace:/workspace
     environment:
       - PUID=1000

docs/CHANGELOG.md

@@ -4,6 +4,19 @@ All notable changes to HolyCode will be documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/), and this project adheres to [Semantic Versioning](https://semver.org/).
 
+## [1.0.1] - 03/31/2026
+
+### Fixed
+
+- Detect CIFS/SMB network mounts and warn about SQLite WAL incompatibility
+- Add `nobrl,mfsymlinks` mount option documentation for README Troubleshooting section
+
+### Changed
+
+- Expand SQLite WAL note with network storage guidance
+- Add startup check in entrypoint.sh for CIFS/SMB detection
+- Replace the `holycode-cache` named volume guidance with an explicit local-path cache bind mount for CIFS/SMB setups
+
 ## [1.0.0] - 03/30/2026
 
 ### Added

docs/translations/README.de.md

@@ -97,11 +97,13 @@ services:
       - "4096:4096"
     volumes:
       - ./data/opencode:/home/opencode
+      - ./local-cache/opencode:/home/opencode/.cache/opencode
       - ./workspace:/workspace
     environment:
       - PUID=1000
       - PGID=1000
       - ANTHROPIC_API_KEY=your-key-here
+
 ```
 
 **Schritt 3.** Starte es.
@@ -221,11 +223,13 @@ services:
       - "4096:4096"           # OpenCode Web-UI
     volumes:
       - ./data/opencode:/home/opencode
+      - ./local-cache/opencode:/home/opencode/.cache/opencode
       - ./workspace:/workspace  # Deine Projektdateien
     environment:
       - PUID=1000
       - PGID=1000
       - ANTHROPIC_API_KEY=your-key-here  # Oder durch beliebigen Anbieterschlüssel ersetzen
+
 ```
 
 <p align="right">
@@ -255,7 +259,10 @@ services:
 
     volumes:
       # --- Persistent state (all OpenCode data under home dir) ---
-      - ./data/opencode:/home/opencode   # Config, sessions, plugins, cache, all XDG paths
+      - ./data/opencode:/home/opencode   # Config, sessions, plugins, all XDG paths
+
+      # --- Cache isolation (keeps plugin cache on local disk, avoids CIFS/SMB symlink issues) ---
+      - ./local-cache/opencode:/home/opencode/.cache/opencode
 
       # --- Workspace ---
       - ./workspace:/workspace   # Your project files
@@ -309,6 +316,7 @@ services:
       # Installs automatically on first boot when enabled
       # Toggle on/off with docker compose down && up -d
       # - ENABLE_OH_MY_OPENAGENT=true
+
 ```
 
 <p align="right">
@@ -551,12 +559,14 @@ Der gesamte OpenCode-Zustand lebt in einem einzigen Bind-Mount unter `./data/ope
 | `./data/opencode/.config/opencode` | `/home/opencode/.config/opencode` | Einstellungen, Agenten, MCP-Konfigurationen, Themes, Plugins |
 | `./data/opencode/.local/share/opencode` | `/home/opencode/.local/share/opencode` | SQLite-Sitzungsdatenbank, MCP-OAuth-Tokens |
 | `./data/opencode/.local/state/opencode` | `/home/opencode/.local/state/opencode` | Häufigkeitsdaten, Modell-Cache, Schlüssel-Wert-Speicher |
-| `./data/opencode/.cache/opencode` | `/home/opencode/.cache/opencode` | Plugin-node_modules, automatisch installierte Abhängigkeiten |
+| `./local-cache/opencode` | `/home/opencode/.cache/opencode` | Plugin-node_modules, automatisch installierte Abhängigkeiten |
 
 Den Container jederzeit neu erstellen. `docker compose pull && docker compose up -d` ausführen und Sitzungen, Einstellungen und Konfigurationen kommen automatisch zurück.
 
 **SQLite WAL-Hinweis.** Die Sitzungsdatenbank verwendet Write-Ahead Logging. Die `.db`-Datei nicht kopieren, während der Container läuft. Den Container zuerst stoppen, wenn die Datenbankdatei gesichert oder migriert werden muss.
 
+**Netzwerkspeicher-Hinweis.** Wenn sich `./data/opencode` auf einem CIFS/SMB-Netzwerk-Mount (NAS, Synology, TrueNAS) befindet, kann der SQLite WAL-Modus fehlschlagen, da SMB standardmäßig kein Byte-Range-Locking unterstützt. HolyCode erkennt dies beim Start und gibt eine Warnung mit dem Fix aus. Siehe den Abschnitt Fehlerbehebung unten.
+
 <p align="right">
   <a href="#top">nach oben</a>
 </p>
@@ -698,6 +708,40 @@ security_opt:
 
 </details>
 
+<details>
+<summary><strong>SQLite WAL schlägt auf CIFS/SMB-Netzwerk-Mounts fehl (NAS)</strong></summary>
+
+Wenn sich das Verzeichnis `./data/opencode` auf einer CIFS/SMB-Netzwerkfreigabe befindet, schlägt OpenCode
+möglicherweise mit folgendem Fehler fehl:
+
+```
+Failed to run the query 'PRAGMA journal_mode = WAL'
+```
+
+OpenCode verwendet SQLite mit Write-Ahead Logging (WAL) für die Sitzungsdatenbank.
+WAL erfordert Byte-Range-Locking, das CIFS/SMB standardmäßig nicht unterstützt. HolyCode erkennt dies beim Start.
+
+**Fix:** Fügen Sie `nobrl,mfsymlinks` zu den CIFS-Mount-Optionen in `/etc/fstab` hinzu:
+
+```
+# Vorher
+//192.168.1.100/share /mnt/share cifs credentials=/etc/smbcreds,uid=1000,gid=1000 0 0
+
+# Nachher (nobrl,mfsymlinks hinzufügen)
+//192.168.1.100/share /mnt/share cifs credentials=/etc/smbcreds,uid=1000,gid=1000,nobrl,mfsymlinks 0 0
+```
+
+Dann neu einhängen:
+
+```bash
+sudo umount /mnt/share
+sudo mount /mnt/share
+```
+
+HolyCode neu starten: `docker compose up -d --force-recreate`
+
+</details>
+
 <p align="right">
   <a href="#top">nach oben</a>
 </p>

docs/translations/README.es.md

@@ -97,11 +97,13 @@ services:
       - "4096:4096"
     volumes:
       - ./data/opencode:/home/opencode
+      - ./local-cache/opencode:/home/opencode/.cache/opencode
       - ./workspace:/workspace
     environment:
       - PUID=1000
       - PGID=1000
       - ANTHROPIC_API_KEY=your-key-here
+
 ```
 
 **Paso 3.** Inícialo.
@@ -221,11 +223,13 @@ services:
       - "4096:4096"           # Interfaz web de OpenCode
     volumes:
       - ./data/opencode:/home/opencode
+      - ./local-cache/opencode:/home/opencode/.cache/opencode
       - ./workspace:/workspace  # Los archivos de tu proyecto
     environment:
       - PUID=1000
       - PGID=1000
       - ANTHROPIC_API_KEY=your-key-here  # O cambia por cualquier clave de proveedor
+
 ```
 
 <p align="right">
@@ -255,7 +259,10 @@ services:
 
     volumes:
       # --- Persistent state (all OpenCode data under home dir) ---
-      - ./data/opencode:/home/opencode   # Config, sessions, plugins, cache, all XDG paths
+      - ./data/opencode:/home/opencode   # Config, sessions, plugins, all XDG paths
+
+      # --- Cache isolation (keeps plugin cache on local disk, avoids CIFS/SMB symlink issues) ---
+      - ./local-cache/opencode:/home/opencode/.cache/opencode
 
       # --- Workspace ---
       - ./workspace:/workspace   # Your project files
@@ -309,6 +316,7 @@ services:
       # Installs automatically on first boot when enabled
       # Toggle on/off with docker compose down && up -d
       # - ENABLE_OH_MY_OPENAGENT=true
+
 ```
 
 <p align="right">
@@ -551,12 +559,14 @@ Todo el estado de OpenCode vive en un único bind mount en `./data/opencode`. El
 | `./data/opencode/.config/opencode` | `/home/opencode/.config/opencode` | Ajustes, agentes, configuraciones MCP, temas, plugins |
 | `./data/opencode/.local/share/opencode` | `/home/opencode/.local/share/opencode` | Base de datos SQLite de sesiones, tokens OAuth de MCP |
 | `./data/opencode/.local/state/opencode` | `/home/opencode/.local/state/opencode` | Datos de frecuencia, caché de modelos, almacén clave-valor |
-| `./data/opencode/.cache/opencode` | `/home/opencode/.cache/opencode` | node_modules de plugins, dependencias instaladas automáticamente |
+| `./local-cache/opencode` | `/home/opencode/.cache/opencode` | node_modules de plugins, dependencias instaladas automáticamente |
 
 Reconstruye el contenedor cuando quieras. Ejecuta `docker compose pull && docker compose up -d` y tus sesiones, ajustes y configuraciones vuelven automáticamente.
 
 **Nota sobre SQLite WAL.** La base de datos de sesiones usa Write-Ahead Logging. No copies el archivo `.db` mientras el contenedor esté en ejecución. Detén el contenedor primero si necesitas hacer copia de seguridad o migrar el archivo de base de datos.
 
+**Nota sobre almacenamiento en red.** Si `./data/opencode` está en un montaje de red CIFS/SMB (NAS, Synology, TrueNAS), el modo WAL de SQLite puede fallar porque SMB no soporta bloqueo de rango de bytes por defecto. HolyCode detecta esto al inicio y muestra una advertencia con la solución. Consulta la sección de Solución de problemas a continuación.
+
 <p align="right">
   <a href="#top">volver arriba</a>
 </p>
@@ -698,6 +708,40 @@ security_opt:
 
 </details>
 
+<details>
+<summary><strong>El modo WAL de SQLite falla en montajes de red CIFS/SMB (NAS)</strong></summary>
+
+Si tu directorio `./data/opencode` está en un recurso compartido de red CIFS/SMB (p. ej. NAS, Synology, TrueNAS), OpenCode puede fallar con:
+
+```
+Failed to run the query 'PRAGMA journal_mode = WAL'
+```
+
+OpenCode usa SQLite con Write-Ahead Logging (WAL) para su base de datos de sesiones. WAL requiere bloqueo de rango de bytes, lo cual CIFS/SMB no soporta por defecto.
+
+HolyCode detecta esto al inicio y muestra una advertencia con las instrucciones de solución.
+
+**Solución:** Añade `nobrl,mfsymlinks` a las opciones de montaje CIFS en `/etc/fstab`:
+
+```
+# Antes
+//192.168.1.100/share /mnt/share cifs credentials=/etc/smbcreds,uid=1000,gid=1000 0 0
+
+# Después — añade nobrl,mfsymlinks
+//192.168.1.100/share /mnt/share cifs credentials=/etc/smbcreds,uid=1000,gid=1000,nobrl,mfsymlinks 0 0
+```
+
+Luego vuelve a montar:
+
+```bash
+sudo umount /mnt/share
+sudo mount /mnt/share
+```
+
+Reinicia HolyCode: `docker compose up -d --force-recreate`
+
+</details>
+
 <p align="right">
   <a href="#top">volver arriba</a>
 </p>