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

> Learn how to set up a local Pumpkin-MC/Pumpkin instance for testing by compiling Rust source code or deploying the Docker image. Follow our complete guide for a seamless setup.

- Repository: [Pumpkin MC/Pumpkin](https://github.com/Pumpkin-MC/Pumpkin)
- Tags: how-to-guide
- Published: 2026-07-23

---

**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`](https://github.com/Pumpkin-MC/Pumpkin/blob/main/Cargo.toml). Install via [rustup](https://www.rust-lang.org/tools/install).
- **Git** – To clone the repository from GitHub.
- **Docker** (optional) – For containerized deployment. Install [Docker Engine](https://docs.docker.com/get-docker/) 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:

```bash
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`](https://github.com/Pumpkin-MC/Pumpkin/blob/main/Cargo.toml) and produces the optimized server executable:

```bash
cargo build --release

```

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

### Configure and Run

Pumpkin looks for a [`pumpkin.toml`](https://github.com/Pumpkin-MC/Pumpkin/blob/main/pumpkin.toml) configuration file in the current working directory. Create a minimal configuration to enable Java Edition networking:

```toml
[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`](https://github.com/Pumpkin-MC/Pumpkin/blob/main/pumpkin-config/src/lib.rs)).

Launch the server:

```bash
./target/release/pumpkin

```

According to the source code in [`pumpkin/src/main.rs`](https://github.com/Pumpkin-MC/Pumpkin/blob/main/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):

```bash
docker build -t pumpkin .

```

### Run the Container Directly

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

```bash
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`](https://github.com/Pumpkin-MC/Pumpkin/blob/main/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:

```bash
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`](https://github.com/Pumpkin-MC/Pumpkin/blob/main/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`](https://github.com/Pumpkin-MC/Pumpkin/blob/main/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`](https://github.com/Pumpkin-MC/Pumpkin/blob/main/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`](https://github.com/Pumpkin-MC/Pumpkin/blob/main/pumpkin.toml), with networking controls defined in the `pumpkin-config` crate.
- **Source entry point** is [`pumpkin/src/main.rs`](https://github.com/Pumpkin-MC/Pumpkin/blob/main/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`](https://github.com/Pumpkin-MC/Pumpkin/blob/main/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`](https://github.com/Pumpkin-MC/Pumpkin/blob/main/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.