Homelab/minecraft_server
1
0
Fork 0
Code Issues 1 Pull Requests Actions Projects Activity

Update README.md
All checks were successful
Deploy / Deploy (push) Successful in 2m10s
Details

Browse Source
This commit is contained in:
Kappeh
2026-01-30 22:14:19 +00:00
parent 063e182f03
commit 78f3609594
1 changed files with 158 additions and 53 deletions
Download Patch File Download Diff File Expand all files Collapse all files

211
README.md
View File

@@ -1,83 +1,188 @@
# minecraft_server # minecraft_server
The configuration files for the Illegal Crime Minecraft server. This repository defines the configuration for a private, multi-server Minecraft network. The project is guided by a set of core principles:
## Usage - **Reproducible & Declarative:** The entire infrastructure is defined in code and version-controlled. This ensures that the network can be rebuilt, migrated, or mirrored with minimal friction, and changes can always be rolled back safely. Declarative configuration goes hand-in-hand with reproducibility, making disaster recovery and host migrations straightforward.
- **Automated & Low-Maintenance:** Routine maintenance is minimized through automation. Servers automatically restart after crashes, backups are handled programmatically, and deployments leverage CI/CD pipelines rather than manual intervention. This keeps the network reliable without requiring constant hands-on management.
- **Secure & Private:** Secrets are never stored in the repository and are carefully injected at runtime. Player data is kept private, and the network prioritizes security with SSL for web services, and adherence to best practices for storage and authentication.
- **Robust & Recoverable:** Backup and restore strategies are central to the design. All persistent data lives in managed volumes, and the system is prepared to recover from failures. Future improvements, like continuous restore verification, are anticipated and planned for.
- **Transparent:** Configuration and infrastructure are as openly documented as possible. Persistent data and secrets are excluded from public exposure, but the setup, services, and operational practices are visible and auditable.
Follow these steps to set up and configure the project: ## Stack Overview
1. **Clone the repository**: This repository defines a multi-server Minecraft network built around a Velocity proxy, with both Paper and Fabric backend servers, shared services, and supporting infrastructure. All components are orchestrated using Docker Compose and connected via a dedicated internal bridge network and shared volumes.
``` ## Network Model
git clone https://gitea.leaf.home.kappeh.org/Homelab/minecraft_server.git
cd minecraft_server
```
2. **Create required directories**: See [Directory Setup](#directory-setup) for details. All containers are connected to a dedicated bridge network with static IPv4 addresses assigned per service.
3. **Set up environment variables**: See [Environment Variables](#environment-variables) for details. This provides:
4. **Import world files**: - Stable addressing between services
- Predictable configuration for plugins that require fixed endpoints
- Isolation from the host network (only explicitly exposed ports are reachable)
The world for the Fabric server is located at `fabric/data/world`. If you want to use an existing world, copy it to this location before running the container: Only the following services are exposed to the host:
``` - Velocity (player ingress)
cp path/to/world fabric/data/world - BlueMap (web UI)
``` - LuckPerms PostgreSQL (admin access)
- Schematics web UI
5. **Adjust permissions (recommended)**: Run the following commands in the root of the repository, replacing `PUID` and `PGID` with the corresponding values from your `.env` file: All Minecraft backend servers are internal-only and can only be reached through Velocity.
``` ## Service Breakdown
sudo chown -R PUID:PGID .
sudo chmod -R 770 .
```
6. **Start the Docker Compose stack**: To start the services in detached mode, run: ### `velocity` - Proxy & Network Control Plane
``` Velocity is the public-facing entry point and the logical "hub" of the server network.
docker compose up -d
```
7. **Stop the Docker Compose stack**: To stop and remove the running containers, use: - Accepts player connections
- Allows players to link their Minecraft account to their Discord account
- Uses Discord membership to whitelist access to backend servers
- Forwards traffic to backend servers using modern forwarding
- Integrated with LuckPerms for centralized permissions
- Handles chat messages and tab list to allow seamless communication between backend servers
``` **Configuration Management**
docker compose down
```
## Directory Setup - Configuration files are mounted from the repository directory `velocity/config` into the container at `/config`.
- At container startup, the `itzg/mc-proxy` image copies these files into the persistent `velocity_data` volume, injecting environment variables along the way.
- All injected variables use the `CFG_` prefix (e.g. `CFG_RCON_PASSWORD`) to distinguish them from other environment variables.
- This approach ensures that secrets and environment specific settings are applied dynamically while keeping the repository configuration read-only and version-controlled.
Make a directory called `schematics` in the root of the repository. This directory is used for storing [WorldEdit](https://worldedit.org/) schematic files. To create it, run: ---
``` ### `fabric` - Primary Server
mkdir schematics
``` The Fabric server is the `primary backend server` in the network.
- Hosts creative flat map
- Provides mods and tools to support technical/redstone projects (Carpet, G4mespeed, WorldEdit, etc)
- Generates map data for BlueMap
- Integrated with LuckPerms for centralized permissions
- WorldEdit schematics are shared with the Paper server and the schematics web UI
**Configuration Management**
- Configuration files are mounted from the repository directory `fabric/config` into the container at `/config`.
- At container startup, the `itzg/minecraft-server` image copies these files into the persistent `fabric_data` volume, injecting environment variables along the way.
- All injected variables use the `CFG_` prefix (e.g. `CFG_RCON_PASSWORD`) to distinguish them from other environment variables.
- This approach ensures that secrets and environment specific settings are applied dynamically while keeping the repository configuration read-only and version-controlled.
---
### `paper` - Secondary Server
The Paper server is the `secondary backend server`, used for casual gameplay and exploration.
- Hosts survival worlds for casual gameplay
- Hosts creative worlds for building/testing on Paper
- Hosts archived worlds (e.g. Redstoner and Synergy plot worlds)
- Generates map data for BlueMap
- Integrated with LuckPerms for centralized permissions
- WorldEdit schematics are shared with the Fabric server and the schematics web UI
**Configuration Management**
- Configuration files are mounted from the repository directories `paper/config` and `paper/plugins` into the container at `/config` and `/plugins` respectively.
- At container startup, the `itzg/minecraft-server` image copies these files into the persistent `paper_data` volume, injecting environment variables along the way.
- All injected variables use the `CFG_` prefix (e.g. `CFG_RCON_PASSWORD`) to distinguish them from other environment variables.
- This approach ensures that secrets and environment specific settings are applied dynamically while keeping the repository configuration read-only and version-controlled.
---
### `bluemap` - World Map Web Interface
BlueMap runs as a standalone service that serves the web interface for exploring Minecraft worlds.
- Serves the web-accessible map UI
- Provides access to map assets rendered by the backend servers
- Unifies worlds from multiple backend servers into a single interface
---
### `luckperms` - Permission Database
LuckPerms uses a PostgreSQL backend for permissions storage.
- Stores users, groups, permissions and metadata
- Provides consistent permissions across all servers and the proxy
---
### `schematics` - Schematics Web UI
The schematics service exposes a shared directory of WorldEdit schematics. This allows players to import schematics to the server and export schematics from the server via a web interface.
---
### `init` — Volume Initialization
The `init` container is a one-shot helper service that prepares the environment for all other containers.
- Initialize and prepare named Docker volumes
- Ensure the correct directory structure within volumes
- Set appropriate ownership and permissions for volume contents
- Support backup and restore scripts by managing volume data
All other services are configured to wait until init completes successfully before starting, ensuring a consistent and predictable environment.
---
### `sqlite_helper` - Backup Utility
This container exists solely to assist with backups.
- Used to dump SQLite databases from mounted volumes
- Write backups to the shared backups volume
## Backup & Restore
Persistent server data, schematics, and databases are stored in named Docker volumes. Backup and restore operations are handled via scripts in the repository `scripts` directory.
- See `scripts/README.md` for detailed instructions on creating, restoring, and managing backups.
- The scripts leverage the `init` and `sqlite_helper` containers to safely manage volume contents and database dumps.
- Backups can be run manually or automated.
- Automated backups are intended to be orchestrated on the host using tools such as cron or systemd.
## Environment Variables ## Environment Variables
To configure environment variables, make a copy of the example file: The server stack is configured via environment variables, which are injected into the containers and, in some cases, the configuration files. These variables allow the stack to:
``` - Configure network ports, secrets, and authentication mechanisms
cp .env.example .env - Provide centralized credentials for services such as RCON, LuckPerms, and Discord integration
``` - Enable dynamic, environment-specific configuration without changing modifying repository files
Then, open `.env` in a text editor and set appropriate values for your setup. ### CI/CD Integration
|**Environment Variable**|**Description**| In deployments, the repository provides a `template.env` file that defines all the required variables using placeholders (e.g. `${CFG_RCON_PASSWORD}`). During deployment, CI/CD pipelines or scripts can materialize `template.env` into a `.env` file using tools such as `envsubst`.
|---|---|
|`PUID`|The user ID that should be used for file ownership within the project.|
|`PGID`|The group ID that should be used for file ownership within the project.|
|`VELOCITY_PORT`|The port number where the Velocity proxy service will listen. Default is set to `25565`.|
|`RCON_PASSWORD`|The password for Remote Console (RCON) access. This should be a secure password.|
|`FORWARDING_SECRET`|A secret key for forwarding data between services or to the proxy. This should be a secure password.|
|`DCLINK_GUILD`|The Discord guild ID (server ID) where the bot will operate. See [dclink](#dclink) for more information.|
|`DCLINK_CHANNEL`|The Discord channel ID where the bot will operate. See [dclink](#dclink) for more information.|
|`DCLINK_ROLE`|The ID of the role that the bot will give to Discord members when they link their accounts. See [dclink](#dclink) for more information.|
|`DCLINK_TOKEN`|The bot token used for authentication with Discord's API. Ensure this is kept secret and secure.|
|`LUCKPERMS_PASSWORD`|The password for the LuckPerms database. This should be a secure password.|
Instead of using environment variables, the secrets section of `docker-compose.yml` can be modified to read files instead. This method will likely be used by default in future. This approach allows:
- **Environment-specific configuration:** the same repository can be deployed to different environments (local, staging, production) with appropriate variables injected at deployment time.
- **Secure injection of secrets:** sensitive values (RCON passwords, forwarding secrets, Discord bot tokens, etc.) are never stored directly in the repository, but are provided by the CI/CD system.
- **Consistent container setup:** each service receives the variables it needs, and configuration files that reference `CFG_` variables are automatically populated at runtime.
### Key Variables
| **Environment Variable** | **Purpose** |
| ------------------------ | --------------- |
| `VELOCITY_PORT` | Host port where the Velocity proxy is exposed for player connections. |
| `BLUEMAP_PORT` | Host port where the BlueMap web interface is exposed. |
| `RCON_PASSWORD` | The password for Remote Console (RCON) access. |
| `FORWARDING_SECRET` | Secret key enabling secure communication between Velocity and backend servers. |
| `DCLINK_GUILD` | Discord server (guild) ID where the linking bot operates. |
| `DCLINK_CHANNEL` | Discord channel ID used by the linking bot. |
| `DCLINK_ROLE` | Role ID assigned to Discord members when they link accounts. |
| `DCLINK_TOKEN` | Discord bot token for API authentication. |
| `LUCKPERMS_PASSWORD` | Password for the LuckPerms database user. |
| `LUCKPERMS_PORT` | Host port for external access to the LuckPerms PostgreSQL database (used mainly for monitoring or admin tools) |
## dclink ## dclink
This configuration uses [dclink](https://github.com/Kalimero2Team/dclink) to link users' Minecraft accounts and Discord accounts. This is so that a user can gain access to the Minecraft server if they are a member of the configured Discord server.
For this to work you must first [setup a discord bot](https://github.com/Kalimero2Team/dclink/wiki/Setup-Discord-Bot). Then set the relevant [Environment Variables](#environment-variables). This server uses [dclink](https://github.com/Kalimero2Team/dclink), a plugin that allows players to link their Minecraft and Discord accounts using a Discord bot. Server access is restricted to members of the configured Discord server, effectively using Discord membership as the whitelist.
Details on the Discord bot configuration can be found in the [dclink documentation](https://github.com/LaapulliDev/dclink/wiki).
**Note:** Account information is stored in a local database and used solely for access control purposes. The only data stored are the Minecraft account UUID and the corresponding Discord account ID.