echoes-of-the-ash/docs/archive/PWA_QUICKSTART.md

🎮 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

./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

# 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

cd pwa
npm install
cd ..

Step 2: Add JWT Secret to .env

# Generate secure key
openssl rand -hex 32

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

Step 3: Run Migration

docker exec -it echoes_of_the_ashes_bot python migrate_web_auth.py

Step 4: Build & Deploy

docker-compose up -d --build echoes_of_the_ashes_api echoes_of_the_ashes_pwa

---

🔍 Troubleshooting

API Not Starting

# 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

# 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

# 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

# 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

# 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.