Add support ticket documentation and relevant attachments
- Created new markdown file for Support Ticket - 3224942 with a link to the support page. - Added a separate markdown file for Supprt Tickets with the same link. - Updated workspace files to include new markdown files and attachments. - Added various attachments related to the support ticket, including images and PDFs.
This commit is contained in:
287
docs/projects/Pokedex.Online/setup/build.md
Normal file
287
docs/projects/Pokedex.Online/setup/build.md
Normal file
@@ -0,0 +1,287 @@
|
||||
# Build Process Documentation
|
||||
|
||||
## Overview
|
||||
|
||||
Pokedex.Online uses a multi-stage build process for frontend and backend components.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- Node.js 20+ (LTS)
|
||||
- npm 10+
|
||||
- Docker & Docker Compose (for containerized builds)
|
||||
|
||||
## Build Scripts
|
||||
|
||||
### Frontend Build
|
||||
|
||||
```bash
|
||||
# Build frontend only
|
||||
npm run build:frontend
|
||||
|
||||
# Output: dist/ directory with optimized Vue.js app
|
||||
```
|
||||
|
||||
**What it does:**
|
||||
- Compiles Vue 3 components
|
||||
- Bundles JavaScript with Vite (uses Rollup)
|
||||
- Minifies with Terser
|
||||
- Generates source maps
|
||||
- Splits vendor chunks for better caching
|
||||
- Optimizes CSS with code splitting
|
||||
- Processes assets (images, fonts)
|
||||
|
||||
**Build Optimizations:**
|
||||
- **Code Splitting**: Separate chunks for Vue, Highlight.js, Virtual Scroller
|
||||
- **Tree Shaking**: Removes unused code
|
||||
- **Minification**: Reduces bundle size
|
||||
- **Source Maps**: Enables production debugging
|
||||
- **Asset Optimization**: Inlines small assets, optimizes images
|
||||
|
||||
### Backend Build
|
||||
|
||||
```bash
|
||||
# Build backend (validation only - Node.js doesn't need compilation)
|
||||
npm run build:backend
|
||||
```
|
||||
|
||||
**What it does:**
|
||||
- Validates environment configuration
|
||||
- Checks dependencies are installed
|
||||
- No actual compilation (Node.js runs directly)
|
||||
|
||||
### Full Build
|
||||
|
||||
```bash
|
||||
# Build both frontend and backend
|
||||
npm run build
|
||||
|
||||
# Then verify the build
|
||||
npm run build:verify
|
||||
```
|
||||
|
||||
### Build Verification
|
||||
|
||||
```bash
|
||||
npm run build:verify
|
||||
```
|
||||
|
||||
**Checks:**
|
||||
- ✅ dist/ directory exists
|
||||
- ✅ index.html present
|
||||
- ✅ JavaScript bundles created
|
||||
- ✅ CSS files generated
|
||||
- ✅ Assets directory populated
|
||||
- ⚠️ Warns on large bundles (>1MB)
|
||||
- 📊 Shows total build size
|
||||
|
||||
## Build Output
|
||||
|
||||
### Frontend (`dist/`)
|
||||
|
||||
```
|
||||
dist/
|
||||
├── index.html # Entry point
|
||||
├── assets/
|
||||
│ ├── vue-vendor.*.js # Vue + Vue Router chunk
|
||||
│ ├── highlight.*.js # Highlight.js chunk
|
||||
│ ├── virtual-scroller.*.js # Virtual Scroller chunk
|
||||
│ ├── index.*.js # Main app bundle
|
||||
│ ├── index.*.css # Compiled styles
|
||||
│ └── *.{png,svg,ico} # Optimized assets
|
||||
└── vite.svg # App icon
|
||||
```
|
||||
|
||||
**Expected Sizes:**
|
||||
- Total: 2-3 MB (uncompressed)
|
||||
- vue-vendor chunk: ~500 KB
|
||||
- Main bundle: ~300-500 KB
|
||||
- Highlight.js: ~200-400 KB
|
||||
- CSS: ~50-100 KB
|
||||
|
||||
### Backend (No build output)
|
||||
|
||||
Backend runs directly from source in production container.
|
||||
|
||||
## Docker Build
|
||||
|
||||
### Build Production Images
|
||||
|
||||
```bash
|
||||
# Build both containers
|
||||
npm run docker:build
|
||||
|
||||
# Or manually
|
||||
docker compose -f docker-compose.production.yml build
|
||||
```
|
||||
|
||||
**Images created:**
|
||||
- `pokedex-frontend`: Nginx + built static files
|
||||
- `pokedex-backend`: Node.js + Express server
|
||||
|
||||
### Frontend Dockerfile (`Dockerfile.frontend`)
|
||||
|
||||
```dockerfile
|
||||
FROM nginx:alpine
|
||||
COPY dist /usr/share/nginx/html
|
||||
COPY nginx.conf /etc/nginx/conf.d/default.conf
|
||||
EXPOSE 80 443
|
||||
```
|
||||
|
||||
### Backend Dockerfile (`server/Dockerfile`)
|
||||
|
||||
```dockerfile
|
||||
FROM node:20-alpine
|
||||
WORKDIR /app
|
||||
COPY package*.json ./
|
||||
RUN npm ci --only=production
|
||||
COPY . .
|
||||
EXPOSE 3000
|
||||
CMD ["node", "oauth-proxy.js"]
|
||||
```
|
||||
|
||||
## Development vs Production
|
||||
|
||||
### Development Build
|
||||
|
||||
```bash
|
||||
npm run dev # Hot reload, no optimization
|
||||
npm run dev:full # Frontend + Backend with hot reload
|
||||
```
|
||||
|
||||
**Features:**
|
||||
- Hot Module Replacement (HMR)
|
||||
- Fast rebuilds
|
||||
- Detailed error messages
|
||||
- No minification
|
||||
- Source maps enabled
|
||||
|
||||
### Production Build
|
||||
|
||||
```bash
|
||||
npm run build # Full optimization
|
||||
npm run build:verify # Validate build
|
||||
```
|
||||
|
||||
**Features:**
|
||||
- Minified code
|
||||
- Tree shaking
|
||||
- Code splitting
|
||||
- Asset optimization
|
||||
- Production source maps
|
||||
- Vendor chunk splitting
|
||||
|
||||
## Build Configuration
|
||||
|
||||
### Vite Config (`vite.config.js`)
|
||||
|
||||
```javascript
|
||||
build: {
|
||||
target: 'es2015', // Browser compatibility
|
||||
minify: 'terser', // Minifier
|
||||
sourcemap: true, // Source maps
|
||||
rollupOptions: {
|
||||
output: {
|
||||
manualChunks: { // Chunk splitting
|
||||
'vue-vendor': ['vue', 'vue-router'],
|
||||
'highlight': ['highlight.js'],
|
||||
'virtual-scroller': ['vue-virtual-scroller']
|
||||
}
|
||||
}
|
||||
},
|
||||
chunkSizeWarningLimit: 600, // 600KB warning limit
|
||||
cssCodeSplit: true, // Split CSS per chunk
|
||||
assetsInlineLimit: 10240 // Inline <10KB assets
|
||||
}
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Build Fails
|
||||
|
||||
```bash
|
||||
# Clean and rebuild
|
||||
rm -rf dist node_modules
|
||||
npm install
|
||||
npm run build
|
||||
```
|
||||
|
||||
### Build Verification Fails
|
||||
|
||||
**Missing index.html:**
|
||||
- Check Vite config
|
||||
- Verify `index.html` exists in project root
|
||||
|
||||
**No JavaScript bundles:**
|
||||
- Check for build errors
|
||||
- Verify Vue plugin is configured
|
||||
|
||||
**Large bundle warnings:**
|
||||
- Review `manualChunks` configuration
|
||||
- Consider lazy loading components
|
||||
- Check for unnecessary dependencies
|
||||
|
||||
### Out of Memory
|
||||
|
||||
```bash
|
||||
# Increase Node.js memory
|
||||
NODE_OPTIONS="--max-old-space-size=4096" npm run build
|
||||
```
|
||||
|
||||
### Slow Builds
|
||||
|
||||
**Solutions:**
|
||||
- Enable Vite cache
|
||||
- Reduce bundle size with lazy loading
|
||||
- Use faster disk (SSD)
|
||||
- Upgrade Node.js version
|
||||
|
||||
## Performance Tips
|
||||
|
||||
1. **Lazy Load Routes**: Split Vue Router routes into separate chunks
|
||||
2. **Optimize Images**: Use WebP format, compress before build
|
||||
3. **Tree Shaking**: Ensure imports are ES modules
|
||||
4. **Bundle Analysis**: Use `rollup-plugin-visualizer`
|
||||
5. **CDN Assets**: Consider CDN for large vendor libraries
|
||||
|
||||
## CI/CD Integration
|
||||
|
||||
```yaml
|
||||
# Example GitHub Actions
|
||||
- name: Install dependencies
|
||||
run: npm ci
|
||||
|
||||
- name: Run tests
|
||||
run: npm run test:run
|
||||
|
||||
- name: Build frontend
|
||||
run: npm run build:frontend
|
||||
|
||||
- name: Verify build
|
||||
run: npm run build:verify
|
||||
|
||||
- name: Build Docker images
|
||||
run: npm run docker:build
|
||||
```
|
||||
|
||||
## Environment Variables
|
||||
|
||||
### Build-time Variables
|
||||
|
||||
No build-time environment variables required for frontend.
|
||||
|
||||
### Runtime Variables (Backend)
|
||||
|
||||
See `server/.env.example` for required variables:
|
||||
- `NODE_ENV`
|
||||
- `PORT`
|
||||
- `CHALLONGE_CLIENT_ID`
|
||||
- `CHALLONGE_CLIENT_SECRET`
|
||||
- `SESSION_SECRET`
|
||||
|
||||
## Next Steps
|
||||
|
||||
After successful build:
|
||||
|
||||
1. **Local Testing**: `npm run docker:up`
|
||||
2. **Deployment**: `npm run deploy:internal` or `npm run deploy:external`
|
||||
3. **Monitoring**: Check logs with `npm run docker:logs`
|
||||
359
docs/projects/Pokedex.Online/setup/deployment.md
Normal file
359
docs/projects/Pokedex.Online/setup/deployment.md
Normal file
@@ -0,0 +1,359 @@
|
||||
# Pokedex.Online Deployment Guide
|
||||
|
||||
## Overview
|
||||
|
||||
Pokedex.Online uses a multi-container Docker setup with:
|
||||
- **Frontend**: Nginx serving built Vue.js application
|
||||
- **Backend**: Node.js Express server (OAuth proxy + Gamemaster API)
|
||||
|
||||
## Automated Deployment (Recommended)
|
||||
|
||||
Use `deploy.sh` for a complete, automated deployment with built-in safety checks.
|
||||
|
||||
### Basic Usage
|
||||
|
||||
```bash
|
||||
# Deploy to internal network
|
||||
./deploy.sh --target internal
|
||||
|
||||
# Deploy to external (requires Cloudflare tunnel)
|
||||
./deploy.sh --target external --port 8080 --backend-port 3000
|
||||
|
||||
# Dry run (preview without deploying)
|
||||
./deploy.sh --dry-run --target internal
|
||||
```
|
||||
|
||||
### Options
|
||||
|
||||
- `--target <internal|external>` - Deployment target (default: internal)
|
||||
- `--port <number>` - Frontend HTTP port (default: 8080)
|
||||
- `--ssl-port <number>` - Frontend HTTPS port (optional)
|
||||
- `--backend-port <number>` - Backend port (default: 3000)
|
||||
- `--skip-tests` - Skip test execution
|
||||
- `--skip-build` - Skip build step (use existing dist/)
|
||||
- `--no-backup` - Skip backup creation
|
||||
- `--dry-run` - Preview without deploying
|
||||
|
||||
### What deploy.sh Does
|
||||
|
||||
The deployment script automates the entire process:
|
||||
|
||||
1. **Prerequisites Check** - Verifies Node.js, npm, and dependencies
|
||||
2. **Environment Validation** - Checks for server/.env configuration
|
||||
3. **Test Suite** - Runs frontend and backend tests
|
||||
4. **Build Process** - Builds and verifies the application
|
||||
5. **Backup Creation** - Creates timestamped backup (keeps last 5)
|
||||
6. **Deployment** - Transfers files and starts containers
|
||||
7. **Verification** - Health checks both services
|
||||
8. **Summary** - Reports deployment URLs and next steps
|
||||
|
||||
### Examples
|
||||
|
||||
```bash
|
||||
# Standard internal deployment
|
||||
./deploy.sh --target internal
|
||||
|
||||
# External deployment with custom ports
|
||||
./deploy.sh --target external --port 8080
|
||||
|
||||
# Quick deploy (skip tests, use existing build)
|
||||
./deploy.sh --skip-tests --skip-build
|
||||
|
||||
# Development iteration (no backup needed)
|
||||
./deploy.sh --no-backup --target internal
|
||||
|
||||
# Check what would happen
|
||||
./deploy.sh --dry-run
|
||||
```
|
||||
|
||||
## Manual Deployment
|
||||
|
||||
### Quick Deploy
|
||||
|
||||
```bash
|
||||
# Deploy to internal network (10.0.0.81)
|
||||
npm run deploy:pokedex
|
||||
|
||||
# Deploy to external (home.gregrjacobs.com)
|
||||
npm run deploy:pokedex -- --target external
|
||||
|
||||
# Custom ports
|
||||
npm run deploy:pokedex -- --port 8081 --backend-port 3001
|
||||
|
||||
# With HTTPS
|
||||
npm run deploy:pokedex -- --port 8080 --backend-port 3000
|
||||
```
|
||||
|
||||
## Configuration
|
||||
|
||||
### Deployment Targets
|
||||
|
||||
| Target | Host | SSH Port | Default Frontend Port | Default Backend Port |
|
||||
|--------|------|----------|----------------------|---------------------|
|
||||
| internal | 10.0.0.81 | 2323 | 8080 | 3000 |
|
||||
| external | home.gregrjacobs.com | 2323 | 8080 | 3000 |
|
||||
|
||||
### Command Line Arguments
|
||||
|
||||
- `--target <internal|external>` - Deployment target (default: internal)
|
||||
- `--port <number>` - Frontend HTTP port (default: 8080)
|
||||
- `--ssl-port <number>` - Frontend HTTPS port (optional)
|
||||
- `--backend-port <number>` - Backend API port (default: 3000)
|
||||
|
||||
## Deployment Process
|
||||
|
||||
The deploy script (`code/utils/deploy-pokedex.js`) performs:
|
||||
|
||||
1. **Build** - Runs `npm run build` locally
|
||||
2. **Connect** - SSH to Synology NAS
|
||||
3. **Transfer Files**:
|
||||
- Built `dist/` directory
|
||||
- Backend server code (`server/`)
|
||||
- Docker configuration files
|
||||
- Nginx configuration
|
||||
4. **Deploy Containers**:
|
||||
- Stops existing containers
|
||||
- Builds new images
|
||||
- Starts frontend + backend containers
|
||||
5. **Health Checks**:
|
||||
- Verifies frontend responds on configured port
|
||||
- Verifies backend responds on configured port
|
||||
6. **Rollback** - Automatically reverts on failure
|
||||
|
||||
## Docker Compose Files
|
||||
|
||||
### Production (`docker-compose.production.yml`)
|
||||
- Multi-container setup
|
||||
- Health checks enabled
|
||||
- Volume mounts for persistence
|
||||
- Container networking
|
||||
|
||||
### Development (`docker-compose.yml`)
|
||||
- Simple single-container setup
|
||||
- For local testing only
|
||||
|
||||
## Environment Variables
|
||||
|
||||
Backend requires `.env` file with:
|
||||
|
||||
```bash
|
||||
# Copy from example
|
||||
cp server/.env.example server/.env
|
||||
|
||||
# Edit with your values
|
||||
CHALLONGE_CLIENT_ID=your_client_id
|
||||
CHALLONGE_CLIENT_SECRET=your_client_secret
|
||||
REDIRECT_URI=https://yourdomain.com/oauth/callback
|
||||
SESSION_SECRET=your_random_secret
|
||||
PORT=3000
|
||||
NODE_ENV=production
|
||||
```
|
||||
|
||||
## Health Checks
|
||||
|
||||
Both containers expose health endpoints:
|
||||
|
||||
- **Frontend**: `http://localhost:8080/health`
|
||||
- **Backend**: `http://localhost:3000/health`
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Build Fails
|
||||
```bash
|
||||
# Clean and rebuild
|
||||
rm -rf dist node_modules
|
||||
npm install
|
||||
npm run build
|
||||
```
|
||||
|
||||
### Container Won't Start
|
||||
```bash
|
||||
# SSH to Synology and check logs
|
||||
ssh GregRJacobs@10.0.0.81 -p 2323
|
||||
cd /volume1/docker/pokedex-online/base
|
||||
docker compose logs
|
||||
```
|
||||
|
||||
### Port Already in Use
|
||||
```bash
|
||||
# Use different port
|
||||
./deploy.sh --target internal --port 8081 --backend-port 3001
|
||||
```
|
||||
|
||||
### Backend Can't Connect to Frontend
|
||||
- Check nginx.conf proxy settings
|
||||
- Verify backend container is on same Docker network
|
||||
- Check backend service name in nginx config matches compose file
|
||||
|
||||
## Rollback
|
||||
|
||||
### Automated Backups
|
||||
|
||||
The deploy script creates timestamped backups before each deployment in `backups/`:
|
||||
|
||||
```bash
|
||||
# List available backups
|
||||
ls -lh backups/
|
||||
|
||||
# Example:
|
||||
# backup_20240115_143022.tar.gz (5.2M)
|
||||
# backup_20240115_151534.tar.gz (5.3M)
|
||||
```
|
||||
|
||||
The script automatically keeps only the last 5 backups to save space.
|
||||
|
||||
### Rollback Procedure
|
||||
|
||||
**1. Stop Current Deployment**
|
||||
```bash
|
||||
ssh GregRJacobs@10.0.0.81 -p 2323
|
||||
cd /volume1/docker/pokedex.online
|
||||
docker compose down
|
||||
```
|
||||
|
||||
**2. Restore from Backup (Local)**
|
||||
```bash
|
||||
# Extract backup to temporary directory
|
||||
mkdir /tmp/restore
|
||||
tar -xzf backups/backup_TIMESTAMP.tar.gz -C /tmp/restore
|
||||
|
||||
# Copy files back
|
||||
rsync -av /tmp/restore/ ./
|
||||
```
|
||||
|
||||
**3. Redeploy**
|
||||
```bash
|
||||
./deploy.sh --skip-tests --target internal
|
||||
```
|
||||
|
||||
### Quick Restart
|
||||
|
||||
If you just need to restart existing containers without code changes:
|
||||
|
||||
```bash
|
||||
# On the server
|
||||
cd /volume1/docker/pokedex.online
|
||||
docker compose restart
|
||||
```
|
||||
|
||||
### Git-Based Rollback
|
||||
|
||||
Roll back to a previous commit:
|
||||
|
||||
```bash
|
||||
# Find commit to rollback to
|
||||
git log --oneline -n 10
|
||||
|
||||
# Checkout previous version
|
||||
git checkout <commit-hash>
|
||||
|
||||
# Redeploy
|
||||
./deploy.sh --target internal
|
||||
|
||||
# Return to main branch when done
|
||||
git checkout main
|
||||
```
|
||||
|
||||
### Emergency Rollback
|
||||
|
||||
If deployment completely fails and you need to restore quickly:
|
||||
|
||||
```bash
|
||||
# Stop failed deployment
|
||||
ssh GregRJacobs@10.0.0.81 -p 2323 "cd /volume1/docker/pokedex.online && docker compose down"
|
||||
|
||||
# Extract most recent backup directly on server
|
||||
LATEST_BACKUP=$(ls -t backups/backup_*.tar.gz | head -1)
|
||||
ssh GregRJacobs@10.0.0.81 -p 2323 "cd /volume1/docker/pokedex.online && tar -xzf /path/to/backup"
|
||||
|
||||
# Restart containers
|
||||
ssh GregRJacobs@10.0.0.81 -p 2323 "cd /volume1/docker/pokedex.online && docker compose up -d"
|
||||
```
|
||||
|
||||
## URLs After Deployment
|
||||
|
||||
### Internal Network
|
||||
- Frontend: http://10.0.0.81:8080
|
||||
- Backend API: http://10.0.0.81:3000
|
||||
- Backend Health: http://10.0.0.81:3000/health
|
||||
|
||||
### External
|
||||
- Frontend: http://home.gregrjacobs.com:8080
|
||||
- Backend API: http://home.gregrjacobs.com:3000
|
||||
- Backend Health: http://home.gregrjacobs.com:3000/health
|
||||
|
||||
## Pre-Deployment Checklist
|
||||
|
||||
Before running `./deploy.sh`, ensure:
|
||||
|
||||
- [ ] All tests passing (`npm run test:all`)
|
||||
- [ ] Code committed to git
|
||||
- [ ] Environment variables configured in `server/.env`
|
||||
- [ ] Build completes successfully (`npm run build`)
|
||||
- [ ] No uncommitted breaking changes
|
||||
- [ ] Deployment target accessible (ping host)
|
||||
- [ ] Previous deployment backed up (script does this automatically)
|
||||
|
||||
## Post-Deployment Checklist
|
||||
|
||||
After deployment, verify:
|
||||
|
||||
- [ ] Frontend loads: http://10.0.0.81:8080
|
||||
- [ ] Backend health check: http://10.0.0.81:3000/health
|
||||
- [ ] OAuth flow works (login with Challonge)
|
||||
- [ ] Gamemaster API accessible
|
||||
- [ ] Browser console shows no errors
|
||||
- [ ] Check Docker logs: `ssh ... && docker compose logs --tail=50`
|
||||
- [ ] Monitor backend logs in `server/logs/`
|
||||
|
||||
## Manual Deployment
|
||||
|
||||
If automated deploy fails, you can deploy manually:
|
||||
|
||||
```bash
|
||||
# 1. Build locally
|
||||
npm run build
|
||||
|
||||
# 2. SSH to Synology
|
||||
ssh GregRJacobs@10.0.0.81 -p 2323
|
||||
|
||||
# 3. Navigate to deployment directory
|
||||
cd /volume1/docker/pokedex-online/base
|
||||
|
||||
# 4. Upload files (use scp or FileStation)
|
||||
|
||||
# 5. Deploy
|
||||
docker compose -f docker-compose.yml down
|
||||
docker compose -f docker-compose.yml up -d --build
|
||||
|
||||
# 6. Check logs
|
||||
docker compose logs -f
|
||||
```
|
||||
|
||||
## Rollback
|
||||
|
||||
Automatic rollback occurs on deployment failure. Manual rollback:
|
||||
|
||||
```bash
|
||||
ssh GregRJacobs@10.0.0.81 -p 2323
|
||||
cd /volume1/docker/pokedex-online/base
|
||||
docker compose down
|
||||
docker tag <previous-image-id> pokedex-frontend:latest
|
||||
docker tag <previous-image-id> pokedex-backend:latest
|
||||
docker compose up -d
|
||||
```
|
||||
|
||||
## Production Checklist
|
||||
|
||||
Before deploying to production:
|
||||
|
||||
- [ ] Update `.env` with production credentials
|
||||
- [ ] Set `NODE_ENV=production`
|
||||
- [ ] Configure SSL/TLS certificates (if using HTTPS)
|
||||
- [ ] Update CORS origins in backend
|
||||
- [ ] Set secure session secret
|
||||
- [ ] Test locally with `docker compose -f docker-compose.production.yml up`
|
||||
- [ ] Verify health checks pass
|
||||
- [ ] Check backend can reach external APIs (Challonge, etc.)
|
||||
- [ ] Verify frontend can call backend endpoints
|
||||
- [ ] Test OAuth flow end-to-end
|
||||
137
docs/projects/Pokedex.Online/setup/discord-permissions.md
Normal file
137
docs/projects/Pokedex.Online/setup/discord-permissions.md
Normal file
@@ -0,0 +1,137 @@
|
||||
# Discord User Permissions Setup Guide
|
||||
|
||||
## Overview
|
||||
|
||||
The app now checks Discord usernames/IDs to grant developer tool access. Users must be in the allowlist to access developer features.
|
||||
|
||||
## Configuration
|
||||
|
||||
### 1. Find Your Discord Username/ID
|
||||
|
||||
You can use any of the following to identify users:
|
||||
|
||||
- **Username**: Your current Discord username (e.g., `fragginwagon`)
|
||||
- **Global Name**: Your display name (if different from username)
|
||||
- **Discord ID**: Your numeric Discord ID (e.g., `123456789012345678`)
|
||||
|
||||
**How to Find Your Discord ID:**
|
||||
1. Enable Developer Mode in Discord: Settings → Advanced → Developer Mode (ON)
|
||||
2. Right-click your username anywhere → Copy User ID
|
||||
3. Or use this Discord bot command: `/userinfo` or `!userinfo`
|
||||
|
||||
### 2. Configure Environment Variables
|
||||
|
||||
Add allowed users to your `.env` file:
|
||||
|
||||
```env
|
||||
# Discord User Permissions
|
||||
# Comma-separated list of Discord usernames, display names, or IDs
|
||||
DISCORD_ADMIN_USERS=fragginwagon,AnotherUser,123456789012345678
|
||||
```
|
||||
|
||||
**Multiple formats supported:**
|
||||
```env
|
||||
# Just usernames
|
||||
DISCORD_ADMIN_USERS=fragginwagon,coolguy99
|
||||
|
||||
# Mix of usernames and IDs
|
||||
DISCORD_ADMIN_USERS=fragginwagon,123456789012345678,coolguy99
|
||||
|
||||
# Using Discord IDs (most reliable)
|
||||
DISCORD_ADMIN_USERS=123456789012345678,987654321098765432
|
||||
```
|
||||
|
||||
### 3. Location of Configuration
|
||||
|
||||
**Development (.env file):**
|
||||
```bash
|
||||
/Users/fragginwagon/Developer/MemoryPalace/code/websites/pokedex.online/server/.env
|
||||
```
|
||||
|
||||
**Production (Docker):**
|
||||
Add to your `docker-compose.tmp.yml` or production environment:
|
||||
```yaml
|
||||
environment:
|
||||
- DISCORD_ADMIN_USERS=fragginwagon,user2,123456789012345678
|
||||
```
|
||||
|
||||
Or in your server's `.env` file that gets loaded by Docker.
|
||||
|
||||
## How It Works
|
||||
|
||||
1. User logs in with Discord OAuth
|
||||
2. Backend fetches user info from Discord API
|
||||
3. Backend checks if username, global name, OR Discord ID matches the allowlist
|
||||
4. Backend returns `permissions: ['developer_tools.view']` if user is authorized
|
||||
5. Frontend checks `hasDevAccess()` to show/hide developer tools
|
||||
|
||||
## Testing
|
||||
|
||||
### Test if you're in the allowlist:
|
||||
|
||||
1. Add your Discord username to `DISCORD_ADMIN_USERS` in `.env`
|
||||
2. Restart the backend server:
|
||||
```bash
|
||||
docker compose -f docker-compose.tmp.yml restart backend
|
||||
```
|
||||
3. Log in with Discord OAuth in the app
|
||||
4. Open Developer Tools (should now be visible if authorized)
|
||||
|
||||
### Check backend logs:
|
||||
|
||||
Look for these messages:
|
||||
```
|
||||
✅ Discord user authenticated { username: 'fragginwagon', id: '123456789012345678' }
|
||||
✅ Discord user granted developer access { username: 'fragginwagon' }
|
||||
```
|
||||
|
||||
Or if not authorized:
|
||||
```
|
||||
✅ Discord user authenticated { username: 'unauthorized', id: '999999999999999999' }
|
||||
```
|
||||
|
||||
## Security Notes
|
||||
|
||||
- **Case-insensitive matching**: Usernames are compared in lowercase
|
||||
- **Multiple formats**: Supports username, display name, and Discord ID
|
||||
- **Fallback behavior**: If Discord user info fetch fails, no permissions are granted (fail-safe)
|
||||
- **No permissions stored client-side**: Permissions are checked on every OAuth login
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
**Developer tools not appearing after adding username:**
|
||||
1. Check backend logs for "Discord user authenticated" message
|
||||
2. Verify your username matches exactly (check for typos)
|
||||
3. Try using your Discord ID instead of username (more reliable)
|
||||
4. Ensure backend restarted after changing `.env`
|
||||
|
||||
**"Failed to fetch Discord user info" in logs:**
|
||||
- OAuth token may not have `identify` scope
|
||||
- Check Discord OAuth app settings
|
||||
- Verify `VITE_DISCORD_CLIENT_ID` and `DISCORD_CLIENT_SECRET` are correct
|
||||
|
||||
## Example Configuration
|
||||
|
||||
```env
|
||||
# Development
|
||||
NODE_ENV=development
|
||||
PORT=3099
|
||||
|
||||
# Discord OAuth
|
||||
VITE_DISCORD_CLIENT_ID=your_client_id_here
|
||||
DISCORD_CLIENT_SECRET=your_client_secret_here
|
||||
VITE_DISCORD_REDIRECT_URI=http://localhost:5173/oauth/callback
|
||||
|
||||
# Allowed Users (add your Discord username or ID)
|
||||
DISCORD_ADMIN_USERS=fragginwagon,123456789012345678
|
||||
```
|
||||
|
||||
## Permission Levels
|
||||
|
||||
Currently implemented:
|
||||
- `developer_tools.view` - Access to developer tools panel and feature flags
|
||||
|
||||
Future permissions (not yet implemented):
|
||||
- `admin` - Full admin access
|
||||
- `gamemaster.edit` - Edit gamemaster data
|
||||
- `tournaments.manage` - Manage tournaments
|
||||
Reference in New Issue
Block a user