# GC Platform · Deployment Guide

This guide covers four deployment paths — pick the one that matches your environment. The platform is **pure static HTML/CSS/JS**, so any HTTP server (or no server at all) will work.

---

## Method 1 · Local (file://)

The simplest possible deployment: just open the file.

1. Locate `gc-platform/index.html`.
2. Double-click it in File Explorer / Finder.
3. The platform loads in your default browser.

**When to use** — personal use, demos, sharing as a zip, kiosks without internet.

**Limitations**
- Some browsers restrict `clipboard.writeText()` on `file://`. The bundled `GCUtils.copyToClipboard()` falls back to `document.execCommand('copy')` automatically.
- `localStorage` may be partitioned per-file. Theme preferences may not persist across sessions on some browsers.
- `fetch()` is **not** used anywhere on the homepage — but if you author new tools, embed JSON via `<script>` tags instead of `fetch()`.

---

## Method 2 · Nginx

Best for self-hosted production deployments on Linux / Mac.

### 2.1 Quick install (recommended)

```bash
cd gc-platform/deploy
sudo ./deploy.sh                     # default → /var/www/gc-platform
sudo ./deploy.sh /srv/www/gc         # custom directory
```

The script will:
1. Copy all platform files to the target directory
2. Apply `www-data:www-data` ownership and `755` permissions
3. Install `nginx.conf` to `/etc/nginx/sites-available/`
4. Symlink to `/etc/nginx/sites-enabled/`
5. Run `nginx -t` and reload the service

### 2.2 Manual install

```bash
# Copy platform files
sudo mkdir -p /var/www/gc-platform
sudo cp -r gc-platform/* /var/www/gc-platform/
sudo chown -R www-data:www-data /var/www/gc-platform

# Install nginx site
sudo cp gc-platform/deploy/nginx.conf /etc/nginx/sites-available/gc-platform.conf
sudo ln -s /etc/nginx/sites-available/gc-platform.conf /etc/nginx/sites-enabled/

# Adjust server_name in /etc/nginx/sites-available/gc-platform.conf if needed
sudo nginx -t
sudo systemctl reload nginx
```

### 2.3 Local hostname

Add to `/etc/hosts` (Linux/Mac) or `C:\Windows\System32\drivers\etc\hosts` (Windows) so the friendly URL resolves:

```
127.0.0.1   gc-platform.local
```

Then visit **http://gc-platform.local/** in your browser.

### 2.4 HTTPS

For production HTTPS, the easiest path is Let's Encrypt:

```bash
sudo apt install certbot python3-certbot-nginx
sudo certbot --nginx -d gc-platform.example.com
```

Certbot will edit the nginx config in place and set up auto-renewal.

---

## Method 3 · GitHub Pages

Free, fast, perfect for clubs.

1. Create a new GitHub repository, e.g. `gc-platform`.
2. Push the `gc-platform/` folder contents to the `main` branch (the **contents**, not the wrapper folder — `index.html` should be at the repo root).
3. Go to **Settings → Pages**.
4. Set **Source** to `Deploy from a branch`, branch `main`, folder `/ (root)`.
5. Save. After ~1 minute the URL `https://<your-username>.github.io/gc-platform/` is live.

To use a custom domain, add a `CNAME` file containing the domain to the repo root and configure the DNS A/CNAME record.

---

## Method 4 · Any Static Host (Vercel · Netlify · Cloudflare Pages)

All three offer free tiers and one-click static hosting.

### Vercel
```bash
npm i -g vercel
cd gc-platform
vercel deploy --prod
```
Or drag the `gc-platform` folder onto **vercel.com/new**.

### Netlify
- Drag the `gc-platform` folder onto **app.netlify.com/drop**, **or**
- Connect a GitHub repo at **app.netlify.com**. Build command: *(leave empty)*. Publish directory: `/`.

### Cloudflare Pages
- **dash.cloudflare.com → Workers & Pages → Create → Pages → Direct Upload**, drop the folder.

---

## Method 5 · Windows packaging (deploy.bat)

For Windows users who want a clean, distributable folder:

```cmd
cd gc-platform\deploy
deploy.bat
```

This produces `gc-platform/deploy-output/` containing `index.html` and all sub-modules. Zip it to share with teammates, or upload to any static host.

---

## Troubleshooting

| Symptom | Likely cause | Fix |
|---------|--------------|-----|
| **Blank page on file://** | Browser blocked an inline script | Open DevTools → Console for errors. Make sure no `fetch()` is used in your custom tools. |
| **Fonts look wrong** | Google Fonts blocked offline | The platform falls back to system serif/sans automatically. To bundle fonts, download Fraunces + Inter Tight to `assets/fonts/` and replace the `<link>` with `@font-face`. |
| **"403 Forbidden" on Nginx** | File permissions | Run `sudo chmod -R 755 /var/www/gc-platform && sudo chown -R www-data:www-data /var/www/gc-platform` |
| **`nginx -t` fails** | Config syntax error | Compare your edited `nginx.conf` against `gc-platform/deploy/nginx.conf`. Common: missing semicolons. |
| **Tool links 404 on Nginx** | Wrong document root | Confirm `root /var/www/gc-platform;` matches where you copied the files. |
| **Counters never animate** | IntersectionObserver disabled | Old browser. The numbers will simply show as `0`. Upgrade Chromium/Firefox/Safari to the latest. |
| **Theme doesn't persist** | `localStorage` blocked on `file://` | Expected. Use Method 2/3/4 to enable persistence. |

---

## Security Notes

- The bundled `nginx.conf` already adds `X-Frame-Options`, `X-Content-Type-Options`, and `X-XSS-Protection` headers.
- No analytics, cookies, or third-party tracking calls are used.
- All external assets (Google Fonts, ECharts, html2canvas) are loaded from public CDNs over HTTPS — disconnect to test offline behavior.