Configuration

Configuration

Stowry uses a YAML configuration file with environment variable overrides.

Configuration Precedence

Configuration values are loaded in this order (later sources override earlier ones):

1. Default values
2. Configuration file (config.yaml)
3. Environment variables (STOWRY_ prefix)
4. Command-line flags

Full Configuration Reference

# Server configuration
server:
  port: 5708              # HTTP server port (default: 5708)
  mode: store             # Server mode: store, static, spa (default: store)

# Database configuration
database:
  type: sqlite            # Database type: sqlite, postgres (default: sqlite)
  dsn: stowry.db         # Connection string or file path
  table: stowry_metadata  # Metadata table name (default: stowry_metadata)
  auto_migrate: true      # Automatically create/update tables on startup (default: false)

# Storage configuration
storage:
  path: ./data           # Directory for file storage (default: ./data)

# Authentication configuration
auth:
  region: us-east-1      # AWS region for signature verification
  service: s3            # AWS service name (default: s3)
  keys:                  # List of access keys
    - access_key: AKIAIOSFODNN7EXAMPLE
      secret_key: wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY

# Access control
access:
  public_read: false     # Allow unauthenticated read access (default: false)
  public_write: false    # Allow unauthenticated write access (default: false)

# Logging
log:
  level: info            # Log level: debug, info, warn, error (default: info)

Configuration Sections

Server

Option	Type	Default	Description
port	int	5708	HTTP server port
mode	string	store	Server mode (store, static, spa)

Database

Option	Type	Default	Description
type	string	sqlite	Database type (sqlite, postgres)
dsn	string	stowry.db	Connection string
table	string	stowry_metadata	Metadata table name
auto_migrate	bool	false	Automatically create/update database schema on startup

Migration Options:

1. Auto-migrate (recommended for development): Set auto_migrate: true in config
2. CLI migration: Run stowry init before starting the server
3. Manual SQL: Execute the schema SQL below directly in your database

PostgreSQL Schema

-- Table name can be anything - just ensure it matches database.table in your config
CREATE TABLE IF NOT EXISTS stowry_metadata (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    path TEXT NOT NULL UNIQUE,
    content_type TEXT NOT NULL,
    etag TEXT NOT NULL,
    file_size_bytes BIGINT NOT NULL,
    created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
    updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
    deleted_at TIMESTAMPTZ,
    cleaned_up_at TIMESTAMPTZ
);

CREATE INDEX IF NOT EXISTS idx_stowry_metadata_deleted_at
ON stowry_metadata (deleted_at)
WHERE (deleted_at IS NOT NULL);

CREATE INDEX IF NOT EXISTS idx_stowry_metadata_pending_cleanup
ON stowry_metadata (deleted_at, cleaned_up_at)
WHERE (deleted_at IS NOT NULL AND cleaned_up_at IS NULL);

CREATE INDEX IF NOT EXISTS idx_stowry_metadata_active_list
ON stowry_metadata (created_at, path)
WHERE (deleted_at IS NULL);

SQLite Schema

-- Table name can be anything - just ensure it matches database.table in your config
CREATE TABLE IF NOT EXISTS stowry_metadata (
    id TEXT NOT NULL PRIMARY KEY,
    path TEXT NOT NULL UNIQUE,
    content_type TEXT NOT NULL,
    etag TEXT NOT NULL,
    file_size_bytes INTEGER NOT NULL,
    created_at TEXT NOT NULL,
    updated_at TEXT NOT NULL,
    deleted_at TEXT,
    cleaned_up_at TEXT
);

CREATE INDEX IF NOT EXISTS idx_stowry_metadata_deleted_at
ON stowry_metadata (deleted_at);

CREATE INDEX IF NOT EXISTS idx_stowry_metadata_pending_cleanup
ON stowry_metadata (deleted_at, cleaned_up_at);

CREATE INDEX IF NOT EXISTS idx_stowry_metadata_active_list
ON stowry_metadata (created_at, path);

SQLite DSN Examples:

dsn: stowry.db           # File-based database
dsn: :memory:            # In-memory (testing only)
dsn: /var/lib/stowry/db  # Absolute path

PostgreSQL DSN Examples:

dsn: postgres://user:password@localhost:5432/stowry
dsn: postgres://user:password@localhost:5432/stowry?sslmode=disable
dsn: host=localhost port=5432 user=stowry password=secret dbname=stowry

Storage

Option	Type	Default	Description
path	string	./data	Directory for file storage

The storage directory is created automatically if it doesn’t exist. Files are organized by their path, maintaining the original directory structure.

Auth

Option	Type	Default	Description
region	string	us-east-1	AWS region for signature verification
service	string	s3	AWS service name
keys	list	[]	List of access key pairs

Multiple Keys:

auth:
  keys:
    - access_key: KEY1
      secret_key: SECRET1
    - access_key: KEY2
      secret_key: SECRET2

Access

Option	Type	Default	Description
public_read	bool	false	Allow unauthenticated GET requests
public_write	bool	false	Allow unauthenticated PUT/DELETE requests

Access Control Matrix:

public_read	public_write	GET	PUT	DELETE
false	false	Auth required	Auth required	Auth required
true	false	Public	Auth required	Auth required
true	true	Public	Public	Public
false	true	Auth required	Public	Public

Log

Option	Type	Default	Description
level	string	info	Minimum log level

Log levels: debug, info, warn, error

Environment Variables

All configuration options can be set via environment variables using the STOWRY_ prefix with underscores replacing dots.

Config Path	Environment Variable
server.port	STOWRY_SERVER_PORT
server.mode	STOWRY_SERVER_MODE
database.type	STOWRY_DATABASE_TYPE
database.dsn	STOWRY_DATABASE_DSN
database.table	STOWRY_DATABASE_TABLE
database.auto_migrate	STOWRY_DATABASE_AUTO_MIGRATE
storage.path	STOWRY_STORAGE_PATH
auth.region	STOWRY_AUTH_REGION
access.public_read	STOWRY_ACCESS_PUBLIC_READ
access.public_write	STOWRY_ACCESS_PUBLIC_WRITE
log.level	STOWRY_LOG_LEVEL

Example:

STOWRY_SERVER_PORT=8080 \
STOWRY_DATABASE_TYPE=postgres \
STOWRY_DATABASE_DSN="postgres://localhost/stowry" \
./stowry serve

Command-Line Flags

Global flags available for all commands:

--config string         Config file path (default "config.yaml")
--db-type string        Database type (sqlite, postgres)
--db-dsn string         Database connection string
--db-table string       Database table name
--storage-path string   Storage directory path

Example:

./stowry serve --config /etc/stowry/config.yaml --db-type postgres

Configuration Examples

Development (SQLite)

server:
  port: 5708
  mode: store

database:
  type: sqlite
  dsn: dev.db
  auto_migrate: true

storage:
  path: ./uploads

access:
  public_read: true
  public_write: true

log:
  level: debug

Production (PostgreSQL)

server:
  port: 5708
  mode: store

database:
  type: postgres
  dsn: postgres://stowry:${DB_PASSWORD}@db.example.com:5432/stowry?sslmode=require
  table: stowry_metadata
  auto_migrate: true  # Or run 'stowry init' manually before first start

storage:
  path: /var/lib/stowry/data

auth:
  region: us-east-1
  service: s3
  keys:
    - access_key: ${STOWRY_ACCESS_KEY}
      secret_key: ${STOWRY_SECRET_KEY}

access:
  public_read: false
  public_write: false

log:
  level: info

Static File Server

server:
  port: 80
  mode: static

database:
  type: sqlite
  dsn: metadata.db
  auto_migrate: true

storage:
  path: /var/www/html

access:
  public_read: true
  public_write: false

SPA Hosting

server:
  port: 3000
  mode: spa

database:
  type: sqlite
  dsn: app.db
  auto_migrate: true

storage:
  path: ./dist

access:
  public_read: true
  public_write: false