tigerstyle-whiskers/docs/DEVELOPER.md

TigerStyle Whiskers Documentation - Developer Guide

This guide is for developers who need to build, deploy, or contribute to the documentation site.

🐳 Docker Deployment

Prerequisites

• Docker and Docker Compose
• Caddy Docker Proxy network setup
• Domain configured for whiskers.$DOMAIN

Quick Deployment

# Build and start the container
docker compose up -d

# Check container status
docker compose ps

# View logs
docker compose logs tigerstyle-whiskers-docs

# Stop and remove
docker compose down

Domain Access

The container is configured to be accessible via Caddy Docker Proxy at:

https://whiskers.example.com

Replace example.com with your actual domain set in the DOMAIN environment variable.

🛠️ Development Setup

Local Development

npm install
npm run dev          # Start development server
npm run build        # Build for production
npm run preview      # Preview production build

Visit http://localhost:4323/whiskers to view the documentation.

Available Scripts

npm run astro        # Run Astro CLI commands
npm run astro check  # Validate configuration

🐳 Docker Architecture

Multi-stage Build

1. Builder Stage: Node.js 18 Alpine for building the Astro site
2. Production Stage: Caddy 2 Alpine for serving static files

Caddy Configuration

• Compression: Gzip encoding for all responses
• Security Headers: XSS protection, MIME sniffing prevention
• Caching: Aggressive caching for static assets (1 year)
• Health Check: /health endpoint for monitoring
• SPA Routing: Fallback to index.html for client-side routing

Environment Variables

DOMAIN=example.com              # Your base domain
NODE_ENV=production            # Environment mode
SITE_TITLE=TigerStyle Whiskers Documentation
SITE_DESCRIPTION=WordPress GDPR Compliance Plugin Documentation

📁 Project Structure

docs/
├── public/                    # Static assets
├── src/
│   ├── components/           # Astro components
│   │   └── AlpineInit.astro # Alpine.js initialization
│   ├── content/docs/        # Documentation content
│   └── assets/              # Images and other assets
├── astro.config.mjs         # Astro configuration
├── package.json             # Dependencies and scripts
├── Dockerfile               # Multi-stage Docker build
├── Caddyfile               # Caddy web server config
├── docker-compose.yml      # Container orchestration
└── .dockerignore           # Docker build exclusions

🚨 Troubleshooting

Container Issues

# Check container logs
docker compose logs tigerstyle-whiskers-docs

# Verify Caddyfile syntax
docker run --rm -v $(pwd)/Caddyfile:/etc/caddy/Caddyfile caddy:2-alpine caddy validate --config /etc/caddy/Caddyfile

# Check health status
docker inspect tigerstyle-whiskers-docs --format '{{.State.Health.Status}}'

Build Issues

# Clear npm cache
npm cache clean --force

# Remove node_modules and reinstall
rm -rf node_modules package-lock.json
npm install

# Check Node.js version
node --version  # Should be 18+

Deployment Issues

• Verify Caddy Docker Proxy network exists: docker network ls
• Check domain DNS configuration
• Ensure DOMAIN environment variable is set

📈 Performance Optimization

Build Optimizations

• Tree-shaking for unused code elimination
• Minification of CSS and JavaScript
• Image optimization and responsive images
• Critical CSS inlining

Serving Optimizations

• Caddy's efficient static file serving
• Gzip compression (6 levels)
• Browser caching headers
• CDN-ready static assets

🔧 Content Management

Adding New Pages

1. Create Markdown/MDX file in appropriate src/content/docs/ subdirectory
2. Add frontmatter with title and description
3. Update sidebar navigation in astro.config.mjs if needed
4. Build and test locally

Interactive Components

Alpine.js stores in src/components/AlpineInit.astro:

• Consent Demo: Privacy banner simulation
• Privacy Configurator: Settings generator
• Compliance Checker: Audit checklist
• Cookie Explorer: Cookie category browser
• Geographic Simulator: Location-based compliance

🤝 Contributing to Documentation

1. Edit content in src/content/docs/
2. Test changes locally with npm run dev
3. Build and test production version with npm run build && npm run preview
4. Commit changes to version control

The documentation automatically rebuilds when the container is restarted.

🔗 Technical References

• Astro Documentation
• Starlight Documentation
• Alpine.js Documentation
• Caddy Documentation
• Docker Compose Documentation