242 lines
5.1 KiB
Markdown
242 lines
5.1 KiB
Markdown
# 🎮 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.
|