From 193fcb37919d8a18822031f59e407556d909a0c6 Mon Sep 17 00:00:00 2001 From: kawa Date: Sun, 8 Mar 2026 17:24:33 +0100 Subject: [PATCH] Add a thorough description of the app in the readme --- README.md | 345 ++++++++++++++++++++++++++++++++++++++++++++++++++---- 1 file changed, 325 insertions(+), 20 deletions(-) diff --git a/README.md b/README.md index e215bc4..d2d2e50 100644 --- a/README.md +++ b/README.md @@ -1,36 +1,341 @@ -This is a [Next.js](https://nextjs.org) project bootstrapped with [`create-next-app`](https://nextjs.org/docs/app/api-reference/cli/create-next-app). +# CubeAdmin -## Getting Started +A production-ready Minecraft server administration panel built with Next.js, Bun, and SQLite. -First, run the development server: +## Features + +- **Real-time console** — stream server output and send commands via Socket.io +- **Server control** — start, stop, and restart your Minecraft server from the dashboard +- **Player management** — view online/offline players, ban/unban, manage the whitelist +- **Plugin management** — list, enable/disable, and upload plugins +- **File explorer** — browse, upload, download, and delete server files +- **Backup system** — create and restore backups on demand or on a schedule +- **Team management** — invite team members by email with role-based access control +- **World map** — embedded BlueMap 3D map integration +- **Server version management** — switch between Vanilla, Paper, and Fabric versions +- **Monitoring** — live CPU and memory charts +- **Task scheduler** — run RCON commands on a cron schedule +- **Audit log** — full record of all administrative actions +- **Dark/light theme** — persisted per user + +--- + +## Tech Stack + +| Layer | Technology | +|---|---| +| Runtime | [Bun](https://bun.sh) | +| Framework | [Next.js 16](https://nextjs.org) (App Router) | +| Database | SQLite via `bun:sqlite` + [Drizzle ORM](https://orm.drizzle.team) | +| Auth | [Better Auth v1.5](https://better-auth.com) | +| UI | [shadcn/ui v4](https://ui.shadcn.com) + [Base UI](https://base-ui.com) + Tailwind CSS v4 | +| Real-time | [Socket.io](https://socket.io) | +| Email | [Resend](https://resend.com) | + +--- + +## Quick Start (Development) + +### Prerequisites + +- [Bun](https://bun.sh) ≥ 1.1 +- A Minecraft server with RCON enabled (or use the provided `docker-compose.dev.yml`) + +### 1. Clone and install + +```bash +git clone https://github.com/your-org/cubeadmin.git +cd cubeadmin +bun install +``` + +### 2. Configure environment + +```bash +cp .env.example .env.local +``` + +Edit `.env.local` — at minimum you need: + +```env +BETTER_AUTH_SECRET=your-32-char-secret-here +MC_SERVER_PATH=/path/to/your/minecraft/server +MC_RCON_PASSWORD=your-rcon-password +``` + +### 3. Spin up a local Minecraft server (optional) + +```bash +docker compose -f docker-compose.dev.yml up -d +``` + +This starts a Paper Minecraft server with RCON exposed on port 25575. + +### 4. Run the development server ```bash -npm run dev -# or -yarn dev -# or -pnpm dev -# or bun dev ``` -Open [http://localhost:3000](http://localhost:3000) with your browser to see the result. +Open [http://localhost:3000](http://localhost:3000). The first account you register automatically becomes the administrator. -You can start editing the page by modifying `app/page.tsx`. The page auto-updates as you edit the file. +--- -This project uses [`next/font`](https://nextjs.org/docs/app/building-your-application/optimizing/fonts) to automatically optimize and load [Geist](https://vercel.com/font), a new font family for Vercel. +## Deployment -## Learn More +### Option A — Docker Compose (recommended) -To learn more about Next.js, take a look at the following resources: +This is the easiest way to run CubeAdmin and a Minecraft server together on a single host. -- [Next.js Documentation](https://nextjs.org/docs) - learn about Next.js features and API. -- [Learn Next.js](https://nextjs.org/learn) - an interactive Next.js tutorial. +#### 1. Create your environment file -You can check out [the Next.js GitHub repository](https://github.com/vercel/next.js) - your feedback and contributions are welcome! +```bash +cp .env.example .env +``` -## Deploy on Vercel +Fill in all required values (see [Environment Variables](#environment-variables) below). -The easiest way to deploy your Next.js app is to use the [Vercel Platform](https://vercel.com/new?utm_medium=default-template&filter=next.js&utm_source=create-next-app&utm_campaign=create-next-app-readme) from the creators of Next.js. +#### 2. Start the stack -Check out our [Next.js deployment documentation](https://nextjs.org/docs/app/building-your-application/deploying) for more details. +```bash +docker compose up -d +``` + +This starts three services: + +| Service | Description | Port | +|---|---|---| +| `cubeadmin` | The admin panel | 3000 | +| `minecraft` | Paper Minecraft server | 25565 | +| `bluemap` | 3D world map (optional) | 8100 | + +#### 3. Reverse proxy (recommended) + +Put Nginx or Caddy in front of CubeAdmin on port 3000. Example Caddyfile: + +``` +cubeadmin.example.com { + reverse_proxy localhost:3000 +} +``` + +> **Important:** Socket.io requires WebSocket support. Ensure your proxy forwards the `Upgrade` header. + +Nginx snippet: + +```nginx +location / { + proxy_pass http://localhost:3000; + proxy_http_version 1.1; + proxy_set_header Upgrade $http_upgrade; + proxy_set_header Connection "upgrade"; + proxy_set_header Host $host; + proxy_set_header X-Real-IP $remote_addr; + proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; + proxy_set_header X-Forwarded-Proto $scheme; +} +``` + +#### 4. First login + +Navigate to `https://your-domain.com` and register the first account — it is automatically granted the `superadmin` role. + +--- + +### Option B — Bare Metal (Bun) + +#### 1. Build + +```bash +bun install +bun run build +``` + +#### 2. Run + +```bash +NODE_ENV=production bun --bun run server.ts +``` + +The server binds to `0.0.0.0:3000` by default. Use `PORT` and `HOSTNAME` env vars to change this. + +#### 3. Run as a systemd service + +```ini +# /etc/systemd/system/cubeadmin.service +[Unit] +Description=CubeAdmin +After=network.target + +[Service] +Type=simple +User=cubeadmin +WorkingDirectory=/opt/cubeadmin +ExecStart=/usr/local/bin/bun --bun run server.ts +Restart=on-failure +RestartSec=5 +Environment=NODE_ENV=production +EnvironmentFile=/opt/cubeadmin/.env + +[Install] +WantedBy=multi-user.target +``` + +```bash +systemctl daemon-reload +systemctl enable --now cubeadmin +``` + +--- + +## Database Migrations + +CubeAdmin uses Drizzle ORM with a SQLite database. Migrations are applied automatically at startup via `lib/db/migrate.ts`. + +To generate a new migration after changing `lib/db/schema.ts`: + +```bash +bun run db:generate +``` + +> **Note:** `bun run db:migrate` (drizzle-kit) does not work with Bun's native `bun:sqlite` driver. Always apply migrations through the app startup migrator or manually with `bun:sqlite` scripts. + +To open the Drizzle Studio database browser: + +```bash +bun run db:studio +``` + +--- + +## Environment Variables + +### Authentication + +| Variable | Required | Default | Description | +|---|---|---|---| +| `BETTER_AUTH_SECRET` | **Yes** | — | Secret key used to sign sessions and tokens. Must be at least 32 characters. Generate one with `openssl rand -base64 32`. | +| `BETTER_AUTH_URL` | No | `http://localhost:3000` | The public base URL of the CubeAdmin app. Used by Better Auth to construct callback URLs. | +| `NEXT_PUBLIC_BETTER_AUTH_URL` | No | *(inferred from browser)* | Browser-side auth URL. Only needed if the public URL differs from what the browser can infer (e.g. behind a proxy). | +| `BETTER_AUTH_TRUSTED_ORIGINS` | No | `http://localhost:3000` | Comma-separated list of allowed origins for CORS and CSRF protection. Add your public domain in production. | + +### Email + +| Variable | Required | Default | Description | +|---|---|---|---| +| `RESEND_API_KEY` | No* | — | API key for [Resend](https://resend.com). Required for team invitation emails to work. The app starts without it, but invitations will fail silently. | +| `EMAIL_FROM` | No | `CubeAdmin ` | The sender address used for outgoing emails. Must be a verified address in your Resend account. | + +### Minecraft Server + +| Variable | Required | Default | Description | +|---|---|---|---| +| `MC_SERVER_PATH` | No | `/opt/minecraft/server` | Absolute path to the Minecraft server directory on the host. CubeAdmin reads/writes files here and spawns the server process from this directory. | +| `MC_RCON_HOST` | No | `127.0.0.1` | Hostname or IP where the Minecraft RCON interface is listening. Use `minecraft` when running the Docker Compose stack. | +| `MC_RCON_PORT` | No | `25575` | TCP port for the Minecraft RCON interface. Must match `rcon.port` in `server.properties`. | +| `MC_RCON_PASSWORD` | **Yes*** | — | Password for the Minecraft RCON interface. Must match `rcon.password` in `server.properties`. Required for player management, whitelist, and scheduler features. | + +*Only truly required if you want RCON-based features (player commands, scheduler). The app will start without it. + +### Database + +| Variable | Required | Default | Description | +|---|---|---|---| +| `DATABASE_PATH` | No | `./data/cubeadmin.db` | Path to the SQLite database file. The directory must exist and be writable. In Docker, this is mapped to a named volume. | + +### Server + +| Variable | Required | Default | Description | +|---|---|---|---| +| `PORT` | No | `3000` | TCP port the HTTP server listens on. | +| `HOSTNAME` | No | `0.0.0.0` | Hostname the HTTP server binds to. | +| `NODE_ENV` | No | `development` | Set to `production` for production deployments. Affects CSP headers, error verbosity, and Hot Module Replacement. | + +### Optional / Advanced + +| Variable | Required | Default | Description | +|---|---|---|---| +| `BLUEMAP_URL` | No | — | URL where BlueMap is accessible from the browser (e.g. `http://localhost:8100`). Enables the Map page. Configurable from the Server Settings UI as well. | +| `RATE_LIMIT_RPM` | No | `100` | Maximum number of API requests per minute per IP address. Applied to all `/api/*` routes by the middleware. | + +--- + +## Role System + +CubeAdmin has three roles: + +| Role | Description | +|---|---| +| `superadmin` | Full access — server control, settings, team management, everything. Automatically granted to the first registered user. | +| `admin` | Can manage players, plugins, files, backups, and the scheduler. Cannot change server settings or manage team roles. | +| `moderator` | Read-only access to most sections. Can send console commands and manage players. | + +Roles are assigned when inviting team members. The initial superadmin can promote/demote others from the Team page. + +--- + +## Project Structure + +``` +. +├── app/ +│ ├── (auth)/ # Login, register, accept-invite pages +│ ├── (dashboard)/ # All protected dashboard pages +│ │ ├── dashboard/ # Overview page (/) +│ │ ├── console/ # Real-time server console +│ │ ├── players/ # Player management +│ │ ├── plugins/ # Plugin management +│ │ ├── files/ # File explorer +│ │ ├── backups/ # Backup manager +│ │ ├── monitoring/ # CPU/RAM charts +│ │ ├── scheduler/ # Cron task scheduler +│ │ ├── team/ # Team & invitations +│ │ ├── audit/ # Audit log +│ │ ├── map/ # BlueMap integration +│ │ ├── server/ # Server settings +│ │ ├── updates/ # Version management +│ │ └── settings/ # Account settings +│ └── api/ # API routes +├── components/ +│ ├── layout/ # Sidebar, Topbar +│ └── ui/ # shadcn/ui components +├── lib/ +│ ├── auth/ # Better Auth config + client +│ ├── backup/ # Backup manager +│ ├── db/ # Drizzle schema + migrations +│ ├── email/ # Resend email client +│ ├── minecraft/ # Process manager, RCON, version fetcher +│ ├── security/ # Rate limiting +│ └── socket/ # Socket.io server setup +├── data/ # SQLite database (gitignored) +├── server.ts # Bun entry point (HTTP + Socket.io) +├── proxy.ts # Next.js middleware (auth guard + CSP) +├── docker-compose.yml # Production stack +└── docker-compose.dev.yml # Dev Minecraft server only +``` + +--- + +## Enabling RCON on Your Minecraft Server + +Add these lines to your `server.properties`: + +```properties +enable-rcon=true +rcon.port=25575 +rcon.password=your-strong-password +broadcast-rcon-to-ops=false +``` + +Restart the Minecraft server after editing `server.properties`. + +--- + +## Security Notes + +- **Change the default `BETTER_AUTH_SECRET`** before going to production. A leaked secret allows anyone to forge session tokens. +- **Use a strong RCON password.** RCON has full server control — never expose RCON port 25575 to the public internet. +- **HTTPS in production.** Better Auth cookies are `Secure` in production; the app will not authenticate over plain HTTP. +- **`BETTER_AUTH_TRUSTED_ORIGINS`** — add your production domain to prevent CSRF attacks from other origins. +- The middleware (`proxy.ts`) enforces a strict Content Security Policy with per-request nonces. No inline scripts are permitted. +- All API routes are rate-limited to 100 requests/minute per IP by default.