# 🎮 Echoes of the Ashes - PWA Quick Start

## Overview

You now have a complete Progressive Web App setup for Echoes of the Ashes! This allows players to access the game through their web browser on any device.

## 🚀 Quick Deploy (3 Steps)

### 1. Run Setup Script

```bash
./setup_pwa.sh
```

This will:
- ✅ Check/add JWT secret to .env
- ✅ Install npm dependencies
- ✅ Create placeholder icons (if ImageMagick available)
- ✅ Run database migration
- ✅ Build and start Docker containers

### 2. Verify It's Working

```bash
# Check containers
docker ps | grep echoes

# Check API
curl https://echoesoftheashgame.patacuack.net/api/

# Should return: {"message":"Echoes of the Ashes API","status":"online"}
```

### 3. Create Test Account

Open your browser and go to:
```
https://echoesoftheashgame.patacuack.net
```

You should see the login screen. Click "Register" and create an account!

---

## 📋 Manual Setup (If Script Fails)

### Step 1: Install Dependencies

```bash
cd pwa
npm install
cd ..
```

### Step 2: Add JWT Secret to .env

```bash
# Generate secure key
openssl rand -hex 32

# Add to .env
echo "JWT_SECRET_KEY=<your-generated-key>" >> .env
```

### Step 3: Run Migration

```bash
docker exec -it echoes_of_the_ashes_bot python migrate_web_auth.py
```

### Step 4: Build & Deploy

```bash
docker-compose up -d --build echoes_of_the_ashes_api echoes_of_the_ashes_pwa
```

---

## 🔍 Troubleshooting

### API Not Starting

```bash
# Check logs
docker logs echoes_of_the_ashes_api

# Common issues:
# - Missing JWT_SECRET_KEY in .env
# - Database connection failed
# - Port 8000 already in use
```

### PWA Not Loading

```bash
# Check logs
docker logs echoes_of_the_ashes_pwa

# Common issues:
# - npm install not run
# - Missing icons (creates blank screen)
# - Nginx config error
```

### Can't Connect to API

```bash
# Check if API container is running
docker ps | grep api

# Test direct connection
docker exec echoes_of_the_ashes_pwa curl http://echoes_of_the_ashes_api:8000/

# Check Traefik routing
docker logs traefik | grep echoesoftheashgame
```

### Migration Failed

```bash
# Check if bot is running
docker ps | grep bot

# Try running manually
docker exec -it echoes_of_the_ashes_db psql -U $POSTGRES_USER $POSTGRES_DB

# Then in psql:
\d players  -- See current table structure
```

---

## 🎯 What You Get

### For Players

- 🌐 **Web Access**: Play from any browser
- 📱 **Mobile Friendly**: Works on phones and tablets
- 🏠 **Install as App**: Add to home screen
- 🔔 **Notifications**: Get alerted to game events (coming soon)
- 📶 **Offline Mode**: Play without internet (coming soon)

### For You (Developer)

- ⚡ **Modern Stack**: React + TypeScript + FastAPI
- 🔐 **Secure Auth**: JWT tokens + bcrypt hashing
- 🐳 **Easy Deploy**: Docker + Traefik
- 🔄 **Auto HTTPS**: Let's Encrypt certificates
- 📊 **Scalable**: Can add more features easily

---

## 📚 Key Files

| File | Purpose |
|------|---------|
| `pwa/src/App.tsx` | Main React app |
| `api/main.py` | FastAPI backend |
| `docker-compose.yml` | Service definitions |
| `nginx.conf` | Web server config |
| `PWA_IMPLEMENTATION.md` | Full implementation details |
| `PWA_DEPLOYMENT.md` | Deployment guide |

---

## 🛠️ Next Steps

### Immediate

1. **Create Better Icons**: Replace placeholder icons in `pwa/public/`
2. **Test Registration**: Create a few test accounts
3. **Check Mobile**: Test on phone browser
4. **Monitor Logs**: Watch for errors

### Short Term

1. **Complete API**: Implement real game state endpoints
2. **Add Inventory UI**: Show player items
3. **Movement System**: Integrate with world map
4. **Combat Interface**: Basic attack/defend UI

### Long Term

1. **Push Notifications**: Web Push API integration
2. **WebSockets**: Real-time multiplayer updates
3. **Offline Mode**: Cache game data
4. **Advanced UI**: Animations, sounds, polish

---

## 📞 Need Help?

### Documentation

- `PWA_IMPLEMENTATION.md` - Complete implementation summary
- `PWA_DEPLOYMENT.md` - Detailed deployment guide
- `pwa/README.md` - PWA project documentation

### Useful Commands

```bash
# View logs
docker logs -f echoes_of_the_ashes_api
docker logs -f echoes_of_the_ashes_pwa

# Restart services
docker-compose restart echoes_of_the_ashes_api echoes_of_the_ashes_pwa

# Rebuild after code changes
docker-compose up -d --build echoes_of_the_ashes_api echoes_of_the_ashes_pwa

# Check resource usage
docker stats echoes_of_the_ashes_api echoes_of_the_ashes_pwa

# Access container shell
docker exec -it echoes_of_the_ashes_api bash
docker exec -it echoes_of_the_ashes_pwa sh
```

---

## ✅ Success Checklist

- [ ] Setup script ran without errors
- [ ] Both containers are running
- [ ] API responds at /api/
- [ ] PWA loads in browser
- [ ] Can register new account
- [ ] Can login with credentials
- [ ] JWT token is returned
- [ ] Game screen shows after login
- [ ] No console errors
- [ ] Mobile view works
- [ ] HTTPS certificate valid
- [ ] Icons appear correctly

---

**🎉 You're all set! Enjoy your new web-based game!**

For questions or issues, check the documentation files or review container logs.