Apppublic

Ranger12/NebulaOS

sourceHugging Faceupdated 3mo agoView on Hugging Face

0likes

App README

Nebula 🌌

A production-grade, browser-based container management panel for self-hosted Ubuntu environments. Runs in a single Docker container with a dual-mode init:

—🟢 systemd as PID 1 when the container has --privileged + /sys/fs/cgroup. Tools that require systemd (x-ui, real .service units, journalctl, etc.) work fully.
—🟡 s6-overlay + systemctl shim when running unprivileged (Hugging Face Spaces, plain docker run). The shim translates systemctl start/stop/restart/status/enable/... calls so most tools that opportunistically use systemctl keep working. Tools that need a real D-Bus connection won't, but the panel itself is fully functional.

The entrypoint auto-detects the environment and picks the right init on every boot — you don't have to configure anything.

Open port 7860 and get:

—Real interactive terminal with persistent sessions (15-min reattach), tabs, search, zoom, copy/paste
—Services manager with live log tailing
—Files browser with inline editor + drag-and-drop upload
—Env vars with secrets masking
—Proxy rules to expose internal services on sub-paths (e.g. /n8n)
—Rich Monitor dashboard — per-core CPU, memory breakdown, swap, disk, network throughput
—Process list with kill action
—shadcn/ui design system, dark/light themes, 6 accent colors, Three.js animated background

Quick start (local Docker)

bash

docker build -t nebula .
docker run -d \
  --name nebula \
  --privileged \
  --tmpfs /tmp --tmpfs /run --tmpfs /run/lock \
  -v /sys/fs/cgroup:/sys/fs/cgroup:ro \
  -p 7860:7860 \
  -v nebula-data:/data \
  -v nebula-logs:/var/log/nebula \
  -e ADMIN_USERNAME=admin \
  -e ADMIN_PASSWORD=changeme \
  -e PUBLIC_URL=https://your.domain.com \
  nebula

Then visit <http://localhost:7860>. Default credentials: admin / admin (forced change on first login).

The --privileged flag and /sys/fs/cgroup mount are required for systemd to function correctly inside the container.

Hugging Face Spaces

Push this repo as a Docker Space. The frontmatter above declares sdk: docker and app_port: 7860. The container auto-detects the unprivileged Spaces sandbox and switches to s6-overlay automatically — no Space-side configuration required. systemctl calls from user-installed tools are intercepted by the shim.

Caveat: tools that need a working D-Bus + cgroup hierarchy (full systemd internals) won't work on HF Spaces. The panel itself, pm2, plain background processes, npm/pip installed binaries, and Docker CLI all work fine. For full systemd (x-ui's journalctl integration, real .service units with dependencies, etc.) use a VPS with --privileged.

Environment variables

Variable	Default	Description
`ADMIN_USERNAME`	`admin`	Login username
`ADMIN_PASSWORD`	`admin`	Login password (forced change on first login)
`JWT_SECRET`	auto-generated	JWT signing secret (set this for sessions to survive restart)
`BACKEND_PORT`	`3001`	Internal backend port
`DB_PATH`	`/data/nebula.db`	SQLite database path
`LOG_DIR`	`/var/log/nebula`	Service logs directory
`ROOT_FS_DIR`	`/home`	File manager root (cannot be `/`)
`PUBLIC_URL`	auto-detected	Override the URL shown in logs/UI. Otherwise inferred from `SPACE_HOST`/`SPACE_ID` (HF) or falls back to `localhost`.

Stack

Layer	Tech
Init	systemd (PID 1)
Base	`ubuntu:24.04`
Backend	Node.js 22, Express 5, Socket.IO 4, better-sqlite3, node-pty
Frontend	Next.js 15 (static export), React 19, TypeScript, Tailwind 3, shadcn/ui + Radix, Framer Motion, Three.js, GSAP, Recharts, xterm.js
Reverse proxy	nginx on :7860 → backend on :3001
Pre-installed CLIs	pm2, pnpm, yarn, typescript, ts-node, tsx, nodemon, serve, http-server, ncu, ipython, pipx, htop, btop, vim, nano, tree, jq, sqlite3, docker, nmap, ...

License

MIT