fix(database): use WAL mode to prevent readonly errors in restricted Docker

Enable SQLite WAL (Write-Ahead Logging) mode by default to reduce filesystem
operations and improve compatibility with Docker containers running with
restricted capabilities (cap_drop: [ALL]).

Changes:
- Add journal_mode=WAL, temp_store=MEMORY, synchronous=NORMAL PRAGMAs
- Add web.database.journal_mode config option for flexibility
- Improve error messages for readonly database errors with actionable guidance
- Document new configuration in example.scrutiny.yaml

Fixes #25
Upstream: AnalogJ#772

Author: Starosdev

example.scrutiny.yaml

@@ -30,6 +30,10 @@ web:
   database:
     # can also set absolute path here
     location: /opt/scrutiny/config/scrutiny.db
+    # SQLite journal mode: WAL (default), DELETE, TRUNCATE, PERSIST, MEMORY, OFF
+    # WAL mode is recommended for Docker containers with restricted capabilities (cap_drop: [ALL])
+    # If you experience database issues with WAL mode on network filesystems (NFS), try DELETE mode
+    # journal_mode: WAL
   src:
     # the location on the filesystem where scrutiny javascript + css is located
     frontend:

webapp/backend/pkg/config/config.go

@@ -36,6 +36,7 @@ func (c *configuration) Init() error {
 	c.SetDefault("web.listen.basepath", "")
 	c.SetDefault("web.src.frontend.path", "/opt/scrutiny/web")
 	c.SetDefault("web.database.location", "/opt/scrutiny/config/scrutiny.db")
+	c.SetDefault("web.database.journal_mode", "WAL")
 
 	c.SetDefault("log.level", "INFO")
 	c.SetDefault("log.file", "")

webapp/backend/pkg/database/scrutiny_repository.go

@@ -5,6 +5,12 @@ import (
 	"crypto/tls"
 	"encoding/json"
 	"fmt"
+	"io/ioutil"
+	"net/http"
+	"net/url"
+	"strings"
+	"time"
+
 	"github.com/analogj/scrutiny/webapp/backend/pkg/config"
 	"github.com/analogj/scrutiny/webapp/backend/pkg/models"
 	"github.com/glebarez/sqlite"
@@ -13,10 +19,6 @@ import (
 	"github.com/influxdata/influxdb-client-go/v2/domain"
 	"github.com/sirupsen/logrus"
 	"gorm.io/gorm"
-	"io/ioutil"
-	"net/http"
-	"net/url"
-	"time"
 )
 
 const (
@@ -74,15 +76,37 @@ func NewScrutinyRepository(appConfig config.Interface, globalLogger logrus.Field
 	// https://rsqlite.r-dbi.org/reference/sqlitesetbusyhandler
 	// retrying for 30000 milliseconds, 30seconds - this would be unreasonable for a distributed multi-tenant application,
 	// but should be fine for local usage.
+	//
+	// WAL (Write-Ahead Logging) mode is used by default to reduce filesystem operations and improve
+	// compatibility with Docker containers running with restricted capabilities (cap_drop: [ALL]).
+	// fixes #772 (upstream), #25
+	// https://www.sqlite.org/wal.html
+	journalMode := appConfig.GetString("web.database.journal_mode")
+	if journalMode == "" {
+		journalMode = "WAL"
+	}
+
 	pragmaStr := sqlitePragmaString(map[string]string{
 		"busy_timeout": "30000",
+		"journal_mode": journalMode,
+		"temp_store":   "MEMORY",
+		"synchronous":  "NORMAL",
 	})
 	database, err := gorm.Open(sqlite.Open(appConfig.GetString("web.database.location")+pragmaStr), &gorm.Config{
 		//TODO: figure out how to log database queries again.
 		//Logger: logger
 		DisableForeignKeyConstraintWhenMigrating: true,
 	})
 	if err != nil {
+		if strings.Contains(err.Error(), "readonly database") ||
+			strings.Contains(err.Error(), "attempt to write") {
+			return nil, fmt.Errorf("Database write error: %v\n\n"+
+				"This often occurs when running Docker with 'cap_drop: [ALL]'.\n"+
+				"Solutions:\n"+
+				"1. Ensure database directory has write permissions\n"+
+				"2. If using cap_drop, add: cap_add: [CHOWN, DAC_OVERRIDE, FOWNER]\n"+
+				"3. Set 'web.database.journal_mode: DELETE' in scrutiny.yaml if WAL causes issues", err)
+		}
 		return nil, fmt.Errorf("Failed to connect to database! - %v", err)
 	}
 	globalLogger.Infof("Successfully connected to scrutiny sqlite db: %s\n", appConfig.GetString("web.database.location"))

webapp/backend/pkg/database/scrutiny_repository_migrations.go

@@ -5,6 +5,7 @@ import (
 	"errors"
 	"fmt"
 	"strconv"
+	"strings"
 	"time"
 
 	"github.com/analogj/scrutiny/webapp/backend/pkg"
@@ -436,7 +437,18 @@ func (sr *scrutinyRepository) Migrate(ctx context.Context) error {
 	})
 
 	if err := m.Migrate(); err != nil {
-		sr.logger.Errorf("Database migration failed with error. \n Please open a github issue at https://github.com/AnalogJ/scrutiny and attach a copy of your scrutiny.db file. \n %v", err)
+		if strings.Contains(err.Error(), "readonly database") ||
+			strings.Contains(err.Error(), "attempt to write") {
+			sr.logger.Errorf("Database migration failed: unable to write to database.\n\n"+
+				"This error commonly occurs in Docker containers with restricted capabilities.\n"+
+				"Solutions:\n"+
+				"1. Check file permissions on the database directory\n"+
+				"2. If using 'cap_drop: [ALL]', add necessary capabilities back\n"+
+				"3. Verify the volume mount has correct ownership\n\n"+
+				"Original error: %v", err)
+		} else {
+			sr.logger.Errorf("Database migration failed with error.\nPlease open a github issue at https://github.com/Starosdev/scrutiny and attach a copy of your scrutiny.db file.\n%v", err)
+		}
 		return err
 	}
 	sr.logger.Infoln("Database migration completed successfully")
@@ -459,7 +471,18 @@ func (sr *scrutinyRepository) Migrate(ctx context.Context) error {
 	})
 
 	if err := gm.Migrate(); err != nil {
-		sr.logger.Errorf("SQLite global configuration migrations failed with error. \n Please open a github issue at https://github.com/AnalogJ/scrutiny and attach a copy of your scrutiny.db file. \n %v", err)
+		if strings.Contains(err.Error(), "readonly database") ||
+			strings.Contains(err.Error(), "attempt to write") {
+			sr.logger.Errorf("SQLite global configuration migrations failed: unable to write to database.\n\n"+
+				"This error commonly occurs in Docker containers with restricted capabilities.\n"+
+				"Solutions:\n"+
+				"1. Check file permissions on the database directory\n"+
+				"2. If using 'cap_drop: [ALL]', add necessary capabilities back\n"+
+				"3. Verify the volume mount has correct ownership\n\n"+
+				"Original error: %v", err)
+		} else {
+			sr.logger.Errorf("SQLite global configuration migrations failed with error.\nPlease open a github issue at https://github.com/Starosdev/scrutiny and attach a copy of your scrutiny.db file.\n%v", err)
+		}
 		return err
 	}
 	sr.logger.Infoln("SQLite global configuration migrations completed successfully")