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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
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

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

### DNS Management

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

### SSL Management

```bash
onebox ssl renew [domain]
onebox ssl list
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>
```

### Configuration

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

### Metrics

```bash
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

```bash
# 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](https://code.foss.global/serve.zone/onebox/src/branch/main/docs)
- [Issue Tracker](https://code.foss.global/serve.zone/onebox/issues)
- [Changelog](./changelog.md)