Documentation: Update Example Configurations for AWS SDK v2

[corylanou]

Documentation: Update Example Configurations for AWS SDK v2

Overview

With the AWS SDK v2 upgrade and new configuration options, we need to update all example configuration files to showcase the new capabilities and best practices.

Problem

Current example configurations don't demonstrate:

• New multipart upload configuration options
• S3-compatible service configurations
• Performance tuning options
• Various authentication methods
• Best practices for different use cases

Files to Update

1. etc/litestream.yml - Main example configuration
2. Documentation examples on litestream.io
3. README.md examples
4. Docker example configurations

Proposed Updates

1. Update etc/litestream.yml

# Litestream configuration file
#
# This file demonstrates various configuration options available
# after the AWS SDK v2 upgrade.

# Single database replication to S3
dbs:
  - path: /var/lib/myapp/db.sqlite
    replicas:
      - type: s3
        bucket: my-app-backups
        path: db
        region: us-east-1
        
        # AWS SDK v2 Performance Options (optional)
        # part-size: 10MB        # Size of multipart upload parts (min: 5MB)
        # concurrency: 5         # Number of parallel uploads
        # http-timeout: 6h      # Total operation timeout
        
        # Retention (optional)
        retention: 24h
        retention-check-interval: 1h
        
        # Sync interval
        sync-interval: 10s

# Multiple database configuration with different strategies
# dbs:
#   # High-frequency updates, small database
#   - path: /data/cache.db
#     replicas:
#       - type: s3
#         bucket: backups
#         path: cache
#         region: us-west-2
#         sync-interval: 1s      # Frequent syncs
#         # Small database, use defaults for multipart settings
#
#   # Large database, infrequent updates  
#   - path: /data/analytics.db
#     replicas:
#       - type: s3
#         bucket: backups
#         path: analytics
#         region: us-west-2
#         sync-interval: 1h      # Less frequent syncs
#         part-size: 50MB        # Larger parts for efficiency
#         concurrency: 20        # High parallelism
#         http-timeout: 24h     # Long timeout for large uploads

# Monitoring (optional)
# prometheus:
#   url: http://localhost:9090
#   job: litestream

2. S3-Compatible Services Examples

Create etc/examples/s3-compatible.yml:

# Examples for S3-compatible storage services

# MinIO (self-hosted)
dbs:
  - path: /data/app.db
    replicas:
      - type: s3
        endpoint: https://minio.mycompany.com
        bucket: litestream-backups
        path: app-db
        access-key-id: ${MINIO_ACCESS_KEY}
        secret-access-key: ${MINIO_SECRET_KEY}
        force-path-style: true  # Required for MinIO

# Wasabi Cloud Storage
# dbs:
#   - path: /data/app.db
#     replicas:
#       - type: s3
#         endpoint: https://s3.wasabisys.com
#         bucket: my-wasabi-bucket
#         path: backups/app-db
#         region: us-east-1
#         access-key-id: ${WASABI_ACCESS_KEY}
#         secret-access-key: ${WASABI_SECRET_KEY}

# Backblaze B2
# dbs:
#   - path: /data/app.db
#     replicas:
#       - type: s3
#         endpoint: https://s3.us-west-002.backblazeb2.com
#         bucket: my-b2-bucket
#         path: litestream/app-db
#         region: us-west-002
#         access-key-id: ${B2_KEY_ID}
#         secret-access-key: ${B2_APPLICATION_KEY}

# DigitalOcean Spaces
# dbs:
#   - path: /data/app.db
#     replicas:
#       - type: s3
#         endpoint: https://nyc3.digitaloceanspaces.com
#         bucket: my-space
#         path: backups/app-db
#         region: nyc3
#         access-key-id: ${DO_SPACES_KEY}
#         secret-access-key: ${DO_SPACES_SECRET}

3. Performance Tuning Examples

Create etc/examples/performance-tuning.yml:

# Performance tuning examples for different scenarios

# Small database (<100MB) - Use defaults
dbs:
  - path: /data/small.db
    replicas:
      - type: s3
        bucket: backups
        path: small-db
        region: us-east-1
        # Defaults work well for small databases:
        # part-size: 5MB (default)
        # concurrency: 5 (default)

---
# Medium database (100MB - 1GB) - Balanced settings
dbs:
  - path: /data/medium.db
    replicas:
      - type: s3
        bucket: backups
        path: medium-db
        region: us-east-1
        part-size: 10MB      # Reduce number of parts
        concurrency: 5       # Moderate parallelism
        sync-interval: 30s   # Less frequent syncs

---
# Large database (1GB - 10GB) - Optimized for throughput
dbs:
  - path: /data/large.db
    replicas:
      - type: s3
        bucket: backups
        path: large-db
        region: us-east-1
        part-size: 20MB      # Larger parts
        concurrency: 10      # Higher parallelism
        http-timeout: 6h    # Longer timeout
        sync-interval: 5m    # Less frequent syncs

---
# Very large database (>10GB) - Maximum throughput
dbs:
  - path: /data/huge.db
    replicas:
      - type: s3
        bucket: backups
        path: huge-db
        region: us-east-1
        part-size: 50MB      # Large parts
        concurrency: 20      # Maximum parallelism
        http-timeout: 24h   # Very long timeout
        sync-interval: 1h    # Infrequent syncs

---
# Memory-constrained environment (container/VM)
dbs:
  - path: /data/app.db
    replicas:
      - type: s3
        bucket: backups
        path: app-db
        region: us-east-1
        part-size: 5MB       # Minimum size
        concurrency: 2       # Low parallelism
        # Total memory: ~10MB during uploads

---
# High-latency network (cross-region/continent)
dbs:
  - path: /data/app.db
    replicas:
      - type: s3
        bucket: backups
        path: app-db
        region: ap-southeast-1
        part-size: 20MB      # Fewer round trips
        concurrency: 10      # Overlap latency
        http-timeout: 12h   # Account for latency

4. Authentication Examples

Create etc/examples/authentication.yml:

# Various authentication methods for S3

# 1. Explicit credentials (not recommended for production)
dbs:
  - path: /data/app.db
    replicas:
      - type: s3
        bucket: my-bucket
        path: app-db
        region: us-east-1
        access-key-id: AKIAIOSFODNN7EXAMPLE
        secret-access-key: wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY

---
# 2. Environment variables (recommended)
# Set these environment variables:
# AWS_ACCESS_KEY_ID=AKIAIOSFODNN7EXAMPLE
# AWS_SECRET_ACCESS_KEY=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
# AWS_REGION=us-east-1
dbs:
  - path: /data/app.db
    replicas:
      - type: s3
        bucket: my-bucket
        path: app-db
        # Credentials loaded from environment

---
# 3. IAM Role (EC2/ECS/Lambda)
# No credentials needed when running on AWS infrastructure
dbs:
  - path: /data/app.db
    replicas:
      - type: s3
        bucket: my-bucket
        path: app-db
        region: us-east-1
        # IAM role credentials used automatically

---
# 4. Shared credentials file
# Uses ~/.aws/credentials and ~/.aws/config
dbs:
  - path: /data/app.db
    replicas:
      - type: s3
        bucket: my-bucket
        path: app-db
        # Credentials loaded from AWS config files

---
# 5. With encryption (age)
dbs:
  - path: /data/secure.db
    replicas:
      - type: s3
        bucket: encrypted-backups
        path: secure-db
        region: us-east-1
        age-public-keys:
          - age1ql3z7hjy54pw3hyww5ayyfg7zqgvc7w3j2elw8zmrj2kg5sfn9aqmcac8p

5. Docker Compose Example

Create etc/examples/docker-compose.yml:

version: '3.8'

services:
  app:
    image: myapp:latest
    volumes:
      - db-data:/data
    environment:
      - DATABASE_PATH=/data/app.db

  litestream:
    image: litestream/litestream:latest
    command: replicate
    volumes:
      - db-data:/data
      - ./litestream.yml:/etc/litestream.yml
    environment:
      # AWS credentials (or use IAM role on AWS)
      - AWS_ACCESS_KEY_ID=${AWS_ACCESS_KEY_ID}
      - AWS_SECRET_ACCESS_KEY=${AWS_SECRET_ACCESS_KEY}
      - AWS_REGION=us-east-1
    
    # Litestream configuration
    configs:
      - source: litestream_config
        target: /etc/litestream.yml

volumes:
  db-data:

configs:
  litestream_config:
    content: |
      dbs:
        - path: /data/app.db
          replicas:
            - type: s3
              bucket: my-app-backups
              path: docker-db
              region: us-east-1
              # Performance tuning for container environment
              part-size: 10MB
              concurrency: 3
              sync-interval: 30s

6. Kubernetes ConfigMap Example

Create etc/examples/kubernetes-configmap.yml:

apiVersion: v1
kind: ConfigMap
metadata:
  name: litestream-config
  namespace: default
data:
  litestream.yml: |
    dbs:
      - path: /data/app.db
        replicas:
          - type: s3
            bucket: k8s-app-backups
            path: app-db
            region: us-east-1
            # Use IAM role for service account (IRSA) on EKS
            # No credentials needed
            
            # Performance settings for pod environment
            part-size: 10MB
            concurrency: 5
            http-timeout: 6h
            
            # Retention
            retention: 7d
            retention-check-interval: 1h
            
            # Sync settings
            sync-interval: 10s
            
    # Prometheus monitoring
    prometheus:
      url: http://prometheus:9090
      job: litestream

7. Update README.md Examples

## Quick Start

### Basic S3 Configuration

```yaml
dbs:
  - path: /path/to/db.sqlite
    replicas:
      - type: s3
        bucket: my-bucket
        path: db
        region: us-east-1

With Performance Tuning (New in v0.4.0)

dbs:
  - path: /path/to/large-db.sqlite
    replicas:
      - type: s3
        bucket: my-bucket
        path: db
        region: us-east-1
        part-size: 20MB      # Optimize for large files
        concurrency: 10      # Increase parallelism

S3-Compatible Services

# MinIO example
dbs:
  - path: /path/to/db.sqlite
    replicas:
      - type: s3
        endpoint: https://minio.example.com
        bucket: backups
        path: db
        force-path-style: true

### Implementation Steps

1. Update `etc/litestream.yml` with new options and comments
2. Create example files in `etc/examples/` directory
3. Update README.md with v0.4.0 examples
4. Test all example configurations
5. Add examples to documentation website
6. Create migration guide from old to new configurations

### Testing Requirements

- Validate all YAML files for syntax
- Test each configuration with actual Litestream binary
- Verify environment variable substitution works
- Test with various S3 and S3-compatible services
- Ensure examples work in Docker and Kubernetes

### Priority
Medium - Important for user adoption of new features

### Labels
- documentation
- examples
- configuration
- s3

[corylanou]

Additional Example: NATS JetStream Object Store Configuration

With the NATS replica client being added in PR #712, here's an example configuration for NATS JetStream Object Store:

# Example Litestream configuration file with NATS JetStream Object Store replica
#
# This configuration demonstrates how to use NATS JetStream Object Store as a
# replication destination for Litestream.
#
# NATS JetStream Object Store provides distributed, persistent object storage
# with features like:
# - Automatic chunking for large objects
# - Configurable replication and storage types
# - Built-in deduplication and compression
# - Multi-tenancy and security

# Database configuration
dbs:
  - path: /var/lib/db1.db
    replica:
      # NATS replica configuration
      type: nats

      # NATS server URL - can also be specified as "url: nats://server:port/bucket"
      url: nats://nats.example.com:4222

      # Object store bucket name (required)
      # IMPORTANT: Bucket must be pre-created using NATS CLI or API
      # Example: nats object add litestream-backups --max-bucket-size=10G --replicas=3
      bucket: litestream-backups

      # Authentication options (choose one method)

      # JWT authentication (recommended for production)
      jwt: /path/to/user.jwt
      seed: /path/to/user.nk

      # Or credentials file
      # creds: /path/to/user.creds

      # Or NKey authentication
      # nkey: /path/to/user.nk

      # Or username/password (not recommended for production)
      # username: myuser
      # password: mypassword

      # Or token authentication
      # token: mytoken

      # TLS configuration
      tls: true
      # root-cas:
      #   - /path/to/ca-cert.pem

      # Connection options (optional, defaults shown)
      max-reconnects: -1  # -1 for unlimited
      reconnect-wait: 2s
      timeout: 10s

      # Standard litestream replica options
      sync-interval: 1s

      # Age encryption (optional)
      age:
        identities:
          - /path/to/age-identity.txt
        recipients:
          - age1ql3z7hjy54pw3hyww5ayyfg7zqgvc7w3j2elw8zmrj2kg5sfn9aqmcac8p

# Multiple databases can be configured
  - path: /var/lib/db2.db
    replica:
      # Alternative URL format that includes bucket name
      url: nats://nats.example.com:4222/myapp-backups
      creds: /path/to/user.creds

Key Points for NATS Configuration:

1. Bucket must be pre-created - Unlike some other storage backends, NATS buckets need to be created beforehand using the NATS CLI
2. Multiple authentication methods - Supports JWT, credentials file, NKey, username/password, and token auth
3. JetStream must be enabled - The NATS server must have JetStream enabled ()
4. Object Store features - Automatic chunking for large files, configurable replication

This should be added to the examples once PR #712 is merged.

[corylanou]

Additional Documentation: NATS Testing Guide

Here's the testing guide for the NATS replica client that should be included in the documentation:

Testing NATS Replica Client

Prerequisites

1. Install NATS server (or use Docker):

# Using Docker
docker run -p 4222:4222 -p 8222:8222 nats:latest -js

# Or install locally
brew install nats-server  # macOS
# or download from https://github.com/nats-io/nats-server/releases

2. Install NATS CLI tools:

brew install nats-io/nats-tools/nats  # macOS
# or download from https://github.com/nats-io/natscli/releases

Manual Testing

1. Start NATS Server with JetStream

# Start NATS with JetStream enabled
nats-server -js

2. Create Object Store Bucket (Required)

The bucket must be pre-created before use:

# Create an object store bucket
nats object add litestream-backups --max-bucket-size=1G --replicas=3

3. Configure Litestream

Create a test configuration file (litestream-test.yml):

dbs:
  - path: /tmp/test.db
    replica:
      type: nats
      url: nats://localhost:4222
      bucket: litestream-backups
      # Optional: Use authentication
      # username: myuser
      # password: mypassword

4. Run Litestream

# Create a test database
sqlite3 /tmp/test.db "CREATE TABLE test (id INTEGER PRIMARY KEY, value TEXT);"
sqlite3 /tmp/test.db "INSERT INTO test (value) VALUES ('test data');"

# Run litestream with the test config
./litestream replicate -config litestream-test.yml

5. Verify Replication

# List objects in the bucket
nats object ls litestream-backups

# Get info about the bucket
nats object info litestream-backups

6. Test Restoration

# Stop litestream
# Delete the original database
rm /tmp/test.db

# Restore from NATS
./litestream restore -config litestream-test.yml /tmp/test.db

# Verify the data
sqlite3 /tmp/test.db "SELECT * FROM test;"

Integration Testing

Run the integration tests with a real NATS server:

# Start NATS server with JetStream
docker run -d -p 4222:4222 --name nats-test nats:latest -js

# Run integration tests
go test -v ./replica_client_test.go -integration nats

# Clean up
docker stop nats-test
docker rm nats-test

Authentication Testing

JWT/NKey Authentication

1. Generate credentials:

# Create an operator
nsc add operator TestOperator

# Create an account
nsc add account TestAccount

# Create a user
nsc add user TestUser

# Export the credentials
nsc generate creds -n TestUser > user.creds

2. Configure Litestream:

dbs:
  - path: /tmp/test.db
    replica:
      type: nats
      url: nats://localhost:4222
      bucket: litestream-backups
      creds: /path/to/user.creds

Username/Password Authentication

1. Create a NATS server config with auth:

# nats-auth.conf
jetstream: enabled
authorization {
  users = [
    {user: testuser, password: testpass}
  ]
}

2. Start NATS with config:

nats-server -c nats-auth.conf

3. Configure Litestream:

dbs:
  - path: /tmp/test.db
    replica:
      type: nats
      url: nats://localhost:4222
      bucket: litestream-backups
      username: testuser
      password: testpass

Performance Testing

For performance testing with larger databases:

# Create a larger test database
sqlite3 /tmp/large.db < large-dataset.sql

# Run litestream with metrics enabled
./litestream replicate -config litestream-test.yml -addr :9090

# Monitor metrics at http://localhost:9090/metrics

Troubleshooting

1. Connection Issues: Ensure NATS server is running and JetStream is enabled
2. Authentication Failures: Verify credentials and permissions
3. Bucket Issues: Check bucket exists and has sufficient space/replicas
4. Performance: Monitor NATS server metrics and adjust bucket configuration as needed

Important Notes

• The NATS replica client uses the LTX format for storing database snapshots and WAL segments
• Object Store provides automatic chunking for large files
• Bucket replication is handled by NATS JetStream, not Litestream
• TTL and retention should generally be managed by Litestream, not NATS bucket settings
• Buckets must be pre-created - the NATS replica client does not auto-create buckets

This documentation should be added to the main Litestream documentation once PR #712 is merged.