feat: complete deployment documentation and infrastructure
- Add comprehensive DEPLOYMENT.md covering entire CI/CD pipeline - Document Docker containerization, GitHub Actions, Traefik setup - Include troubleshooting guide and architecture overview - Add character integration planning document - Update Claude permissions for deployment tooling 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
Thomas Hallock
parent
91223b6f5d
commit
26f928586e
|
|
@ -124,7 +124,10 @@
|
|||
"Bash(cat:*)",
|
||||
"Bash(npm test:*)",
|
||||
"Bash(gh run list:*)",
|
||||
"Bash(gh run view:*)"
|
||||
"Bash(gh run view:*)",
|
||||
"Bash(nslookup:*)",
|
||||
"Bash(docker stop:*)",
|
||||
"Bash(open http://localhost:3000/games)"
|
||||
],
|
||||
"deny": [],
|
||||
"ask": []
|
||||
|
|
|
|||
|
|
@ -0,0 +1,157 @@
|
|||
# 🕹️ SOROBAN ARCADE - CHARACTER INTEGRATION MASTERPLAN
|
||||
|
||||
## 🎯 MISSION: Make /games look AWESOME with player characters
|
||||
|
||||
### 🎮 OVERALL VISION
|
||||
Transform the games page into a living, breathing arcade where player characters are the stars. Every element should feel like the characters are actively part of the experience.
|
||||
|
||||
---
|
||||
|
||||
## 📋 IMPLEMENTATION PHASES
|
||||
|
||||
### 🏆 PHASE 1: CHARACTER SHOWCASE HEADER
|
||||
**Location**: Between hero section and games grid
|
||||
|
||||
**Components**:
|
||||
- **Character Cards**: Large, animated character displays
|
||||
- **Stats Badges**: Games played, best scores, win streaks
|
||||
- **Level Indicators**: XP-style progression bars
|
||||
- **Quick Customization**: One-click emoji picker access
|
||||
|
||||
**Visual Style**:
|
||||
- Glassmorphism cards with character-themed gradients
|
||||
- Floating animations and hover effects
|
||||
- Achievement-style badges and progress indicators
|
||||
|
||||
---
|
||||
|
||||
### 🎯 PHASE 2: INTERACTIVE GAME RECOMMENDATIONS
|
||||
**Location**: Speech bubbles on game cards
|
||||
|
||||
**Components**:
|
||||
- **Dynamic Recommendations**: Characters "suggest" games based on personality
|
||||
- **Speech Bubbles**: Animated callouts from characters
|
||||
- **Personality System**: Different characters prefer different games
|
||||
|
||||
**Examples**:
|
||||
- 😀: "Memory Lightning is my jam! ⚡"
|
||||
- 😎: "Battle Arena - let's crush some competition! 🏟️"
|
||||
- 🦸♂️: "Number Hunter calls to my heroic side! 🎯"
|
||||
|
||||
---
|
||||
|
||||
### 📊 PHASE 3: CHARACTER VS CHARACTER DASHBOARD
|
||||
**Location**: Sidebar or bottom section
|
||||
|
||||
**Components**:
|
||||
- **Head-to-Head Stats**: Win/loss records between characters
|
||||
- **Recent Achievements**: Latest unlocked badges
|
||||
- **Challenge System**: "😀 challenges 😎 to Memory Lightning!"
|
||||
- **Leaderboard**: This week's champion display
|
||||
|
||||
---
|
||||
|
||||
### 🎨 PHASE 4: CHARACTER SELECTION OVERLAY
|
||||
**Location**: Modal/overlay when clicking game cards
|
||||
|
||||
**Components**:
|
||||
- **Character Picker**: Choose who plays this session
|
||||
- **Game Mode Toggle**: Single vs Two-player with character preview
|
||||
- **Character Readiness**: Animated characters showing they're ready to play
|
||||
- **Quick Stats**: Show character's best performance in this game
|
||||
|
||||
---
|
||||
|
||||
### ✨ PHASE 5: DYNAMIC CHARACTER INTERACTIONS
|
||||
**Location**: Throughout the page
|
||||
|
||||
**Components**:
|
||||
- **Idle Animations**: Characters doing random actions when not hovered
|
||||
- **Reaction Animations**: Characters respond to user interactions
|
||||
- **Achievement Celebrations**: Confetti and animations for milestones
|
||||
- **Character Customization**: Easy access to emoji picker with live preview
|
||||
|
||||
---
|
||||
|
||||
## 🎨 VISUAL DESIGN SYSTEM
|
||||
|
||||
### **Character Card Themes**:
|
||||
- **Player 1**: Blue gradient theme (#3b82f6 → #1d4ed8)
|
||||
- **Player 2**: Purple gradient theme (#8b5cf6 → #7c3aed)
|
||||
- **Neutral**: Multi-color rainbow gradient for shared elements
|
||||
|
||||
### **Animation Library**:
|
||||
- `characterFloat`: Gentle up/down movement
|
||||
- `characterBounce`: Excited celebration animation
|
||||
- `characterPulse`: Attention-getting effect
|
||||
- `speechBubblePop`: Smooth speech bubble appearance
|
||||
- `statCountUp`: Number counting animation for stats
|
||||
|
||||
### **Interactive States**:
|
||||
- **Idle**: Gentle floating animation
|
||||
- **Hover**: Character "looks" at cursor, slight scale up
|
||||
- **Active**: Bouncing excitement animation
|
||||
- **Achievement**: Explosion of confetti and character celebration
|
||||
|
||||
---
|
||||
|
||||
## 🚀 TECHNICAL REQUIREMENTS
|
||||
|
||||
### **Data Structure**:
|
||||
```typescript
|
||||
interface CharacterStats {
|
||||
gamesPlayed: number
|
||||
bestScores: Record<GameType, number>
|
||||
winStreak: number
|
||||
achievements: Achievement[]
|
||||
level: number
|
||||
xp: number
|
||||
}
|
||||
|
||||
interface CharacterPersonality {
|
||||
favoriteGame: GameType
|
||||
recommendationText: string
|
||||
celebrationStyle: AnimationType
|
||||
}
|
||||
```
|
||||
|
||||
### **Component Architecture**:
|
||||
- `CharacterShowcase`: Main character display component
|
||||
- `CharacterCard`: Individual character with stats
|
||||
- `SpeechBubble`: Recommendation system
|
||||
- `CharacterPicker`: Game mode selection
|
||||
- `StatsDisplay`: Progress tracking
|
||||
- `AchievementBadge`: Unlockable rewards
|
||||
|
||||
---
|
||||
|
||||
## ✅ SUCCESS METRICS
|
||||
|
||||
### **User Experience Goals**:
|
||||
- [ ] Characters feel like living personalities, not static images
|
||||
- [ ] Clear progression system motivates continued play
|
||||
- [ ] Easy character customization without leaving /games
|
||||
- [ ] Friendly competition between Player 1 and Player 2
|
||||
- [ ] Smooth animations that enhance (don't distract from) usability
|
||||
|
||||
### **Visual Impact Goals**:
|
||||
- [ ] Page feels like a premium arcade experience
|
||||
- [ ] Characters are clearly the "stars" of the show
|
||||
- [ ] Every interaction feels responsive and delightful
|
||||
- [ ] Consistent character theming throughout
|
||||
- [ ] Mobile-responsive character elements
|
||||
|
||||
---
|
||||
|
||||
## 🎯 IMPLEMENTATION ORDER
|
||||
|
||||
1. **Character Showcase Header** (Core personality display)
|
||||
2. **Quick Customization Access** (Essential UX feature)
|
||||
3. **Game Recommendations** (Personality-driven engagement)
|
||||
4. **Stats Dashboard** (Progress gamification)
|
||||
5. **Character Selection** (Enhanced game entry)
|
||||
6. **Dynamic Interactions** (Polish and delight)
|
||||
|
||||
---
|
||||
|
||||
*This plan will transform /games from a simple game list into an immersive character-driven arcade experience where players feel connected to their digital avatars!*
|
||||
|
|
@ -0,0 +1,219 @@
|
|||
# Soroban Abacus Flashcards - Production Deployment System
|
||||
|
||||
## Overview
|
||||
|
||||
The Soroban Abacus Flashcards application is deployed to production at `https://abaci.one` using a fully automated CI/CD pipeline. The system follows the established NAS deployment pattern with Docker containerization, GitHub Actions for CI/CD, Traefik reverse proxy, Watchtower for auto-updates, and Porkbun DDNS integration.
|
||||
|
||||
## Architecture
|
||||
|
||||
```
|
||||
User Request → Cloudflare → abaci.one (DDNS) → Synology NAS → Traefik → Docker Container
|
||||
```
|
||||
|
||||
### Components
|
||||
|
||||
1. **Source**: Monorepo with pnpm workspaces and Turborepo
|
||||
2. **CI/CD**: GitHub Actions with automated Docker builds
|
||||
3. **Registry**: GitHub Container Registry (ghcr.io)
|
||||
4. **Deployment**: Synology NAS with Docker Compose
|
||||
5. **Reverse Proxy**: Traefik with Let's Encrypt SSL
|
||||
6. **Auto-Updates**: Watchtower (5-minute polling)
|
||||
7. **DNS**: Porkbun DDNS for dynamic IP updates
|
||||
|
||||
## Deployment Process
|
||||
|
||||
### 1. Code Push Triggers Build
|
||||
|
||||
When code is pushed to the `main` branch:
|
||||
|
||||
1. GitHub Actions workflow (`.github/workflows/deploy.yml`) triggers
|
||||
2. Multi-stage Docker build runs:
|
||||
- Install dependencies with pnpm
|
||||
- Generate Panda CSS styled-system
|
||||
- Build Next.js app with Turborepo
|
||||
- Create optimized production image
|
||||
3. Image pushed to `ghcr.io/antialias/soroban-abacus-flashcards`
|
||||
|
||||
### 2. Automatic Deployment
|
||||
|
||||
1. Watchtower polls GitHub Container Registry every 5 minutes
|
||||
2. Detects new image version and pulls it
|
||||
3. Gracefully stops old container and starts new one
|
||||
4. Traefik automatically routes traffic to new container
|
||||
|
||||
### 3. DNS and SSL
|
||||
|
||||
1. Porkbun DDNS keeps `abaci.one` pointing to current NAS IP
|
||||
2. Traefik handles SSL certificate provisioning via Let's Encrypt
|
||||
3. Automatic HTTPS redirect and certificate renewal
|
||||
|
||||
## File Structure
|
||||
|
||||
```
|
||||
/
|
||||
├── Dockerfile # Multi-stage build configuration
|
||||
├── .github/workflows/deploy.yml # CI/CD pipeline
|
||||
├── apps/web/next.config.js # Next.js standalone output config
|
||||
├── nas-deployment/
|
||||
│ ├── docker-compose.yaml # Production container orchestration
|
||||
│ └── .env # Environment variables (not committed)
|
||||
└── DEPLOYMENT.md # This documentation
|
||||
```
|
||||
|
||||
## Key Configuration Files
|
||||
|
||||
### Dockerfile
|
||||
- Multi-stage build optimized for monorepo
|
||||
- pnpm workspace dependency management
|
||||
- Panda CSS generation step
|
||||
- Next.js standalone output for optimal Docker deployment
|
||||
- Proper static file serving configuration
|
||||
|
||||
### GitHub Actions Workflow
|
||||
- Triggers on push to main branch
|
||||
- Builds and pushes Docker images to ghcr.io
|
||||
- Uses GitHub Container Registry for hosting
|
||||
- Simplified build process (no type checking in CI)
|
||||
|
||||
### Docker Compose
|
||||
- Single service deployment
|
||||
- Traefik labels for reverse proxy routing
|
||||
- Watchtower compatibility for auto-updates
|
||||
- Environment variable configuration
|
||||
|
||||
### Next.js Configuration
|
||||
- Standalone output mode for Docker optimization
|
||||
- Build optimization settings
|
||||
- Static file serving configuration
|
||||
|
||||
## Environment Variables
|
||||
|
||||
Required in `nas-deployment/.env`:
|
||||
|
||||
```bash
|
||||
# GitHub Container Registry
|
||||
GITHUB_TOKEN=<personal_access_token>
|
||||
GITHUB_USERNAME=<username>
|
||||
|
||||
# Application
|
||||
NODE_ENV=production
|
||||
```
|
||||
|
||||
## NAS Deployment Directory
|
||||
|
||||
```
|
||||
/volume1/homes/antialias/projects/abaci.one/
|
||||
├── docker-compose.yaml
|
||||
├── .env
|
||||
└── logs/
|
||||
```
|
||||
|
||||
## Monitoring and Maintenance
|
||||
|
||||
### Checking Deployment Status
|
||||
|
||||
```bash
|
||||
# On NAS
|
||||
docker-compose ps
|
||||
docker-compose logs -f app
|
||||
|
||||
# GitHub Actions status
|
||||
gh run list --repo antialias/soroban-abacus-flashcards
|
||||
```
|
||||
|
||||
### Manual Updates
|
||||
|
||||
```bash
|
||||
# Force update (if needed)
|
||||
docker-compose pull
|
||||
docker-compose up -d
|
||||
```
|
||||
|
||||
### DNS Status
|
||||
|
||||
```bash
|
||||
# Check DNS resolution
|
||||
nslookup abaci.one
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Common Issues
|
||||
|
||||
1. **CSS not loading**: Check static file paths in Dockerfile
|
||||
2. **DNS not updating**: Verify DDNS configuration in existing updater
|
||||
3. **Container not starting**: Check environment variables and logs
|
||||
4. **SSL certificate issues**: Traefik will auto-renew, check Traefik logs
|
||||
|
||||
### Build Failures
|
||||
|
||||
1. **TypeScript errors**: Review apps/web/src files for type issues
|
||||
2. **Dependency issues**: Verify workspace dependencies are correctly referenced
|
||||
3. **Docker build timeout**: Check .dockerignore and build optimization
|
||||
|
||||
### Production Issues
|
||||
|
||||
1. **Site not accessible**: Check Traefik configuration and DNS
|
||||
2. **Auto-updates not working**: Verify Watchtower is running
|
||||
3. **Performance issues**: Monitor container resources
|
||||
|
||||
## Security
|
||||
|
||||
- Non-root user in Docker container
|
||||
- Minimal Alpine Linux base image
|
||||
- GitHub Container Registry with token authentication
|
||||
- Traefik handles SSL termination
|
||||
- No sensitive data in committed files
|
||||
|
||||
## Dependencies
|
||||
|
||||
### External Services
|
||||
- GitHub (source code and CI/CD)
|
||||
- GitHub Container Registry (image hosting)
|
||||
- Porkbun (DNS management)
|
||||
- Let's Encrypt (SSL certificates)
|
||||
|
||||
### Infrastructure
|
||||
- Synology NAS (hosting)
|
||||
- Docker and Docker Compose
|
||||
- Traefik reverse proxy
|
||||
- Watchtower auto-updater
|
||||
|
||||
## Backup and Recovery
|
||||
|
||||
### Container Recovery
|
||||
```bash
|
||||
# Stop and remove container
|
||||
docker-compose down
|
||||
|
||||
# Pull latest image
|
||||
docker-compose pull
|
||||
|
||||
# Start fresh container
|
||||
docker-compose up -d
|
||||
```
|
||||
|
||||
### Configuration Backup
|
||||
- `docker-compose.yaml` and `.env` files are backed up via NAS snapshots
|
||||
- Source code is version controlled in GitHub
|
||||
- Container images stored in GitHub Container Registry
|
||||
|
||||
## Performance Optimization
|
||||
|
||||
- Next.js standalone output reduces image size
|
||||
- Multi-stage Docker build minimizes production image
|
||||
- Panda CSS pre-compilation
|
||||
- Traefik connection pooling and compression
|
||||
- Docker layer caching in CI/CD
|
||||
|
||||
## Future Improvements
|
||||
|
||||
- Health checks in Docker configuration
|
||||
- Container resource limits
|
||||
- Monitoring and alerting integration
|
||||
- Staging environment setup
|
||||
- Database integration (if needed)
|
||||
|
||||
---
|
||||
|
||||
*This deployment system provides a production-ready, automated, and maintainable infrastructure for the Soroban Abacus Flashcards application.*
|
||||
Loading…
Reference in New Issue