Static Frontend Deployment Guide

Complete guide for building and deploying the docs-angular static site to gograb.space/docs.

Overview

The docs-angular app can be built as a static Angular application that reads documentation from the backend-docs-api. This allows hosting the frontend separately from the API.

Architecture

flowchart LR
    User["User Browser"] -->|HTTPS| StaticSite["gograb.space/docs<br/>(Static Files)"]
    StaticSite -->|REST API| DocsAPI["backend-docs-api<br/>Railway"]
    DocsAPI -->|Read/Write| MongoDB["MongoDB<br/>test-modules"]

Step 1: Update Production Environment

Ensure production environment points to Railway API:

// apps/docs-angular/src/environments/environment.prod.ts
export const environment = {
  production: true,
  docsApiUrl: 'https://your-docs-api.railway.app/docs-api',
  wsUrl: 'wss://your-docs-api.railway.app',
  enableCloudSync: true,
  enableAnalytics: true,
};

Step 2: Build Production Bundle

# Build docs-angular for production
nx build docs-angular --configuration=production

Expected output:

✔ Browser application bundle generation complete.
✔ Copying assets complete.
✔ Index html generation complete.

Initial chunk files   | Names         | Raw size
main-HASH.js          | main          | 450.2 kB
polyfills-HASH.js     | polyfills     | 90.1 kB
styles-HASH.css       | styles        | 125.3 kB

Output location: dist/apps/docs-angular/browser

Step 3: Test Production Build Locally

# Serve the production build locally
nx serve-static docs-angular

Navigate to http://localhost:5010 and verify:

• App loads correctly
• Documentation pages render
• API calls go to Railway (check Network tab)
• Analytics tracking works
• Search functionality works

Step 4: Deployment Options

Option 1: Copy to Existing gograb.space/docs

If you have access to the gograb.space server:

# Copy build output to server
scp -r dist/apps/docs-angular/browser/* [email protected]:/var/www/gograb.space/docs/

Option 2: Deploy to Railway (Static Site)

Create a new Railway service for static hosting:

# In Railway dashboard:
# 1. Create new service: "docs-angular-static"
# 2. Connect to GitHub repo
# 3. Set build command: nx build docs-angular --configuration=production
# 4. Set start command: npx serve dist/apps/docs-angular/browser -p $PORT

Option 3: Deploy to Vercel

# Install Vercel CLI
npm i -g vercel

# Deploy
cd dist/apps/docs-angular/browser
vercel --prod

Option 4: Deploy to Cloudflare Pages

1. Go to Cloudflare Pages dashboard
2. Create new project
3. Connect to GitHub
4. Build settings:
   • Build command: nx build docs-angular --configuration=production
   • Output directory: dist/apps/docs-angular/browser
5. Deploy

Step 5: Configure Domain

For gograb.space/docs Subdirectory

If deploying to a subdirectory, update the base href:

// apps/docs-angular/src/index.html
<base href="/docs/">

Rebuild:

nx build docs-angular --configuration=production --base-href=/docs/

For Custom Domain

If using a custom domain (e.g., docs.gograb.space):

1. Add CNAME record: docs.gograb.space → Railway/Vercel/Cloudflare
2. Update CORS in backend-docs-api:
   • Add https://docs.gograb.space to ALLOWED_ORIGINS
3. Update environment.prod.ts if needed

Step 6: Verify Production Deployment

Test Checklist

• Navigate to https://gograb.space/docs (or your domain)
• Homepage loads correctly
• Documentation pages render
• Search works (⌘K / Ctrl+K)
• Navigation sidebar works
• Language switching works
• Admin panel loads (if authenticated)
• Analytics tracking works
• API calls succeed (check Network tab)
• WebSocket connects (if applicable)
• No console errors

API Connection Test

Open browser console:

// Test API connection
fetch('https://your-docs-api.railway.app/docs-api/health')
  .then(r => r.json())
  .then(d => console.log('✅ API Health:', d))
  .catch(e => console.error('❌ API Error:', e));

Analytics Test

// Test analytics tracking
fetch('https://your-docs-api.railway.app/docs-api/analytics/page-views', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    path: '/test',
    project: 'test',
    language: 'en'
  })
})
  .then(r => r.json())
  .then(d => console.log('✅ Analytics tracked:', d))
  .catch(e => console.error('❌ Analytics error:', e));

Step 7: Configure CDN (Optional)

For better performance, configure CDN caching:

Cloudflare

1. Add page rule for /docs/*
2. Cache Level: Standard
3. Edge Cache TTL: 2 hours
4. Browser Cache TTL: 4 hours

Cache Headers

Configure your server to send:

Cache-Control: public, max-age=3600

For static assets (JS, CSS):

Cache-Control: public, max-age=31536000, immutable

Performance Optimization

Bundle Analysis

# Analyze bundle size
nx build docs-angular --configuration=production --stats-json

# View bundle analyzer
npx webpack-bundle-analyzer dist/apps/docs-angular/browser/stats.json

Optimization Tips

1. Enable compression: Gzip/Brotli on server
2. Lazy load routes: Already configured
3. Image optimization: Use WebP format
4. Preload critical assets: Add to index.html
5. Service Worker: Consider adding for offline support

Monitoring

Analytics Dashboard

Monitor your deployment:

1. Navigate to /admin/analytics
2. View real-time usage data
3. Export analytics reports

Error Monitoring

Add error tracking (optional):

// In main.ts or app.config.ts
import * as Sentry from '@sentry/angular';

Sentry.init({
  dsn: 'your-sentry-dsn',
  environment: 'production',
});

Rollback Procedure

If deployment fails:

1. Keep previous build: cp -r dist/apps/docs-angular/browser dist/backup
2. If issues occur, restore: cp -r dist/backup/* /var/www/gograb.space/docs/
3. Check API logs for errors
4. Verify environment variables

Continuous Deployment

GitHub Actions (Optional)

Create .github/workflows/deploy-docs.yml:

name: Deploy Docs

on:
  push:
    branches: [main]
    paths:
      - 'apps/docs-angular/**'
      - 'docs/**'

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
      - run: yarn install
      - run: nx build docs-angular --configuration=production
      - run: ./deployment/deploy-docs-frontend.sh

Troubleshooting

Build Fails

Problem: Production build fails

Solution:

1. Check for TypeScript errors: nx lint docs-angular
2. Verify all imports are correct
3. Check bundle size limits
4. Clear NX cache: nx reset

API Connection Fails

Problem: Frontend can't connect to API

Solution:

1. Verify environment.prod.ts has correct API URL
2. Check CORS configuration in backend-docs-api
3. Ensure Railway API is deployed and healthy
4. Check browser console for CORS errors

Routes Not Working

Problem: Direct URL navigation fails (404)

Solution:

1. Configure server for SPA routing
2. Add rewrite rules to serve index.html for all routes
3. For Nginx: try_files $uri $uri/ /index.html;
4. For Apache: Use .htaccess with RewriteRule

Assets Not Loading

Problem: CSS/JS files not loading

Solution:

1. Check base href is correct
2. Verify asset paths in build output
3. Check server MIME types
4. Review browser console for 404 errors

Performance Benchmarks

Expected Metrics

Lighthouse Score Targets

• Performance: >90
• Accessibility: >95
• Best Practices: >90
• SEO: >95

Security

Content Security Policy

Add CSP headers:

Content-Security-Policy: default-src 'self'; 
  script-src 'self' 'unsafe-inline' 'unsafe-eval'; 
  style-src 'self' 'unsafe-inline'; 
  connect-src 'self' https://your-docs-api.railway.app;

HTTPS

Ensure all connections use HTTPS in production:

• Frontend: https://gograb.space/docs
• API: https://your-docs-api.railway.app
• WebSocket: wss://your-docs-api.railway.app

Maintenance

Regular Updates

1. Weekly: Check for dependency updates
2. Monthly: Review bundle size
3. Quarterly: Update Angular version

Monitoring

1. Daily: Check error logs
2. Weekly: Review analytics data
3. Monthly: Performance audit

Related Documentation

• Deployment Guide
• Local Testing Guide
• API Reference