Docker

The recommended way to run Xinference locally or in a single-server production environment is with Docker Compose.

Prerequisites

• Docker 24+
• Docker Compose v2

Project Structure

xinference-saas/
  docker/
    docker-compose.yml
    Dockerfile.backend
    Dockerfile.frontend
  backend/
    .env            ← copy from .env.example

Starting the Stack

cd xinference-saas

# Copy and edit environment config
cp backend/.env.example backend/.env
# Edit backend/.env with your settings

# Start all services
docker compose up -d

Services started: - backend — FastAPI on port 8000 - frontend — Nginx serving the React app on port 3000 - db — PostgreSQL on port 5432

Environment Configuration

Edit backend/.env before starting. Minimum required variables for a working local environment:

APP_ENV=development
DATABASE_URL=postgresql://xinference:xinference@db:5432/xinference

CORS_ALLOW_ORIGINS=http://localhost:3000
XINFERENCE_FRONTEND_URL=http://localhost:3000

SESSION_COOKIE_SECURE=false
SESSION_COOKIE_SAMESITE=lax

# Leave these as 'fake' for local development (no real AWS calls)
XINFERENCE_SAAS_CLOUD_PROVIDER=fake
XINFERENCE_SAAS_XINFERENCE_CLIENT=fake

Checking Service Health

# Check all containers
docker compose ps

# Backend health check
curl http://localhost:8000/healthz
# → {"status": "ok"}

# View logs
docker compose logs -f backend

Running Database Migrations

Migrations run automatically on backend startup when DATABASE_AUTO_CREATE_SCHEMA=true. For production, run Alembic explicitly:

docker compose exec backend alembic upgrade head

Seeding Default Data

On first startup, the backend automatically seeds: - Default user roles - Default deployable models - Default price plan (if BILLING_SEED_DEFAULT_PRICE_PLAN=true)

Stopping the Stack

docker compose down        # stop without removing volumes
docker compose down -v     # stop and delete database volumes

Production Considerations

For production use behind a reverse proxy (nginx, Caddy, etc.):

1. Set APP_ENV=production
2. Set SESSION_COOKIE_SECURE=true
3. Configure CORS_ALLOW_ORIGINS and XINFERENCE_FRONTEND_URL to your real domain
4. Use a managed PostgreSQL instance (AWS RDS, Supabase, etc.) instead of the Docker container
5. Set up real AWS credentials and set XINFERENCE_SAAS_CLOUD_PROVIDER=aws

Render Deployment

To deploy the backend to Render:

1. Connect your GitHub repo
2. Set Build Command: pip install -r backend/requirements.txt
3. Set Start Command: uvicorn app.main:app --host 0.0.0.0 --port $PORT
4. Set root directory to backend/
5. Add all environment variables in the Render dashboard

The frontend can be deployed as a Static Site on Render: 1. Set Build Command: npm run build 2. Set Publish Directory: build 3. Root directory: frontend/