GUIDE ENTRY

Start Here: Setup Guide

Minecraft Server Field Notes

#minecraft#termux#playit#arch-linux#hostel-networks

Minecraft Server Setup Guide (Android/Termux + playit tunnel)

Author: catbox404 Environment: Android/Termux host Network: UTP hostel-style shared NAT (no port forwarding), public access via playit tunnel.

0. Scope and rules (read first)

This guide covers:

Installing a PaperMC server on Android via Termux
Running the server reliably (tmux, scripts, logs)
Basic admin setup (op, permissions, spawn)
Connecting the server to the public Internet using a tunnel (playit)
Common failure modes we actually hit (keepalive, resource packs, DNS, routing)

Primary path here is Android/Termux. If you are hosting on Linux instead, keep the same flow: install Java + tmux, run Paper locally, run the tunnel separately, and forward public traffic to 127.0.0.1:25565.

Not covered:

Anything that bypasses university controls or violates policy
Port-forwarding / router changes / “network tricks” on campus infra
Illegal copies of Minecraft (use legit accounts)

1. Quick architecture (what you’re building)

You cannot “open port 25565” in a CGNAT dorm network. So you need a tunnel.

[Player PC] ---> Internet ---> [Tunnel Relay] ---> [playit agent] ---> [PaperMC on Termux]

If dorm Wi‑Fi is unstable, you can change topology (see Chapter 2/3).

2. Termux base setup

2.1 Install Termux + update packages

In Termux:

pkg update && pkg upgrade -y
pkg install -y git curl wget unzip tar tmux nano

Optional but useful:

pkg install -y openssh htop proot-distro

2.2 Storage access (so you can manage files)

termux-setup-storage

Your shared storage is usually:

~/storage/downloads
~/storage/shared

3. Install Java (PaperMC requirement)

PaperMC needs a modern Java. On Android/Termux you typically use OpenJDK packages.

pkg install -y openjdk-21
java -version

If your Paper build requires a different Java major, use the matching package version available in Termux repos.

3.1 Version sanity check

Common mapping:

Minecraft 1.20.5+ -> Java 21
Minecraft 1.18 to 1.20.4 -> Java 17
Older versions may require Java 8/16

If startup logs mention an unsupported class version, Java and Paper do not match.

4. Create server directory + download Paper

4.1 Directory layout

mkdir -p ~/minecraft
cd ~/minecraft

Recommended layout:

~/minecraft/
  server.jar
  start.sh
  eula.txt
  logs/
  plugins/
  world/

4.2 Download Paper

You have two safe options:

Option A: use Paper’s download page in a browser and copy the direct link into wget/curl. Tip: to get the direct link, right‑click the download button and choose “Copy link address”. Option B: manually upload the jar into your Termux storage and move it.

Example (replace URL with your exact version):

wget -O server.jar "https://example.com/paper-1.xx.xx.jar"

Sanity check:

ls -lh server.jar

5. First boot (EULA + config)

5.1 Create start script

Create start.sh:

nano start.sh

Paste:

#!/data/data/com.termux/files/usr/bin/bash
cd "$(dirname "$0")"

# adjust RAM based on your phone; don't exceed what Android will tolerate
JAVA_OPTS="-Xms2G -Xmx4G"

exec java $JAVA_OPTS -jar server.jar --nogui

Make it executable:

chmod +x start.sh

5.2 Run once to generate files

./start.sh

Stop the server (in console):

stop

Accept EULA:

sed -i 's/eula=false/eula=true/' eula.txt

5.3 Recommended baseline in `server.properties`

Edit:

nano server.properties

Recommended starting point:

server-port=25565
server-ip=
motd=Club Survival Server
online-mode=true
white-list=true

Notes:

Keep server-ip blank unless you have a specific reason not to.
Keep whitelist on for closed groups.
Keep online-mode=true unless you understand the tradeoff and actually need to change it.

6. Run reliably (tmux + logs)

Android will kill background tasks if you’re not careful. tmux helps.

6.1 Start server in tmux

cd ~/minecraft
tmux new -s mc
./start.sh

Detach: Ctrl+b then d

Reattach later:

tmux attach -t mc
tmux ls

6.2 Logs

Paper writes logs in:

logs/latest.log

Tail logs:

tail -f logs/latest.log

7. Admin basics (op, whitelist, commands)

7.1 OP yourself

In server console:

op <your_minecraft_username>

7.2 Whitelist (recommended)

whitelist on
whitelist add <username>

7.3 Set spawn behaviour

Vanilla /spawn is world spawn.
You can set world spawn:

setworldspawn

If you want /home commands, you’ll need a plugin (EssentialsX etc.). Keep plugins minimal on mobile.

8. Public access using playit tunnel

8.1 What playit does

playit runs an agent that connects outbound to a relay and gives players a stable address to join. This avoids port-forwarding.

8.2 Run playit

You can run playit:

on the same Android host, or
on a PC in the same LAN (sometimes more stable)

General pattern:

start playit agent
configure Minecraft TCP for port 25565 (or whatever Paper listens on)
obtain the hostname/port from playit and share it to players

Because playit versions and UIs change, keep your playit steps in your website as:

“install agent"
“login/claim"
“create tunnel (Minecraft TCP)"
“copy public address"

If the playit binary misbehaves in Termux, use proot-distro Debian as a fallback instead of changing the overall design. Keep the tunnel target as 127.0.0.1:25565.

(If you want, paste your current playit agent output and I’ll rewrite the exact steps for your version.)

8.3 Connectivity smoke test

Before blaming the network, verify these basics first:

mc tmux session is still running the server
the playit agent is still running
players are using the public playit address, not 127.0.0.1 or a LAN-only IP

9. Hosting in a dorm network: common issues (we hit these)

9.1 Players join but can’t break blocks

Usually one of:

server lag (check TPS/MSPT)
network jitter causing desync
proxy/tunnel instability

Check:

/tps
logs/latest.log for timeouts
players’ ping stability

9.2 Keepalive timeouts

Often network variance, not “server is dead”. Things that trigger it:

chunk loads, elytra travel
dorm Wi‑Fi contention/bufferbloat
tunnel relay path changes

Fix lever:

topology change (PC ethernet uplink + hotspot)
reduce view-distance/simulation-distance
pre-generate chunks (Chunky) if your device can handle it

9.3 Resource pack download fails

If you hosted packs via a local python HTTP server, common failures are:

DNS name not resolving from clients
phone/Termux dying (server stops serving file)
wrong URL or missing file

Simplest fix: remove resource pack requirement unless essential.

9.4 “dig not found” / weak tooling

On Termux, install what you need:

pkg install -y dnsutils

Then you get dig.

9.5 Proot vs Termux networking differences

We saw cases where:

Termux could reach playit API
proot-distro container couldn’t (or vice versa)

Rule:

treat proot like a different network namespace-ish environment
if tunnel works in one but not the other, run both server + tunnel in the environment that behaves.

10. Performance tuning (mobile-safe defaults)

These are practical, not “max performance” marketing.

10.1 Paper settings (starting point)

In server.properties:

reduce view-distance
keep simulation-distance reasonable

Example target for a phone host:

view-distance: 6–8
simulation-distance: 4–6

10.2 Chunk generation

Chunky can help long-term but is expensive short-term. Run it when nobody is playing and watch thermals.

If you use Chunky, put the jar in ~/minecraft/plugins and restart Paper cleanly after adding it.

Useful commands in server console:

chunky radius 5000
chunky start
chunky progress

10.3 RAM and GC

Don’t give Java “all your RAM”. Android will kill it. Start with -Xmx3G to -Xmx5G depending on device and stability.

11. Backup and migration

11.1 Backup world + configs

Stop server:

stop

Backup:

cd ~/minecraft
tar -czf backup-$(date +%F).tar.gz world world_nether world_the_end plugins server.properties paper*.yml spigot.yml ops.json whitelist.json

Copy to PC:

scp backup-YYYY-MM-DD.tar.gz user@pc:/path

11.2 Migrating hosts

If moving from Android -> PC:

copy world folders and configs
keep plugin versions compatible with same MC version

11.3 Routine ops

Quick routine:

tmux ls
tail -f logs/latest.log
confirm the tunnel still points to the correct local destination

When updating Paper:

stop the server cleanly
replace the jar
boot once and verify logs/plugins before calling it done

12. Safety and policy note

In a university network:

do not attempt to bypass controls
do not interfere with shared infrastructure
use tunnels and topology changes that remain within policy

Default safety posture:

keep online-mode=true
keep whitelist enabled for closed groups
keep regular backups
avoid random plugin jars from unknown sources

13. Read next

If this gets the server online, continue with the other field-notes chapters for the network-side lessons:

Chapter 2: case study and diagnostics screenshots
Chapter 3: infrastructure workarounds
Chapter 4: networking failures, false leads, and the fixes that actually helped

END

Sunday, 08 March 2026