Skip to main content
Contributions to the Docker Minecraft Server project are welcome! This guide explains how to develop, test, and contribute improvements.

​
Ways to Contribute

  • Add new server type support
  • Fix bugs and issues
  • Improve documentation
  • Add new features
  • Report issues and suggestions

​
Adding a Server Type

Adding support for a new server TYPE varies in complexity depending on how the server is obtained and configured.
1

Copy an existing deploy script

Copy an existing start-deploy* script, such as start-deployFabric, and rename it with the “start-deploy” prefix.
cp scripts/start-deployFabric scripts/start-deployYourType
2

Modify type-specific behavior

Edit your new script to implement the type-specific logic between:
  • The “start-utils” preamble at the beginning
  • The hand-off to start-setupWorld at the end
Keep the overall structure but customize the download and configuration logic for your server type.
3

Test your changes

Use the iterative development process (described below) to develop and test your changes.
4

Register in start-configuration

Add a case entry to the case "${TYPE^^}" statement in start-configuration:
YOURTYPE)
  exec "${SCRIPTS:-/}start-deployYourType" "$@"
  ;;
5

Add documentation

Add a documentation section in the docs directory. Copy and modify an existing section to maintain consistent style and detail level.
6

Submit a pull request

Submit your pull request with:
  • Clear description of the new server type
  • Testing notes
  • Documentation updates

​
Iterative Script Development

The compose-dev.yml file enables rapid development by mounting local scripts into the container.

​
Setup

# Clone the repository
git clone https://github.com/itzg/docker-minecraft-server.git
cd docker-minecraft-server

​
Development Workflow

# Run with development mounts
docker compose -f compose-dev.yml run --rm -it mc-dev

# With environment variables for testing
docker compose -f compose-dev.yml run --rm -it \
  -e TYPE=PAPER \
  -e VERSION=1.20.4 \
  mc-dev
To speed up the development cycle, set SETUP_ONLY=true to skip starting the actual Minecraft server:
docker compose -f compose-dev.yml run --rm -it \
  -e SETUP_ONLY=true \
  -e TYPE=YOURTYPE \
  mc-dev
This allows you to:
  1. Edit scripts locally in your editor
  2. Run the container to test changes
  3. See results immediately without rebuilding
  4. Iterate quickly

​
Using Development Copy of Tools

You can test local versions of supporting tools like mc-image-helper.

​
Java-based Tools (mc-image-helper)

1

Clone and build the tool

git clone https://github.com/itzg/mc-image-helper.git
cd mc-image-helper
./gradlew installDist
The distribution will be installed in build/install/mc-image-helper.
2

Get the absolute path

pwd
# Note the output, e.g., /home/user/projects/mc-image-helper
3

Mount in container

Using docker run:
docker run -it --rm \
  -v /path/to/mc-image-helper/build/install/mc-image-helper:/usr/share/mc-image-helper \
  -e EULA=true \
  itzg/minecraft-server
Using docker-compose.yml:
services:
  mc:
    image: itzg/minecraft-server
    volumes:
      - /path/to/mc-image-helper/build/install/mc-image-helper:/usr/share/mc-image-helper:ro
      - ./data:/data

​
Go-based Tools

1

Build snapshot release

cd /path/to/tool-repo
goreleaser release --snapshot --clean
2

Setup github-releases-proxy

Clone and run itzg/github-releases-proxy according to its instructions.
3

Build Docker image with proxy

docker build \
  --build-arg GITHUB_BASEURL=http://host.docker.internal:8080 \
  --build-arg APPS_REV=1 \
  --build-arg MC_HELPER_VERSION=1.8.1-SNAPSHOT \
  -t itzg/minecraft-server .

​
Contributing to Documentation

The documentation is written in Markdown and built using Zensical.

​
Documentation Structure

  • Source files: docs/ directory
  • Organized into sections by directory
  • Written in Markdown with Zensical extensions
The README.md rarely needs modification - it only serves as a brief project introduction. Most updates should go in the docs/ directory.

​
Local Documentation Development

1

Start the documentation server

docker compose -f compose-docs.yml -p zensical up
2

View live documentation

Open http://localhost:8000 in your browser.
3

Edit and see changes

Edit files in the docs/ directory. Changes will be reflected automatically in your browser.

​
Documentation Guidelines

  • Follow existing patterns: Look at similar pages for style and structure
  • Be concise but complete: Provide enough detail for users to succeed
  • Include examples: Show both docker run and docker-compose.yml examples
  • Use proper formatting: Follow Zensical markdown conventions
  • Test locally: Always preview changes before submitting

​
Generating Release Notes

When preparing a release, use this git command to generate release notes: 
git log --invert-grep \
  --grep "^ci:" \
  --grep "^misc:" \
  --grep "^docs:" \
  --pretty="* %s" \
  1.1.0..1.2.0
Replace version tags as appropriate. This filters out CI, miscellaneous, and documentation commits to focus on user-facing changes.

​
Pull Request Guidelines

When submitting a pull request:
1

Create a focused PR

  • Address one feature or fix per PR
  • Keep changes focused and atomic
  • Avoid mixing unrelated changes
2

Write a clear description

Explain:
  • What the PR does
  • Why the change is needed
  • How you tested it
  • Any breaking changes or special considerations
3

Include tests and documentation

  • Test your changes thoroughly
  • Update or add documentation
  • Include example configurations if applicable
4

Follow conventions

  • Match existing code style
  • Use consistent naming
  • Follow shell script best practices
  • Add comments for complex logic

​
Getting Help

If you need help contributing:
  • Discussions: Ask questions in GitHub Discussions
  • Issues: Check existing issues for similar problems
  • Code examples: Look at existing server type implementations
  • Community: Join the community for support and collaboration

​
Code of Conduct

Be respectful and constructive in all interactions. We’re all here to make Minecraft server hosting better for everyone.

​
License

By contributing, you agree that your contributions will be licensed under the Apache License 2.0, the same license as the project.

Build docs developers (and LLMs) love

Get started for freeTalk to us