# Deploy

## Fresh install

Target host: Debian 13 w/ Docker + Compose v2. Userns-remap optional (see PERMISSIONS.md).

```bash
# 1. Prep host dir
sudo mkdir -p /opt/docker/minecraft
sudo chown $(id -u):$(id -g) /opt/docker/minecraft

# 2. Seed configs from this repo
git clone https://github.com/<you>/minecraft-server.git /tmp/mc-repo
cp -r /tmp/mc-repo/config/* /opt/docker/minecraft/
mv /opt/docker/minecraft/paper /opt/docker/minecraft/config   # paper-global.yml etc live in ./config/
cp /tmp/mc-repo/docker-compose.yml /opt/docker/minecraft/

# 3. Apply 777 (only if userns-remap in /etc/docker/daemon.json — see PERMISSIONS.md)
chmod -R 777 /opt/docker/minecraft

# 4. Ensure proxy network exists (for Traefik integration)
docker network create proxy 2>/dev/null || true

# 5. Boot
cd /opt/docker/minecraft
docker compose pull
docker compose up -d
docker logs -f minecraft-mc
```

Watch for `[Server thread/INFO]: Done (XX.XXXs)!` — server is live.

## Migrating from existing server

If you have an existing Bukkit-family server (Paper/Spigot/Purpur):

```bash
# On old host
cd /path/to/old-server
docker compose down 2>/dev/null || systemctl stop minecraft 2>/dev/null
tar czf /tmp/mc-old.tar.gz .

# Transfer
scp /tmp/mc-old.tar.gz user@new-host:/tmp/

# On new host
mkdir -p /opt/docker/minecraft
cd /opt/docker/minecraft
tar xzf /tmp/mc-old.tar.gz

# Drop in this repo's compose
cp /tmp/mc-repo/docker-compose.yml ./
chmod -R 777 .

# Optional: clear plugins/ to let MODRINTH_PROJECTS pull fresh latest
rm -rf plugins/*.jar

docker compose up -d
```

`REMOVE_OLD_MODS=true` + `REMOVE_OLD_MODS_INCLUDE=*.jar` in compose deletes manually-placed jars on every boot. Disable if you want manual jars to persist.

## Updating

```bash
cd /opt/docker/minecraft
docker compose pull         # latest itzg image
docker compose down
docker compose up -d        # auto-DLs latest Purpur build + latest plugins
```

Purpur version: set `VERSION: LATEST` in compose (default in this repo) to track newest stable. Pin to e.g. `VERSION: "1.21.10"` for reproducibility.

## Stopping / removing

```bash
docker compose down                              # stop, keep data
docker compose down -v                           # stop, remove anonymous volumes (worlds are bind-mounted, safe)
sudo rm -rf /opt/docker/minecraft                # nuke everything
```

## Troubleshooting

- **Restart loop, "Operation not permitted" on chown** → see PERMISSIONS.md, run `chmod -R 777 /opt/docker/minecraft`.
- **`Project(s) could not be located: [foo]`** → Modrinth slug wrong. Check the project page URL on modrinth.com — slug is the last path segment.
- **`UnknownHostException: api.purpurmc.org`** → host DNS broken. On nullstone, Tailscale ate `/etc/resolv.conf`; fix: `sudo tailscale set --accept-dns=false`.
- **Server starts but plugins missing** → check `docker logs minecraft-mc` for `[mc-image-helper]` lines; download errors print there.