From e701156597f59eb0fa73edc2c13bdfb3d51d297a Mon Sep 17 00:00:00 2001
From: Brandon Nguyen <58405975+Bratah123@users.noreply.github.com>
Date: Tue, 7 Jul 2026 20:20:30 -0700
Subject: [PATCH] REFACT: docs on proper nginx deployment

---
 README.md        |  3 +++
 deploy/README.md | 57 +++++++++++++++++++++---------------------------
 2 files changed, 28 insertions(+), 32 deletions(-)

diff --git a/README.md b/README.md
index 8fea4a4..7cd80a1 100644
--- a/README.md
+++ b/README.md
@@ -84,6 +84,9 @@ The reason is that the login handshake redirects the client to a follow-up addre
    assetURL=http://your.public.ip.or.domain:8000/
    ```
 
+> **Hosting on a VPS?** See [`deploy/`](deploy/README.md) Not needed for local
+> development only for reliable remote hosting.
+
 ## Custom Card Creation
 
 SpiritPTCGO supports a modular card injection system. You add a custom card by dropping an image and a python script into the designated folders, and the server handles the Unity AssetBundle generation automatically on startup. A card is two things: a **data definition** (its name, HP, cost, weakness, etc.) and, if you want it to actually *do* something in a match, a bit of **scripted behavior**. We'll cover both.
diff --git a/deploy/README.md b/deploy/README.md
index 4bfe452..6b110bb 100644
--- a/deploy/README.md
+++ b/deploy/README.md
@@ -1,29 +1,9 @@
 # Remote (VPS) deployment
 
-The game server runs fine locally but two classes of data don't survive a
-`git clone`/`pull` deploy, and Python's built-in asset server doesn't hold up
-over WAN. This directory fixes both.
+The game server runs fine locally but Python's built-in asset server doesn't hold up
+over WAN. This directory fixes that.
 
-## 1. Get the data onto the VPS
-
-A `git pull` gives you the code, the card PNGs, the bundle template, and (now)
-the localization DB. It does **not** give you the built bundles or avatars —
-those are gitignored on purpose (too large / regenerable). Ship them with rsync:
-
-```bash
-# from the repo root, in Git Bash or WSL
-VPS=user@66.179.95.41 REMOTE=/home/user/Spirit-PTCGO ./deploy/sync-assets.sh
-```
-
-- **Localization strings** (the raw-key bug): fixed by `git pull` now that
-  `LocalizationDB-UTF8.db` is committed. `sync-assets.sh` verifies it matches by
-  checksum. A cold VPS was showing ~2,868 strings (just the auto-generated
-  custom-card names) instead of the full ~30,418 because the DB wasn't present.
-- **Card bundles** (`Bundle-Failed` / slow): shipped prebuilt by the script.
-  Shipping them prebuilt avoids the VPS cold-generating ~1 GB from PNGs on first
-  boot while players are waiting.
-
-## 2. Put a real static edge in front of the asset server
+## 1. Put a real static edge in front of the asset server
 
 Python's `http.server` writes each ~84 MB set bundle in one `wfile.write()` with
 no HTTP Range / resume. Over WAN that truncates. Front it with nginx (recommended)
@@ -36,28 +16,41 @@ client ──HTTP :8000──> nginx (cache + range) ──> Python asset server
 Run the Python server on 8001 so nginx can own the public port:
 
 ```bash
-SPIRIT_HTTP_PORT=8001 SPIRIT_PUBLIC_HOST=66.179.95.41 python -m spirit.main
+SPIRIT_HTTP_PORT=8001 SPIRIT_PUBLIC_HOST=YOUR_VPS_IP python -m spirit.main
 ```
 
 `AssetURL` is built from the client's `Host` header, so it keeps resolving to
 `:8000` (nginx) with no server code change.
 
-- **nginx** (built-in disk cache + byte-range): see `nginx-spirit.conf` — install
-  steps are in the file header.
-- **Caddy** (simpler, streams robustly; response caching needs the Souin plugin):
-  see `Caddyfile`.
+### nginx (recommended — built-in disk cache + byte-range)
+
+Stand up the edge on the VPS:
+
+```bash
+sudo cp deploy/nginx-spirit.conf /etc/nginx/sites-available/spirit
+sudo ln -s /etc/nginx/sites-available/spirit /etc/nginx/sites-enabled/
+sudo mkdir -p /var/cache/spirit_assets && sudo chown www-data:www-data /var/cache/spirit_assets
+sudo nginx -t && sudo systemctl reload nginx
+```
+
+Then start the game server on 8001 (command above). Firewall: open `8000` (nginx)
+and `39389` (TCP game server); keep `8001` closed — nginx reaches Python over loopback.
+
+### Caddy (simpler; streams robustly, but response caching needs the Souin plugin)
+
+See `Caddyfile`.
 
 ### Verify range/resume works
 
 ```bash
 # should return HTTP/1.1 206 Partial Content and a Content-Range header
-curl -s -D- -o /dev/null -r 0-1023 http://66.179.95.41:8000/en_US/en_US_SWSH8.unity3d
+curl -s -D- -o /dev/null -r 0-1023 http://YOUR_VPS_IP:8000/en_US/en_US_SWSH8.unity3d
 # second hit should show X-Cache-Status: HIT (nginx)
-curl -s -D- -o /dev/null http://66.179.95.41:8000/en_US/en_US_SWSH8.unity3d | grep -i x-cache
+curl -s -D- -o /dev/null http://YOUR_VPS_IP:8000/en_US/en_US_SWSH8.unity3d | grep -i x-cache
 ```
 
-## 3. (Optional) config.py default host
+## 2. (Optional) config.py default host
 
 `spirit/config.py` defaults `PUBLIC_HOST` to a hardcoded IP. On the VPS always
-set `SPIRIT_PUBLIC_HOST=66.179.95.41` (env) rather than relying on the committed
+set `SPIRIT_PUBLIC_HOST=YOUR_VPS_IP` (env) rather than relying on the committed
 default — it's the address the Warg login handshake redirects clients to for TCP.