Imperium Maledictum Digital

Appearance

Documentation Deployment Guide ​

This guide covers deploying the VitePress documentation to Cloudflare Workers.

Why Cloudflare Workers? ​

As of 2024-2025, Cloudflare recommends using Workers for all new projects, including static sites:

  • Unified Platform: Both your app and docs on the same infrastructure
  • Better Performance: Edge computing with zero cold starts
  • Static Asset Support: Workers now support static asset hosting
  • Advanced Features: Headers manipulation, redirects, authentication

Prerequisites ​

  1. Cloudflare account
  2. Wrangler CLI installed
  3. Domain configured in Cloudflare (for custom domain)

Deployment Steps ​

1. Build Documentation ​

bash
npm run docs:build

This creates optimized static files in dist-docs/.

2. Deploy to Cloudflare Workers ​

bash
npm run docs:deploy

This command:

  1. Builds the documentation
  2. Deploys to Cloudflare Workers using wrangler-docs.toml

3. Configure Custom Domain ​

After first deployment:

  1. Go to Cloudflare Dashboard → Workers & Pages
  2. Find your imperium-docs worker
  3. Go to Settings → Triggers
  4. Add custom domain: docs.maledictum.jatoft.se

Or use Wrangler CLI:

bash
wrangler domains add docs.maledictum.jatoft.se --config wrangler-docs.toml

Configuration Files ​

docs-worker.js ​

The worker handles:

  • Static asset serving from KV
  • Proper routing for VitePress
  • Security headers
  • 404 handling

wrangler-docs.toml ​

toml
name = "imperium-docs"
main = "docs-worker.js"
compatibility_date = "2024-01-01"

[site]
bucket = "./dist-docs"

[env.production]
route = "docs.maledictum.jatoft.se/*"

Development Workflow ​

Local Development ​

bash
# Start VitePress dev server
npm run docs:dev

Visit http://localhost:5173

Preview with Worker ​

bash
# Build and preview with Wrangler
npm run docs:worker:dev

Visit http://localhost:8787

Continuous Deployment ​

GitHub Actions ​

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

yaml
name: Deploy Documentation

on:
  push:
    branches: [main]
    paths:
      - 'docs/**'
      - 'docs-worker.js'
      - 'wrangler-docs.toml'
      - 'package.json'

jobs:
  deploy:
    runs-on: ubuntu-latest
    
    steps:
      - uses: actions/checkout@v4
      
      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'
          cache: 'npm'
          
      - name: Install dependencies
        run: npm ci
        
      - name: Build documentation
        run: npm run docs:build
        
      - name: Deploy to Cloudflare Workers
        uses: cloudflare/wrangler-action@v3
        with:
          apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}
          command: deploy --config wrangler-docs.toml

Required Secrets ​

Add to GitHub repository settings:

Environment-Specific Deployments ​

Staging Environment ​

Create wrangler-docs-staging.toml:

toml
name = "imperium-docs-staging"
main = "docs-worker.js"
compatibility_date = "2024-01-01"

[site]
bucket = "./dist-docs"

[env.staging]
route = "docs-staging.maledictum.jatoft.se/*"

[vars]
ENVIRONMENT = "staging"

Deploy to staging:

bash
wrangler deploy --config wrangler-docs-staging.toml --env staging

Performance Optimization ​

Caching Strategy ​

The docs worker implements aggressive caching:

javascript
cacheControl: {
  browserTTL: 60 * 60 * 24 * 365, // 1 year for assets
  edgeTTL: 60 * 60 * 24 * 30,     // 30 days on edge
  bypassCache: false,
}

Cache Purging ​

After deploying updates:

bash
# Purge all cache
wrangler cache purge --all

# Purge specific paths
wrangler cache purge "/guide/*" "/api/*"

Monitoring ​

Analytics ​

View in Cloudflare Dashboard:

  1. Workers & Pages → imperium-docs
  2. Analytics tab

Real-time Logs ​

bash
wrangler tail --config wrangler-docs.toml

Troubleshooting ​

Common Issues ​

1. Asset Not Found ​

Check that dist-docs contains built files:

bash
ls -la dist-docs/

2. Routing Issues ​

VitePress generates .html files. The worker handles:

  • /guide → /guide.html
  • /guide/installation → /guide/installation.html

3. Build Failures ​

Clear cache and rebuild:

bash
rm -rf docs/.vitepress/cache docs/.vitepress/dist dist-docs
npm run docs:build

4. Domain Not Working ​

Check DNS settings:

bash
dig docs.maledictum.jatoft.se

Should point to Cloudflare's edge network.

Security Headers ​

The worker adds security headers automatically:

  • X-Content-Type-Options: nosniff
  • X-Frame-Options: DENY
  • X-XSS-Protection: 1; mode=block
  • Referrer-Policy: strict-origin-when-cross-origin

Advanced Features ​

Password Protection ​

Add basic auth to docs-worker.js:

javascript
async function handleRequest(event) {
  const authorization = event.request.headers.get('Authorization');
  
  if (!authorization || !checkAuth(authorization)) {
    return new Response('Unauthorized', {
      status: 401,
      headers: {
        'WWW-Authenticate': 'Basic realm="Documentation"'
      }
    });
  }
  
  // Continue with normal handling...
}

Redirects ​

Add to worker for URL changes:

javascript
const redirects = {
  '/old-path': '/new-path',
  '/guide/setup': '/guide/installation'
};

if (redirects[url.pathname]) {
  return Response.redirect(url.origin + redirects[url.pathname], 301);
}

Cost Considerations ​

Workers Free Tier (as of 2025) ​

  • 100,000 requests/day
  • 10ms CPU time per request
  • Unlimited static asset requests

Documentation typically uses: ​

  • ~1ms CPU time per request
  • Minimal bandwidth
  • Well within free tier limits

Next Steps ​

  1. Deploy documentation: npm run docs:deploy
  2. Configure custom domain
  3. Set up GitHub Actions
  4. Monitor analytics
  5. Add search functionality