onebox/readme.hints.md

Onebox Project Hints

SSL Certificate Storage (November 2025)

SSL certificates are now stored directly in the SQLite database as PEM content instead of file paths:

• ISslCertificate and ICertificate interfaces use certPem, keyPem, fullchainPem properties
• Database migration 8 converted the certificates table schema
• No filesystem storage for certificates - everything in DB
• reverseproxy.ts reads certificate PEM content from database
• certmanager.ts stores SmartACME certificates directly to database

Architecture Notes

Database Layer (November 2025 Refactoring)

The database layer has been refactored into a repository pattern:

Directory Structure:

ts/database/
├── index.ts              # Main OneboxDatabase class (composes repositories, handles migrations)
├── types.ts              # Shared types (TBindValue, TQueryFunction)
├── base.repository.ts    # Base repository class
└── repositories/
    ├── index.ts          # Repository exports
    ├── service.repository.ts      # Services CRUD
    ├── registry.repository.ts     # Registries + Registry Tokens
    ├── certificate.repository.ts  # Domains, Certificates, Cert Requirements, SSL Certificates (legacy)
    ├── auth.repository.ts         # Users, Settings
    ├── metrics.repository.ts      # Metrics, Logs
    └── platform.repository.ts     # Platform Services, Platform Resources

Import paths:

• Main: import { OneboxDatabase } from './database/index.ts'
• Legacy (deprecated): import { OneboxDatabase } from './classes/database.ts' (re-exports from new location)

API Compatibility:

• The OneboxDatabase class maintains the same public API
• All methods delegate to the appropriate repository
• No breaking changes for existing code

Current Migration Version: 8

Migration 8 converted certificate storage from file paths to PEM content.

Reverse Proxy (November 2025 - Caddy Docker Service)

The reverse proxy uses Caddy running as a Docker Swarm service for production-grade reverse proxying with native SNI support, HTTP/2, HTTP/3, and WebSocket handling.

Architecture:

• Caddy runs as Docker Swarm service (onebox-caddy) on the overlay network
• No binary download required - uses caddy:2-alpine Docker image
• Configuration pushed dynamically via Caddy Admin API (port 2019)
• Automatic HTTPS disabled - certificates managed externally via SmartACME
• Zero-downtime configuration updates
• Services reached by Docker service name (e.g., onebox-hello-world:80)

Key files:

• ts/classes/caddy.ts - CaddyManager class for Docker service and Admin API
• ts/classes/reverseproxy.ts - Delegates to CaddyManager

Certificate workflow:

1. CertRequirementManager creates requirements for domains
2. Daemon processes requirements via certmanager.ts
3. Certificates stored in database (PEM content)
4. reverseProxy.addCertificate() passes PEM content to Caddy via load_pem (inline in config)
5. Caddy serves TLS with the loaded certificates (no volume mounts needed)

Docker Service Configuration:

• Service name: onebox-caddy
• Image: caddy:2-alpine
• Network: onebox-network (overlay, attachable)
• Startup: Writes initial config with admin.listen: 0.0.0.0:2019 for host access

Port Mapping:

• Dev mode: HTTP on 8080, HTTPS on 8443, Admin on 2019
• Production: HTTP on 80, HTTPS on 443, Admin on 2019
• All ports use PublishMode: 'host' for direct binding

Log Receiver:

• Caddy sends access logs to tcp/172.17.0.1:9999 (Docker bridge gateway)
• CaddyLogReceiver on host receives and processes logs