first template launch
This commit is contained in:
Michael DiLeo
266
README.md
266
README.md
@@ -1,3 +1,265 @@
|
||||
# Keyboard-Vagabond-Web
|
||||
# Keyboard Vagabond Web
|
||||
|
||||
static website landing page for Keyboard Vagabond
|
||||
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! 🚀**
|
||||
Reference in New Issue
Block a user