Skip to content

Deployment

FluxUI apps run on top of uvicorn and FastAPI, so they deploy like any ASGI application.

Step 1 — Generate Docker files

fluxui export-docker app.py --port 8000

This creates Dockerfile and docker-compose.yml in the current directory.

Generated Dockerfile:

FROM python:3.11-slim

WORKDIR /app
COPY . .

RUN pip install --no-cache-dir fluxui

EXPOSE 8000

CMD ["python", "app.py"]

Generated docker-compose.yml:

version: "3.9"
services:
  app:
    build: .
    ports:
      - "8000:8000"
    environment:
      - FLUXUI_HOST=0.0.0.0
      - FLUXUI_PORT=8000
    restart: unless-stopped

Step 2 — Build and run

docker compose up --build

Your app is now accessible at http://localhost:8000.

Step 3 — Production settings

Make sure your app.py reads host/port from environment variables:

import os
import fluxui as ui

app = ui.App("My App", debug=False)

@app.page("/")
def home(session):
    ...

if __name__ == "__main__":
    app.run(
        host=os.environ.get("FLUXUI_HOST", "127.0.0.1"),
        port=int(os.environ.get("FLUXUI_PORT", "8000")),
    )

Manual (gunicorn + uvicorn workers)

For multi-worker production deployments, use gunicorn with uvicorn workers:

pip install gunicorn uvicorn[standard]

gunicorn app:app._fastapi \
    --worker-class uvicorn.workers.UvicornWorker \
    --workers 4 \
    --bind 0.0.0.0:8000 \
    --timeout 120

Session affinity

FluxUI sessions are stored in-process. With multiple workers, a WebSocket connection must always reach the same worker. Use a load balancer with sticky sessions (e.g., nginx ip_hash or HAProxy source balance) when running multiple workers.

Environment Variables

Variable Default Description
FLUXUI_HOST 127.0.0.1 Bind host (set to 0.0.0.0 in containers)
FLUXUI_PORT 8000 Bind port
FLUXUI_DEBUG 1 Set to 0 to disable debug overlay
FLUXUI_SESSION_TIMEOUT 1800 Session GC timeout in seconds

Reverse Proxy (nginx)

FluxUI uses WebSockets, so your reverse proxy must forward the Upgrade header:

server {
    listen 80;
    server_name myapp.example.com;

    location / {
        proxy_pass         http://127.0.0.1:8000;
        proxy_http_version 1.1;

        # WebSocket support
        proxy_set_header Upgrade    $http_upgrade;
        proxy_set_header Connection "upgrade";

        proxy_set_header Host              $host;
        proxy_set_header X-Real-IP         $remote_addr;
        proxy_set_header X-Forwarded-For   $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_read_timeout 3600s;
    }
}

Public Sharing (share=True)

For quick demos and prototyping, FluxUI can open a temporary public tunnel:

fluxui run app.py --share

Or from code:

app.run(port=8000, share=True)

This prints a public HTTPS URL that anyone can open. The tunnel closes when the server stops.

Requires:

pip install "fluxui[share]"

Warning

share=True is intended for demos only. The URL is temporary and the tunnel server is not operated by the FluxUI project. Do not expose sensitive data or production workloads through a share tunnel.