serve.zone/onebox
3
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

ui rebuild

Browse Source
This commit is contained in:
Jürgen Kunz
2025-11-24 19:52:35 +00:00
parent c9beae93c8
commit 9aa6906ca5
73 changed files with 8514 additions and 4537 deletions
Download Patch File Download Diff File Expand all files Collapse all files

491
readme.md
View File

@@ -1,59 +1,88 @@
# @serve.zone/onebox
> Self-hosted container platform with automatic SSL and DNS - a mini Heroku for single servers
> 🚀 Self-hosted Docker Swarm platform with native reverse proxy, automatic SSL, and real-time WebSocket updates
**Onebox** is a single-executable tool that transforms any Linux server into a simple container hosting platform. Deploy Docker containers with automatic HTTPS, DNS configuration, and Nginx reverse proxy - all managed through a beautiful Angular web interface or powerful CLI.
**Onebox** transforms any Linux server into a powerful container hosting platform. Deploy Docker Swarm services with automatic HTTPS, DNS configuration, and a native Deno reverse proxy - all managed through a beautiful Angular web interface with real-time updates.
## Features
## Issue Reporting and Security
- 🐳 **Docker Container Management** - Deploy, start, stop, and manage containers
- 🌐 **Automatic Nginx Reverse Proxy** - Traffic routing with zero configuration
- 🔒 **Automatic SSL Certificates** - Let's Encrypt integration via SmartACME
- ☁️ **Cloudflare DNS Integration** - Automatic DNS record management
- 📊 **Metrics & Monitoring** - Historical CPU, memory, and network stats
- 📝 **Log Aggregation** - Centralized container logs
- 🎨 **Angular Web UI** - Modern, responsive interface
- 👥 **Multi-user Support** - Role-based access control
- 🔐 **Private Registry Support** - Use Docker Hub, Gitea, or custom registries
For reporting bugs, issues, or security vulnerabilities, please visit [community.foss.global/](https://community.foss.global/). This is the central community hub for all issue reporting. Developers who sign and comply with our contribution agreement and go through identification can also get a [code.foss.global/](https://code.foss.global/) account to submit Pull Requests directly.
## What Makes Onebox Different? 🎯
- **Native Deno Reverse Proxy** - Built from scratch in Deno (no Nginx required!), featuring HTTP/HTTPS servers with SNI support and bidirectional WebSocket proxying
- **Docker Swarm First** - All workloads run as Swarm services, not standalone containers, for built-in orchestration
- **Real-time Everything** - WebSocket-powered live updates for service status, logs, and metrics across all connected clients
- **Single Executable** - Compiles to a standalone binary - just run it, no dependencies
- **Private Registry Included** - Built-in Docker registry with auto-deploy on push
- **Zero Config SSL** - Automatic Let's Encrypt certificates with hot-reload
- **Cloudflare Integration** - Automatic DNS record management
- **Modern Stack** - Deno runtime + SQLite database + Angular 18 UI
## Features ✨
### Core Platform
- 🐳 **Docker Swarm Management** - Deploy, scale, and orchestrate services with Swarm mode
- 🌐 **Native Reverse Proxy** - Deno-based HTTP/HTTPS proxy with dynamic routing from database
- 🔒 **Automatic SSL Certificates** - Let's Encrypt integration with hot-reload and renewal monitoring
- ☁️ **Cloudflare DNS Integration** - Automatic DNS record creation and synchronization
- 📦 **Built-in Registry** - Private Docker registry with per-service tokens and auto-update
- 🔄 **Real-time WebSocket Updates** - Live service status, logs, and system events
### Monitoring & Management
- 📊 **Metrics Collection** - Historical CPU, memory, and network stats (every 60s)
- 📝 **Centralized Logging** - Container logs with retention policies
- 🎨 **Angular Web UI** - Modern, responsive interface with real-time updates
- 👥 **Multi-user Support** - Role-based access control (admin/user)
- 💾 **SQLite Database** - Embedded, zero-configuration storage
- 📦 **Single Executable** - No dependencies, no installation hassle
- 🔄 **Systemd Integration** - Run as a daemon with auto-restart
## Quick Start
### Developer Experience
- 🚀 **Auto-update on Push** - Push to registry and services update automatically
- 🔐 **Private Registry Support** - Use Docker Hub, Gitea, or custom registries
- 🔄 **Systemd Integration** - Run as a daemon with auto-restart
- 🎛️ **Full CLI & API** - Manage everything from terminal or HTTP API
## Quick Start 🏁
### Installation
```bash
# Install via shell script
curl -sSL https://code.foss.global/serve.zone/onebox/raw/branch/main/install.sh | sudo bash
# Download the latest release for your platform
curl -sSL https://code.foss.global/serve.zone/onebox/releases/latest/download/onebox-linux-x64 -o onebox
chmod +x onebox
sudo mv onebox /usr/local/bin/
# Or via npm/pnpm
# Or install from npm
pnpm install -g @serve.zone/onebox
```
### Deploy Your First Service
### First Run
```bash
# Add a registry (optional, for private images)
onebox registry add --url registry.example.com --username myuser --password mypass
# Start the server in development mode
onebox server --ephemeral
# Deploy a service
# In another terminal, deploy your first service
onebox service add myapp \
--image nginx:latest \
--domain app.example.com \
--env PORT=80
# Check status
onebox service list
# View logs
onebox service logs myapp
--port 80
```
### Install as Daemon
### Access the Web UI
Open `http://localhost:3000` in your browser.
**Default credentials:**
- Username: `admin`
- Password: `admin`
⚠️ **Change the default password immediately after first login!**
### Production Setup
```bash
# Install systemd service
# Install as systemd service
sudo onebox daemon install
# Start the daemon
@@ -63,147 +92,395 @@ sudo onebox daemon start
sudo onebox daemon logs
```
### Access Web UI
## Architecture 🏗️
The web UI is available at `http://localhost:3000` (or configured port).
Onebox is built with modern technologies for performance and developer experience:
Default credentials:
- Username: `admin`
- Password: `admin` (change immediately!)
```
┌─────────────────────────────────────────────────┐
│ Angular 18 Web UI │
│ (Real-time WebSocket Updates) │
└─────────────────┬───────────────────────────────┘
│ HTTP/WS
┌─────────────────▼───────────────────────────────┐
│ Deno HTTP Server (Port 3000) │
│ REST API + WebSocket Broadcast │
└─────────────────┬───────────────────────────────┘
│
┌─────────────────▼───────────────────────────────┐
│ Native Reverse Proxy │
│ HTTP (80) + HTTPS (443) + SNI + WS Proxy │
└─────┬───────────────────────────────────────────┘
│
├──► Docker Swarm Services
├──► SSL Certificate Manager (Let's Encrypt)
├──► Cloudflare DNS Manager
├──► Built-in Docker Registry
└──► SQLite Database
```
## CLI Reference
### Core Components
- **Deno Runtime** - Modern TypeScript with built-in security
- **Native Reverse Proxy** - Custom HTTP/HTTPS proxy with TLS SNI support
- **Docker Swarm** - Container orchestration (NOT standalone containers)
- **SQLite Database** - Configuration, metrics, and user data
- **WebSocket Server** - Real-time bidirectional communication
- **Let's Encrypt** - Automatic SSL certificate management
- **Cloudflare API** - DNS record automation
## CLI Reference 📖
### Service Management
```bash
onebox service add <name> --image <image> --domain <domain> [--env KEY=VALUE]
onebox service remove <name>
# Deploy a service
onebox service add <name> --image <image> --domain <domain> [--port <port>] [--env KEY=VALUE]
# Deploy with Onebox Registry (auto-update on push)
onebox service add myapp --use-onebox-registry --domain myapp.example.com
# List services
onebox service list
# Control services
onebox service start <name>
onebox service stop <name>
onebox service restart <name>
onebox service list
onebox service logs <name> [--follow]
# Remove service
onebox service remove <name>
# View logs
onebox service logs <name>
```
### Server Management
```bash
# Start server (development)
onebox server --ephemeral # Runs in foreground with monitoring
# Start server (production)
onebox daemon install # Install systemd service
onebox daemon start # Start daemon
onebox daemon stop # Stop daemon
onebox daemon logs # View logs
```
### Registry Management
```bash
onebox registry add --url <url> --username <user> --password <pass>
onebox registry remove <url>
# Add external registry credentials
onebox registry add --url registry.example.com --username user --password pass
# List registries
onebox registry list
# Remove registry
onebox registry remove <url>
```
### DNS Management
```bash
onebox dns add <domain> --ip <ip>
onebox dns remove <domain>
# Add DNS record (requires Cloudflare config)
onebox dns add <domain>
# List DNS records
onebox dns list
# Sync from Cloudflare
onebox dns sync
# Remove DNS record
onebox dns remove <domain>
```
### SSL Management
```bash
onebox ssl renew [domain]
onebox ssl list
# Renew expiring certificates
onebox ssl renew
# Force renew specific domain
onebox ssl force-renew <domain>
```
### Nginx Management
```bash
onebox nginx reload
onebox nginx test
onebox nginx status
```
### Daemon Management
```bash
onebox daemon install
onebox daemon start
onebox daemon stop
onebox daemon restart
onebox daemon logs
```
### User Management
```bash
onebox user add <username> --password <password> [--role admin|user]
onebox user remove <username>
onebox user list
onebox user passwd <username>
# List certificates
onebox ssl list
```
### Configuration
```bash
# Show all settings
onebox config show
# Set configuration value
onebox config set <key> <value>
# Example: Configure Cloudflare
onebox config set cloudflareAPIKey your-api-key
onebox config set cloudflareEmail your@email.com
onebox config set cloudflareZoneID your-zone-id
```
### Metrics
### System Status
```bash
onebox metrics [service-name]
# Get full system status
onebox status
```
## Architecture
## Configuration 🔧
Onebox is built with Deno and compiles to a standalone binary for each platform:
### System Requirements
- **Deno Runtime** - Modern TypeScript with built-in security
- **SQLite** - Embedded database for configuration and metrics
- **Docker Engine** - Container runtime (required on host)
- **Nginx** - Reverse proxy and SSL termination
- **Cloudflare API** - DNS management
- **Let's Encrypt** - Free SSL certificates
- **Angular 18+** - Modern web interface
## Requirements
- **Linux** x64 or ARM64 (primary target)
- **Linux** (x64 or ARM64)
- **Docker** installed and running
- **Nginx** installed
- **Root/sudo access** (for nginx, Docker, ports 80/443)
- **(Optional) Cloudflare account** for DNS management
- **Docker Swarm** initialized (`docker swarm init`)
- **Root/sudo access** for ports 80/443
- **(Optional) Cloudflare account** for DNS automation
## Development
### Data Locations
- **Database**: `./onebox.db` (or custom path)
- **SSL Certificates**: Managed by CertManager
- **Registry Data**: `./.nogit/registry-data`
### Environment Variables
```bash
# Database location
ONEBOX_DB_PATH=/path/to/onebox.db
# HTTP server port (default: 3000)
ONEBOX_HTTP_PORT=3000
# Enable debug logging
ONEBOX_DEBUG=true
```
## Development 💻
### Setup
```bash
# Clone repository
git clone https://code.foss.global/serve.zone/onebox
cd onebox
# Run in development mode
# Install dependencies (Deno handles this automatically)
deno task dev
```
### Tasks
```bash
# Development server (auto-restart on changes)
deno task dev
# Run tests
deno task test
# Compile for all platforms
# Watch mode for tests
deno task test:watch
# Compile binaries for all platforms
deno task compile
```
## Configuration
### Project Structure
Onebox stores configuration in:
- **Database**: `/var/lib/onebox/onebox.db`
- **Nginx configs**: `/etc/nginx/sites-available/onebox-*`
- **SSL certificates**: `/etc/letsencrypt/live/`
```
onebox/
├── ts/
│ ├── classes/ # Core implementations
│ │ ├── onebox.ts # Main coordinator
│ │ ├── reverseproxy.ts # Native HTTP/HTTPS proxy
│ │ ├── docker.ts # Docker Swarm API
│ │ ├── database.ts # SQLite storage
│ │ ├── httpserver.ts # REST API + WebSocket
│ │ ├── services.ts # Service orchestration
│ │ ├── certmanager.ts # SSL certificate management
│ │ ├── registry.ts # Built-in Docker registry
│ │ └── ...
│ ├── cli.ts # CLI router
│ ├── types.ts # TypeScript interfaces
│ └── plugins.ts # Dependency imports
├── ui/ # Angular web interface
├── test/ # Test files
├── mod.ts # Main entry point
└── deno.json # Deno configuration
```
## Contributing
### API Endpoints
Contributions welcome! Please read the contributing guidelines first.
The HTTP server exposes the following endpoints:
## License
- `POST /api/auth/login` - User authentication (returns token)
- `GET /api/status` - System status (requires auth)
- `GET /api/services` - List all services (requires auth)
- `POST /api/services` - Create service (requires auth)
- `PUT /api/services/:id` - Update service (requires auth)
- `DELETE /api/services/:id` - Delete service (requires auth)
- `GET /api/ws` - WebSocket connection for real-time updates
MIT © Lossless GmbH
See `ts/classes/httpserver.ts` for complete API documentation.
## Links
### WebSocket Messages
- [Documentation](https://code.foss.global/serve.zone/onebox/src/branch/main/docs)
- [Issue Tracker](https://code.foss.global/serve.zone/onebox/issues)
- [Changelog](./changelog.md)
Real-time updates are broadcast via WebSocket:
```typescript
// Service lifecycle updates
{
type: 'service_update',
action: 'created' | 'updated' | 'deleted' | 'started' | 'stopped',
service: { id, name, status, ... }
}
// Service status changes
{
type: 'service_status',
service: { id, name, status, ... }
}
// System status updates
{
type: 'system_status',
status: { docker, reverseProxy, services, ... }
}
```
## Advanced Usage 🚀
### Using the Built-in Registry
```bash
# Deploy a service with Onebox Registry
onebox service add myapp \
--use-onebox-registry \
--domain myapp.example.com \
--auto-update-on-push
# Get the registry token for pushing images
# (Token is automatically created and stored in database)
# Push your image
docker tag myimage:latest localhost:4000/myapp:latest
docker push localhost:4000/myapp:latest
# Service automatically updates! 🎉
```
### Cloudflare DNS Integration
```bash
# Configure Cloudflare (one-time setup)
onebox config set cloudflareAPIKey your-api-key
onebox config set cloudflareEmail your@email.com
onebox config set cloudflareZoneID your-zone-id
# Deploy with automatic DNS
onebox service add myapp \
--image nginx:latest \
--domain myapp.example.com
# DNS record is automatically created!
```
### SSL Certificate Management
SSL certificates are automatically obtained and renewed:
- Certificates are requested when a service with a domain is deployed
- Renewal happens automatically 30 days before expiry
- Certificates are hot-reloaded without downtime
- Force renewal: `onebox ssl force-renew <domain>`
### Monitoring and Metrics
Metrics are collected every 60 seconds (configurable):
```bash
# Set metrics interval (milliseconds)
onebox config set metricsInterval 30000
# View in web UI or query database directly
sqlite3 onebox.db "SELECT * FROM metrics WHERE service_id = 1 ORDER BY timestamp DESC LIMIT 10"
```
## Troubleshooting 🔧
### Docker Swarm Not Initialized
```bash
# Initialize Docker Swarm
docker swarm init
# Verify swarm mode
docker info | grep "Swarm: active"
```
### Port Already in Use
```bash
# Check what's using port 80/443
sudo lsof -i :80
sudo lsof -i :443
# Kill the process or change Onebox ports
onebox config set httpPort 8080
```
### SSL Certificate Issues
```bash
# Check certificate status
onebox ssl list
# Verify DNS is pointing to your server
dig +short yourdomain.com
# Force certificate renewal
onebox ssl force-renew yourdomain.com
```
### WebSocket Connection Issues
- Ensure firewall allows WebSocket connections
- Check browser console for connection errors
- Verify `/api/ws` endpoint is accessible
### Service Not Starting
```bash
# Check Docker logs
docker service logs <service-name>
# Check Onebox logs
onebox daemon logs
# Verify image exists
docker images | grep <image-name>
```
## License and Legal Information
This repository contains open-source code that is licensed under the MIT License. A copy of the MIT License can be found in the [license](license) file within this repository.
**Please note:** The MIT License does not grant permission to use the trade names, trademarks, service marks, or product names of the project, except as required for reasonable and customary use in describing the origin of the work and reproducing the content of the NOTICE file.
### Trademarks
This project is owned and maintained by Task Venture Capital GmbH. The names and logos associated with Task Venture Capital GmbH and any related products or services are trademarks of Task Venture Capital GmbH and are not included within the scope of the MIT license granted herein. Use of these trademarks must comply with Task Venture Capital GmbH's Trademark Guidelines, and any usage must be approved in writing by Task Venture Capital GmbH.
### Company Information
Task Venture Capital GmbH
Registered at District court Bremen HRB 35230 HB, Germany
For any legal inquiries or if you require further information, please contact us via email at hello@task.vc.
By using this repository, you acknowledge that you have read this section, agree to comply with its terms, and understand that the licensing of the code does not imply endorsement by Task Venture Capital GmbH of any derivative works.