Add a thorough description of the app in the readme
This commit is contained in:
345
README.md
345
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
|
```bash
|
||||||
npm run dev
|
|
||||||
# or
|
|
||||||
yarn dev
|
|
||||||
# or
|
|
||||||
pnpm dev
|
|
||||||
# or
|
|
||||||
bun dev
|
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.
|
#### 1. Create your environment file
|
||||||
- [Learn Next.js](https://nextjs.org/learn) - an interactive Next.js tutorial.
|
|
||||||
|
|
||||||
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 <noreply@example.com>` | 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.
|
||||||
|
|||||||
Reference in New Issue
Block a user