docs: refresh readme and legal info
This commit is contained in:
+1
-1
@@ -26,7 +26,7 @@
|
|||||||
"paas",
|
"paas",
|
||||||
"deployment"
|
"deployment"
|
||||||
],
|
],
|
||||||
"author": "Lossless GmbH",
|
"author": "Task Venture Capital GmbH",
|
||||||
"license": "MIT",
|
"license": "MIT",
|
||||||
"repository": {
|
"repository": {
|
||||||
"type": "git",
|
"type": "git",
|
||||||
|
|||||||
@@ -1,506 +1,251 @@
|
|||||||
# @serve.zone/onebox
|
# @serve.zone/onebox
|
||||||
|
|
||||||
> 🚀 Self-hosted Docker Swarm platform with SmartProxy reverse proxy, automatic SSL, and real-time WebSocket updates
|
Onebox is a self-hosted application platform for a single server. It combines Docker, SmartProxy routing, a typed web control plane, app templates, platform services, and containerarchive-powered backups into one Deno-distributed binary.
|
||||||
|
|
||||||
**Onebox** transforms any Linux server into a powerful container hosting platform. Deploy Docker Swarm services with automatic HTTPS, DNS configuration, and SmartProxy reverse proxy running as a Docker service - all managed through a modern web interface with real-time updates.
|
|
||||||
|
|
||||||
## Issue Reporting and Security
|
## Issue Reporting and Security
|
||||||
|
|
||||||
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.
|
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? 🎯
|
## What Onebox Does
|
||||||
|
|
||||||
- **SmartProxy Reverse Proxy in Docker** - Production-grade HTTP/HTTPS proxy running as a Swarm service with native service discovery, TLS termination, and bidirectional WebSocket proxying
|
Onebox turns a Linux host into a small PaaS that can run your own containers and curated app templates without a separate control plane. It is designed for the "one good server" use case: one machine, one local Docker runtime, one web dashboard, one operational surface.
|
||||||
- **Docker Swarm First** - All workloads (including the reverse proxy!) run as Swarm services on the overlay network for seamless service-to-service communication
|
|
||||||
- **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 token-based auth and auto-deploy on push
|
|
||||||
- **Zero Config SSL** - Automatic Let's Encrypt certificates passed directly into SmartProxy routes
|
|
||||||
- **Cloudflare Integration** - Automatic DNS record management and zone synchronization
|
|
||||||
- **Modern Stack** - Deno runtime + SQLite database + typed web UI
|
|
||||||
|
|
||||||
## Features ✨
|
- Deploys Docker workloads from external images or Onebox App Store templates.
|
||||||
|
- Uses the local Docker socket and creates the `onebox-network` network automatically.
|
||||||
|
- Runs workloads as Docker Swarm services when Swarm is active, otherwise as standalone containers.
|
||||||
|
- Starts a SmartProxy-backed reverse proxy for HTTP/S routing and WebSocket traffic.
|
||||||
|
- Serves the web UI and TypedRequest/TypedSocket API through `OpsServer` on port `3000` by default.
|
||||||
|
- Stores platform state in SQLite.
|
||||||
|
- Can provision app dependencies through local platform providers: MongoDB, MinIO/S3, ClickHouse, MariaDB, and Redis.
|
||||||
|
- Tracks domains, Cloudflare DNS records, ACME certificates, service logs, metrics, backup schedules, and app template metadata.
|
||||||
|
- Can sync routes and import certificates from an external `dcrouter` gateway when configured.
|
||||||
|
|
||||||
### Core Platform
|
## Architecture
|
||||||
|
|
||||||
- 🐳 **Docker Swarm Management** - Deploy, scale, and orchestrate services with Swarm mode
|
```text
|
||||||
- 🌐 **SmartProxy Reverse Proxy** - Production-grade proxy running as Docker service with TLS termination and WebSocket support
|
browser / CLI
|
||||||
- 🔒 **Automatic SSL Certificates** - Let's Encrypt integration with hot-reload and renewal monitoring
|
|
|
||||||
- ☁️ **Cloudflare DNS Integration** - Automatic DNS record creation and zone synchronization
|
v
|
||||||
- 📦 **Built-in Registry** - Private Docker registry with per-service tokens and auto-update
|
OpsServer :3000
|
||||||
- 🔄 **Real-time WebSocket Updates** - Live service status, logs, and system events
|
- bundled web UI
|
||||||
|
- TypedRequest handlers
|
||||||
|
- TypedSocket dashboard events
|
||||||
|
|
|
||||||
|
v
|
||||||
|
Onebox coordinator
|
||||||
|
- SQLite repositories
|
||||||
|
- Docker manager
|
||||||
|
- SmartProxy route manager
|
||||||
|
- DNS and SSL managers
|
||||||
|
- platform service providers
|
||||||
|
- app store manager
|
||||||
|
- backup manager and scheduler
|
||||||
|
|
|
||||||
|
v
|
||||||
|
Docker host
|
||||||
|
- onebox-network
|
||||||
|
- SmartProxy
|
||||||
|
- user services
|
||||||
|
- optional platform services
|
||||||
|
```
|
||||||
|
|
||||||
### Monitoring & Management
|
`Onebox` is the central class. It initializes the database, Docker, SmartProxy, DNS, SSL, platform services, App Store, backup subsystem, optional external gateway integration, and the web/API server.
|
||||||
|
|
||||||
- 📊 **Metrics Collection** - Historical CPU, memory, and network stats (every 60s)
|
## Installation
|
||||||
- 📝 **Centralized Logging** - Container logs with streaming and retention policies
|
|
||||||
- 🎨 **Web UI** - Modern, responsive interface with real-time updates
|
|
||||||
- 👥 **Multi-user Support** - Role-based access control (admin/user)
|
|
||||||
- 💾 **SQLite Database** - Embedded, zero-configuration storage
|
|
||||||
|
|
||||||
### Developer Experience
|
Install the released binary:
|
||||||
|
|
||||||
- 🚀 **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** - Manage everything from terminal or web interface
|
|
||||||
|
|
||||||
## Quick Start 🏁
|
|
||||||
|
|
||||||
### Installation
|
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
# One-line install (recommended)
|
|
||||||
curl -sSL https://code.foss.global/serve.zone/onebox/raw/branch/main/install.sh | sudo bash
|
curl -sSL https://code.foss.global/serve.zone/onebox/raw/branch/main/install.sh | sudo bash
|
||||||
|
|
||||||
# Install a specific version
|
|
||||||
curl -sSL https://code.foss.global/serve.zone/onebox/raw/branch/main/install.sh | sudo bash -s -- --version v1.11.0
|
|
||||||
|
|
||||||
# Or install from npm
|
|
||||||
pnpm install -g @serve.zone/onebox
|
|
||||||
```
|
```
|
||||||
|
|
||||||
### First Run
|
Install through the npm package wrapper with pnpm:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
pnpm add --global @serve.zone/onebox
|
||||||
|
```
|
||||||
|
|
||||||
|
The package wrapper downloads the platform-specific binary during postinstall. Current release assets are named for Linux, macOS, and Windows on x64/ARM64 where available.
|
||||||
|
|
||||||
|
## Quick Start
|
||||||
|
|
||||||
|
Run a foreground development instance:
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
# Start the server in development mode
|
|
||||||
onebox server --ephemeral
|
onebox server --ephemeral
|
||||||
|
|
||||||
# In another terminal, deploy your first service
|
|
||||||
onebox service add myapp \
|
|
||||||
--image nginx:latest \
|
|
||||||
--domain app.example.com \
|
|
||||||
--port 80
|
|
||||||
```
|
```
|
||||||
|
|
||||||
### Access the Web UI
|
Open the dashboard:
|
||||||
|
|
||||||
Open `http://localhost:3000` in your browser.
|
```text
|
||||||
|
http://localhost:3000
|
||||||
|
```
|
||||||
|
|
||||||
**Default credentials:**
|
Default bootstrap credentials are created when no admin user exists:
|
||||||
|
|
||||||
- Username: `admin`
|
```text
|
||||||
- Password: `admin`
|
username: admin
|
||||||
|
password: admin
|
||||||
|
```
|
||||||
|
|
||||||
⚠️ **Change the default password immediately after first login!**
|
Change the default password immediately after first login.
|
||||||
|
|
||||||
### Production Setup
|
Deploy a simple service:
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
# Install as systemd service
|
onebox service add web --image nginx:latest --domain web.example.com --port 80
|
||||||
sudo onebox daemon install
|
|
||||||
|
|
||||||
# Start the daemon
|
|
||||||
sudo onebox daemon start
|
|
||||||
|
|
||||||
# View logs
|
|
||||||
sudo onebox daemon logs
|
|
||||||
```
|
```
|
||||||
|
|
||||||
## Architecture 🏗️
|
For production, install and run the systemd service:
|
||||||
|
|
||||||
Onebox is built with modern technologies for performance and developer experience:
|
|
||||||
|
|
||||||
```
|
|
||||||
┌─────────────────────────────────────────────────┐
|
|
||||||
│ Web UI │
|
|
||||||
│ (Real-time WebSocket Updates) │
|
|
||||||
└─────────────────┬───────────────────────────────┘
|
|
||||||
│ HTTP/WS
|
|
||||||
┌─────────────────▼───────────────────────────────┐
|
|
||||||
│ OpsServer (Port 3000) │
|
|
||||||
│ TypedRequest + TypedSocket │
|
|
||||||
└─────────────────┬───────────────────────────────┘
|
|
||||||
│
|
|
||||||
┌─────────────────▼───────────────────────────────┐
|
|
||||||
│ Docker Swarm │
|
|
||||||
│ ┌──────────────────────────────┐ │
|
|
||||||
│ │ onebox-network (overlay) │ │
|
|
||||||
│ ├──────────────────────────────┤ │
|
|
||||||
│ │ onebox-smartproxy (proxy) │ │
|
|
||||||
│ │ HTTP (80) + HTTPS (443) │ │
|
|
||||||
│ │ Admin API → config updates │ │
|
|
||||||
│ ├──────────────────────────────┤ │
|
|
||||||
│ │ Your Services │ │
|
|
||||||
│ │ (reachable by service name) │ │
|
|
||||||
│ └──────────────────────────────┘ │
|
|
||||||
└─────┬───────────────────────────────────────────┘
|
|
||||||
│
|
|
||||||
├──► SSL Certificate Manager (Let's Encrypt)
|
|
||||||
├──► Cloudflare DNS Manager
|
|
||||||
├──► Built-in Docker Registry
|
|
||||||
└──► SQLite Database
|
|
||||||
```
|
|
||||||
|
|
||||||
### Core Components
|
|
||||||
|
|
||||||
| Component | Description |
|
|
||||||
| ----------------------- | -------------------------------------------------------------------- |
|
|
||||||
| **Deno Runtime** | Modern TypeScript with built-in security |
|
|
||||||
| **SmartProxy Reverse Proxy** | Docker Swarm service with TLS termination and WebSocket support |
|
|
||||||
| **Docker Swarm** | Container orchestration (all workloads run as services) |
|
|
||||||
| **SQLite Database** | Configuration, metrics, and user data |
|
|
||||||
| **OpsServer** | TypedRequest API and TypedSocket real-time updates |
|
|
||||||
| **Let's Encrypt** | Automatic SSL certificate management |
|
|
||||||
| **Cloudflare API** | DNS record automation |
|
|
||||||
|
|
||||||
## CLI Reference 📖
|
|
||||||
|
|
||||||
### Service Management
|
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
# Deploy a service
|
sudo onebox systemd enable
|
||||||
onebox service add <name> --image <image> --domain <domain> [--port <port>] [--env KEY=VALUE]
|
sudo onebox systemd start
|
||||||
|
sudo onebox systemd logs
|
||||||
# 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>
|
|
||||||
|
|
||||||
# Remove service
|
|
||||||
onebox service remove <name>
|
|
||||||
|
|
||||||
# View logs
|
|
||||||
onebox service logs <name>
|
|
||||||
```
|
```
|
||||||
|
|
||||||
### Server Management
|
The systemd unit runs `onebox systemd start-daemon` with `/var/lib/onebox` as its working directory. From source or foreground runs, the default SQLite path is `./.nogit/onebox.db` relative to the current working directory.
|
||||||
|
|
||||||
|
## CLI Reference
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
# Start server (development)
|
onebox <command> [options]
|
||||||
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
|
Core commands:
|
||||||
|
|
||||||
|
| Command | Purpose |
|
||||||
|
| --- | --- |
|
||||||
|
| `server [--ephemeral] [--port <port>] [--monitor]` | Start the web/API server in the foreground. |
|
||||||
|
| `service add <name> --image <image> [--domain <domain>] [--port <port>] [--env KEY=VALUE]` | Deploy a workload. |
|
||||||
|
| `service list` | List known services. |
|
||||||
|
| `service start <name>` | Start a stopped service. |
|
||||||
|
| `service stop <name>` | Stop a running service. |
|
||||||
|
| `service restart <name>` | Restart a service. |
|
||||||
|
| `service remove <name>` | Remove a service and its route. |
|
||||||
|
| `service logs <name>` | Print Docker logs for a service. |
|
||||||
|
| `appstore list` | List remote app templates. |
|
||||||
|
| `appstore config <app-id> [--version <version>]` | Print app metadata and version config. |
|
||||||
|
| `appstore install <app-id> --name <name> [--domain <domain>] [--version <version>] [--env KEY=VALUE]` | Install an app template. |
|
||||||
|
| `registry add --url <url> --username <user> --password <pass>` | Store external registry credentials. |
|
||||||
|
| `registry remove --url <url>` | Remove registry credentials. |
|
||||||
|
| `registry list` | List configured registries. |
|
||||||
|
| `dns add <domain>` | Add a DNS record through the configured DNS manager. |
|
||||||
|
| `dns sync` | Sync Cloudflare domains into Onebox. |
|
||||||
|
| `ssl renew [domain]` | Renew one certificate or expiring certificates. |
|
||||||
|
| `ssl list` | List stored certificates. |
|
||||||
|
| `ssl force-renew <domain>` | Force certificate renewal for a domain. |
|
||||||
|
| `proxy reload` | Reload routes and certificates into SmartProxy. |
|
||||||
|
| `proxy test` | Check reverse proxy state. |
|
||||||
|
| `proxy status` | Print route/certificate counts and ports. |
|
||||||
|
| `systemd enable` | Install and enable the systemd unit. |
|
||||||
|
| `systemd disable` | Stop, disable, and remove the systemd unit. |
|
||||||
|
| `systemd start` | Start Onebox through systemd. |
|
||||||
|
| `systemd stop` | Stop Onebox through systemd. |
|
||||||
|
| `systemd status` | Show service status. |
|
||||||
|
| `systemd logs` | Follow `journalctl` logs. |
|
||||||
|
| `config show` | Show stored settings with secret values masked. |
|
||||||
|
| `config set <key> <value>` | Store a setting or supported secret setting. |
|
||||||
|
| `status` | Print JSON system status. |
|
||||||
|
| `upgrade` | Install the latest released binary. Requires root. |
|
||||||
|
|
||||||
|
The legacy `nginx` command name is still accepted as an alias for `proxy`, but SmartProxy is the active proxy backend.
|
||||||
|
|
||||||
|
## Configuration Notes
|
||||||
|
|
||||||
|
Useful settings include:
|
||||||
|
|
||||||
|
| Setting | Purpose |
|
||||||
|
| --- | --- |
|
||||||
|
| `serverIP` | IP address used for DNS records. |
|
||||||
|
| `cloudflareToken` | Cloudflare API token. `cloudflareAPIKey` is accepted as a legacy alias. |
|
||||||
|
| `cloudflareZoneId` | Cloudflare zone identifier. |
|
||||||
|
| `acmeEmail` | ACME account email for certificate issuance. |
|
||||||
|
| `httpPort` | OpsServer/web UI port. Defaults to `3000`. |
|
||||||
|
| `metricsInterval` | Metrics collection interval in milliseconds. |
|
||||||
|
| `backupPassword` | Secret passphrase for encrypted backup repositories. |
|
||||||
|
| `dcrouterGatewayUrl` | Optional external dcrouter API endpoint. |
|
||||||
|
| `dcrouterGatewayApiToken` | Optional external dcrouter API token. |
|
||||||
|
| `dcrouterWorkHosterId` | Optional work hoster identity used for route ownership. |
|
||||||
|
| `dcrouterTargetHost` | Optional target host advertised to dcrouter. |
|
||||||
|
| `dcrouterTargetPort` | Optional target port advertised to dcrouter. |
|
||||||
|
|
||||||
|
Example:
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
# Add external registry credentials
|
onebox config set serverIP 203.0.113.10
|
||||||
onebox registry add --url registry.example.com --username user --password pass
|
onebox config set acmeEmail ops@example.com
|
||||||
|
onebox config set cloudflareToken cf-token
|
||||||
# List registries
|
onebox config set cloudflareZoneId zone-id
|
||||||
onebox registry list
|
|
||||||
|
|
||||||
# Remove registry
|
|
||||||
onebox registry remove <url>
|
|
||||||
```
|
```
|
||||||
|
|
||||||
### DNS Management
|
## App Store
|
||||||
|
|
||||||
|
The App Store manager fetches catalog data from `serve.zone/appstore-apptemplates` and caches it briefly. Templates can declare platform requirements, so installing an app can automatically provision MongoDB, S3-compatible storage, ClickHouse, Redis, or MariaDB resources and inject the resulting credentials as environment variables.
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
# Add DNS record (requires Cloudflare config)
|
onebox appstore list
|
||||||
onebox dns add <domain>
|
onebox appstore config cloudly
|
||||||
|
onebox appstore install cloudly --name cloudly --domain cloudly.example.com --env SERVEZONE_ADMINACCOUNT=admin:change-me
|
||||||
# List DNS records
|
|
||||||
onebox dns list
|
|
||||||
|
|
||||||
# Sync from Cloudflare
|
|
||||||
onebox dns sync
|
|
||||||
|
|
||||||
# Remove DNS record
|
|
||||||
onebox dns remove <domain>
|
|
||||||
```
|
```
|
||||||
|
|
||||||
### SSL Management
|
## Backups
|
||||||
|
|
||||||
|
Backups are built around `@serve.zone/containerarchive`. Onebox exports service configuration, platform resource metadata, supported platform data, and optionally Docker images into a content-addressed archive repository. The code also keeps compatibility paths for older `.tar.enc` backup flows.
|
||||||
|
|
||||||
|
Backup and schedule operations are primarily exposed through the OpsServer/web UI handlers.
|
||||||
|
|
||||||
|
## Development
|
||||||
|
|
||||||
|
Requirements:
|
||||||
|
|
||||||
|
- Deno for the application runtime.
|
||||||
|
- pnpm for package scripts.
|
||||||
|
- Docker for any runtime path that initializes Onebox fully.
|
||||||
|
|
||||||
|
Common tasks:
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
# Renew expiring certificates
|
|
||||||
onebox ssl renew
|
|
||||||
|
|
||||||
# Force renew specific domain
|
|
||||||
onebox ssl force-renew <domain>
|
|
||||||
|
|
||||||
# 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 cloudflareToken your-api-token
|
|
||||||
onebox config set cloudflareZoneId your-zone-id
|
|
||||||
```
|
|
||||||
|
|
||||||
### System Status
|
|
||||||
|
|
||||||
```bash
|
|
||||||
# Get full system status
|
|
||||||
onebox status
|
|
||||||
```
|
|
||||||
|
|
||||||
### Upgrade
|
|
||||||
|
|
||||||
```bash
|
|
||||||
# Upgrade to the latest version (requires root)
|
|
||||||
sudo onebox upgrade
|
|
||||||
```
|
|
||||||
|
|
||||||
## Configuration 🔧
|
|
||||||
|
|
||||||
### System Requirements
|
|
||||||
|
|
||||||
- **Linux** (x64 or ARM64)
|
|
||||||
- **Docker** installed and running
|
|
||||||
- **Docker Swarm** initialized (`docker swarm init`)
|
|
||||||
- **Root/sudo access** for ports 80/443
|
|
||||||
- **(Optional) Cloudflare account** for DNS automation
|
|
||||||
|
|
||||||
### Data Locations
|
|
||||||
|
|
||||||
| Data | Location |
|
|
||||||
| -------------------- | ------------------------------ |
|
|
||||||
| **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
|
|
||||||
|
|
||||||
# Start development server (auto-restart on changes)
|
|
||||||
pnpm run watch
|
pnpm run watch
|
||||||
```
|
pnpm build
|
||||||
|
|
||||||
### Tasks
|
|
||||||
|
|
||||||
```bash
|
|
||||||
# Development server (auto-restart on changes)
|
|
||||||
deno task dev
|
|
||||||
|
|
||||||
# Run tests
|
|
||||||
deno task test
|
deno task test
|
||||||
|
|
||||||
# Watch mode for tests
|
|
||||||
deno task test:watch
|
deno task test:watch
|
||||||
|
|
||||||
# Compile binaries for all platforms
|
|
||||||
deno task compile
|
deno task compile
|
||||||
```
|
```
|
||||||
|
|
||||||
### Project Structure
|
Source map:
|
||||||
|
|
||||||
```
|
| Path | Purpose |
|
||||||
onebox/
|
| --- | --- |
|
||||||
├── ts/
|
| `mod.ts` | Deno entry point. |
|
||||||
│ ├── classes/ # Core implementations
|
| `ts/cli.ts` | CLI router and command help. |
|
||||||
│ │ ├── onebox.ts # Main coordinator
|
| `ts/classes/onebox.ts` | Main coordinator. |
|
||||||
│ │ ├── reverseproxy.ts # Reverse proxy orchestration
|
| `ts/classes/docker.ts` | Docker client, networks, containers, and Swarm services. |
|
||||||
│ │ ├── smartproxy.ts # SmartProxy Docker service management
|
| `ts/classes/reverseproxy.ts` | SmartProxy route and certificate bridge. |
|
||||||
│ │ ├── docker.ts # Docker Swarm API
|
| `ts/classes/platform-services/` | Local platform service providers. |
|
||||||
│ │ ├── services.ts # Service orchestration
|
| `ts/classes/appstore.ts` | Remote App Store catalog and upgrade logic. |
|
||||||
│ │ ├── certmanager.ts # SSL certificate management
|
| `ts/classes/backup-manager.ts` | Backup and restore orchestration. |
|
||||||
│ │ ├── cert-requirement-manager.ts # Certificate requirements
|
| `ts/opsserver/` | Web UI server and TypedRequest handlers. |
|
||||||
│ │ ├── ssl.ts # SSL utilities
|
| `ts/database/` | SQLite repositories and migrations. |
|
||||||
│ │ ├── registry.ts # Built-in Docker registry
|
| `ts_web/` | Dashboard source. |
|
||||||
│ │ ├── registries.ts # External registry management
|
|
||||||
│ │ ├── dns.ts # DNS record management
|
|
||||||
│ │ ├── cloudflare-sync.ts # Cloudflare zone sync
|
|
||||||
│ │ └── daemon.ts # Systemd daemon management
|
|
||||||
│ ├── opsserver/ # Active server implementation
|
|
||||||
│ │ ├── classes.opsserver.ts # TypedRequest + TypedSocket server
|
|
||||||
│ │ └── handlers/ # Typed request handlers
|
|
||||||
│ ├── database/ # Database layer (repository pattern)
|
|
||||||
│ │ ├── index.ts # Main OneboxDatabase class
|
|
||||||
│ │ ├── base.repository.ts # Base repository class
|
|
||||||
│ │ └── repositories/ # Domain-specific repositories
|
|
||||||
│ │ ├── service.repository.ts
|
|
||||||
│ │ ├── certificate.repository.ts
|
|
||||||
│ │ ├── auth.repository.ts
|
|
||||||
│ │ ├── metrics.repository.ts
|
|
||||||
│ │ └── ...
|
|
||||||
│ ├── cli.ts # CLI router
|
|
||||||
│ ├── types.ts # TypeScript interfaces
|
|
||||||
│ ├── logging.ts # Logging utilities
|
|
||||||
│ └── plugins.ts # Dependency imports
|
|
||||||
├── ts_web/ # Web interface source
|
|
||||||
├── test/ # Test files
|
|
||||||
├── mod.ts # Main entry point
|
|
||||||
└── deno.json # Deno configuration
|
|
||||||
```
|
|
||||||
|
|
||||||
### Active Server Surface
|
|
||||||
|
|
||||||
The active server surface is the `OpsServer`, which serves the bundled web UI and exposes typed operations via `TypedRequest` and real-time events via `TypedSocket`.
|
|
||||||
|
|
||||||
The previously documented legacy `/api/*` REST interface has been removed.
|
|
||||||
|
|
||||||
## 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! 🎉
|
|
||||||
```
|
|
||||||
|
|
||||||
### Registry Token Management
|
|
||||||
|
|
||||||
```bash
|
|
||||||
# Create a CI/CD token in the web UI, then use it for docker login
|
|
||||||
docker login localhost:4000 -u ci -p <token>
|
|
||||||
```
|
|
||||||
|
|
||||||
### Cloudflare DNS Integration
|
|
||||||
|
|
||||||
```bash
|
|
||||||
# Configure Cloudflare (one-time setup)
|
|
||||||
onebox config set cloudflareToken your-api-token
|
|
||||||
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!
|
|
||||||
|
|
||||||
# Sync all domains from Cloudflare
|
|
||||||
onebox dns sync
|
|
||||||
```
|
|
||||||
|
|
||||||
### 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 the dashboard socket connection is established
|
|
||||||
|
|
||||||
### 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
|
## 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.
|
This repository contains open-source code licensed under the MIT License. A copy of the license can be found in the [license](./license) file.
|
||||||
|
|
||||||
**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.
|
**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
|
### 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.
|
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 or third parties, and are not included within the scope of the MIT license granted herein.
|
||||||
|
|
||||||
### Issue Reporting and Security
|
Use of these trademarks must comply with Task Venture Capital GmbH's Trademark Guidelines or the guidelines of the respective third-party owners, and any usage must be approved in writing. Third-party trademarks used herein are the property of their respective owners and used only in a descriptive manner, e.g. for an implementation of an API or similar.
|
||||||
|
|
||||||
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.
|
|
||||||
|
|
||||||
### Company Information
|
### Company Information
|
||||||
|
|
||||||
Task Venture Capital GmbH
|
Task Venture Capital GmbH\
|
||||||
Registered at District court Bremen HRB 35230 HB, Germany
|
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.
|
For any legal inquiries or 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.
|
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.
|
||||||
|
|||||||
Reference in New Issue
Block a user