111 lines
5.5 KiB
Markdown
111 lines
5.5 KiB
Markdown
# Minecraft 26.3 Fabric Server + CraftDeck Panel
|
||
|
||
For Orion, use the managed deployment in **homelab-infra**, described in [docs/orion.md](docs/orion.md). The root Compose file is the standalone LAN setup; it is not the TCPShield ingress configuration.
|
||
|
||
A production-quality, self-hosted Minecraft **Java 26.3** server for friends:
|
||
|
||
- **Fabric** loader with invisible server-side performance mods — any vanilla client
|
||
(including TLauncher) can join, no client mods needed
|
||
- **Offline mode + gated authentication**: only usernames *you* approve can join, each
|
||
must register a password within a short window, and log in on every visit
|
||
- **CraftDeck**, a full web management panel: live console, players & stats, lag
|
||
diagnostics, performance graphs, mod manager with Modrinth search, backups & restore,
|
||
file browser/editor, config editor, scheduled tasks, Discord alerts
|
||
- **Worlds & Network**: isolated concurrent server profiles, Velocity lobby routing,
|
||
Paper/Folia and modded runtimes, live map integrations, resource pack settings,
|
||
per-server consoles/files and verified backup/restore — [guide](docs/worlds-and-network.md)
|
||
- **Automatic backups** with retention, **one-command deployment**, everything in Docker
|
||
|
||
| | |
|
||
|---|---|
|
||
| Minecraft | `26.3` (review loader and all mod pins together) |
|
||
| Loader | Fabric (NeoForge/Forge/vanilla supported via config) |
|
||
| Server mods | Fabric API, EasyAuth, spark, Lithium, FerriteCore — auto-updated |
|
||
| Panel | Next.js, port `8080`, LAN/VPN only |
|
||
| Host needs | Linux x86_64, Docker + Compose, ~10 GB RAM |
|
||
|
||
---
|
||
|
||
## Quick start
|
||
|
||
```bash
|
||
git clone <this-repo> minecraft && cd minecraft
|
||
./scripts/setup.sh # creates .env with generated secrets, prints your panel login
|
||
docker compose up -d # first start downloads the server + mods (a few minutes)
|
||
```
|
||
|
||
Then open **http://\<server-ip\>:8080**, log in (`admin` / password printed by setup.sh),
|
||
change the password, and you're live:
|
||
|
||
- Minecraft: `<server-ip>:25565`
|
||
- Dashboard: `http://<server-ip>:8080`
|
||
|
||
> No `setup.sh`? Copy `.env.example` to `.env` and fill in `RCON_PASSWORD`,
|
||
> `PANEL_SESSION_SECRET`, `PANEL_ADMIN_PASSWORD` yourself.
|
||
|
||
## Letting a friend join (the auth flow)
|
||
|
||
1. Panel → **Access & Auth** → type their Minecraft username → **Approve & open window**
|
||
2. Tell them to join `<server-ip>:25565` **right away** (TLauncher: any username works,
|
||
but it must match the approved name exactly)
|
||
3. In game they run `/register <password> <password>` before the countdown ends
|
||
(default 2 minutes — configurable in Settings)
|
||
4. Done. On every future visit they just `/login <password>`
|
||
|
||
If the window lapses, the name is auto-removed from the whitelist — re-approve when
|
||
they're ready. Full details: [docs/auth-flow.md](docs/auth-flow.md).
|
||
|
||
## Everyday operations
|
||
|
||
| Task | Where |
|
||
|---|---|
|
||
| Start / stop / restart | Overview page (or `docker compose restart mc`) |
|
||
| Watch console, run commands | Console page |
|
||
| See who's lagging (them vs you) | Performance & Lag page |
|
||
| Add/remove mods | Mods page (Modrinth search built in) |
|
||
| Back up / restore | Backups page |
|
||
| Change version, memory, MOTD… | Configuration page → Save → Apply |
|
||
| Auto-restarts & scheduled backups | Schedules page |
|
||
| Discord alerts | Settings page |
|
||
|
||
## Documentation
|
||
|
||
- [docs/worlds-and-network.md](docs/worlds-and-network.md) — multiple servers, lobby routing, maps and resource packs
|
||
- [docs/apple-container.md](docs/apple-container.md) — native Mac tests and x86_64 image builds with Apple’s container CLI
|
||
|
||
- [docs/auth-flow.md](docs/auth-flow.md) — how the approval/registration system works
|
||
- [docs/mods-and-modpacks.md](docs/mods-and-modpacks.md) — adding mods, switching to modpacks or other loaders
|
||
- [docs/updating.md](docs/updating.md) — upgrading Minecraft, mods, and the panel
|
||
- [docs/backups-and-restore.md](docs/backups-and-restore.md) — backup schedule, restores, disaster recovery
|
||
- [docs/networking.md](docs/networking.md) — ports, firewall, Tailscale, why the panel stays off the internet
|
||
- [docs/troubleshooting.md](docs/troubleshooting.md) — common problems and fixes
|
||
|
||
## Architecture
|
||
|
||
```
|
||
docker-compose.yml
|
||
├── mc itzg/minecraft-server (Fabric 26.3, offline mode, whitelist enforced,
|
||
│ RCON on the internal network only, mods resolved from Modrinth at start)
|
||
├── backup itzg/mc-backup (scheduled world tars + retention pruning)
|
||
└── dashboard ./dashboard (CraftDeck: Next.js + node:sqlite; talks to the
|
||
Docker socket, RCON, and the server files)
|
||
data/
|
||
├── mc/ world, configs, mods, logs (bind mount → survives everything)
|
||
├── backups/ world-*.tgz
|
||
└── dashboard/ panel database
|
||
```
|
||
|
||
The panel's registration-window enforcement, activity feed, metrics sampler, and
|
||
scheduler run inside the dashboard container; state lives in `data/dashboard/` and the
|
||
`.env` file is the single source of truth for server configuration.
|
||
|
||
## Security model (read this once)
|
||
|
||
- The Minecraft port (25565) is the only thing that should ever be internet-exposed.
|
||
- `online-mode=false` means Mojang doesn't verify usernames — the whitelist + EasyAuth
|
||
passwords are what keep strangers out. Keep registration windows short.
|
||
- The dashboard can start/stop containers and edit server files (it mounts the Docker
|
||
socket), so treat it like root on the host: **LAN or VPN only, never port-forward
|
||
8080.** See [docs/networking.md](docs/networking.md) for the Tailscale setup.
|
||
- RCON is not published outside the Docker network.
|