feat: show admin UI warning for SQLite on networked filesystem (#1713)

Co-authored-by: Elias Schneider <login@eliasschneider.com>

backend/go.mod

@@ -25,7 +25,7 @@ require (
 	github.com/google/uuid v1.6.0
 	github.com/italypaleale/francis v0.1.0-beta.23
 	github.com/italypaleale/go-kit v1.0.0
-	github.com/italypaleale/go-sql-utils v0.3.5
+	github.com/italypaleale/go-sql-utils v0.3.6
 	github.com/jackc/pgx/v5 v5.10.0
 	github.com/jinzhu/copier v0.4.0
 	github.com/joho/godotenv v1.5.1

backend/go.sum

@@ -247,6 +247,8 @@ github.com/italypaleale/go-kit v1.0.0 h1:c+SaYHTaoZzTgbPXhSbNVdNRkNdNhE0YljBWWoP
 github.com/italypaleale/go-kit v1.0.0/go.mod h1:wg4UsIbsbtDiVqUjJdo/tO9lXo0OXBuwPOpSJ+u+1jI=
 github.com/italypaleale/go-sql-utils v0.3.5 h1:kkrhIo1tVJvcsjRc1kePWE9Cqdm26+Et5XZYSNmv764=
 github.com/italypaleale/go-sql-utils v0.3.5/go.mod h1:STWS4qGjiGKt2tf9OdRUlf025FhKZvUA31siUOnejj0=
+github.com/italypaleale/go-sql-utils v0.3.6 h1:ND14osePZFhn717qqI+nuH2blxKLTcYqWYSAG9anVDg=
+github.com/italypaleale/go-sql-utils v0.3.6/go.mod h1:STWS4qGjiGKt2tf9OdRUlf025FhKZvUA31siUOnejj0=
 github.com/jackc/pgerrcode v0.0.0-20250907135507-afb5586c32a6 h1:D/V0gu4zQ3cL2WKeVNVM4r2gLxGGf6McLwgXzRTo2RQ=
 github.com/jackc/pgerrcode v0.0.0-20250907135507-afb5586c32a6/go.mod h1:a/s9Lp5W7n/DD0VrVoyJ00FbP2ytTPDVOivvn2bMlds=
 github.com/jackc/pgpassfile v1.0.0 h1:/6Hmqy13Ss2zCq62VdNG8tM1wchn8zjSGOBJ6icpsIM=

backend/internal/bootstrap/db_bootstrap.go

@@ -27,6 +27,10 @@ import (
 	sqliteutil "github.com/pocket-id/pocket-id/backend/internal/utils/sqlite"
 )
 
+// Records whether the SQLite database was found on a networked filesystem
+// It's always false when using Postgres
+var sqliteOnNetworkedFilesystem bool
+
 func NewDatabase(ctx context.Context) (db *gorm.DB, pg *pgxpool.Pool, err error) {
 	db, pg, err = ConnectDatabase(ctx)
 	if err != nil {
@@ -68,6 +72,9 @@ func ConnectDatabase(ctx context.Context) (db *gorm.DB, pg *pgxpool.Pool, err er
 			return nil, nil, err
 		}
 
+		// Detect whether the database lives on a networked filesystem to show a warning in the admin UI
+		sqliteOnNetworkedFilesystem = connector.IsNetworked()
+
 		// We open the connection ourselves, rather than letting Gorm do it, so it goes through the instrumented driver
 		// It also caps in-memory databases to a single connection, which they need to see the whole data
 		sqliteDB, err := sqliteinstrument.Open(connector, sqlInstrumentOptions())

backend/internal/bootstrap/router_bootstrap.go

@@ -176,7 +176,7 @@ func registerRoutes(r *gin.Engine, db *gorm.DB, svc *services, rateLimitServices
 	controller.NewUserGroupController(apiGroup, authMiddleware, svc.appConfigService, svc.userGroupService)
 	svc.apiModule.RegisterRoutes(apiGroup, authMiddleware.Add())
 	controller.NewCustomClaimController(apiGroup, authMiddleware, svc.customClaimService)
-	controller.NewVersionController(apiGroup, authMiddleware, svc.versionService)
+	svc.environmentModule.RegisterRoutes(apiGroup, authMiddleware.WithAdminNotRequired().Add())
 	svc.scimSyncModule.RegisterRoutes(apiGroup, authMiddleware.Add())
 	svc.userSignUpModule.RegisterRoutes(apiGroup,
 		authMiddleware.Add(),

backend/internal/bootstrap/services_bootstrap.go

@@ -14,6 +14,7 @@ import (
 	"github.com/pocket-id/pocket-id/backend/internal/devicelogin"
 	"github.com/pocket-id/pocket-id/backend/internal/email"
 	"github.com/pocket-id/pocket-id/backend/internal/emailverification"
+	"github.com/pocket-id/pocket-id/backend/internal/environment"
 	"github.com/pocket-id/pocket-id/backend/internal/geolite"
 	"github.com/pocket-id/pocket-id/backend/internal/ldapsync"
 	"github.com/pocket-id/pocket-id/backend/internal/oidc"
@@ -37,7 +38,6 @@ type services struct {
 	customClaimService *service.CustomClaimService
 	oidcService        *service.OidcService
 	userGroupService   *service.UserGroupService
-	versionService     *service.VersionService
 	fileStorage        storage.FileStorage
 
 	apiKeyModule            *apikey.Module
@@ -51,6 +51,7 @@ type services struct {
 	oneTimeAccessModule     *onetimeaccess.Module
 	emailVerificationModule *emailverification.Module
 	apiModule               *api.Module
+	environmentModule       *environment.Module
 	actors                  *local.Host
 }
 
@@ -247,7 +248,10 @@ func initServices(
 		return nil, fmt.Errorf("failed to create email verification module: %w", err)
 	}
 
-	svc.versionService = service.NewVersionService(httpClient)
+	svc.environmentModule = environment.New(environment.Dependencies{
+		HTTPClient:                  httpClient,
+		SQLiteOnNetworkedFilesystem: sqliteOnNetworkedFilesystem,
+	})
 
 	return svc, nil
 }

backend/internal/common/env_config.go

@@ -16,15 +16,20 @@ import (
 	_ "github.com/joho/godotenv/autoload"
 )
 
-type AppEnv string
-type DbProvider string
-type TrustProxyConfig []string
+type (
+	AppEnv                            string
+	DbProvider                        string
+	TrustProxyConfig                  []string
+	DismissSQLiteStorageWarningConfig bool
+)
 
 const (
 	// TracerName should be passed to otel.Tracer, trace.SpanFromContext when creating custom spans.
 	TracerName = "github.com/pocket-id/pocket-id/backend/tracing"
 	// MeterName should be passed to otel.Meter when create custom metrics.
 	MeterName = "github.com/pocket-id/pocket-id/backend/metrics"
+	// dismissSQLiteStorageWarningPhrase is the exact phrase DISMISS_SQLITE_STORAGE_WARNING must be set to to suppress the warning (matched case-insensitive)
+	dismissSQLiteStorageWarningPhrase = "i accept the risks"
 )
 
 const (
@@ -99,6 +104,10 @@ type EnvConfigSchema struct {
 	// LogQueryArgs includes the values of SQL query parameters in traces and in the query logs printed when LogLevel is "debug"
 	// Note that these may can contain sensitive data
 	LogQueryArgs bool `env:"LOG_QUERY_ARGS"`
+
+	// This is true when DISMISS_SQLITE_STORAGE_WARNING is the exact confirmation phrase set in the constant above
+	// Note: this is omitted from the general list of environment variables in the docs, and documented only in the SQLite-specific section
+	DismissSQLiteStorageWarning DismissSQLiteStorageWarningConfig `env:"DISMISS_SQLITE_STORAGE_WARNING"`
 }
 
 var EnvConfig = defaultConfig()
@@ -422,6 +431,15 @@ func (a AppEnv) IsTest() bool {
 	return a == AppEnvTest
 }
 
+func (config *DismissSQLiteStorageWarningConfig) UnmarshalText(text []byte) error {
+	// Make lowercase, then replace all - and _ with spaces
+	value := strings.ToLower(strings.TrimSpace(string(text)))
+	value = strings.ReplaceAll(value, "_", " ")
+	value = strings.ReplaceAll(value, "-", " ")
+	*config = DismissSQLiteStorageWarningConfig(value == dismissSQLiteStorageWarningPhrase)
+	return nil
+}
+
 func (config *TrustProxyConfig) UnmarshalText(text []byte) error {
 	value := strings.TrimSpace(string(text))
 

backend/internal/common/env_config_test.go

@@ -337,6 +337,49 @@ func TestParseEnvConfig(t *testing.T) {
 		assert.ErrorContains(t, err, "TLS_CERT_FILE not found")
 	})
 
+	t.Run("should not dismiss the SQLite storage warning by default", func(t *testing.T) {
+		EnvConfig = defaultConfig()
+		t.Setenv("DB_CONNECTION_STRING", "file:test.db")
+		t.Setenv("APP_URL", "http://localhost:3000")
+
+		err := parseAndValidateEnvConfig(t)
+		require.NoError(t, err)
+		assert.False(t, bool(EnvConfig.DismissSQLiteStorageWarning))
+	})
+
+	t.Run("should not dismiss the SQLite storage warning with an unrelated value", func(t *testing.T) {
+		EnvConfig = defaultConfig()
+		t.Setenv("DB_CONNECTION_STRING", "file:test.db")
+		t.Setenv("APP_URL", "http://localhost:3000")
+		t.Setenv("DISMISS_SQLITE_STORAGE_WARNING", "true")
+
+		err := parseAndValidateEnvConfig(t)
+		require.NoError(t, err)
+		assert.False(t, bool(EnvConfig.DismissSQLiteStorageWarning))
+	})
+
+	t.Run("should dismiss the SQLite storage warning with the confirmation phrase", func(t *testing.T) {
+		EnvConfig = defaultConfig()
+		t.Setenv("DB_CONNECTION_STRING", "file:test.db")
+		t.Setenv("APP_URL", "http://localhost:3000")
+		t.Setenv("DISMISS_SQLITE_STORAGE_WARNING", "  I Accept The Risks  ")
+
+		err := parseAndValidateEnvConfig(t)
+		require.NoError(t, err)
+		assert.True(t, bool(EnvConfig.DismissSQLiteStorageWarning))
+	})
+
+	t.Run("should dismiss the SQLite storage warning with the confirmation phrase with dashes", func(t *testing.T) {
+		EnvConfig = defaultConfig()
+		t.Setenv("DB_CONNECTION_STRING", "file:test.db")
+		t.Setenv("APP_URL", "http://localhost:3000")
+		t.Setenv("DISMISS_SQLITE_STORAGE_WARNING", " I-Accept_The_Risks  ")
+
+		err := parseAndValidateEnvConfig(t)
+		require.NoError(t, err)
+		assert.True(t, bool(EnvConfig.DismissSQLiteStorageWarning))
+	})
+
 	t.Run("should fail when TLS key file does not exist", func(t *testing.T) {
 		EnvConfig = defaultConfig()
 		t.Setenv("DB_CONNECTION_STRING", "file:test.db")

backend/internal/controller/version_controller.go

@@ -1,60 +0,0 @@
-package controller
-
-import (
-	"net/http"
-	"time"
-
-	"github.com/gin-gonic/gin"
-	"github.com/pocket-id/pocket-id/backend/internal/common"
-	_ "github.com/pocket-id/pocket-id/backend/internal/dto"
-	"github.com/pocket-id/pocket-id/backend/internal/httpserver"
-	"github.com/pocket-id/pocket-id/backend/internal/middleware"
-	"github.com/pocket-id/pocket-id/backend/internal/service"
-	"github.com/pocket-id/pocket-id/backend/internal/utils"
-)
-
-// NewVersionController registers version-related routes.
-func NewVersionController(group *gin.RouterGroup, authMiddleware *middleware.AuthMiddleware, versionService *service.VersionService) {
-	vc := &VersionController{versionService: versionService}
-	group.GET("/version/latest", httpserver.Handle(vc.getLatestVersionHandler))
-	group.GET("/version/current", authMiddleware.WithAdminNotRequired().Add(), httpserver.Handle(vc.getCurrentVersionHandler))
-}
-
-type VersionController struct {
-	versionService *service.VersionService
-}
-
-// getLatestVersionHandler godoc
-// @Summary Get latest available version of Pocket ID
-// @Tags Version
-// @Produce json
-// @Success 200 {object} map[string]string "Latest version information"
-// @Failure default {object} dto.ErrorDto "Error"
-// @Router /api/version/latest [get]
-func (vc *VersionController) getLatestVersionHandler(c *gin.Context) error {
-	tag, err := vc.versionService.GetLatestVersion(c.Request.Context())
-	if err != nil {
-		return err
-	}
-
-	utils.SetCacheControlHeader(c, 5*time.Minute, 15*time.Minute)
-
-	c.JSON(http.StatusOK, gin.H{
-		"latestVersion": tag,
-	})
-	return nil
-}
-
-// getCurrentVersionHandler godoc
-// @Summary Get current deployed version of Pocket ID
-// @Tags Version
-// @Produce json
-// @Success 200 {object} map[string]string "Current version information"
-// @Failure default {object} dto.ErrorDto "Error"
-// @Router /api/version/current [get]
-func (vc *VersionController) getCurrentVersionHandler(c *gin.Context) error {
-	c.JSON(http.StatusOK, gin.H{
-		"currentVersion": common.Version,
-	})
-	return nil
-}

backend/internal/environment/handler.go

@@ -0,0 +1,70 @@
+package environment
+
+import (
+	"net/http"
+	"time"
+
+	"github.com/gin-gonic/gin"
+
+	"github.com/pocket-id/pocket-id/backend/internal/common"
+	_ "github.com/pocket-id/pocket-id/backend/internal/dto"
+	"github.com/pocket-id/pocket-id/backend/internal/utils"
+)
+
+type handler struct {
+	service *Service
+}
+
+func newHandler(service *Service) *handler {
+	return &handler{service: service}
+}
+
+// getLatestVersion godoc
+// @Summary Get latest available version of Pocket ID
+// @Tags Version
+// @Produce json
+// @Success 200 {object} map[string]string "Latest version information"
+// @Failure default {object} dto.ErrorDto "Error"
+// @Router /api/version/latest [get]
+func (h *handler) getLatestVersion(c *gin.Context) error {
+	tag, err := h.service.GetLatestVersion(c.Request.Context())
+	if err != nil {
+		return err
+	}
+
+	utils.SetCacheControlHeader(c, 5*time.Minute, 15*time.Minute)
+
+	c.JSON(http.StatusOK, gin.H{
+		"latestVersion": tag,
+	})
+	return nil
+}
+
+// getCurrentVersion godoc
+// @Summary Get current deployed version of Pocket ID
+// @Tags Version
+// @Produce json
+// @Success 200 {object} map[string]string "Current version information"
+// @Failure default {object} dto.ErrorDto "Error"
+// @Router /api/version/current [get]
+func (h *handler) getCurrentVersion(c *gin.Context) error {
+	c.JSON(http.StatusOK, gin.H{
+		"currentVersion": common.Version,
+	})
+	return nil
+}
+
+// getSqliteStorageWarning godoc
+// @Summary Get whether the SQLite storage warning should be shown
+// @Description Reports whether Pocket ID found its SQLite database on a networked filesystem, which is unsupported and can lead to database corruption
+// @Tags Storage
+// @Produce json
+// @Success 200 {object} map[string]bool "SQLite storage warning state"
+// @Failure default {object} dto.ErrorDto "Error"
+// @Router /api/storage/sqlite-warning [get]
+func (h *handler) getSqliteStorageWarning(c *gin.Context) error {
+	c.JSON(http.StatusOK, gin.H{
+		"showWarning": h.service.ShowSQLiteStorageWarning(),
+	})
+	return nil
+}

backend/internal/environment/module.go

@@ -0,0 +1,38 @@
+package environment
+
+import (
+	"net/http"
+
+	"github.com/gin-gonic/gin"
+
+	"github.com/pocket-id/pocket-id/backend/internal/httpserver"
+)
+
+type Dependencies struct {
+	HTTPClient *http.Client
+
+	// SQLiteOnNetworkedFilesystem is true when the SQLite database was found on a networked filesystem
+	// It's always false when using Postgres
+	SQLiteOnNetworkedFilesystem bool
+}
+
+// Module exposes read-only facts about the environment Pocket ID runs in, such as its version and where its database is stored
+type Module struct {
+	service *Service
+	handler *handler
+}
+
+func New(deps Dependencies) *Module {
+	service := newService(deps)
+	return &Module{
+		service: service,
+		handler: newHandler(service),
+	}
+}
+
+// RegisterRoutes mounts the environment endpoints
+func (m *Module) RegisterRoutes(apiGroup *gin.RouterGroup, auth gin.HandlerFunc) {
+	apiGroup.GET("/version/latest", httpserver.Handle(m.handler.getLatestVersion))
+	apiGroup.GET("/version/current", auth, httpserver.Handle(m.handler.getCurrentVersion))
+	apiGroup.GET("/storage/sqlite-warning", auth, httpserver.Handle(m.handler.getSqliteStorageWarning))
+}

backend/internal/environment/service.go

@@ -1,4 +1,4 @@
-package service
+package environment
 
 import (
 	"context"
@@ -19,19 +19,22 @@ const (
 	versionCheckURL = "https://api.github.com/repos/pocket-id/pocket-id/releases/latest"
 )
 
-type VersionService struct {
+type Service struct {
 	httpClient *http.Client
 	cache      *utils.Cache[string]
+
+	sqliteOnNetworkedFilesystem bool
 }
 
-func NewVersionService(httpClient *http.Client) *VersionService {
-	return &VersionService{
-		httpClient: httpClient,
-		cache:      utils.New[string](versionTTL),
+func newService(deps Dependencies) *Service {
+	return &Service{
+		httpClient:                  deps.HTTPClient,
+		cache:                       utils.New[string](versionTTL),
+		sqliteOnNetworkedFilesystem: deps.SQLiteOnNetworkedFilesystem,
 	}
 }
 
-func (s *VersionService) GetLatestVersion(ctx context.Context) (string, error) {
+func (s *Service) GetLatestVersion(ctx context.Context) (string, error) {
 	if common.EnvConfig.VersionCheckDisabled {
 		return "", nil
 	}
@@ -76,3 +79,8 @@ func (s *VersionService) GetLatestVersion(ctx context.Context) (string, error) {
 
 	return version, err
 }
+
+// ShowSQLiteStorageWarning reports whether admins should be warned that the SQLite database is on a networked filesystem
+func (s *Service) ShowSQLiteStorageWarning() bool {
+	return s.sqliteOnNetworkedFilesystem && !bool(common.EnvConfig.DismissSQLiteStorageWarning)
+}

backend/internal/environment/service_test.go

@@ -0,0 +1,36 @@
+package environment
+
+import (
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+
+	"github.com/pocket-id/pocket-id/backend/internal/common"
+)
+
+func TestShowSQLiteStorageWarning(t *testing.T) {
+	tests := []struct {
+		name                        string
+		sqliteOnNetworkedFilesystem bool
+		dismissed                   bool
+		want                        bool
+	}{
+		{name: "warns when the database is on a networked filesystem", sqliteOnNetworkedFilesystem: true, want: true},
+		{name: "does not warn when the database is on a local filesystem", sqliteOnNetworkedFilesystem: false, want: false},
+		{name: "does not warn when the warning has been dismissed", sqliteOnNetworkedFilesystem: true, dismissed: true, want: false},
+		{name: "does not warn when dismissed and the database is on a local filesystem", sqliteOnNetworkedFilesystem: false, dismissed: true, want: false},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			prevConfig := common.EnvConfig
+			t.Cleanup(func() {
+				common.EnvConfig = prevConfig
+			})
+			common.EnvConfig.DismissSQLiteStorageWarning = common.DismissSQLiteStorageWarningConfig(tt.dismissed)
+
+			svc := newService(Dependencies{SQLiteOnNetworkedFilesystem: tt.sqliteOnNetworkedFilesystem})
+			assert.Equal(t, tt.want, svc.ShowSQLiteStorageWarning())
+		})
+	}
+}