Add µPaaS deployment setup for fsn1app1

- Add Docker HEALTHCHECK instruction probing /.well-known/healthcheck.json
  (30s interval, 5s timeout, 10s start period, 3 retries) for µPaaS
  container health verification
- Create deploy/README.md with full µPaaS app configuration reference
  (app name, repo URL, branch, env vars, volumes, ports, production config)
- Add Deployment section to README.md linking to deploy docs
- Add deploy/ to .dockerignore (docs not needed in build context)

.dockerignore

@@ -6,3 +6,4 @@
 node_modules
 bin/
 data/
+deploy/

Dockerfile

@@ -75,4 +75,7 @@ WORKDIR /var/lib/pixa
 
 EXPOSE 8080
 
+HEALTHCHECK --interval=30s --timeout=5s --start-period=10s --retries=3 \
+    CMD wget -q --spider http://localhost:8080/.well-known/healthcheck.json
+
 ENTRYPOINT ["/usr/local/bin/pixad", "--config", "/etc/pixa/config.yml"]

README.md

@@ -125,6 +125,17 @@ See `config.example.yml` for all options with defaults.
 - **Metrics**: Prometheus
 - **Logging**: stdlib slog
 
+## Deployment
+
+Pixa is deployed via
+[µPaaS](https://git.eeqj.de/sneak/upaas) on `fsn1app1`
+(paas.datavi.be). Pushes to `main` trigger automatic builds and
+deployments. The Dockerfile includes a `HEALTHCHECK` that probes
+`/.well-known/healthcheck.json`.
+
+See [deploy/README.md](deploy/README.md) for the full µPaaS app
+configuration, volume mounts, and production setup instructions.
+
 ## TODO
 
 See [TODO.md](TODO.md) for the full prioritized task list.

cmd/pixad/main.go

@@ -17,7 +17,10 @@ import (
 	"sneak.berlin/go/pixa/internal/server"
 )
 
-var Version string //nolint:gochecknoglobals // set by ldflags
+var (
+	Appname = "pixad" //nolint:gochecknoglobals // set by ldflags
+	Version string    //nolint:gochecknoglobals // set by ldflags
+)
 
 var configPath string //nolint:gochecknoglobals // cobra flag
 
@@ -37,6 +40,7 @@ func main() {
 }
 
 func run(_ *cobra.Command, _ []string) {
+	globals.Appname = Appname
 	globals.Version = Version
 
 	// Set config path in environment if specified via flag

deploy/README.md

@@ -0,0 +1,78 @@
+# Pixa Deployment via µPaaS
+
+Pixa is deployed on `fsn1app1` via
+[µPaaS](https://git.eeqj.de/sneak/upaas) (paas.datavi.be).
+
+## µPaaS App Configuration
+
+Create the app in the µPaaS web UI with these settings:
+
+| Setting | Value |
+| --- | --- |
+| **App name** | `pixa` |
+| **Repo URL** | `git@git.eeqj.de:sneak/pixa.git` |
+| **Branch** | `main` |
+| **Dockerfile path** | `Dockerfile` |
+
+### Environment Variables
+
+| Variable | Description | Required |
+| --- | --- | --- |
+| `PORT` | HTTP listen port (default: 8080) | No |
+
+Configuration is provided via the config file baked into the Docker
+image at `/etc/pixa/config.yml`. To override it, mount a custom
+config file as a volume (see below).
+
+### Volumes
+
+| Host Path | Container Path | Description |
+| --- | --- | --- |
+| `/srv/pixa/data` | `/var/lib/pixa` | SQLite database and image cache |
+| `/srv/pixa/config.yml` | `/etc/pixa/config.yml` | Production config (signing key, whitelist, etc.) |
+
+### Ports
+
+| Host Port | Container Port | Protocol |
+| --- | --- | --- |
+| (assigned) | 8080 | TCP |
+
+### Docker Network
+
+Attach to the shared reverse-proxy network if using Caddy/Traefik
+for TLS termination.
+
+## Production Configuration
+
+Copy `config.example.yml` from the repo root and customize for
+production:
+
+```yaml
+port: 8080
+debug: false
+maintenance_mode: false
+state_dir: /var/lib/pixa
+signing_key: "<generate with: openssl rand -base64 32>"
+whitelist_hosts:
+    - s3.sneak.cloud
+    - static.sneak.cloud
+    - sneak.berlin
+allow_http: false
+```
+
+**Important:** Generate a unique `signing_key` for production. Never
+use the default placeholder value.
+
+## Health Check
+
+The Dockerfile includes a `HEALTHCHECK` instruction that probes
+`/.well-known/healthcheck.json` every 30 seconds. µPaaS verifies
+container health 60 seconds after deployment.
+
+## Deployment Flow
+
+1. Push to `main` triggers the Gitea webhook
+2. µPaaS clones the repo and runs `docker build .`
+3. The Dockerfile runs `make check` (format, lint, test) during build
+4. On success, µPaaS stops the old container and starts the new one
+5. After 60 seconds, µPaaS checks container health

internal/database/database.go

@@ -35,41 +35,6 @@ type Database struct {
 	config *config.Config
 }
 
-// ParseMigrationVersion extracts the numeric version prefix from a migration
-// filename. Filenames must follow the pattern "<version>.sql" or
-// "<version>_<description>.sql", where version is a zero-padded numeric
-// string (e.g. "001", "002"). Returns the version string and an error if
-// the filename does not match the expected pattern.
-func ParseMigrationVersion(filename string) (string, error) {
-	name := strings.TrimSuffix(filename, filepath.Ext(filename))
-	if name == "" {
-		return "", fmt.Errorf("invalid migration filename %q: empty name", filename)
-	}
-
-	// Split on underscore to separate version from description.
-	// If there's no underscore, the entire stem is the version.
-	version := name
-	if idx := strings.IndexByte(name, '_'); idx >= 0 {
-		version = name[:idx]
-	}
-
-	if version == "" {
-		return "", fmt.Errorf("invalid migration filename %q: empty version prefix", filename)
-	}
-
-	// Validate the version is purely numeric.
-	for _, ch := range version {
-		if ch < '0' || ch > '9' {
-			return "", fmt.Errorf(
-				"invalid migration filename %q: version %q contains non-numeric character %q",
-				filename, version, string(ch),
-			)
-		}
-	}
-
-	return version, nil
-}
-
 // New creates a new Database instance.
 func New(lc fx.Lifecycle, params Params) (*Database, error) {
 	s := &Database{
@@ -119,33 +84,96 @@ func (s *Database) connect(ctx context.Context) error {
 	s.db = db
 	s.log.Info("database connected")
 
-	return ApplyMigrations(ctx, s.db, s.log)
+	return s.runMigrations(ctx)
 }
 
-// collectMigrations reads the embedded schema directory and returns
-// migration filenames sorted lexicographically.
-func collectMigrations() ([]string, error) {
-	entries, err := schemaFS.ReadDir("schema")
+func (s *Database) runMigrations(ctx context.Context) error {
+	// Create migrations tracking table
+	_, err := s.db.ExecContext(ctx, `
+		CREATE TABLE IF NOT EXISTS schema_migrations (
+			version TEXT PRIMARY KEY,
+			applied_at DATETIME DEFAULT CURRENT_TIMESTAMP
+		)
+	`)
 	if err != nil {
-		return nil, fmt.Errorf("failed to read schema directory: %w", err)
+		return fmt.Errorf("failed to create migrations table: %w", err)
 	}
 
-	var migrations []string
+	// Get list of migration files
+	entries, err := schemaFS.ReadDir("schema")
+	if err != nil {
+		return fmt.Errorf("failed to read schema directory: %w", err)
+	}
 
+	// Sort migration files by name (001.sql, 002.sql, etc.)
+	var migrations []string
 	for _, entry := range entries {
 		if !entry.IsDir() && strings.HasSuffix(entry.Name(), ".sql") {
 			migrations = append(migrations, entry.Name())
 		}
 	}
-
 	sort.Strings(migrations)
 
-	return migrations, nil
+	// Apply each migration that hasn't been applied yet
+	for _, migration := range migrations {
+		version := strings.TrimSuffix(migration, filepath.Ext(migration))
+
+		// Check if already applied
+		var count int
+		err := s.db.QueryRowContext(ctx,
+			"SELECT COUNT(*) FROM schema_migrations WHERE version = ?",
+			version,
+		).Scan(&count)
+		if err != nil {
+			return fmt.Errorf("failed to check migration status: %w", err)
+		}
+
+		if count > 0 {
+			s.log.Debug("migration already applied", "version", version)
+
+			continue
+		}
+
+		// Read and apply migration
+		content, err := schemaFS.ReadFile(filepath.Join("schema", migration))
+		if err != nil {
+			return fmt.Errorf("failed to read migration %s: %w", migration, err)
+		}
+
+		s.log.Info("applying migration", "version", version)
+
+		_, err = s.db.ExecContext(ctx, string(content))
+		if err != nil {
+			return fmt.Errorf("failed to apply migration %s: %w", migration, err)
+		}
+
+		// Record migration as applied
+		_, err = s.db.ExecContext(ctx,
+			"INSERT INTO schema_migrations (version) VALUES (?)",
+			version,
+		)
+		if err != nil {
+			return fmt.Errorf("failed to record migration %s: %w", migration, err)
+		}
+
+		s.log.Info("migration applied successfully", "version", version)
+	}
+
+	return nil
 }
 
-// ensureMigrationsTable creates the schema_migrations tracking table if
-// it does not already exist.
-func ensureMigrationsTable(ctx context.Context, db *sql.DB) error {
+// DB returns the underlying sql.DB.
+func (s *Database) DB() *sql.DB {
+	return s.db
+}
+
+// ApplyMigrations applies all migrations to the given database.
+// This is useful for testing where you want to use the real schema
+// without the full fx lifecycle.
+func ApplyMigrations(db *sql.DB) error {
+	ctx := context.Background()
+
+	// Create migrations tracking table
 	_, err := db.ExecContext(ctx, `
 		CREATE TABLE IF NOT EXISTS schema_migrations (
 			version TEXT PRIMARY KEY,
@@ -156,32 +184,27 @@ func ensureMigrationsTable(ctx context.Context, db *sql.DB) error {
 		return fmt.Errorf("failed to create migrations table: %w", err)
 	}
 
-	return nil
-}
-
-// ApplyMigrations applies all pending migrations to db. An optional logger
-// may be provided for informational output; pass nil for silent operation.
-// This is exported so tests can apply the real schema without the full fx
-// lifecycle.
-func ApplyMigrations(ctx context.Context, db *sql.DB, log *slog.Logger) error {
-	if err := ensureMigrationsTable(ctx, db); err != nil {
-		return err
-	}
-
-	migrations, err := collectMigrations()
+	// Get list of migration files
+	entries, err := schemaFS.ReadDir("schema")
 	if err != nil {
-		return err
+		return fmt.Errorf("failed to read schema directory: %w", err)
 	}
 
+	// Sort migration files by name (001.sql, 002.sql, etc.)
+	var migrations []string
+	for _, entry := range entries {
+		if !entry.IsDir() && strings.HasSuffix(entry.Name(), ".sql") {
+			migrations = append(migrations, entry.Name())
+		}
+	}
+	sort.Strings(migrations)
+
+	// Apply each migration that hasn't been applied yet
 	for _, migration := range migrations {
-		version, parseErr := ParseMigrationVersion(migration)
-		if parseErr != nil {
-			return parseErr
-		}
+		version := strings.TrimSuffix(migration, filepath.Ext(migration))
 
-		// Check if already applied.
+		// Check if already applied
 		var count int
-
 		err := db.QueryRowContext(ctx,
 			"SELECT COUNT(*) FROM schema_migrations WHERE version = ?",
 			version,
@@ -191,46 +214,29 @@ func ApplyMigrations(ctx context.Context, db *sql.DB, log *slog.Logger) error {
 		}
 
 		if count > 0 {
-			if log != nil {
-				log.Debug("migration already applied", "version", version)
-			}
-
 			continue
 		}
 
-		// Read and apply migration.
-		content, readErr := schemaFS.ReadFile(filepath.Join("schema", migration))
-		if readErr != nil {
-			return fmt.Errorf("failed to read migration %s: %w", migration, readErr)
+		// Read and apply migration
+		content, err := schemaFS.ReadFile(filepath.Join("schema", migration))
+		if err != nil {
+			return fmt.Errorf("failed to read migration %s: %w", migration, err)
 		}
 
-		if log != nil {
-			log.Info("applying migration", "version", version)
+		_, err = db.ExecContext(ctx, string(content))
+		if err != nil {
+			return fmt.Errorf("failed to apply migration %s: %w", migration, err)
 		}
 
-		_, execErr := db.ExecContext(ctx, string(content))
-		if execErr != nil {
-			return fmt.Errorf("failed to apply migration %s: %w", migration, execErr)
-		}
-
-		// Record migration as applied.
-		_, recErr := db.ExecContext(ctx,
+		// Record migration as applied
+		_, err = db.ExecContext(ctx,
 			"INSERT INTO schema_migrations (version) VALUES (?)",
 			version,
 		)
-		if recErr != nil {
-			return fmt.Errorf("failed to record migration %s: %w", migration, recErr)
-		}
-
-		if log != nil {
-			log.Info("migration applied successfully", "version", version)
+		if err != nil {
+			return fmt.Errorf("failed to record migration %s: %w", migration, err)
 		}
 	}
 
 	return nil
 }
-
-// DB returns the underlying sql.DB.
-func (s *Database) DB() *sql.DB {
-	return s.db
-}

internal/database/database_test.go

@@ -1,155 +0,0 @@
-package database
-
-import (
-	"context"
-	"database/sql"
-	"testing"
-
-	_ "modernc.org/sqlite" // SQLite driver registration
-)
-
-func TestParseMigrationVersion(t *testing.T) {
-	tests := []struct {
-		name     string
-		filename string
-		want     string
-		wantErr  bool
-	}{
-		{
-			name:     "version only",
-			filename: "001.sql",
-			want:     "001",
-		},
-		{
-			name:     "version with description",
-			filename: "001_initial_schema.sql",
-			want:     "001",
-		},
-		{
-			name:     "multi-digit version",
-			filename: "042_add_indexes.sql",
-			want:     "042",
-		},
-		{
-			name:     "long version number",
-			filename: "00001_long_prefix.sql",
-			want:     "00001",
-		},
-		{
-			name:     "description with multiple underscores",
-			filename: "003_add_user_auth_tables.sql",
-			want:     "003",
-		},
-		{
-			name:     "empty filename",
-			filename: ".sql",
-			wantErr:  true,
-		},
-		{
-			name:     "leading underscore",
-			filename: "_description.sql",
-			wantErr:  true,
-		},
-		{
-			name:     "non-numeric version",
-			filename: "abc_migration.sql",
-			wantErr:  true,
-		},
-		{
-			name:     "mixed alphanumeric version",
-			filename: "001a_migration.sql",
-			wantErr:  true,
-		},
-	}
-
-	for _, tt := range tests {
-		t.Run(tt.name, func(t *testing.T) {
-			got, err := ParseMigrationVersion(tt.filename)
-			if tt.wantErr {
-				if err == nil {
-					t.Errorf("ParseMigrationVersion(%q) expected error, got %q", tt.filename, got)
-				}
-
-				return
-			}
-
-			if err != nil {
-				t.Errorf("ParseMigrationVersion(%q) unexpected error: %v", tt.filename, err)
-
-				return
-			}
-
-			if got != tt.want {
-				t.Errorf("ParseMigrationVersion(%q) = %q, want %q", tt.filename, got, tt.want)
-			}
-		})
-	}
-}
-
-func TestApplyMigrations(t *testing.T) {
-	db, err := sql.Open("sqlite", ":memory:")
-	if err != nil {
-		t.Fatalf("failed to open in-memory database: %v", err)
-	}
-	defer db.Close()
-
-	// Apply migrations should succeed.
-	if err := ApplyMigrations(context.Background(), db, nil); err != nil {
-		t.Fatalf("ApplyMigrations failed: %v", err)
-	}
-
-	// Verify the schema_migrations table recorded the version.
-	var version string
-
-	err = db.QueryRowContext(context.Background(),
-		"SELECT version FROM schema_migrations LIMIT 1",
-	).Scan(&version)
-	if err != nil {
-		t.Fatalf("failed to query schema_migrations: %v", err)
-	}
-
-	if version != "001" {
-		t.Errorf("expected version %q, got %q", "001", version)
-	}
-
-	// Verify a table from the migration exists (source_content).
-	var tableName string
-
-	err = db.QueryRowContext(context.Background(),
-		"SELECT name FROM sqlite_master WHERE type='table' AND name='source_content'",
-	).Scan(&tableName)
-	if err != nil {
-		t.Fatalf("expected source_content table to exist: %v", err)
-	}
-}
-
-func TestApplyMigrationsIdempotent(t *testing.T) {
-	db, err := sql.Open("sqlite", ":memory:")
-	if err != nil {
-		t.Fatalf("failed to open in-memory database: %v", err)
-	}
-	defer db.Close()
-
-	// Apply twice should succeed (idempotent).
-	if err := ApplyMigrations(context.Background(), db, nil); err != nil {
-		t.Fatalf("first ApplyMigrations failed: %v", err)
-	}
-
-	if err := ApplyMigrations(context.Background(), db, nil); err != nil {
-		t.Fatalf("second ApplyMigrations failed: %v", err)
-	}
-
-	// Should still have exactly one migration recorded.
-	var count int
-
-	err = db.QueryRowContext(context.Background(),
-		"SELECT COUNT(*) FROM schema_migrations",
-	).Scan(&count)
-	if err != nil {
-		t.Fatalf("failed to count schema_migrations: %v", err)
-	}
-
-	if count != 1 {
-		t.Errorf("expected 1 migration record, got %d", count)
-	}
-}

internal/globals/globals.go

@@ -5,10 +5,11 @@ import (
 	"go.uber.org/fx"
 )
 
-const appname = "pixad"
-
-// Version is populated from main() via ldflags.
-var Version string //nolint:gochecknoglobals // set from main
+// Build-time variables populated from main() via ldflags.
+var (
+	Appname string //nolint:gochecknoglobals // set from main
+	Version string //nolint:gochecknoglobals // set from main
+)
 
 // Globals holds application-wide constants.
 type Globals struct {
@@ -19,7 +20,7 @@ type Globals struct {
 // New creates a new Globals instance from build-time variables.
 func New(_ fx.Lifecycle) (*Globals, error) {
 	return &Globals{
-		Appname: appname,
+		Appname: Appname,
 		Version: Version,
 	}, nil
 }

internal/handlers/handlers_test.go

@@ -82,7 +82,7 @@ func setupTestDB(t *testing.T) *sql.DB {
 		t.Fatalf("failed to open test db: %v", err)
 	}
 
-	if err := database.ApplyMigrations(context.Background(), db, nil); err != nil {
+	if err := database.ApplyMigrations(db); err != nil {
 		t.Fatalf("failed to apply migrations: %v", err)
 	}
 

internal/imgcache/stats_test.go

@@ -16,7 +16,7 @@ func setupStatsTestDB(t *testing.T) *sql.DB {
 	if err != nil {
 		t.Fatal(err)
 	}
-	if err := database.ApplyMigrations(context.Background(), db, nil); err != nil {
+	if err := database.ApplyMigrations(db); err != nil {
 		t.Fatal(err)
 	}
 	t.Cleanup(func() { db.Close() })

internal/imgcache/testutil_test.go

@@ -2,7 +2,6 @@ package imgcache
 
 import (
 	"bytes"
-	"context"
 	"database/sql"
 	"image"
 	"image/color"
@@ -194,7 +193,7 @@ func setupServiceTestDB(t *testing.T) *sql.DB {
 	}
 
 	// Use the real production schema via migrations
-	if err := database.ApplyMigrations(context.Background(), db, nil); err != nil {
+	if err := database.ApplyMigrations(db); err != nil {
 		t.Fatalf("failed to apply migrations: %v", err)
 	}