Local Minecraft server for both Java and Bedrock editions

I made this for myself to play with my kid locally on the same network from different devices with different versions Java and Bedrock editions (MacBook and iPad).
Sharing in case it helps someone else. Click star ⭐️ if you find it useful!

This repository contains instructions and configurations to set up a local Minecraft server on your Mac using Docker. The server supports both Java Edition and Bedrock Edition clients, allowing you to play with friends on the same network.

The main feature - it allows to play together from Mac OS, Linux, Windows (Java Edition) and iOS (iPhone, iPad), Android, XBox, and other mobile devices (Bedrock Edition) using GeyserMC and Floodgate plugins.

Prerequisites

• Docker installed on your Mac / Linux / Windows (which will be server host). Can be downloaded from here
• At least 4GB RAM allocated to Docker (you can try with less, but performance may be affected)
• Ports 25565 (Java) and 19132 (Bedrock) available
• Basic knowledge of terminal/command line
• PlayIt account to make it accessible over the internet (optional, sometimes it may be required for Bedrock clients)
• Git and Makefile installed (optional, for easier commands)

Quick Setup Instructions

# clone repository
git clone github.com/wowkin2/minecraft-server.git

# Create account on PlayIt.gg (optional, for internet access)
# Create `.secret_key` file with your PlayIt secret key (if using PlayIt)

# Start Minecraft server
make start

# Start agent for PlayIt (if using PlayIt)
make online

# View server logs
make logs

# Stop the server
make stop

Full Setup Instructions (step by step)

1. Clone the Repository

   git clone github.com/wowkin2/minecraft-server.git
   cd minecraft-server

2. Start the Server

   docker compose up -d

   This command will download the necessary Docker image and start the Minecraft server with GeyserMC and Floodgate plugins.

3. Monitor the First Startup The first time will take 3-5 minutes to download everything. Watch the progress:

   docker compose logs -f

   Wait until you see: "Done! For help, type 'help'"

   Press Ctrl+C to exit the logs (server keeps running).

4. Check if Server is Running

   Use Docker Desktop app or run:

   docker compose ps

   You should see the container status as "running".

5. Connect from MacBook (Java Edition)

   1. Open Minecraft Java Edition
   2. Multiplayer > Add Server
   3. Server Address: localhost or <Mac IP address> (e.g., 192.168.0.100 or 192.168.1.100)
   4. Save and Join

6. Connect from iPad (Bedrock Edition)

   1. Open Minecraft Bedrock Edition
   2. Play > Servers > Add Server
   3. Server Name: My Server
   4. Server Address: <IP address of your Mac WiFi connection> (e.g., 192.168.0.100)
   5. Port: 19132
   6. Save and Join

7. Optional: Make the Server Accessible Over the Internet

   1. If you want to make the server accessible over the internet or you'll have issues accessing within local network (firewall rules or router restrictions) - use PlayIt. It's free.
   2. Follow their instructions to set up a tunnel for ports 19132 and 25565 (if needed too).
   3. As result they will provide you with public addresses to connect from anywhere, which should be used as Server Address in Minecraft clients.
   4. And also with secret key to run PlayIt client on the server host machine:

   docker exec -it minecraft-server_minecraft_1 /bin/sh
   wget https://playit.gg/downloads/playit-linux-amd64
   chmod +x playit-linux-amd64
   ./playit-linux-amd64 -key YOUR_SECRET_KEY

8. Stop the Server

   cd minecraft-server
   docker compose stop

Details

• The server uses the itzg/minecraft-server Docker image with GeyserMC and Floodgate plugins pre-installed.
• World data is stored in the ./data directory on the host machine, so it persists across container restarts.
• You can customize server properties by modifying the docker-compose.yml file.

File Locations

• World: data/world/
• Config: data/server.properties
• Plugins: data/plugins/
• Logs: data/logs/

Advanced Configuration

Enable Whitelist

To restrict access to specific players, enable the whitelist in data/server.properties:

Then add players using RCON commands:

docker exec -i minecraft-server_minecraft_1 rcon-cli whitelist add <username>

RCON Access

You can manage the server using RCON:

docker exec -i minecraft-server_minecraft_1 rcon-cli

Common commands:

• list - Show online players
• op <username> - Make player an operator
• whitelist add <username> - Add player to whitelist
• stop - Stop server gracefully
• Type exit to leave rcon-cli.

Troubleshooting

• If you cannot connect from Bedrock clients, ensure that your firewall allows traffic on port 19132.
• If using PlayIt, ensure the tunnel is active and correctly configured.
• Check server logs for errors:

  docker compose logs -f

• Make sure both devices (server host and client) are on the same network for local connections.
• If the server is not starting, check the logs for errors and ensure Docker has enough resources allocated.
• If you face issues with PlayIt, refer to their documentation or support for help.
• Ensure your Minecraft client versions are compatible with the server version.