Self-Hosting Guide

Dieser Inhalt ist noch nicht in deiner Sprache verfügbar.

Deploy Eryxon Flow on your own infrastructure with full control.

This guide is the authoritative production checklist. For the shortest setup path, see the Deployment Guide.

Quick Start (Recommended)

The fastest way to get production-ready deployment using our automated script.

Prerequisites

Node.js 20+
Git
A Supabase project (supabase.com - free tier available)
Your Supabase credentials

One-Command Setup

# Clone the repository
git clone https://github.com/SheetMetalConnect/eryxon-flow.git
cd eryxon-flow

# Create your .env file (the automated script requires it)
cp .env.example .env
# Edit .env and fill in your Supabase credentials (URL, anon key, project ID)

# Set your database password
export SUPABASE_DB_PASSWORD='your-database-password'

# Run automated setup
chmod +x scripts/automate_self_hosting.sh
./scripts/automate_self_hosting.sh

The script will automatically:

Install required dependencies (Node.js packages)
Install Supabase CLI globally (if not present)
Fix configuration issues
Link your Supabase project
Apply database migrations (schema + seed)
Deploy all Edge Functions
Run verification checks

Start Development Server

npm run dev
# Open http://localhost:8080

First User Setup

Navigate to the application
Click Sign Up
Enter email and password
First user automatically becomes admin with a new tenant

Manual Setup (Step by Step)

Use this for custom configurations or troubleshooting.

1. Create Supabase Project

Go to supabase.com → New Project
Save these credentials from Settings → API:
- Project URL: https://yourproject.supabase.co
- Project ID: The subdomain (e.g., yourproject)
- Anon key: Public key for frontend
- Service role key: Secret key for backend
- Database password: From project creation

2. Configure Environment

# Copy example file
cp .env.example .env

Edit .env:

VITE_SUPABASE_URL="https://yourproject.supabase.co"
VITE_SUPABASE_PUBLISHABLE_KEY="your-anon-key"
VITE_SUPABASE_PROJECT_ID="yourproject"

# Optional: For database scripts
SUPABASE_SERVICE_ROLE_KEY="your-service-role-key"
SUPABASE_DB_PASSWORD="your-database-password"

3. Link Supabase Project

# Install Supabase CLI
npm install -g supabase

# Login and link
supabase login
supabase link --project-ref yourproject

4. Apply Database Schema

# Push all migrations
supabase db push

# Verify migrations applied
supabase migration list

5. Run Seed SQL

Creates storage buckets, RLS policies, and cron jobs:

# Option A: Using Supabase CLI
supabase db execute --file supabase/seed.sql

# Option B: Via Dashboard
# Go to SQL Editor, paste seed.sql content, and execute

6. Deploy Edge Functions

# Deploy all functions
supabase functions deploy

# Set required secrets
supabase secrets set \
  SUPABASE_URL="https://yourproject.supabase.co" \
  SUPABASE_SERVICE_ROLE_KEY="your-service-role-key" \
  SELF_HOSTED_MODE="true"

SELF_HOSTED_MODE indicates deployment mode to the plan-mode edge function (used for UI messaging only). It does not disable plan limits. Unlimited operations are achieved by setting the tenant’s plan field in the database to enterprise with null limit columns — the app treats null as unlimited. Valid plan values are: free, pro, premium, enterprise.

The signup notification uses a Supabase Database Webhook instead of hardcoded SQL URLs. Configure this in Supabase Dashboard:

Open Database -> Webhooks
Create a webhook named notify-new-signup
Table: public.profiles
Event: INSERT
Type: Supabase Edge Function
Edge Function: notify-new-signup
Filter: record.role = 'admin' AND record.has_email_login = true

This is required only if you want admin signup email notifications.

8. Install and Run

# Install dependencies
npm ci

# Development mode
npm run dev

# Production build
npm run build
npm run preview

Docker Deployment (Production)

Using Pre-built Image

# Pull latest image
docker pull ghcr.io/sheetmetalconnect/eryxon-flow:latest

# Run container with your runtime VITE_* configuration
docker run -d \
  -p 80:80 \
  --name eryxon-flow \
  --restart unless-stopped \
  --env-file .env \
  ghcr.io/sheetmetalconnect/eryxon-flow:latest

The shipped image reads your VITE_* variables at container start and writes them to /env.js, so you can point the same image at your own Supabase project without rebuilding it.

Build Custom Image

If you want your own image artifact or build-time defaults, you can still build one locally:

docker build \
  --build-arg VITE_SUPABASE_URL="https://yourproject.supabase.co" \
  --build-arg VITE_SUPABASE_PUBLISHABLE_KEY="your-anon-key" \
  --build-arg VITE_SUPABASE_PROJECT_ID="yourproject" \
  -t eryxon-flow .

docker run -d -p 80:80 --name eryxon-flow eryxon-flow

Docker Compose (Recommended)

The repository ships with a ready-to-use docker-compose.yml. In the current v0.6 repo, this is the single self-hosted Docker entry point and it already reads .env through env_file.

docker compose up -d

To build your own image instead of using ghcr.io/sheetmetalconnect/eryxon-flow:latest, replace the image line in docker-compose.yml with a build block:

services:
  eryxon-flow:
    # Replace this:
    #   image: ghcr.io/sheetmetalconnect/eryxon-flow:latest
    # With this:
    build:
      context: .
      args:
        VITE_SUPABASE_URL: ${VITE_SUPABASE_URL}
        VITE_SUPABASE_PUBLISHABLE_KEY: ${VITE_SUPABASE_PUBLISHABLE_KEY}
        VITE_SUPABASE_PROJECT_ID: ${VITE_SUPABASE_PROJECT_ID}
    container_name: eryxon-flow
    restart: unless-stopped
    ports:
      - "80:80"
    healthcheck:
      test: ["CMD", "wget", "--quiet", "--tries=1", "--spider", "http://localhost/health"]
      interval: 30s
      timeout: 10s
      retries: 3

Make sure the corresponding VITE_SUPABASE_* variables are set in your .env file (Docker Compose reads .env automatically).

Then rebuild and start:

docker compose up -d --build

Docker Compose with SSL (Production)

The repo no longer uses a separate docker-compose.prod.yml. For HTTPS in the current v0.6 line, stay on the shipped docker-compose.yml and enable the optional Caddy service that is already commented into that file:

Uncomment the caddy service and the volumes: block in docker-compose.yml
Change the eryxon-flow service from ports: ["80:80"] to expose: ["80"]
Edit the included Caddyfile
Start the stack with docker compose up -d

The shipped Caddyfile supports two real deployment modes:

a public hostname with automatic Let’s Encrypt certificates
a LAN-only rollout with Caddy tls internal, a .local host, and a trusted local root certificate for operator devices

Use the section that matches your environment and replace the example domain, LAN_HOST, or LAN_IP values before you bring the stack up.

Cloudflare Pages Deployment

Best for edge deployment with global CDN.

Connect Repository
- Go to Cloudflare Pages
- Create a project → Connect your Git repository
Configure Build
- Build command: npm run build
- Output directory: dist

Set Environment Variables

VITE_SUPABASE_URL=https://yourproject.supabase.co
VITE_SUPABASE_PUBLISHABLE_KEY=your-anon-key
VITE_SUPABASE_PROJECT_ID=yourproject

Deploy
- Cloudflare handles SSL, CDN, and global distribution automatically

Optional Enhancements

Email Notifications (Resend)

Enable automated email invitations and admin signup notifications:

supabase secrets set \
  RESEND_API_KEY="re_your_api_key" \
  APP_URL="https://your-domain.com" \
  EMAIL_FROM="Eryxon <noreply@your-domain.com>" \
  SIGNUP_NOTIFY_EMAIL="admin@your-domain.com"

SIGNUP_NOTIFY_EMAIL is the address that receives notifications when a new company signs up. Required for the notify-new-signup edge function to send emails.

Cloudflare Turnstile (CAPTCHA)

Add bot protection to auth forms:

Create widget at Cloudflare Turnstile
Add to .env:
Terminal window
```
VITE_TURNSTILE_SITE_KEY="your-site-key"
```
Configure secret key in Supabase Authentication → Captcha Protection
On Vercel, keep the repo vercel.json so SPA rewrites and CSP headers continue to allow https://challenges.cloudflare.com

Redis Caching (Upstash)

Improve Edge Function performance:

supabase secrets set \
  UPSTASH_REDIS_REST_URL="https://your-redis.upstash.io" \
  UPSTASH_REDIS_REST_TOKEN="your-token"

3D STEP Viewer & CAD Processing

The built-in 3D STEP viewer works out of the box using browser-based WASM parsing (occt-import-js). No server-side CAD service is required.

How it works: STEP/STP files uploaded to the parts-cad storage bucket are parsed client-side using WebAssembly. The viewer supports orbit controls, exploded view, wireframe mode, and measurement tools (distance, angle, radius).

CSP requirements: The STEP parser needs specific Content Security Policy directives. These are already configured in the shipped index.html and vercel.json, but if your reverse proxy (Nginx, Caddy, Cloudflare) adds its own CSP headers, make sure they include:

script-src 'self' 'unsafe-eval' 'wasm-unsafe-eval' https://cdn.jsdelivr.net;
worker-src 'self' blob:;

Directive	Reason
`'unsafe-eval'`	Emscripten embind (occt-import-js) uses `new Function()`
`'wasm-unsafe-eval'`	Explicit WASM compilation permission
`https://cdn.jsdelivr.net`	CDN host for the `occt-import-js` library
`worker-src blob:`	occt-import-js creates Web Workers from blob URLs

Note: The default Nginx and Caddy configs shipped with this repo do not set CSP headers (they rely on the <meta> tag in index.html), so you only need to worry about this if you add custom CSP rules at the proxy level.

Optional: Server-side CAD processing

For server-side geometry extraction and PMI (Product Manufacturing Information) data, configure an external CAD service:

VITE_CAD_SERVICE_URL="https://your-cad-service.example.com"
VITE_CAD_SERVICE_API_KEY="your-api-key"

If not configured, browser-based processing is used automatically. The viewer supports three backend modes: custom (Eryxon3D Docker), byob (Bring Your Own Backend), and frontend (browser-only, the default).

MCP Server (Optional - Local Use Only)

The MCP server is NOT part of the deployment stack. It’s an optional local tool for Claude Desktop integration.

What it does:

Allows Claude Desktop to interact with your database using natural language
Provides 50 tools for managing jobs, parts, operations via AI

Quick start:

cd mcp-server
npm install && npm run build
export SUPABASE_URL="https://your-project.supabase.co"
export SUPABASE_SERVICE_KEY="your-service-key"
npm start

Complete setup instructions: See MCP Setup Guide for:

Local development setup
Cloud deployment (Railway, Fly.io, Docker)
Claude Desktop configuration
All 55 available tools

Note: Your self-hosted application works perfectly without the MCP server. It’s only for developers who want AI assistant integration via Claude Desktop.

Verification

Run the verification script to check your setup:

bash scripts/verify-setup.sh

Checks:

Environment variables
Supabase connectivity
Database tables
Storage buckets (see note below)
Dependencies
Production build

Note: Storage bucket check may report FAIL (HTTP 400) even when buckets exist. This is expected because the buckets are private (public: false) and the verification script uses the Anon Key, which cannot list private buckets. Verify manually via SQL:
SELECT * FROM storage.buckets;
Required buckets: parts-images, issues, parts-cad, batch-images

Updating Your Deployment

Pull Latest Changes

git pull origin main
npm ci

Update Database

supabase db push
supabase functions deploy

Rebuild Application

npm run build

# For Docker:
docker compose build --no-cache
docker compose up -d

Security Checklist

.env file is in .gitignore (never commit)
Service role key is kept secret
Database password is strong (16+ characters)
RLS policies are applied (via migrations)
Storage bucket policies restrict access properly
HTTPS is enabled in production (use Caddy or Cloudflare)

Troubleshooting

For deployment-specific issues (migrations, edge functions, storage, STEP viewer CSP), see the Troubleshooting Guide.