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`
|
||||
Reference in New Issue
Block a user