onebox/readme.hints.md

Onebox - Project Hints

Architecture Overview

Onebox is a Deno-based self-hosted container platform that compiles to standalone binaries. It follows the same architectural patterns as nupst and spark projects.

Core Components

1. OneboxDatabase (ts/onebox.classes.database.ts)

   • SQLite-based storage
   • Tables: services, registries, nginx_configs, ssl_certificates, dns_records, metrics, logs, users, settings
   • Migration system for schema updates

2. OneboxDockerManager (ts/onebox.classes.docker.ts)

   • Docker API integration via @apiclient.xyz/docker
   • Container lifecycle management
   • Network management (onebox-network bridge)
   • Stats collection and logging

3. OneboxServicesManager (ts/onebox.classes.services.ts)

   • High-level service orchestration
   • Coordinates Docker + Nginx + DNS + SSL
   • Service deployment workflow

4. OneboxRegistriesManager (ts/onebox.classes.registries.ts)

   • Docker registry authentication
   • Credential storage (encrypted)
   • Auto-login on daemon start

5. OneboxNginxManager (ts/onebox.classes.nginx.ts)

   • Nginx reverse proxy configuration
   • Config file generation
   • SSL enablement
   • Reload and testing

6. OneboxDnsManager (ts/onebox.classes.dns.ts)

   • Cloudflare API integration
   • Automatic A record creation
   • DNS sync and verification

7. OneboxSslManager (ts/onebox.classes.ssl.ts)

   • Let's Encrypt integration via certbot
   • Certificate issuance and renewal
   • Expiry monitoring

8. OneboxDaemon (ts/onebox.classes.daemon.ts)

   • Background monitoring loop
   • Metrics collection (every 60s by default)
   • SSL certificate renewal checks
   • Service health monitoring
   • Systemd integration

9. OneboxHttpServer (ts/onebox.classes.httpserver.ts)

   • REST API endpoints
   • Static file serving (for Angular UI)
   • Authentication middleware

10. Onebox (ts/onebox.classes.onebox.ts)

    • Main coordinator class
    • Initializes all components
    • Provides unified API

CLI Structure

• onebox service - Service management
• onebox registry - Registry credentials
• onebox dns - DNS records
• onebox ssl - SSL certificates
• onebox nginx - Nginx control
• onebox daemon - Systemd daemon
• onebox config - Settings management
• onebox status - System status

Deployment Workflow

1. User runs: onebox service add myapp --image nginx --domain app.example.com
2. Service record created in database
3. Docker image pulled from registry
4. Container created and started
5. Nginx config generated and reloaded
6. DNS record created (if configured)
7. SSL certificate obtained (if configured)
8. Service is live!

Configuration

Settings stored in database (settings table):

• cloudflareAPIKey - Cloudflare API key
• cloudflareEmail - Cloudflare email
• cloudflareZoneID - Cloudflare zone ID
• acmeEmail - Let's Encrypt email
• serverIP - Server public IP
• nginxConfigDir - Custom nginx config directory
• httpPort - HTTP server port (default: 3000)
• metricsInterval - Metrics collection interval (default: 60000ms)
• logRetentionDays - Log retention period

Data Locations

• Database: /var/lib/onebox/onebox.db
• Nginx configs: /etc/nginx/sites-available/onebox-*
• SSL certificates: /etc/letsencrypt/live/<domain>/
• Certbot webroot: /var/www/certbot

Development

Running Locally

# Development mode
deno task dev

# Run tests
deno task test

# Compile all binaries
deno task compile

Adding a New Feature

1. Create new class in ts/onebox.classes.<name>.ts
2. Add to main Onebox class in ts/onebox.classes.onebox.ts
3. Add CLI commands in ts/onebox.cli.ts
4. Add API endpoints in ts/onebox.classes.httpserver.ts
5. Update types in ts/onebox.types.ts
6. Add tests in test/
7. Update documentation

Database Migrations

Add migration logic in OneboxDatabase.runMigrations():

if (currentVersion === 1) {
  this.db.query('ALTER TABLE services ADD COLUMN new_field TEXT');
  this.setMigrationVersion(2);
}

TODO

Core Functionality (Complete ✓)

• Database layer with SQLite
• Docker integration
• Service management
• Registry authentication
• Nginx reverse proxy
• DNS management (Cloudflare)
• SSL certificates (Let's Encrypt)
• Background daemon
• HTTP API server
• CLI commands
• Build system

Next Steps

• Angular UI implementation
  • Dashboard with service cards
  • Service deployment form
  • Logs viewer
  • Metrics charts
  • Settings page
• Authentication system (JWT)
  • Login endpoint
  • Token validation middleware
  • Password hashing (bcrypt)
• WebSocket support for real-time logs/metrics
• Health checks for services
• Backup/restore functionality
• Multi-server support
• Load balancing
• Service templates/blueprints

Testing

• Unit tests for all managers
• Integration tests for deployment workflow
• Mock Docker API for tests
• Database migration tests

Documentation

• API documentation (OpenAPI/Swagger)
• Architecture diagram
• Deployment guide
• Troubleshooting guide
• Video tutorial

Common Issues

Docker Connection

If Docker commands fail, ensure:

• Docker daemon is running: systemctl status docker
• User has Docker permissions: usermod -aG docker $USER
• Socket exists: ls -l /var/run/docker.sock

Nginx Issues

If nginx fails to reload:

• Check syntax: onebox nginx test
• Check logs: journalctl -u nginx -n 50
• Verify config files exist in /etc/nginx/sites-available/

SSL Certificate Issues

If certbot fails:

• Verify domain DNS points to server
• Check port 80 is accessible
• Verify nginx is serving .well-known/acme-challenge/
• Check certbot logs: journalctl -u certbot -n 50

Cloudflare DNS Issues

If DNS records aren't created:

• Verify API credentials: onebox config show
• Check zone ID matches your domain
• Verify API key has DNS edit permissions

Dependencies

Deno Packages

• @std/path - Path utilities
• @std/fs - Filesystem operations
• @std/http - HTTP server
• @db/sqlite - SQLite database

NPM Packages (via Deno)

• @push.rocks/smartdaemon - Systemd integration
• @apiclient.xyz/docker - Docker API client
• @apiclient.xyz/cloudflare - Cloudflare API client
• @push.rocks/smartacme - ACME/Let's Encrypt

System Dependencies

• docker - Container runtime
• nginx - Reverse proxy
• certbot - SSL certificates
• systemd - Service management

Release Process

1. Update version in deno.json
2. Update changelog.md
3. Commit changes
4. Run deno task compile to build all binaries
5. Test binaries on each platform
6. Create git tag: git tag v1.0.0
7. Push tag: git push origin v1.0.0
8. Create Gitea release and upload binaries
9. Publish to npm: pnpm publish

Notes

• Onebox requires root privileges for nginx, Docker, and port binding
• Default admin password should be changed immediately after installation
• Use --debug flag for verbose logging
• All Docker containers are on the onebox-network bridge
• Metrics are collected every 60 seconds by default
• SSL certificates auto-renew 30 days before expiry