Initial commit: Onebox v1.0.0
- Complete Deno-based architecture following nupst/spark patterns - SQLite database with full schema - Docker container management - Service orchestration (Docker + Nginx + DNS + SSL) - Registry authentication - Nginx reverse proxy configuration - Cloudflare DNS integration - Let's Encrypt SSL automation - Background daemon with metrics collection - HTTP API server - Comprehensive CLI - Cross-platform compilation setup - NPM distribution wrapper - Shell installer script Core features: - Deploy containers with single command - Automatic domain configuration - Automatic SSL certificates - Multi-registry support - Metrics and logging - Systemd integration Ready for Angular UI implementation and testing.
This commit is contained in:
253
readme.hints.md
Normal file
253
readme.hints.md
Normal file
@@ -0,0 +1,253 @@
|
||||
# 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
|
||||
Reference in New Issue
Block a user