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: 15

Migration 15 renames the core reverse proxy platform service from caddy to smartproxy.

Reverse Proxy (April 2026 - SmartProxy Docker Service)

The reverse proxy uses SmartProxy running as a Docker Swarm service for production-grade reverse proxying with TLS termination and WebSocket handling.

Architecture:

• SmartProxy runs as Docker Swarm service (onebox-smartproxy) on the overlay network
• No host binary download required - uses code.foss.global/host.today/ht-docker-smartproxy:latest
• Routes are pushed dynamically via the SmartProxy admin API (host 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/smartproxy.ts - SmartProxyManager class for Docker service and Admin API
• ts/classes/reverseproxy.ts - Delegates to SmartProxyManager

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 SmartProxy route config
5. SmartProxy serves TLS with the loaded certificates (no volume mounts needed)

Docker Service Configuration:

• Service name: onebox-smartproxy
• Image: code.foss.global/host.today/ht-docker-smartproxy:latest
• Network: onebox-network (overlay, attachable)
• Startup: SmartProxy daemon admin API listens on container port 3000, published on host port 2019

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:

• ProxyLogReceiver remains the host-side access-log stream endpoint for proxy log integrations