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, 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.

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.