Keyboard-Vagabond-Web/README.md

# Keyboard Vagabond Web

Static website landing page for the Keyboard Vagabond fediverse community. This project creates an optimized, containerized website for deployment on Kubernetes.

## 🌟 Features

- **Ultra-optimized CSS**: 94.4% reduction (154KB → 8.6KB) using PurgeCSS and cssnano
- **Minified HTML**: 16.3% size reduction with html-minifier-terser  
- **Containerized**: Docker + nginx for Kubernetes deployment
- **Modern CSS Framework**: Built with Pico CSS
- **ARM64 Compatible**: Optimized for ARM-based Kubernetes clusters

## 🏗️ Project Structure

```
Keyboard-Vagabond-Web/
├── dist/                    # 🚀 Production build (optimized)
│   ├── index.html          # Minified landing page
│   ├── about.html          # Minified about page
│   ├── css/styles.css      # Optimized CSS (8.6KB)
│   └── assets/            # Static assets
├── public/                 # 📝 Development files
├── build.sh               # 🐳 Container build script
├── minify-build.js        # 🗜️  CSS/HTML optimization
├── Dockerfile             # 🐳 Container definition
├── nginx.conf             # 🌐 Web server config
└── package.json           # 📦 Dependencies & scripts
```

## 🚀 Quick Start

### Prerequisites

- **Node.js** (v16+ recommended)
- **Docker** 
- **npm**

### Development

```bash
# Clone and setup
git clone <your-repo>
cd Keyboard-Vagabond-Web
npm install

# View development version
open public/index.html
```

### Build & Deploy

```bash
# Full production build (recommended)
npm run build

# to run locally
docker build -t keyboard-vagabond-local .
docker run -d -p 8080:80 --name test-container keyboard-vagabond-local

```

## 📋 Available Scripts

| Command | Description |
|---------|-------------|
| `npm run build` | **Full production build** - Optimize + containerize + push |
| `npm run dist-minified` | Create optimized `dist/` folder (CSS + HTML minified) |
| `npm run dist` | Create `dist/` folder with CSS optimization (auto-runs PurgeCSS) |
| `npm run build-basic` | Basic build using `dist` command |
| `npm run optimize-css` | CSS optimization only (PurgeCSS) |
| `npm run clean` | Clean all build artifacts |
| `./build.sh` | Build and push Docker container |

## 🚢 Deployment Guide

### Step 1: Prepare Environment

```bash
# Ensure you have access to the registry
docker login registry.keyboardvagabond.com

# Install dependencies
npm install
```

### Step 2: Build Production Assets

```bash
# Create optimized build (recommended - includes minification)
npm run dist-minified

# OR create basic optimized build
npm run dist
```

This creates a `dist/` folder with:
- ✅ CSS optimized from 154KB to 8.6KB (94.4% reduction)
- ✅ HTML minified (16.3% reduction)
- ✅ Production-ready static files

### Step 3: Container Build & Push

```bash
# Build and push container
./build.sh
```

Or use the complete pipeline:

```bash
# Full build pipeline
npm run build
```

### Step 4: Kubernetes Deployment

The container is pushed to `registry.keyboardvagabond.com/library/keyboard-vagabond-web:latest`

Example Kubernetes deployment:

```yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: keyboard-vagabond-web
spec:
  replicas: 2
  selector:
    matchLabels:
      app: keyboard-vagabond-web
  template:
    metadata:
      labels:
        app: keyboard-vagabond-web
    spec:
      containers:
      - name: web
        image: registry.keyboardvagabond.com/library/keyboard-vagabond-web:latest
        ports:
        - containerPort: 80
        resources:
          requests:
            memory: "64Mi"
            cpu: "50m"
          limits:
            memory: "128Mi"
            cpu: "100m"
---
apiVersion: v1
kind: Service
metadata:
  name: keyboard-vagabond-web
spec:
  selector:
    app: keyboard-vagabond-web
  ports:
  - port: 80
    targetPort: 80
  type: ClusterIP
```

## 🎯 Optimization Results

| Metric | Before | After | Improvement |
|--------|--------|-------|-------------|
| **CSS Size** | 154.6KB | 8.6KB | **94.4% reduction** |
| **HTML Size** | 14.7KB | 12.3KB | **16.3% reduction** |
| **Total Saved** | - | 148.4KB | **Massive performance gain** |

## 🔧 Development Workflow

### Making Changes

1. **Edit source files** in `public/`
2. **Test locally** by opening `public/index.html`
3. **Build optimized version**: `npm run dist-minified`
4. **Test production build**: `open dist/index.html`
5. **Deploy**: `npm run build`

### CSS Customization

- **Custom styles**: Edit `public/site-styles/style.css`
- **Pico CSS**: Uses green theme with custom variables
- **Optimization**: Automatically removes unused CSS on build

### Content Updates

- **Main page**: `public/index.html`
- **About page**: `public/about.html`
- **Assets**: Add to `public/assets/`

## 🐳 Container Details

- **Base Image**: `nginx:1.25-alpine`
- **Platform**: `linux/arm64` (ARM Kubernetes optimized)
- **Port**: 80
- **Health Check**: Built-in HTTP health endpoint
- **Security**: Runs as non-root nginx user

## 🏷️ Tech Stack

- **HTML/CSS**: Semantic HTML with Pico CSS framework
- **Build Tools**: PurgeCSS, cssnano, html-minifier-terser
- **Container**: Docker + nginx
- **Deployment**: Kubernetes on ARM64 cluster
- **Registry**: Harbor (registry.keyboardvagabond.com)

## 📦 Dependencies

```json
{
  "devDependencies": {
    "purgecss": "^6.0.0",
    "cssnano": "^7.0.6", 
    "cssnano-cli": "^1.0.5",
    "html-minifier-terser": "^7.2.0"
  }
}
```

## 🚨 Troubleshooting

### Build Issues

```bash
# Clean rebuild
rm -rf dist/ node_modules/
npm install
npm run build
```

### Registry Access

```bash
# Login to registry
docker login registry.keyboardvagabond.com

# Verify access
docker pull registry.keyboardvagabond.com/library/keyboard-vagabond-web:latest
```

### Missing dist/ folder

The build script automatically creates `dist/` if missing. If you get errors:

```bash
# Manual dist creation
npm run dist-minified
```

## 📄 License

MIT License - See LICENSE file for details

## 🤝 Contributing

1. Fork the repository
2. Create feature branch
3. Make changes in `public/` directory
4. Test with `npm run dist-minified`
5. Submit pull request

---

**Ready to deploy the Keyboard Vagabond fediverse community! 🚀**