Skip to content

Minecraft — Setup

PaperMC server on a dedicated Debian LXC (109). Public access via playit.gg tunnel — no port forwarding required.

  • GitHub (PaperMC): https://github.com/PaperMC/Paper
  • Website: https://papermc.io
  • playit.gg: https://playit.gg

Infrastructure

Host LXC ID Internal Public
Debian LXC 109 192.168.1.109:25565 nature-increasing.gl.joinmc.link:25565 (via playit.gg)

Observability

Logs

Minecraft server logs are written to /var/log/minecraft/latest.log on LXC 109. Log collection is not yet configured. To enable:

  1. Add Alloy config for LXC 109 (or add to existing Forgejo Alloy on LXC 100 if network-reachable)
  2. Point Alloy to /var/log/minecraft/latest.log with job="minecraft"
  3. Push to main — playbook will deploy and start collecting logs

Once enabled, query via:

Query Purpose
{job="minecraft"} All server logs
{job="minecraft"} \|= "error" Errors only
{job="minecraft"} \|= "player" Player join/leave events

Access: Grafana → Explore → Loki → Enter query (after Alloy is configured)

Metrics

PaperMC does not export Prometheus metrics by default. Use Loki logs to monitor server health.

IaC

Artifact Path
Playbook ansible/playbooks/minecraft.yml
Workflow .forgejo/workflows/minecraft.yml
Config services/minecraft/server.properties
Secret vault kv get secret/minecraft → playit_secret

First-time playit.gg setup (one-time, before running the playbook)

The playit agent generates a claim code on first run.

  1. Create account at https://playit.gg
  2. On LXC 109, run the agent to get a claim URL: 
    ssh [email protected] "pct exec 109 -- nohup /usr/local/bin/playit > /tmp/playit.log 2>&1 & sleep 3 && cat /tmp/playit.log"
  3. Visit the printed URL (e.g. https://playit.gg/claim/<code>) — keep the agent running while you do this
  4. In the dashboard: name the agent (e.g. minecraft), then create a tunnel:
  5. Type: Minecraft Java
  6. Local IP: 127.0.0.1
  7. Local Port: 25565
  8. Proxy protocol: No
  9. After the tunnel is active, read the generated secret key: 
    ssh [email protected] "pct exec 109 -- cat /root/.config/playit_gg/playit.toml"
  10. Store in Vault: 
    vault kv put secret/minecraft playit_secret=<key>
  11. Run workflow: Forgejo Actions → Deploy Minecraft → Run workflow

Note: The agent must stay running while you claim it in the dashboard. If the process exits and restarts, it generates a new claim code.

Updating PaperMC version

Change mc_version var in ansible/playbooks/minecraft.yml and push to main.

Renovate

Renovate runs weekly (Monday 09:00) and opens PRs for outdated Docker image tags. - Major version bumps require manual approval in Forgejo (dependencyDashboardApproval) - n8n updates are also gated for manual review - Workflow: .forgejo/workflows/renovate.yml