# Project Startup Guide

Everything you need to do after the codebase is delivered to get Realm of Forgotten Souls running.

> **Status:** Initial scaffold — expand as features are implemented.

## 1. Third-party accounts and keys

Obtain and configure:

| Service | Purpose | Where to configure |
|---------|---------|-------------------|
| Firebase | Email verification, password recovery | `.env`: `FIREBASE_*` |
| Stripe | USD donations | `.env`: `STRIPE_*` |
| Domain/DNS | Production URLs | DNS panel, Caddy/Nginx |
| Email (optional) | Transactional email beyond Firebase | TBD |

### Firebase setup

1. Create a Firebase project at [console.firebase.google.com](https://console.firebase.google.com).
2. Enable Email/Password authentication.
3. Download service account JSON → save as `firebase-service-account.json` (gitignored).
4. Set `FIREBASE_PROJECT_ID`, `FIREBASE_API_KEY`, `FIREBASE_SERVICE_ACCOUNT_PATH` in `.env`.

### Stripe setup

1. Create a Stripe account at [stripe.com](https://stripe.com).
2. Get API keys from Dashboard → Developers → API keys.
3. Create a webhook endpoint for donation events.
4. Set `STRIPE_SECRET_KEY`, `STRIPE_PUBLISHABLE_KEY`, `STRIPE_WEBHOOK_SECRET` in `.env`.

## 2. Local development setup

```bash
# Clone
git clone <repo-url> RoFS
cd RoFS

# Environment
cp .env.example .env
# Edit .env for local values

# Infrastructure (MySQL + Redis)
docker compose -f infrastructure/docker/docker-compose.yml up -d

# API
cd apps/api && composer install && cd ../..
php -S 0.0.0.0:8080 -t apps/api/public

# World server (new terminal)
cd apps/world && go mod tidy && go run ./cmd/world

# Web client (new terminal)
cd apps/web && npm install && npm run dev
```

Open `http://localhost:5173`

## 3. First-time production setup

Follow [VpsSetupGuide.md](VpsSetupGuide.md) for VPS preparation, then:

1. Clone repo to `/opt/rofs`
2. Copy and fill `.env` with production secrets
3. Run database migrations (when available): `php apps/api/bin/migrate`
4. Seed initial content (when available): `php apps/api/bin/seed`
5. Create first admin account (when available): documented in admin handbook
6. Start all services via systemd or Docker Compose
7. Configure Caddy/Nginx for TLS and reverse proxy

## 4. Smoke test checklist

- [ ] `GET http://localhost:8080/health` returns `{"status":"ok"}`
- [ ] `GET http://localhost:8081/health` returns `{"status":"ok"}`
- [ ] Web client loads at `http://localhost:5173`
- [ ] MySQL accepts connections (`docker exec rofs-mysql mysqladmin ping`)
- [ ] Redis accepts connections (`docker exec rofs-redis redis-cli ping`)
- [ ] (Later) Register account → verify email → login → main menu → enter world

## 5. Deploying updates

```bash
cd /opt/rofs
git pull
cd apps/api && composer install --no-dev --optimize-autoloader
cd ../world && go build -o bin/world ./cmd/world
cd ../web && npm ci && npm run build
sudo systemctl restart rofs-api rofs-world
```

## 6. Backups

- **MySQL:** `docker exec rofs-mysql mysqldump -u root -p rofs > backup.sql`
- **Redis:** persistence enabled via Docker volume `redis_data`
- Schedule daily encrypted backups (cron + off-site storage) — details in deployment runbook.

## 7. Enabling DEBUG mode

In `.env`:

```
APP_DEBUG=true
API_LOG_LEVEL=debug
WORLD_LOG_LEVEL=debug
```

Restart services. Logs include stack traces, correlation IDs, and message tracing. **Never leave DEBUG on in production long-term.**

## 8. Quick troubleshooting

| Symptom | Check |
|---------|-------|
| Blank web page | Browser console; `npm run build` errors |
| API 500 | `apps/api/var/log/api.log`; set `APP_DEBUG=true` |
| WebSocket disconnect | World server logs; proxy WebSocket headers |
| Can't register/login | Firebase config; `FIREBASE_*` in `.env` |
| Donations fail | Stripe keys; webhook URL reachable |

## 9. Documentation index

- [Architecture overview](../architecture/Overview.md)
- [Creation plan](../plans/RealmCreationPlan.md)
- [VPS setup](VpsSetupGuide.md)
- [Game plan](../requirements/GamePlan.txt)
- [Requirements](../requirements/CreationRequirements.txt)