# HEAD OR TAIL — Central Deployment (Stage 1)

This is the **server foundation**: PostgreSQL schema, the money chain
(admin → agent → cashier → player) with a dual-entry ledger, and the central
game loop with the margin-safe payout engine (85% payout / 10% house / 5% jackpot,
near-miss 2×, ≥5-ticket clean-sweep cashback).

The role **pages** (kiosk, cashier, agent, admin) come in Stages 2–4. The server
already serves any `.html` you drop beside it, so pages slot in as they're built.

---

## Files

| File | Purpose |
|------|---------|
| `schema.sql` | PostgreSQL tables |
| `config.py` | All tunable values — the reserve dial, tiers, timing, DB connection |
| `engine.py` | Pure payout logic (safe-outcome filter, near-miss, cashback) — testable |
| `db.py` | PostgreSQL data layer + dual-entry ledger |
| `server.py` | Central game loop, WebSocket stream, role APIs |
| `requirements.txt` | Python dependencies |

---

## 1. Prepare the Contabo VPS (Ubuntu)

SSH in as root (IP + password are in your Contabo welcome email / panel):

```bash
ssh root@YOUR_CONTABO_IP
apt update && apt upgrade -y
apt install -y python3 python3-pip python3-venv postgresql postgresql-contrib
```

## 2. Create the database

```bash
sudo -u postgres psql
```

Inside psql (change the password to a strong one, and match it in `config.py`):

```sql
CREATE DATABASE headortail;
CREATE USER hot_user WITH PASSWORD 'CHANGE_THIS_PASSWORD';
GRANT ALL PRIVILEGES ON DATABASE headortail TO hot_user;
\c headortail
GRANT ALL ON SCHEMA public TO hot_user;
\q
```

## 3. Upload the code

From your Windows machine (or use WinSCP / FileZilla), copy the files to the VPS,
e.g. into `/opt/headortail/`. Then load the schema:

```bash
cd /opt/headortail
psql "postgresql://hot_user:CHANGE_THIS_PASSWORD@127.0.0.1:5432/headortail" -f schema.sql
```

## 4. Configure

Edit `config.py`:
- Set `DB_DSN` with the password you chose.
- Confirm the reserve dial: `PAYOUT_RATE = 0.85`, `HOUSE_RATE = 0.10`, `JACKPOT_RATE = 0.05`.
- Leave `TEST_MODE = False` for real play (only set `True` to verify wins during testing).

## 5. Install Python deps and run

```bash
cd /opt/headortail
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
python3 server.py
```

You should see:

```
HEAD OR TAIL central server | HTTP :3002  WS :9876
Reserve: payout 85% / house 10% / jackpot 5%
```

The game loop now runs centrally and the round number persists across restarts.

## 6. Open the firewall (raw-IP testing)

```bash
ufw allow 3002/tcp
ufw allow 9876/tcp
ufw allow OpenSSH
ufw enable
```

Now reachable at `http://YOUR_CONTABO_IP:3002/` (pages arrive in Stages 2–4).

## 7. Keep it running (so it survives logout / reboot)

Create `/etc/systemd/system/headortail.service`:

```ini
[Unit]
Description=Head Or Tail central server
After=network.target postgresql.service

[Service]
WorkingDirectory=/opt/headortail
ExecStart=/opt/headortail/venv/bin/python3 server.py
Restart=always
User=root

[Install]
WantedBy=multi-user.target
```

```bash
systemctl daemon-reload
systemctl enable --now headortail
systemctl status headortail      # check it's running
journalctl -u headortail -f      # live logs
```

---

## Default admin

On first run an admin is created from `config.py`:
`DEFAULT_ADMIN_USER = "admin"`, `DEFAULT_ADMIN_PASS = "admin"`.
**Change the password** after the admin page ships in Stage 4 (or via SQL now).

## Verify the engine math (no DB needed)

```bash
python3 engine.py
```

Prints a sample round showing the chosen board never exceeds the 85% ceiling.

---

## What Stage 1 does and does NOT include

**Included:** Postgres schema, money chain + dual-entry ledger, terminal
activation, player sessions with Fund/Real wallets (fund-first draw), the central
round loop, the margin-safe payout engine (tiers, near-miss, cashback), jackpot &
house accumulation, round reports.

**Coming next:**
- Stage 2 — **Kiosk** page (game animation, sequential coins, jackpot + `play.png` header).
- Stage 3 — **Cashier** page (betting UI, wallets, silent local printing, redeem, cashback disbursement).
- Stage 4 — **Agent & Admin** pages (funding, cashier reassignment, reports, the reserve dial).

## Security reminder

You're on raw `http://` for testing. **Before taking real customer cash**, register
a domain (~$10/yr), point it at this IP, and add a free Let's Encrypt certificate so
traffic is encrypted (`https://` / `wss://`). That's a server-config step, not a code
rewrite — the software already works either way.