Static hosting Orchestrator

A minimal vercel-inspired static hosting orchestrator for deploying static sites. Uses Docker for builds, MinIO for S3-compatible storage, and Nginx for reverse proxy routing — all wrapped in a fast, modern backend with a beautiful, intuitive UI for managing deployments and projects.

Features

• 🚀 Automated Deployments: Deploy static sites from GitHub repositories
• 🔄 Webhook Integration: Auto-deploy on Git push events
• 🐳 Docker Builds: Isolated build environment for each deployment
• 📦 S3 Storage: MinIO for reliable artifact storage
• 🔁 Retry Logic: Automatic retry with exponential backoff (3 attempts)
• ⏮️ Rollback: Easy rollback to previous successful deployments
• 📊 Deployment History: Track all deployments with logs
• 🔧 Auto Nginx Config: Automatic reverse proxy configuration

Prerequisites

• Node.js 18+
• Docker Desktop (running)
• Git

Quick Start

1. Clone and Install

git clone <your-repo>
cd infra-orchestrator
npm install

2. Configure Environment

cp .env.example .env

Edit .env if needed (defaults work for local development).

3. Start Services

# Start Docker containers (MinIO, Nginx, MongoDB)
npm run docker:up / docker-compose up -d

# Start the orchestrator
npm run dev

The services will be available at:

• Orchestrator API: http://localhost:3000
• MinIO Console: http://localhost:9001 (minioadmin/minioadmin)
• Nginx Proxy: http://localhost:8080
• MongoDB: localhost:27017

API Endpoints

Projects

# Create a project
POST /api/projects
{
  "name": "my-app",
  "githubUrl": "https://github.com/user/repo",
  "branch": "main",
  "buildCommand": "npm run build",
  "outputDir": "dist"
}

# Get all projects
GET /api/projects

# Get single project
GET /api/projects/:id

# Update project
PATCH /api/projects/:id

# Delete project
DELETE /api/projects/:id

# Trigger manual deployment
POST /api/projects/:id/deploy

# Get project deployments
GET /api/projects/:id/deployments

Deployments

# Get all deployments
GET /api/deployments

# Get single deployment
GET /api/deployments/:id

# Get deployment logs
GET /api/deployments/:id/logs

# Rollback to deployment
POST /api/deployments/:id/rollback

# Cancel queued deployment
POST /api/deployments/:id/cancel

# Delete deployment
DELETE /api/deployments/:id

Webhooks

# GitHub webhook endpoint (configure in GitHub)
POST /api/webhook/github

# Test webhook
POST /api/webhook/test
{
  "projectId": "project-id-here"
}

# Get webhook config instructions
GET /api/webhook/config/:projectId

System

# Health check
GET /api/system/health

# Get statistics
GET /api/system/stats

# Get queue status
GET /api/system/queue

Usage Example

1. Create a Project

curl -X POST http://localhost:3000/api/projects \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-portfolio",
    "githubUrl": "https://github.com/yourusername/portfolio",
    "branch": "main",
    "buildCommand": "npm ci && npm run build",
    "outputDir": "dist"
  }'

2. Trigger Deployment

curl -X POST http://localhost:3000/api/projects/{PROJECT_ID}/deploy

3. Access Deployed Site

Once deployment succeeds, your site will be available at:

http://localhost:8080/{project-name}/

4. Setup GitHub Webhook (Optional)

1. Get webhook configuration:

curl http://localhost:3000/api/webhook/config/{PROJECT_ID}

2. In your GitHub repo:
   • Go to Settings > Webhooks > Add webhook
   • Set Payload URL to: http://your-server:3000/api/webhook/github
   • Content type: application/json
   • Events: Just the push event
   • Save

Now deployments will trigger automatically on git push!

Project Structure

src/
├── api/
│   ├── routes/          # API route definitions
│   └── index.ts         # Route initialization
├── config/
│   ├── logger.ts        # Winston logger
│   ├── mongoose.ts      # MongoDB connection
│   ├── morgan.ts        # HTTP request logging
│   └── orchestratorConfig.ts  # Environment config
├── controllers/         # Request handlers
│   ├── project.controller.ts
│   ├── deployment.controller.ts
│   ├── webhook.controller.ts
│   └── system.controller.ts
├── models/              # MongoDB schemas
│   ├── project.model.ts
│   └── deployment.model.ts
├── services/            # Business logic
│   ├── docker.service.ts      # Docker build operations
│   ├── storage.service.ts     # MinIO/S3 operations
│   ├── nginx.service.ts       # Nginx config generation
│   └── buildQueue.service.ts  # Build queue with retry
├── lib/                 # Utilities
│   ├── error.ts         # Error handling
│   └── validate.ts      # Request validation
├── utils/
│   └── ApiError.ts      # Custom error class
└── index.ts             # Application entry point

How It Works

1. Project Creation: Define your project with GitHub URL and build commands
2. Webhook/Manual Trigger: Deployment is triggered via webhook or manually
3. Queue: Deployment is added to the build queue
4. Clone: Repository is cloned to workspace
5. Build: Docker container builds the project
6. Upload: Built files are uploaded to MinIO
7. Configure: Nginx config is regenerated and reloaded
8. Serve: Site is accessible via Nginx at /project-name/

Configuration

Environment Variables

# Server
NODE_ENV=development
PORT=3000

# Database
DB_CONNECTION=mongodb://localhost:27017/infra-orchestrator

# MinIO
MINIO_ENDPOINT=localhost
MINIO_PORT=9000
MINIO_ACCESS_KEY=minioadmin
MINIO_SECRET_KEY=minioadmin
MINIO_BUCKET=deployments

# Nginx
NGINX_HOST=localhost
NGINX_PORT=8080
NGINX_CONFIG_PATH=./nginx/conf.d

# Build
MAX_RETRY_ATTEMPTS=3
BUILD_TIMEOUT_MINUTES=15
WORKSPACE_DIR=./workspace

# Webhook (optional)
WEBHOOK_SECRET=your-secret-here

Deployment Flow

GitHub Push
    ↓
Webhook Received
    ↓
Create Deployment Record
    ↓
Add to Build Queue
    ↓
Clone Repository
    ↓
Build in Docker
    ↓ (retry up to 3x on failure)
Upload to MinIO
    ↓
Update Nginx Config
    ↓
Deployment Live! 🎉

Rollback

If a deployment fails or you need to revert:

# List deployments
GET /api/projects/{PROJECT_ID}/deployments

# Rollback to specific deployment
POST /api/deployments/{DEPLOYMENT_ID}/rollback

Monitoring

View Logs

# Deployment logs
GET /api/deployments/{DEPLOYMENT_ID}/logs

# System stats
GET /api/system/stats

# Queue status
GET /api/system/queue

Docker Logs

# View all container logs
npm run docker:logs

# View specific container
docker logs infra-minio
docker logs infra-nginx

Troubleshooting

Docker not found

# Verify Docker is running
docker --version
docker ps

MinIO connection failed

# Check MinIO is running
docker ps | grep minio

# Access MinIO console
open http://localhost:9001

Build fails

• Check deployment logs: GET /api/deployments/{id}/logs
• Verify build command works locally
• Check Docker has enough resources
• Ensure output directory is correct

Nginx not serving files

# Check nginx config
cat nginx/conf.d/deployments.conf

# Reload nginx manually
docker exec infra-nginx nginx -s reload

Development

# Start in dev mode with hot reload
npm run dev

# Build TypeScript
npm run build

# Start production build
npm start

Production Deployment

For production use:

1. Set NODE_ENV=production in .env
2. Configure proper MongoDB connection string
3. Set WEBHOOK_SECRET for GitHub webhooks
4. Use proper domain names in nginx config
5. Configure SSL/TLS certificates
6. Set up proper monitoring and logging
7. Consider using managed MinIO or S3
8. Run behind a proper reverse proxy (Caddy/Traefik)

Windows Notes

This project works on Windows using:

• Docker Desktop for Windows
• Git Bash or PowerShell
• Node.js for Windows

Make sure Docker Desktop is running before starting the orchestrator.

License

MIT

Contributing

Contributions welcome! This is a portfolio/learning project, so feel free to:

• Add features
• Fix bugs
• Improve documentation
• Share feedback

Future Enhancements

• Multiple build runtimes (Python, Go, etc.)
• Custom domains
• SSL certificate management
• Build caching
• Environment variable management UI
• Deployment preview URLs
• Team/user management
• API authentication
• Metrics and analytics
• Slack/Discord notifications