189 lines
10 KiB
Markdown
Executable File
189 lines
10 KiB
Markdown
Executable File
# minecraft_server
|
|
|
|
This repository defines the configuration for a private, multi-server Minecraft network. The project is guided by a set of core principles:
|
|
|
|
- **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.
|
|
|
|
## Stack Overview
|
|
|
|
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
|
|
|
|
All containers are connected to a dedicated bridge network with static IPv4 addresses assigned per service.
|
|
|
|
This provides:
|
|
|
|
- Stable addressing between services
|
|
- Predictable configuration for plugins that require fixed endpoints
|
|
- Isolation from the host network (only explicitly exposed ports are reachable)
|
|
|
|
Only the following services are exposed to the host:
|
|
|
|
- Velocity (player ingress)
|
|
- BlueMap (web UI)
|
|
- LuckPerms PostgreSQL (admin access)
|
|
- Schematics web UI
|
|
|
|
All Minecraft backend servers are internal-only and can only be reached through Velocity.
|
|
|
|
## Service Breakdown
|
|
|
|
### `velocity` - Proxy & Network Control Plane
|
|
|
|
Velocity is the public-facing entry point and the logical "hub" of the server network.
|
|
|
|
- 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**
|
|
|
|
- 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.
|
|
|
|
---
|
|
|
|
### `fabric` - Primary Server
|
|
|
|
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
|
|
|
|
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
|
|
- Provide centralized credentials for services such as RCON, LuckPerms, and Discord integration
|
|
- Enable dynamic, environment-specific configuration without changing modifying repository files
|
|
|
|
### CI/CD Integration
|
|
|
|
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`.
|
|
|
|
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
|
|
|
|
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.
|