Nerd or Geek Logo
Home / Projects / Pinecraft Docs

Pinecraft

Minecraft Java Server & Pinecraft on Raspberry Pi 4

Tutorial Raspberry Pi Minecraft
Pinecraft project logo

Overview

Pinecraft is a lightweight Minecraft Java server distribution for Raspberry Pi 4, featuring the Paper server implementation optimized for resource-constrained environments.

Requirements

Verify you have all necessary hardware before starting installation.

Required Hardware

  • Raspberry Pi 4 (4GB or 8GB RAM)
  • MicroSD card (32GB+ Class 10/UHS-1)
  • Official Raspberry Pi power supply (3A USB-C)
  • Ethernet cable or reliable WiFi
  • Computer for setup (Windows, macOS, Linux)

Optional Hardware

  • Heatsink and fan for cooling
  • External SSD for improved performance
  • Case with ventilation

Installation

Follow these steps to prepare your Raspberry Pi and install Pinecraft.

Prepare Raspberry Pi OS

Download Imager

Get the official Raspberry Pi Imager from the Raspberry Pi website.

Download Raspberry Pi Imager

Flash OS

Use the Imager to flash Raspberry Pi OS Lite (64-bit) to your MicroSD card.

Configure First Boot

In Imager settings, enable SSH, set hostname, username/password, and WiFi if needed.

Configure System

Expand Filesystem

Ensure the full SD card capacity is available to the system.

bash 
sudo raspi-config

Select: Advanced Options → Expand Filesystem

Update Packages

Update and upgrade all system packages to the latest versions.

bash 
sudo apt update && sudo apt upgrade -y

Install Git

Install Git to clone the Pinecraft repository.

bash 
sudo apt install git -y

Install Pinecraft

Clone Repository

Download the Pinecraft installer from GitHub.

bash 
git clone https://github.com/cat5TV/pinecraft.git

Run Installer

Execute the installation script with elevated privileges.

bash 
cd pinecraft && sudo ./install.sh

Verify Status

Confirm the server service is running after installation.

bash 
/etc/init.d/pinecraft status

Server Management

Essential commands for controlling the Pinecraft server.

Start Server

Launch the Minecraft server process.

bash 
~/minecraft/server

Stop Server

Gracefully shut down the server.

bash 
/etc/init.d/pinecraft stop

Restart Server

Stop and restart the server process.

bash 
~/minecraft/restart

Check Status

Verify if the server is currently running.

bash 
/etc/init.d/pinecraft status

View Logs

Monitor server output in real-time.

bash 
tail -f /var/log/pinecraft.log

Customization

Extend your server with plugins, custom worlds, and Paper updates.

Update Paper

Download the latest Paper build from PaperMC for performance and security updates.

Download Paper JAR

Replace Minecraft.jar in the server directory and restart.

Install Plugins

Add Paper-compatible plugins to extend server functionality.

Place JAR files in the plugins/ directory. Restart the server to apply.

Browse PaperMC Plugins

Add Custom World

Import pre-built or existing Minecraft worlds into your server.

Copy world folder to server directory. Edit server.properties and set level-name to match.

Networking

Connect players to your server on the local network or remotely.

Get Local IP

Find your Pi's local IP address for LAN connections.

bash 
hostname -I

Local Connection

Connect from the same network using your Pi's local IP.

In Minecraft Java Edition: Multiplayer → Direct Connect → Enter local IP.

Get External IP

Find your public IP for remote player connections.

bash 
curl ifconfig.me

Port Forwarding

Enable remote access by forwarding Minecraft's default port.

In your router admin panel, forward TCP port 25565 to your Pi's local IP address.

Remote Connection

Players outside your network connect using your external IP.

Share your external IP. Players enter it in Direct Connect.

Security Tip

Protect your server from unauthorized access.

Enable whitelist in server.properties: set white-list=true and add trusted players.

Troubleshooting

Solutions for common issues encountered during setup or operation.

Server Won't Start

Check logs for startup errors and diagnostics.

bash 
tail -f /var/log/pinecraft.log

Connection Issues

Verify server is running and network is properly configured.

LAN: Confirm same network. Remote: Check port 25565 is forwarded to Pi's local IP.

Check Disk Space

Low storage can cause crashes and world corruption.

bash 
df -h

Performance Issues

Reduce server load for smoother gameplay.

Lower view-distance in server.properties. Limit max players. Use Paper for optimizations.

Java Errors

Ensure correct Java version is installed.

bash 
java -version

Get Help

Community support for advanced issues.

Pinecraft GitHub Issues