How to Set Up a Local Instance of Pumpkin-MC/Pumpkin for Testing: Complete Guide

You can set up a local Pumpkin testing instance either by compiling the Rust source code with Cargo or by deploying the official Docker image, both of which expose the standard Minecraft Java Edition port 25565 by default.

Pumpkin is a fully-Rust Minecraft server implementation designed for performance and modern architecture. Setting up a local instance allows you to test client connections, experiment with configuration options, and verify plugin compatibility before deploying to production.

Prerequisites

Before building or running Pumpkin, ensure your system meets these requirements:

• Rust ≥1.95 – Required to compile the workspace defined in Cargo.toml. Install via rustup.
• Git – To clone the repository from GitHub.
• Docker (optional) – For containerized deployment. Install Docker Engine or Docker Desktop.
• Minecraft Java Edition 1.21.2 (or Bedrock) – To test the running server.

Method 1: Build from Source with Cargo

This approach gives you the fastest iteration cycle for development and testing.

Clone the Repository

Start by cloning the canonical source:

git clone https://github.com/Pumpkin-MC/Pumpkin.git
cd Pumpkin

Compile the Server

Build the release binary using Cargo. This invokes the workspace defined in Cargo.toml and produces the optimized server executable:

cargo build --release

The compiled binary is placed at target/release/pumpkin.

Configure and Run

Pumpkin looks for a pumpkin.toml configuration file in the current working directory. Create a minimal configuration to enable Java Edition networking:

[basic]
world = "world"

[advanced.networking.java]
enabled = true
address = "0.0.0.0:25565"

[advanced.networking.bedrock]
enabled = false

The full configuration schema is defined in the pumpkin-config crate (pumpkin-config/src/lib.rs).

Launch the server:

./target/release/pumpkin

According to the source code in pumpkin/src/main.rs (lines 60-78 and 150-159), this starts the Tokio runtime, loads the vanilla data via VanillaData::load(), and initializes the network listeners. You should see console output similar to:

Starting Pumpkin 0.1.0-dev+26.2 Minecraft (Protocol 761)
Server is now running. Connect using port: Java Edition: 0.0.0.0:25565

Connect Your Client

Open your Minecraft Java Edition client, add a server with the address localhost:25565, and join. If you enabled Bedrock in the configuration, the console will display the Bedrock port separately.

Method 2: Run with Docker (Isolated Environment)

Docker provides a reproducible, isolated environment ideal for testing specific versions without managing Rust toolchains.

Build the Docker Image

The repository includes a multi-stage Dockerfile that compiles the server in a Rust builder stage (lines 13-17) and copies the release binary into a minimal Alpine image (lines 21-33):

docker build -t pumpkin .

Run the Container Directly

Execute the container with port forwarding and a persistent volume for world data:

docker run -d -p 25565:25565 --name pumpkin \
  -v $(pwd)/data:/pumpkin \
  pumpkin

This command mounts your local ./data directory to /pumpkin inside the container, ensuring world files and configuration persist between restarts. The container runs as a non-root user (UID 2613) for security, as specified in the Dockerfile (line 28), and includes health checks on port 25565.

Use Docker Compose (Recommended)

For convenience, use the provided docker-compose.yml (lines 1-12), which includes the volume mount, port mapping, and a read-only root filesystem (read_only: true) for added security:

docker compose up -d

Connect your client to localhost:25565 as before.

Development and Debugging Flags

When testing locally, these flags assist with troubleshooting:

• --features console-subscriber – Enable a pretty-printing console logger by running cargo run --release --features console-subscriber (feature gating is implemented in pumpkin/src/main.rs line 54).
• RUST_BACKTRACE=1 – Print full backtraces on panic. This is already set in the Docker image (line 30) but useful for native builds.
• cargo test – Run the full test suite to verify your build before deploying.

Troubleshooting Common Issues

Symptom	Cause	Solution
Immediate panic on startup	Missing vanilla data or corrupted pumpkin.toml	Verify that VanillaData::load() succeeds (check pumpkin-data availability) and configuration syntax is valid.
"Port already in use" error	Another service bound to 25565	Change the port in pumpkin.toml or terminate the conflicting process.
Client shows empty world	Missing world directory	Create the directory manually or allow Pumpkin to generate it automatically on first start.
Docker container exits immediately	read_only: true with missing writable volume	Ensure the ./data directory exists and is writable by your user before running docker compose up.

Summary

• Two primary methods exist for local testing: native Cargo builds (best for developers) and Docker deployment (best for isolation).
• Key configuration happens in pumpkin.toml, with networking controls defined in the pumpkin-config crate.
• Source entry point is pumpkin/src/main.rs, which handles the Tokio runtime initialization and vanilla data loading.
• Docker security features include non-root execution (UID 2613) and read-only root filesystems when using Docker Compose.

Frequently Asked Questions

What version of Rust is required to build Pumpkin?

Pumpkin requires Rust 1.95 or newer to compile successfully. This ensures compatibility with the workspace dependencies defined in the root Cargo.toml.

Can I run Pumpkin without installing Rust?

Yes. If you have Docker installed, you can build and run Pumpkin without installing the Rust toolchain locally. The multi-stage Dockerfile handles all compilation inside a container and outputs a minimal Alpine-based image.

How do I enable Bedrock protocol support?

Edit your pumpkin.toml configuration and set [advanced.networking.bedrock] enabled = true. The server will print the Bedrock bind address in the console on startup alongside the Java Edition port.

Why does my Docker container exit immediately?

The most common cause is using read_only: true in Docker Compose without a writable volume mounted at /pumpkin. Ensure your ./data directory exists and has proper write permissions, or remove the read_only flag for testing purposes.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}