Jekyll Studio API - Next.js Backend

Backend API Next.js dengan integrasi Gemini AI untuk Jekyll Studio webapp. API ini menyediakan endpoints lengkap untuk membuat, mengelola, dan men-deploy Jekyll sites menggunakan AI.

Terinspirasi dari "Firebase Studio, tapi untuk Jekyll" membangun fondasi backend yang solid dan canggih untuk melakukan persis seperti Firebase Studio.

1. Backend Terkelola (Managed Backend): Sama seperti Firebase yang menyediakan backend siap pakai, proyek ini juga menyediakan API yang mengabstraksi semua kerumitan. Pengguna frontend tidak perlu tahu cara install Ruby, menjalankan jekyll build, atau mengelola Docker. Mereka tinggal klik satu tombol di UI.

2. Fungsi Inti Yang Sudah Siap:

   • "Authentication/Database" (Manajemen Situs): Punya sistem untuk membuat, melihat, dan menghapus "proyek" atau situs.
   • "Hosting" (Build & Serve): Punya endpoint untuk men-deploy (jekyll serve) dan membangun (jekyll build) situs.
   • "Cloud Functions" (AI & Kustomisasi): Menggunakan kekuatan AI dari Gemini sebagai "fungsi cloud" untuk men-generate seluruh struktur situs dari sebuah prompt, sesuatu yang sangat modern.
   • "Storage" (File Management): Punya API untuk eksplorasi, membaca, dan menulis file di dalam setiap situs Jekyll.

---

🚀 Features

• ✅ Gemini AI Integration - Generate Jekyll sites dari natural language prompts
• ✅ Jekyll Container Management - Automated Jekyll site creation dan building
• ✅ Real-time Updates - WebSocket untuk live updates dan file changes
• ✅ File Management - CRUD operations untuk Jekyll files
• ✅ Security - Rate limiting, CORS, input validation
• ✅ Multi-site Support - Handle multiple Jekyll sites simultaneously
• ✅ Live Preview - Development server dengan live reload

📋 Prerequisites

• Node.js 18+
• Docker & Docker Compose
• Gemini AI API Key

⚡ Quick Start

1. Clone dan Setup

git clone https://github.com/daffadevhosting/jekyll-studio-api.git
cd jekyll-studio-api

2. Install Dependencies

npm install

3. Environment Configuration

cp .env.example .env
# Edit .env dengan your API keys

4. Start Development Server

npm run dev

5. Start dengan Docker

# Start complete stack
docker-compose -f docker-compose.api.yml up -d

# Start only API + Jekyll
docker-compose -f docker-compose.api.yml up api jekyll redis

📁 Project Structure

jekyll-studio-api/
├── pages/api/                 # Next.js API routes
│   ├── sites/                # Site management endpoints
│   ├── ai/                   # AI generation endpoints
│   └── websocket.ts          # WebSocket server
├── lib/                      # Core libraries
│   ├── gemini.ts            # Gemini AI service
│   ├── jekyll-manager.ts    # Jekyll operations manager
│   └── utils.ts             # Utility functions
├── middleware/               # Security middleware
├── docker/                  # Docker configurations
├── projects/                # Generated Jekyll sites
└── templates/               # Jekyll templates

🔌 API Endpoints

Sites Management

Create New Site

POST /api/sites/create
Content-Type: application/json

{
  "name": "my-blog",
  "prompt": "Create a personal tech blog with dark theme and syntax highlighting"
}

List All Sites

GET /api/sites

Get Site Details

GET /api/sites/[id]

Delete Site

DELETE /api/sites/[id]

Site Operations

Build Site

POST /api/sites/[id]/build

Start Development Server

POST /api/sites/[id]/serve
Content-Type: application/json

{
  "port": 4001  // optional
}

Stop Development Server

DELETE /api/sites/[id]/serve

File Management

List Files

GET /api/sites/[id]/files?path=/

Read File

GET /api/sites/[id]/files?path=_config.yml

Update File

PUT /api/sites/[id]/files
Content-Type: application/json

{
  "filePath": "_posts/2024-01-01-hello-world.md",
  "content": "---\nlayout: post\ntitle: Hello World\n---\n\nContent here..."
}

AI Generation

Generate Site Structure

POST /api/ai/generate
Content-Type: application/json

{
  "type": "site",
  "prompt": "Create a portfolio website for a web developer"
}

Generate Component

POST /api/ai/generate
Content-Type: application/json

{
  "type": "component",
  "prompt": "Create a hero section layout",
  "context": {
    "componentType": "layout"
  }
}

Generate Styles

POST /api/ai/generate
Content-Type: application/json

{
  "type": "styles",
  "prompt": "Modern dark theme with purple accents"
}

Improve Content

POST /api/ai/generate
Content-Type: application/json

{
  "type": "improve",
  "prompt": "Make this more engaging",
  "context": {
    "content": "existing content here",
    "improvements": "add more personality and examples"
  }
}

🔌 WebSocket Events

Connect to WebSocket

const ws = new WebSocket('ws://localhost:8080');

ws.on('message', (data) => {
  const event = JSON.parse(data);
  console.log('Event:', event.type, event.data);
});

Event Types

• sites - Initial sites list
• siteStatusChanged - Site status updates
• fileChanged - File change notifications
• siteBuilt - Build completion notifications

🛡️ Security Features

Rate Limiting

• API Calls: 100 requests/minute
• AI Generation: 10 requests/minute
• Site Creation: 5 sites/5 minutes

Input Validation

• XSS protection
• SQL injection prevention
• File path traversal protection
• Site name validation

CORS Configuration

• Configurable allowed origins
• Secure headers
• Credential support

🐳 Docker Deployment

Development

docker-compose -f docker-compose.api.yml up -d

Production

# With HTTPS and database
docker-compose -f docker-compose.api.yml --profile production --profile persistence up -d

Services Included

• API: Next.js application
• Jekyll: Jekyll container for site operations
• Redis: Caching and session storage
• Nginx: Reverse proxy (production)
• PostgreSQL: Data persistence (optional)
• FileBrowser: File management UI (optional)

🔧 Configuration

Environment Variables

Required

GEMINI_API_KEY=your_gemini_api_key
NEXTAUTH_SECRET=your_secure_secret

Optional

# Database
DATABASE_URL=postgresql://user:pass@localhost:5432/jekyll_studio

# Redis
REDIS_URL=redis://localhost:6379

# Security
ALLOWED_ORIGINS=http://localhost:3000,https://yourdomain.com
RATE_LIMIT_WINDOW_MS=60000
RATE_LIMIT_MAX_REQUESTS=100

# Email (notifications)
SMTP_HOST=smtp.gmail.com
SMTP_PORT=587
[email protected]
SMTP_PASS=your_app_password

Docker Compose Profiles

• Default: API + Jekyll + Redis
• Production: + Nginx with SSL
• Persistence: + PostgreSQL database
• Tools: + FileBrowser for file management

📊 Usage Examples

Frontend Integration

React/Next.js Frontend

// Create new site
async function createSite(prompt) {
  const response = await fetch('/api/sites/create', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      name: 'my-site',
      prompt: prompt
    })
  });
  
  return response.json();
}

// Watch site status
const ws = new WebSocket('ws://localhost:8080');
ws.onmessage = (event) => {
  const data = JSON.parse(event.data);
  if (data.type === 'siteStatusChanged') {
    updateSiteStatus(data.data);
  }
};

Vue.js Integration

// composables/useSites.js
import { ref, onMounted } from 'vue'

export function useSites() {
  const sites = ref([])
  const loading = ref(false)
  
  const createSite = async (siteData) => {
    loading.value = true
    try {
      const response = await $fetch('/api/sites/create', {
        method: 'POST',
        body: siteData
      })
      sites.value.push(response.site)
      return response
    } finally {
      loading.value = false
    }
  }
  
  const fetchSites = async () => {
    const response = await $fetch('/api/sites')
    sites.value = response.sites
  }
  
  onMounted(fetchSites)
  
  return { sites, createSite, fetchSites, loading }
}

CLI Integration

cURL Examples

# Create site
curl -X POST http://localhost:3000/api/sites/create \
  -H "Content-Type: application/json" \
  -d '{"name": "blog", "prompt": "Create a minimalist blog"}'

# Build site
curl -X POST http://localhost:3000/api/sites/{id}/build

# Update file
curl -X PUT http://localhost:3000/api/sites/{id}/files \
  -H "Content-Type: application/json" \
  -d '{"filePath": "index.md", "content": "# Hello World"}'

Python Integration

import requests
import json

class JekyllStudioClient:
    def __init__(self, base_url="http://localhost:3000"):
        self.base_url = base_url
    
    def create_site(self, name, prompt):
        response = requests.post(
            f"{self.base_url}/api/sites/create",
            json={"name": name, "prompt": prompt}
        )
        return response.json()
    
    def build_site(self, site_id):
        response = requests.post(
            f"{self.base_url}/api/sites/{site_id}/build"
        )
        return response.json()
    
    def serve_site(self, site_id, port=None):
        data = {"port": port} if port else {}
        response = requests.post(
            f"{self.base_url}/api/sites/{site_id}/serve",
            json=data
        )
        return response.json()

# Usage
client = JekyllStudioClient()
site = client.create_site("my-blog", "Create a tech blog with dark theme")
build_result = client.build_site(site['site']['id'])
serve_result = client.serve_site(site['site']['id'])

🧪 Testing

Unit Tests

npm run test

Integration Tests

npm run test:integration

API Testing with Postman

Import the Postman collection:

curl -o jekyll-studio.postman_collection.json \
  https://raw.githubusercontent.com/your-repo/postman-collection.json

Load Testing

# Install k6
npm install -g k6

# Run load tests
k6 run tests/load-test.js

🔍 Monitoring & Logging

Health Checks

GET /api/health

Response:

{
  "status": "healthy",
  "timestamp": "2024-01-01T00:00:00Z",
  "services": {
    "jekyll": "running",
    "redis": "connected",
    "database": "connected"
  }
}

Logs

# View API logs
docker-compose logs -f api

# View Jekyll container logs
docker-compose logs -f jekyll

# View all logs
docker-compose logs -f

Metrics Endpoints

GET /api/metrics

🚀 Production Deployment

1. Environment Setup

# Production environment
cp .env.example .env.production
# Configure production values

2. Build Production Image

docker build -t jekyll-studio-api:latest -f Dockerfile.api .

3. Deploy with Docker Compose

# Start production stack
docker-compose -f docker-compose.api.yml --profile production up -d

4. SSL Configuration

# Generate SSL certificates (Let's Encrypt)
docker run --rm -v ./nginx/ssl:/etc/letsencrypt \
  certbot/certbot certonly --webroot \
  -w /var/www/certbot -d yourdomain.com

5. Database Migration (if using PostgreSQL)

docker-compose exec postgres psql -U jekyll_user -d jekyll_studio -f /app/migrations/init.sql

🔄 Backup & Recovery

Database Backup

# Backup PostgreSQL
docker-compose exec postgres pg_dump -U jekyll_user jekyll_studio > backup.sql

# Restore
docker-compose exec -T postgres psql -U jekyll_user jekyll_studio < backup.sql

Sites Backup

# Backup all sites
tar -czf sites-backup.tar.gz projects/

# Restore
tar -xzf sites-backup.tar.gz

🐛 Troubleshooting

Common Issues

1. Gemini AI Error

Error: GEMINI_API_KEY is required

Solution: Set your Gemini API key in .env

2. Docker Permission Error

Error: Permission denied accessing /var/run/docker.sock

Solution: Add user to docker group

sudo usermod -aG docker $USER

3. Port Already in Use

Error: Port 3000 is already in use

Solution: Change port in .env or stop conflicting service

4. Jekyll Build Failed

Check logs:

docker-compose logs jekyll

Debug Mode

# Enable debug logging
DEBUG=jekyll-studio:* npm run dev

🤝 Contributing

Development Setup

# Clone repository
git clone https://github.com/daffadevhosting/jekyll-studio-api.git
cd jekyll-studio-api

# Install dependencies
npm install

# Start development environment
npm run dev

# Run tests
npm test

Code Style

• ESLint configuration
• Prettier formatting
• TypeScript strict mode

Pull Request Process

1. Fork repository
2. Create feature branch
3. Add tests for new features
4. Ensure all tests pass
5. Update documentation
6. Submit pull request

📝 License

CC0 1.0 Universal License - see LICENSE file for details.

🔗 Links

• Frontend Repository: Jekyll Studio Frontend
• Docker Images: Docker Hub
• Documentation: Full Documentation
• Issues: GitHub Issues