# Technical Overview

This is the technical reference for WhiteRose SMP — the full picture of how the server is set up, where things live, and how to work with it. If you're troubleshooting, planning a change, or helping someone with the server, start here.

## Live Server State

Current server state is published as JSON and updated every 5 minutes:

```
https://whiterose-smp.com/server-status.json
```

This contains the actual plugins installed, server settings, resource usage, and last backup time. If the documentation and the status file disagree, the status file reflects what's actually running.

## Documentation

The admin guide covers day-to-day operations:

| Page | What's in it |
|---|---|
| [Overview](/guide/README.md) | Server info, admin list, console commands |
| [Plugins](/guide/plugins.md) | Installed plugins, install/remove/update steps |
| [Discord](/guide/discord.md) | DiscordSRV setup, bot config, channel routing |
| [WinSCP](/guide/winscp.md) | Connecting to the server, file management |
| [Maintenance](/guide/maintenance.md) | Backups, Paper updates, server.properties, infrastructure |
| [Emergency](/guide/emergency.md) | SSH access, crash recovery, troubleshooting |

---

## Infrastructure

| Field | Value |
|---|---|
| VM | Azure B2s (2 vCPU, 4GB RAM), West US 2 |
| OS | Ubuntu 24.04 LTS |
| IP | `whiterose-smp.com` (static) |
| Java | OpenJDK 21 |
| Memory | `-Xms2G -Xmx2G` |
| Swap | 2 GB on ephemeral disk (`/mnt/swapfile`), swappiness=10 |
| Timezone | UTC |
| SSH | `azureuser@whiterose-smp.com` (key auth, `.pem` file) |

### Ports

| Port | Protocol | Purpose |
|---|---|---|
| 22 | TCP | SSH |
| 80 | TCP | Website, guide, resource packs |
| 25565 | TCP | Minecraft |
| 24454 | UDP | Simple Voice Chat |
| 8100 | TCP | BlueMap (web map) |

### Directory Layout

```
/opt/minecraft/
├── paper.jar              ← server binary
├── start.sh               ← launch script
├── backup.sh              ← backup script
├── server.properties      ← server settings
├── ops.json, whitelist.json
├── plugins/               ← plugin jars + their config folders
├── world/                 ← overworld
│   └── datapacks/
├── world_nether/
├── world_the_end/
├── logs/
└── backups/               ← daily rolling backups

/var/www/minecraft/
├── index.html             ← splash page
├── server-status.json     ← auto-generated status
└── guide/                 ← this documentation (git-tracked)
    ├── index.html         ← guide viewer (SPA)
    ├── README.md, plugins.md, discord.md, etc.
    └── tech.md            ← this file
```

### Services

The Minecraft server runs as a **systemd service** (`minecraft.service`) — it starts on boot and auto-restarts after `stop`.

```bash
sudo systemctl status minecraft   # check
sudo systemctl stop minecraft     # stop (will NOT auto-restart)
sudo systemctl start minecraft    # start
sudo systemctl restart minecraft  # restart
```

Typing `stop` in-game or in Discord `#console` triggers a graceful shutdown followed by auto-restart (via systemd `Restart=always`).

### Scheduled Tasks

| Time (UTC) | What |
|---|---|
| 04:00 | Automated backup → `/opt/minecraft/backups/` |
| 11:00 | Daily server restart (clears memory) |
| Every 5 min | `server-status.json` regenerated |
| Hourly | Guide docs git auto-commit (if changed) |

---

## Key Constraints

- **One command at a time.** Pasting multiple commands into the console (in-game or Discord) crashes the server. Always give commands individually.
- **Paper only.** Plugins must be Paper-compatible. Check [Modrinth](https://modrinth.com) or [Hangar](https://hangar.papermc.io) with the `paper` loader filter and game version `1.21.11`.
- **Whitelist is enforced.** New players must be added: `whitelist add <name>`.
- **The world seed is permanent.** Changing `level-seed` in server.properties does nothing after world creation.
- **Console access:** Discord `#console` channel or in-game `/` commands. SSH is the fallback.
- **Backups are local only.** They protect against bad changes, not VM/disk failure.

---

## Making Changes

### Installing a plugin

See the full guide: [Plugins page](/guide/plugins.md). Short version: download the `.jar`, put it in `/opt/minecraft/plugins/`, restart.

### Changing server settings

Edit `/opt/minecraft/server.properties` via WinSCP or SSH, then restart.

### Updating this documentation

Guide files live at `/var/www/minecraft/guide/*.md`. Edit with WinSCP (double-click, edit, save) or SSH (`nano`). Changes are live immediately and automatically tracked in git.

**When you change the server, update the docs to match.** The guide is only useful when it reflects reality. If you install a plugin, add it to `plugins.md`. If you change a setting, update `maintenance.md`. If the infrastructure changes, update this file.

### Backups

Backups run daily at 04:00 UTC. The script (`/opt/minecraft/backup.sh`) archives:
- World data (overworld, nether, end)
- All plugins and their configs
- Server configuration (server.properties, ops.json, whitelist.json, bukkit/spigot configs)
- Website and guide files
- systemd and nginx configuration

Archives are kept for 7 days in `/opt/minecraft/backups/`.

**To list backups:**

```bash
ls -lh /opt/minecraft/backups/
```

**To restore from a backup:**

1. Stop the server:
   ```bash
   sudo systemctl stop minecraft
   ```

2. Rename current data as a safety net:
   ```bash
   cd /opt/minecraft
   mv world world_old
   mv world_nether world_nether_old
   mv world_the_end world_the_end_old
   ```

3. Extract the backup (paths are relative to `/`):
   ```bash
   sudo tar -xzf /opt/minecraft/backups/backup-YYYYMMDD-HHMMSS.tar.gz -C /
   ```

4. Start the server:
   ```bash
   sudo systemctl start minecraft
   ```

5. Verify everything works, then clean up the `_old` folders:
   ```bash
   rm -rf /opt/minecraft/world_old /opt/minecraft/world_nether_old /opt/minecraft/world_the_end_old
   ```

**To run a manual backup immediately:**

```bash
/opt/minecraft/backup.sh
```