SETUP_GUIDE.md

# 📖 Alpha MC — Complete Setup Guide
> Everything explained: what every file does, how to set it up, and how it all works together.

---

## 📋 Table of Contents
1. [How It All Works](#how-it-all-works)
2. [File-by-File Explanation](#file-by-file-explanation)
3. [Step-by-Step Setup](#step-by-step-setup)
4. [HuggingFace Secrets Reference](#huggingface-secrets-reference)
5. [Google Drive Backup Setup](#google-drive-backup-setup)
6. [How to Connect and Play](#how-to-connect-and-play)
7. [Troubleshooting](#troubleshooting)
8. [FAQ](#faq)

---

## How It All Works

```
┌─────────────────────────────────────────────────────┐
│              HuggingFace Space (Docker)              │
│                                                      │
│  ┌──────────────┐    ┌─────────────────────────┐    │
│  │  Minecraft   │    │  Status Dashboard        │    │
│  │  Bedrock     │    │  (port 7860, HTTP)       │    │
│  │  Server      │    │  Shows: status, logs,    │    │
│  │  (UDP 19132) │    │  tunnel address, RAM/CPU │    │
│  └──────┬───────┘    └─────────────────────────┘    │
│         │                                            │
│  ┌──────▼───────┐    ┌─────────────────────────┐    │
│  │  playit.gg   │    │  Cron Jobs               │    │
│  │  agent       │    │  - Backup every 6 hours  │    │
│  │  (tunnel)    │    │  - Log rotation weekly   │    │
│  └──────┬───────┘    └─────────────────────────┘    │
└─────────┼───────────────────────────────────────────┘
          │ UDP tunnel
          ▼
   playit.gg servers
          │
          ▼
   Your friends' Minecraft (anywhere in the world)
```

**Why playit.gg?** HuggingFace Spaces only expose HTTP (TCP) ports publicly. Minecraft Bedrock uses UDP, which HF doesn't support directly. playit.gg acts as a free UDP tunnel — the Minecraft server connects outward to playit.gg, and players connect to playit.gg's address.

**Why port 7860?** HuggingFace watches this port. If nothing responds on 7860, it marks your Space as "idle" and pauses it. Our status dashboard runs on 7860 and keeps it alive.

---

## File-by-File Explanation

### 🐳 `Dockerfile`
The main blueprint Docker uses to build your container.

**What it does, line by line:**
- `FROM ubuntu:22.04` — Starts with a clean Ubuntu Linux environment
- `ENV DEBIAN_FRONTEND=noninteractive` — Stops apt-get from asking questions during install
- `apt-get install` — Installs tools: curl/wget (downloading), unzip (extracting), python3 (status server + Drive backup), cron (scheduled jobs)
- `pip install` — Installs Python libraries for Google Drive API
- `mkdir -p` — Creates the folder structure: `/data/bedrock-server/`, `/data/scripts/`, `/data/logs/`, `/data/playit_gg/`
- `COPY prepare.sh ... && RUN bash prepare.sh` — Runs the download script at build time (downloads Minecraft + playit)
- `WORKDIR /data/bedrock-server` — Sets the default directory (fixes the path bug from before)
- `COPY server.properties allowlist.json permissions.json ./` — Copies game config INTO the server folder
- `COPY start.sh run.sh status_server.py ./` — Copies startup scripts into server folder
- `COPY backup.sh ... /data/scripts/` — Copies utility scripts to their own folder
- `chmod +x` — Makes all `.sh` scripts executable (runnable)
- `EXPOSE 7860 19132/udp 19133/udp` — Declares which ports the container uses
- `CMD ["bash", "/data/bedrock-server/start.sh"]` — The command that runs when the container starts

---

### 🔧 `prepare.sh`
Runs **once during Docker build** to download Minecraft and playit.

**What it does:**
1. Fetches the Minecraft.net download page with a browser-like User-Agent (so the site doesn't block it)
2. Tries 3 different URL patterns to extract the Bedrock server download link (in case the page layout changes)
3. Downloads the `.zip` with retry logic (retries up to 4 times with exponential backoff: 5s, 10s, 20s)
4. Extracts it to `/data/bedrock-server/`
5. Downloads the latest `playit-linux-amd64` binary from GitHub releases
6. Makes both executables

**Why it runs at build time:** So the Minecraft server binary is baked into the Docker image. Every time your Space restarts, Minecraft is already there — no download wait.

---

### 🚀 `start.sh`
The **main startup script** — this is what runs every time your Space starts.

**What it does, in order:**
1. **Sets up graceful shutdown** — catches SIGTERM signal (when HF stops the container), runs a final backup, stops Minecraft cleanly before exiting
2. **Prints a banner** with system info (CPU cores, RAM, disk)
3. **Warns if SECRET_KEY is missing** so you know immediately if the tunnel won't work
4. **Starts `status_server.py`** on port 7860 — the live dashboard (also prevents HF from pausing the Space)
5. **Starts cron daemon** for scheduled backups and log rotation
6. **Configures playit.toml** — tells playit.gg which local port to tunnel (19132 UDP)
7. **Starts the playit agent** with your SECRET_KEY
8. **Waits up to 180 seconds** for the tunnel to show a claim URL or live address, printing progress every 2 seconds
9. **Starts `bedrock_server`** (the actual Minecraft process), redirecting its output to `/data/logs/minecraft.log`
10. **Starts monitor.sh and health_check.sh** in the background
11. **Keeps running** in a loop, updating the status JSON file every 30 seconds and watching if Minecraft/playit are still alive

**Key fixes from original:**
- No `set -e` (crashes won't kill the whole script)
- Proper SIGTERM trap for graceful shutdown
- Status JSON written continuously so the dashboard has fresh data

---

### 🌐 `status_server.py`
A Python HTTP server that serves a **live web dashboard** on port 7860.

**What it shows:**
- 🟢/🔴 Server online/offline status
- RAM usage (used / total)
- Disk usage (used / total / percent)
- CPU load average
- Tunnel address to copy into Minecraft
- Last 40 lines of the Minecraft server log (auto-scrolled)

**How it works:**
- Reads `/tmp/mc_status.json` (written by `start.sh` every 30 seconds)
- Reads the last 40 lines of `/data/logs/minecraft.log` using the `tail` command
- Reads the playit log to extract the tunnel address
- Generates a full HTML page on every request
- Page auto-refreshes every 15 seconds via a `<meta refresh>` tag
- No dependencies needed beyond Python's built-in `http.server`

**Why this matters:** Without something running on port 7860, HuggingFace marks your Space as idle within minutes and pauses it. This keeps it alive 24/7.

---

### ⚙️ `server.properties`
The Minecraft Bedrock server configuration file.

| Setting | Value | Explanation |
|---|---|---|
| `server-name` | Gaganpreet's Minecraft Server | Name shown in the server browser |
| `gamemode` | survival | Players are in survival mode |
| `difficulty` | hard | Hard difficulty |
| `allow-cheats` | false | No commands like /gamemode |
| `max-players` | 20 | Up to 20 players at once |
| `online-mode` | true | Requires legitimate Xbox/Microsoft account |
| `white-list` | false | Anyone can join (set to true + edit allowlist.json to restrict) |
| `server-port` | 19132 | Main UDP port (IPv4) |
| `server-portv6` | 19133 | IPv6 UDP port |
| `view-distance` | 10 | Chunks loaded around each player |
| `tick-distance` | 4 | Active simulation distance |
| `player-idle-timeout` | 30 | Kick players idle for 30 minutes |
| `level-name` | Bedrock level | Name of the world folder |
| `level-seed` | *(blank)* | Random seed — fill in a number for a specific world |
| `server-authoritative-movement` | server-auth | Server controls player movement (anti-cheat) |

---

### 📋 `allowlist.json`
Controls who can join if `white-list=true` in server.properties.

**Default:** Empty array `[]` — whitelist is disabled so anyone can join.

**To add a player:**
```json
[
  {
    "ignoresPlayerLimit": false,
    "name": "PlayerGamerTag",
    "xuid": "2535123456789"
  }
]
```
Get a player's XUID from sites like xuidgrabber.com.

---

### 🔑 `permissions.json`
Sets operator/member/visitor permissions for specific players.

**Default:** Empty `[]` — everyone gets the `default-player-permission-level` from server.properties.

**To make someone an operator:**
```json
[
  {
    "permission": "operator",
    "xuid": "2535123456789"
  }
]
```

---

### 💾 `backup.sh`
Creates world backups locally and optionally uploads to Google Drive.

**What it does:**
1. Checks if the worlds folder exists and has data
2. Creates a `.tar.gz` archive of the entire `worlds/` folder with a timestamp in the filename (e.g. `world_20240425_143000.tar.gz`)
3. Saves it to `/data/bedrock-server/backups/`
4. Prunes old backups — keeps only the 10 most recent
5. If `GDRIVE_SA_KEY` secret is set → calls `google_drive_backup.py` to upload the new backup to Google Drive
6. If `GDRIVE_SA_KEY` is not set → logs a helpful message and skips Drive upload gracefully

**Run manually:** `bash /data/scripts/backup.sh`

---

### ☁️ `google_drive_backup.py`
Uploads the latest backup `.tar.gz` to a Google Drive folder using a **Service Account** (no browser, works headlessly).

**How it's different from the original:**
- Original used `InstalledAppFlow` → needs a browser popup → **impossible in Docker**
- New version uses a **Service Account** → authenticates silently using a JSON key stored as a base64 HF Secret
- Supports **resumable uploads** with 5 MB chunks → handles large world files reliably
- Shows upload progress percentage
- Auto-deletes oldest Drive backups beyond 10 files
- Cleans up the temp credentials file after upload

**Required HF Secret:** `GDRIVE_SA_KEY` (base64-encoded service account JSON — see setup below)

---

### 🏥 `health_check.sh`
Runs in the background and **automatically restarts** Minecraft or playit if either crashes.

**What it does (every 30 seconds):**
1. Checks if `bedrock_server` process is running — if not, restarts it
2. Checks if `playit` process is running — if not, restarts it with your SECRET_KEY
3. Logs all events with timestamps to `/data/logs/health.log`

**Why this matters:** Without this, if Minecraft crashes at 3am while your friends are playing, the server stays down until you manually restart the Space. With this, it auto-recovers within 30 seconds.

---

### 📊 `monitor.sh`
Logs system resource stats every 60 seconds to `/data/logs/monitor.log`.

**Each log line contains:** timestamp, CPU load average, RAM used/total, disk used/total, Minecraft PID, playit PID.

Useful for diagnosing performance issues or seeing exactly when the server went down.

---

### 🔄 `auto_restart.sh`
A simple utility script to restart Minecraft after a delay.

**Usage:** `bash /data/scripts/auto_restart.sh 10` — restarts after 10 seconds
Called automatically by health_check.sh when needed.

---

### 🕐 `crontab.txt`
Schedules automatic recurring tasks using cron.

```
0 */6 * * *   bash /data/scripts/backup.sh
```
→ Runs backup.sh every 6 hours (at 00:00, 06:00, 12:00, 18:00)

```
0 0 * * 0   truncate -s 0 /data/logs/*.log
```
→ Every Sunday at midnight, clears all log files so they don't grow forever

---

### 🗺️ `run.sh`
A simple wrapper that changes directory to the Minecraft server folder and runs `start.sh`. Kept for compatibility.

---

### 🔧 `setup_google_drive.sh`
Run this **on your own computer** (not on HuggingFace) to walk through the Google Cloud setup and generate your `GDRIVE_SA_KEY`. It even base64-encodes the key file for you automatically if `service-account.json` is in the same folder.

---

## Step-by-Step Setup

### Step 1 — Upload all files to HuggingFace

1. Go to your Space: `https://huggingface.co/spaces/Gagan1322/alpha_mc`
2. Click **Files** tab → **Add file** → **Upload files**
3. Upload ALL of these files:
   ```
   Dockerfile
   README.md
   prepare.sh
   start.sh
   run.sh
   status_server.py
   server.properties
   allowlist.json
   permissions.json
   backup.sh
   monitor.sh
   health_check.sh
   auto_restart.sh
   crontab.txt
   google_drive_backup.py
   setup_google_drive.sh
   ```
4. Commit the changes

---

### Step 2 — Add your playit Secret Key

1. Go to your Space → **Settings** tab → **Repository secrets**
2. Click **New secret**
3. Name: `SECRET_KEY`
4. Value: your playit agent secret key from `https://playit.gg/account/agents`
   - **Regenerate your key first!** The old one was exposed in a screenshot.
5. Click **Add secret**

---

### Step 3 — Restart the Space

1. Go to the **App** tab of your Space
2. Click the **⋮** (three dots) menu → **Restart Space**
3. Wait 2-3 minutes for the Docker image to build (first time only)
4. The Space URL will show your live status dashboard

---

### Step 4 — Get the Tunnel Address

1. Open the Space URL in your browser
2. Look at the dashboard — when the tunnel is live, the **Connect Address** section shows something like:
   ```
   abc123.playit.gg:12345
   ```
3. If it shows a **claim URL** instead:
   - Click that URL → sign into playit.gg → accept the tunnel
   - Wait 10 seconds → the dashboard will show the live address

---

### Step 5 — Connect in Minecraft

1. Open Minecraft Bedrock Edition on your phone/PC/console
2. Go to **Play** → **Servers** tab → **Add Server**
3. Server Address: paste the `*.playit.gg` address
4. Port: paste the port number after the colon (or leave as 19132 if no port shown)
5. Click **Save** → Join!

---

## HuggingFace Secrets Reference

Add these in: Space → Settings → Repository Secrets

| Secret Name | Required? | Description |
|---|---|---|
| `SECRET_KEY` | ✅ Yes | Your playit.gg agent secret key. Without this, nobody can join. |
| `GDRIVE_SA_KEY` | ❌ Optional | Base64-encoded Google Service Account JSON. Enables Drive backups. |

---

## Google Drive Backup Setup

### Why Service Account instead of OAuth?
The old `credentials.json` approach uses OAuth's "installed app" flow which **opens a browser to sign in**. Docker containers have no browser. It can never work headlessly. A Service Account authenticates with a static JSON key — no browser, no interaction, just works.

### Step-by-Step

**1. Create a Google Cloud Project**
- Go to https://console.cloud.google.com
- Top bar → Select project → New Project → name it `alpha-mc` → Create

**2. Enable Google Drive API**
- APIs & Services → Library → search "Google Drive API" → Enable

**3. Create a Service Account**
- IAM & Admin → Service Accounts → Create Service Account
- Name: `minecraft-backup` → Done
- Click the new account → **Keys** tab → Add Key → Create new key → **JSON** → Download
- This downloads something like `alpha-mc-abc123.json` — rename it to `service-account.json`

**4. Share a Drive Folder with the Service Account**
- Open Google Drive → New folder → name it exactly: `Minecraft-Bedrock-Backups`
- Right-click the folder → Share
- Open `service-account.json` and find the `"client_email"` field — copy that email address
- Paste it in the share dialog → role: **Editor** → Share

**5. Generate the GDRIVE_SA_KEY**

On your computer (Linux/Mac terminal or Git Bash on Windows):
```bash
base64 -w 0 service-account.json
```
This prints a long string of random-looking characters. Copy ALL of it.

On Windows (PowerShell):
```powershell
[Convert]::ToBase64String([IO.File]::ReadAllBytes("service-account.json"))
```

**6. Add to HuggingFace**
- Space → Settings → Repository Secrets → New secret
- Name: `GDRIVE_SA_KEY`
- Value: paste the base64 string
- Add secret → Restart Space

**7. Verify**
- Check `/data/logs/backup.log` after 6 hours
- Should show: `Google Drive upload successful!`
- Check your Google Drive folder — the backup `.tar.gz` should appear there

### Security Rules
- ❌ NEVER commit `service-account.json` to git
- ❌ NEVER upload credentials/key files to HuggingFace files tab
- ❌ NEVER share your service account JSON publicly
- ✅ ONLY store it as a HF Secret (encrypted, not visible in git history)

---

## How to Connect and Play

### Finding the Address
The address is shown in two places:
1. **Status Dashboard** — open the Space URL in any browser
2. **Space Logs** — in the App tab logs, look for `TUNNEL IS LIVE`

### Sharing with Friends
Just give them the `*.playit.gg:PORT` address. They need:
- Minecraft Bedrock Edition (any platform — mobile, PC, Xbox, PlayStation, Switch)
- Add Server → paste address → join

### Adding Friends to Allowlist (optional)
If you want only specific people to join:
1. Set `white-list=true` in `server.properties`
2. Edit `allowlist.json` to add their gamertags and XUIDs
3. Re-upload both files and restart the Space

---

## Troubleshooting

### Space shows "Paused"
- Click the Space → click **Run** or **Restart**
- Make sure `SECRET_KEY` is set in secrets
- The status dashboard on port 7860 should prevent future pausing

### "Tunnel not found" / no address shown
- Check that `SECRET_KEY` is correct (regenerate on playit.gg if needed)
- Open Space logs → look for playit errors
- If you see a claim URL → click it and accept the tunnel on playit.gg website

### Build fails (Docker build error)
- Check that ALL files listed in Step 1 are uploaded
- The most common cause: a file is missing so `COPY` fails
- Check the build logs for which `COPY` line failed

### Server starts but nobody can join
- Make sure you're using the playit.gg address (NOT the HuggingFace URL)
- The HF URL is HTTP only — Minecraft needs the playit.gg address
- Check `online-mode` in server.properties — if `true`, players need a valid Microsoft account

### Minecraft crashes (server goes offline)
- `health_check.sh` should auto-restart it within 30 seconds
- Check `/data/logs/minecraft.log` for the crash reason
- Common causes: out of RAM (HF free tier has limited RAM), corrupted world

### Google Drive backup fails
- Check that `GDRIVE_SA_KEY` is set in HF Secrets
- Verify the Drive folder is named exactly `Minecraft-Bedrock-Backups`
- Verify the folder is shared with the service account email
- Check `/data/logs/backup.log` for the specific error message

### Dashboard not loading / Space gets paused
- `status_server.py` might have crashed
- It should auto-recover but if not, restart the Space
- Check `/data/logs/status_server.log` for Python errors

---

## FAQ

**Q: Is this free?**
A: Yes! HuggingFace Spaces (free tier) + playit.gg (free tier) = $0/month. The limitation is HF's free tier has limited RAM (~16GB shared) and CPU.

**Q: Will the world be lost if the Space restarts?**
A: No! HuggingFace persistent storage keeps `/data` between restarts. Your world is safe. Backups are extra insurance.

**Q: How many players can join?**
A: Up to 20 (set in server.properties). The actual limit depends on the HF server's available RAM — more players = more RAM.

**Q: Can I use mods / behaviour packs?**
A: Yes! Upload your pack files to the Space and place them in the correct Minecraft Bedrock folder under `/data/bedrock-server/`. This requires a bit of manual setup.

**Q: How do I update the Minecraft server version?**
A: Rebuild the Space (Settings → Factory reboot). `prepare.sh` always downloads the latest version from Minecraft.net.

**Q: Can I change the world seed?**
A: Yes — set `level-seed=` in `server.properties` to any number before the world is first created. Once a world exists, changing the seed has no effect.

**Q: How do I give myself operator (admin) permissions?**
A: Edit `permissions.json` with your XUID and set `"permission": "operator"`. Alternatively, if you're the first person to join, type your gamertag in the server console — but there's no easy console access on HF.

**Q: The playit address changes every restart — how do I get a permanent address?**
A: Upgrade to playit.gg Pro ($3/month) for a permanent subdomain. On the free tier the address changes each time.

---

*Alpha MC Setup Guide — All files written and debugged for HuggingFace Spaces + playit.gg*