onebox/readme.md

@serve.zone/onebox

Self-hosted container platform with automatic SSL and DNS - a mini Heroku for single servers

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.

Features

• 🐳 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
• 💾 SQLite Database - Embedded, zero-configuration storage
• 📦 Single Executable - No dependencies, no installation hassle
• 🔄 Systemd Integration - Run as a daemon with auto-restart

Quick Start

Installation

# Install via shell script
curl -sSL https://code.foss.global/serve.zone/onebox/raw/branch/main/install.sh | sudo bash

# Or via npm/pnpm
pnpm install -g @serve.zone/onebox

Deploy Your First Service

# Add a registry (optional, for private images)
onebox registry add --url registry.example.com --username myuser --password mypass

# Deploy a 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

Install as Daemon

# Install systemd service
sudo onebox daemon install

# Start the daemon
sudo onebox daemon start

# View logs
sudo onebox daemon logs

Access Web UI

The web UI is available at http://localhost:3000 (or configured port).

Default credentials:

• Username: admin
• Password: admin (change immediately!)

CLI Reference

Service Management

onebox service add <name> --image <image> --domain <domain> [--env KEY=VALUE]
onebox service remove <name>
onebox service start <name>
onebox service stop <name>
onebox service restart <name>
onebox service list
onebox service logs <name> [--follow]

Registry Management

onebox registry add --url <url> --username <user> --password <pass>
onebox registry remove <url>
onebox registry list

DNS Management

onebox dns add <domain> --ip <ip>
onebox dns remove <domain>
onebox dns list
onebox dns sync

SSL Management

onebox ssl renew [domain]
onebox ssl list
onebox ssl force-renew <domain>

Nginx Management

onebox nginx reload
onebox nginx test
onebox nginx status

Daemon Management

onebox daemon install
onebox daemon start
onebox daemon stop
onebox daemon restart
onebox daemon logs

User Management

onebox user add <username> --password <password> [--role admin|user]
onebox user remove <username>
onebox user list
onebox user passwd <username>

Configuration

onebox config show
onebox config set <key> <value>

Metrics

onebox metrics [service-name]

Architecture

Onebox is built with Deno and compiles to a standalone binary for each platform:

• 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)
• Docker installed and running
• Nginx installed
• Root/sudo access (for nginx, Docker, ports 80/443)
• (Optional) Cloudflare account for DNS management

Development

# Clone repository
git clone https://code.foss.global/serve.zone/onebox
cd onebox

# Run in development mode
deno task dev

# Run tests
deno task test

# Compile for all platforms
deno task compile

Configuration

Onebox stores configuration in:

• Database: /var/lib/onebox/onebox.db
• Nginx configs: /etc/nginx/sites-available/onebox-*
• SSL certificates: /etc/letsencrypt/live/

Contributing

Contributions welcome! Please read the contributing guidelines first.

License

MIT © Lossless GmbH

Links

• Documentation
• Issue Tracker
• Changelog