Self-Hosting Guide

Overview

Open Higgsfield AI is a fully client-side application built with Vite, making it simple to deploy to any static hosting provider. This guide covers production builds, deployment options, and security best practices.

Prerequisites

Node.js and npm

Ensure you have Node.js 18+ installed:

node --version  # Should be 18.0.0 or higher
npm --version

Clone the Repository

git clone https://github.com/yourusername/open-higgsfield-ai.git
cd open-higgsfield-ai

Install Dependencies

npm install

This installs:

vite - Build tool and dev server
tailwindcss - CSS framework
puppeteer - For any server-side rendering needs (optional)

Building for Production

Standard Build

npm run build

The dist/ folder contains your optimized production build.

Build Details:

JavaScript is minified and tree-shaken
CSS is optimized with Tailwind’s purge
Assets are fingerprinted with content hashes
Total bundle size: ~500KB (depending on assets)

Build Configuration

Vite configuration from vite.config.js:

import { defineConfig } from 'vite';
import tailwindcss from '@tailwindcss/vite';

export default defineConfig({
    plugins: [
        tailwindcss(),
    ],
    server: {
        proxy: {
            '/api': {
                target: 'https://api.muapi.ai',
                changeOrigin: true,
                secure: false
            }
        }
    }
});

The proxy configuration only applies to development (npm run dev). In production, the app makes direct requests to api.muapi.ai.

Serving the Built App

Local Preview

Test your production build locally:

npm run preview

This serves the dist/ folder on http://localhost:4173.

Static Hosting Providers

Vercel
Netlify
GitHub Pages
Cloudflare Pages
Docker

One-Click Deploy

npm install -g vercel
vercel

Build Configuration:

{
  "buildCommand": "npm run build",
  "outputDirectory": "dist",
  "framework": "vite"
}

Custom Domain:

Go to Vercel project settings
Add your domain
Update DNS CNAME to cname.vercel-dns.com

Deploy from Git

Connect your GitHub repository
Configure build settings:

# netlify.toml
[build]
  command = "npm run build"
  publish = "dist"

[[redirects]]
  from = "/*"
  to = "/index.html"
  status = 200

Environment Variables:

Go to Site settings → Environment variables
Add any required variables (e.g., analytics tokens)

Deploy with GitHub ActionsCreate .github/workflows/deploy.yml:

name: Deploy to GitHub Pages

on:
  push:
    branches: [ main ]

jobs:
  build-and-deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      
      - name: Setup Node
        uses: actions/setup-node@v3
        with:
          node-version: 18
      
      - name: Install and Build
        run: |
          npm install
          npm run build
      
      - name: Deploy
        uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./dist

Base URL Configuration:If deploying to yourusername.github.io/open-higgsfield-ai, update vite.config.js:

export default defineConfig({
    base: '/open-higgsfield-ai/',
    // ... rest of config
});

Deploy from Dashboard

Go to Cloudflare Pages
Connect your Git repository
Configure build:

Build command: npm run build
Build output directory: dist
Node.js version: 18

Custom Headers (Optional):Create _headers file in public/:

/*
  X-Frame-Options: DENY
  X-Content-Type-Options: nosniff
  Referrer-Policy: strict-origin-when-cross-origin

Dockerfile

# Build stage
FROM node:18-alpine AS builder
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build

# Production stage
FROM nginx:alpine
COPY --from=builder /app/dist /usr/share/nginx/html
COPY nginx.conf /etc/nginx/conf.d/default.conf
EXPOSE 80
CMD ["nginx", "-g", "daemon off;"]

nginx.conf

server {
    listen 80;
    server_name _;
    root /usr/share/nginx/html;
    index index.html;

    location / {
        try_files $uri $uri/ /index.html;
    }

    # Security headers
    add_header X-Frame-Options "DENY" always;
    add_header X-Content-Type-Options "nosniff" always;
    add_header Referrer-Policy "strict-origin-when-cross-origin" always;

    # Cache static assets
    location ~* \.(js|css|png|jpg|jpeg|gif|webp|svg|ico)$ {
        expires 1y;
        add_header Cache-Control "public, immutable";
    }
}

Build and Run

docker build -t open-higgsfield-ai .
docker run -p 8080:80 open-higgsfield-ai

Visit http://localhost:8080

Environment Considerations

API Proxy (Development vs Production)

// From muapi.js:6
this.baseUrl = '';  // Uses Vite proxy at http://localhost:5173/api

The client automatically detects the environment:

this.baseUrl = import.meta.env.DEV ? '' : 'https://api.muapi.ai';

In production, your app makes direct requests to api.muapi.ai. CORS is already configured by Muapi.ai, so no additional proxy is needed.

Browser Compatibility

Open Higgsfield AI supports modern browsers:

Chrome 90+
Firefox 88+
Safari 14+
Edge 90+

ES2020+ features used:

Optional chaining (?.)
Nullish coalescing (??)
async/await
ES Modules

For older browser support, add browserslist and Babel to your build pipeline.

CORS and API Access

Why CORS Works in Production

Muapi.ai’s API includes these CORS headers:

Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: GET, POST, OPTIONS
Access-Control-Allow-Headers: Content-Type, x-api-key

This allows direct browser-to-API communication without a proxy.

Development Proxy Explanation

During development, Vite’s proxy (configured in vite.config.js) avoids browser CORS restrictions:

server: {
    proxy: {
        '/api': {
            target: 'https://api.muapi.ai',
            changeOrigin: true,  // Changes host header
            secure: false        // Allows self-signed certs
        }
    }
}

Request Flow:

Browser → http://localhost:5173/api/v1/flux-dev-image
         ↓ (Vite proxy)
         → https://api.muapi.ai/api/v1/flux-dev-image

Security Best Practices

Critical Security Rules:

Never commit API keys to your repository
Use HTTPS for all production deployments
Enable security headers (see Docker nginx example)
Validate user inputs before sending to API
Monitor API usage to detect abuse

Secure API Key Management

Option 1: User-Provided Keys (Recommended) Users enter their own Muapi.ai API key in Settings:

// Stored in browser localStorage
localStorage.setItem('muapi_key', userProvidedKey);

Option 2: Environment Variables (For Private Deployments) If hosting privately for your team:

# .env.local
VITE_MUAPI_KEY=your-api-key

// muapi.js
getKey() {
    return import.meta.env.VITE_MUAPI_KEY || localStorage.getItem('muapi_key');
}

Never use environment variables in public deployments—the key will be visible in the bundled JavaScript!

Content Security Policy (CSP)

Add CSP headers to prevent XSS attacks:

Content-Security-Policy: default-src 'self'; 
  script-src 'self' 'unsafe-inline'; 
  style-src 'self' 'unsafe-inline'; 
  img-src 'self' data: https:; 
  connect-src 'self' https://api.muapi.ai;

Rate Limiting

Implement client-side rate limiting to prevent abuse:

class RateLimiter {
    constructor(maxRequests = 10, windowMs = 60000) {
        this.requests = [];
        this.maxRequests = maxRequests;
        this.windowMs = windowMs;
    }

    canMakeRequest() {
        const now = Date.now();
        this.requests = this.requests.filter(t => now - t < this.windowMs);
        
        if (this.requests.length >= this.maxRequests) {
            return false;
        }
        
        this.requests.push(now);
        return true;
    }
}

const limiter = new RateLimiter(10, 60000); // 10 requests per minute

Performance Optimization

Asset Optimization

# Optimize cinema control assets
for file in public/assets/cinema/*.{png,jpg}; do
  cwebp -q 80 "$file" -o "${file%.*}.webp"
done

Caching Strategy

Static Assets:

location ~* \.(js|css|png|jpg|jpeg|gif|webp|svg|ico)$ {
    expires 1y;
    add_header Cache-Control "public, immutable";
}

API Responses: Cache completed generation results locally:

const cacheResult = (requestId, result) => {
    const cache = JSON.parse(localStorage.getItem('result_cache') || '{}');
    cache[requestId] = { result, timestamp: Date.now() };
    localStorage.setItem('result_cache', JSON.stringify(cache));
};

Monitoring and Analytics

Error Tracking

Integrate Sentry for error monitoring:

npm install @sentry/browser

import * as Sentry from "@sentry/browser";

Sentry.init({
  dsn: "your-sentry-dsn",
  environment: import.meta.env.MODE,
  tracesSampleRate: 0.1,
});

Usage Analytics

Track model usage with Google Analytics or Plausible:

// After successful generation
window.gtag?.('event', 'generation_complete', {
  model_id: params.model,
  studio_type: 'image',  // or 'video', 'cinema'
});

Health Checks and Uptime

API Health Endpoint

Add a simple health check:

// src/health.js
export async function checkAPIHealth() {
    try {
        const response = await fetch('https://api.muapi.ai/health');
        return response.ok;
    } catch {
        return false;
    }
}

Uptime Monitoring

Use services like:

UptimeRobot - Free tier available
Pingdom - Detailed performance metrics
Checkly - API monitoring with Playwright

Troubleshooting Production Issues

Blank page after deployment

Cause: Incorrect base URL or missing index.html fallback.Solution:

Check vite.config.js base URL matches deployment path
Ensure server redirects all routes to /index.html
Verify dist/index.html exists

Assets not loading (404 errors)

Cause: Base path mismatch or incorrect nginx/hosting config.Solution:

Check browser DevTools Network tab for failed requests
Verify base in vite.config.js
Ensure assets are copied to dist/assets/

API requests failing with CORS error

Cause: Incorrect production API URL or network issue.Solution:

Verify muapi.js:6 uses https://api.muapi.ai in production
Check API key is valid

Test API directly with curl:

curl -H "x-api-key: YOUR_KEY" https://api.muapi.ai/health

localStorage not persisting

Cause: Incognito mode or browser settings blocking storage.Solution:

Test in normal browser window
Check browser storage permissions
Add fallback to sessionStorage if needed

Next Steps

API Configuration

Set up your Muapi.ai API key

Model Selection

Choose the right models for your deployment

Get Started

Core Features

Guides

Overview

Prerequisites

Building for Production

Standard Build

Build Configuration

Serving the Built App

Local Preview

Static Hosting Providers

Environment Considerations

API Proxy (Development vs Production)

Browser Compatibility

CORS and API Access

Why CORS Works in Production

Development Proxy Explanation

Security Best Practices

Secure API Key Management

Content Security Policy (CSP)

Rate Limiting

Performance Optimization

Asset Optimization

Caching Strategy

Monitoring and Analytics

Error Tracking

Usage Analytics

Health Checks and Uptime

API Health Endpoint

Uptime Monitoring

Troubleshooting Production Issues

Next Steps

API Configuration

Model Selection

Build docs developers (and LLMs) love

Get Started

Core Features

Guides

​Overview

​Prerequisites

​Building for Production

​Standard Build

​Build Configuration

​Serving the Built App

​Local Preview

​Static Hosting Providers

​Environment Considerations

​API Proxy (Development vs Production)

​Browser Compatibility

​CORS and API Access

​Why CORS Works in Production

​Development Proxy Explanation

​Security Best Practices

​Secure API Key Management

​Content Security Policy (CSP)

​Rate Limiting

​Performance Optimization

​Asset Optimization

​Caching Strategy

​Monitoring and Analytics

​Error Tracking

​Usage Analytics

​Health Checks and Uptime

​API Health Endpoint

​Uptime Monitoring

​Troubleshooting Production Issues

​Next Steps

API Configuration

Model Selection

Build docs developers (and LLMs) love

Overview

Prerequisites

Building for Production

Standard Build

Build Configuration

Serving the Built App

Local Preview

Static Hosting Providers

Environment Considerations

API Proxy (Development vs Production)

Browser Compatibility

CORS and API Access

Why CORS Works in Production

Development Proxy Explanation

Security Best Practices

Secure API Key Management

Content Security Policy (CSP)

Rate Limiting

Performance Optimization

Asset Optimization

Caching Strategy

Monitoring and Analytics

Error Tracking

Usage Analytics

Health Checks and Uptime

API Health Endpoint

Uptime Monitoring

Troubleshooting Production Issues

Next Steps