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

```bash
# 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()`:

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

## TODO

### Core Functionality (Complete ✓)
- [x] Database layer with SQLite
- [x] Docker integration
- [x] Service management
- [x] Registry authentication
- [x] Nginx reverse proxy
- [x] DNS management (Cloudflare)
- [x] SSL certificates (Let's Encrypt)
- [x] Background daemon
- [x] HTTP API server
- [x] CLI commands
- [x] 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