onebox/readme.md

# @serve.zone/onebox

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.

## 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.

## What Onebox Does

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.

- 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.

## Architecture

```text
browser / CLI
    |
    v
OpsServer :3000
  - 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
```

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

## Installation

Install the released binary:

```bash
curl -sSL https://code.foss.global/serve.zone/onebox/raw/branch/main/install.sh | sudo bash
```

For published wrapper builds, install with pnpm:

```bash
pnpm add --global @serve.zone/onebox
```

This repository currently marks the package as private; use the install script or a released wrapper package when available.

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
onebox server --ephemeral
```

Open the dashboard:

```text
http://localhost:3000
```

Default bootstrap credentials are created when no admin user exists:

```text
username: admin
password: admin
```

Change the default password immediately after first login.

Deploy a simple service:

```bash
onebox service add web --image nginx:latest --domain web.example.com --port 80
```

For production, install and run the systemd service:

```bash
sudo onebox systemd enable
sudo onebox systemd start
sudo onebox systemd logs
```

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
onebox <command> [options]
```

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
onebox config set serverIP 203.0.113.10
onebox config set acmeEmail ops@example.com
onebox config set cloudflareToken cf-token
onebox config set cloudflareZoneId zone-id
```

## 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
onebox appstore list
onebox appstore config cloudly
onebox appstore install cloudly --name cloudly --domain cloudly.example.com --env SERVEZONE_ADMINACCOUNT=admin:change-me
```

## 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
pnpm run watch
pnpm build
deno task test
deno task test:watch
deno task compile
```

Source map:

| Path | Purpose |
| --- | --- |
| `mod.ts` | Deno entry point. |
| `ts/cli.ts` | CLI router and command help. |
| `ts/classes/onebox.ts` | Main coordinator. |
| `ts/classes/docker.ts` | Docker client, networks, containers, and Swarm services. |
| `ts/classes/reverseproxy.ts` | SmartProxy route and certificate bridge. |
| `ts/classes/platform-services/` | Local platform service providers. |
| `ts/classes/appstore.ts` | Remote App Store catalog and upgrade logic. |
| `ts/classes/backup-manager.ts` | Backup and restore orchestration. |
| `ts/opsserver/` | Web UI server and TypedRequest handlers. |
| `ts/database/` | SQLite repositories and migrations. |
| `ts_web/` | Dashboard source. |

## License and Legal Information

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.

### 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 or third parties, 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 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.

### Company Information

Task Venture Capital GmbH\
Registered at District Court Bremen HRB 35230 HB, Germany

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.