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