content_cut
OZIO ATELIER
Deployment Specification

AI Hair Transformation Studio
Production Deployment Guide

Comprehensive turnkey specification for deploying the Gemini-powered virtual hairstyle and botanical colour formulation studio across Bare-Metal, Docker, and Nginx environments.

cloud_sync Google Gemini GenAI SDK v2.33
speed FastAPI v0.162 + Uvicorn v0.54
security W3C Secure Context TLS 1.3
hub

1. System Architecture

The application operates as an asynchronous ASGI microservice that serves both the versioned REST API (/api/v1) and the interactive 4-step consultation studio. Hair generation executes in the cloud on Google servers with zero local GPU requirements.

+--------------------------------------------------------------------------------+ | CLIENT TIERS: Laptops, Tablets, Mobile Touchscreens | +--------------------------------------------------------------------------------+ | +-------------------------+-------------------------+ | Port 8443 (HTTPS) | Port 7860 (HTTP) v v +-------------------------------+ +--------------------------------+ | TLS / SSL Termination Layer | | Direct HTTP Access Layer | | (Enables Camera Permissions) | | (File Uploads & REST Endpoints)| +-------------------------------+ +--------------------------------+ | | +-------------------------+-------------------------+ v +--------------------------------------------------------------------------------+ | UVICORN ASGI SERVER (0.0.0.0:7860 / 0.0.0.0:8443) | | • FastAPI REST Engine (/api/v1/transformations, /api/v1/images, /health) | | • Single Page Application Static Asset Pipeline (HTML5, Vanilla JS, CSS3) | +--------------------------------------------------------------------------------+ | | v v +-------------------------------+ +--------------------------------+ | PERSISTENT LOCAL STORAGE | | GOOGLE GENAI CLOUD ENGINE | | • SQLite (history.db) | | • Model: gemini-3.1-flash | | • Uploads (storage/uploads) | | • Native Image Synthesis | | • Generated Looks & Thumbs | | • Identity Preservation | +-------------------------------+ +--------------------------------+
checklist

2. Software & Version Matrix

The studio has been tested, locked, and benchmarked against the following exact software components:

Package / Runtime Tested Version Minimum Function in Studio Architecture
Python Runtime 3.10.12 ≥ 3.10.0 Base execution engine (compatible with Python 3.10, 3.11, 3.12).
fastapi 0.162.5 ≥ 0.115.0 Asynchronous web routing, request validation, and OpenAPI documentation.
uvicorn[standard] 0.54.0 ≥ 0.30.0 Lightning-fast ASGI production server with uvloop event loop.
google-genai 2.33.0 ≥ 1.0.0 Official Google GenAI SDK for image-to-image synthesis and model management.
pydantic 2.14.3 ≥ 2.7.0 Strict schema parsing for hairstyle catalogs, color glazes, and costs.
pillow 12.3.0 ≥ 10.0.0 Image decoding, biometric facial thumbnail cropping, and format normalization.
python-multipart 0.0.32 ≥ 0.0.9 Streaming parser for client photo and webcam portrait uploads.
python-dotenv 1.2.4 ≥ 1.0.1 Loads configurations from .env file into OS environment.
cryptography 50.0.2 ≥ 42.0.0 Underlying TLS engine for SSL SAN key handling and certificate parsing.
httpx 0.28.1 ≥ 0.27.0 Async HTTP client for automated end-to-end verification and connection tests.
pytest 9.2.0 ≥ 8.0.0 Full test suite execution engine (50 unit and integration tests).
videocam

3. Hardware Camera & HTTPS Security

warning
W3C Secure Context Requirement: All modern browsers (Chrome, Safari, Edge, Firefox) strictly restrict navigator.mediaDevices.getUserMedia to **Secure Contexts**. When accessed via LAN IP (e.g. http://192.168.29.180:7860), browsers silently block webcam access and show no permission prompt.

To trigger the browser camera permission dialog on another laptop, tablet, or phone, you **must connect over HTTPS** (e.g. https://192.168.29.180:8443).

lock

4. SSL SAN Certificate Generation

Generate a multi-domain Subject Alternative Name (SAN) certificate to support localhost, 127.0.0.1, and your local network IP (e.g., 192.168.29.180):

bash — Generate Self-Signed Multi-SAN SSL Certificate
mkdir -p backend/storage/certs

openssl req -x509 -newkey rsa:4096 -nodes \
  -keyout backend/storage/certs/key.pem \
  -out backend/storage/certs/cert.pem \
  -days 365 \
  -subj "/CN=AI Hair Studio" \
  -addext "subjectAltName=DNS:localhost,IP:127.0.0.1,IP:192.168.29.180,IP:0.0.0.0"

chmod 0600 backend/storage/certs/key.pem
chmod 0644 backend/storage/certs/cert.pem
info
Client Device First-Time Access: When opening the HTTPS link on another device for the first time, click Advanced → Proceed to 192.168.29.180 (unsafe) once to trust the studio certificate. The camera permission dialog will appear immediately.
deployed_code

5. Docker & Docker Compose Deployment

Containerized production deployment provides full process isolation and automatic restart capabilities.

yaml — docker-compose.yml
version: '3.8'

services:
  hair-studio:
    build:
      context: ./backend
      dockerfile: Dockerfile
    container_name: ai-hair-studio
    restart: unless-stopped
    ports:
      - "7860:7860"   # HTTP Entry & REST API
      - "8443:8443"   # HTTPS Secure Context for Camera
    env_file:
      - ./backend/.env
    volumes:
      - ./backend/storage:/app/storage
    healthcheck:
      test: ["CMD", "curl", "-f", "http://127.0.0.1:7860/api/v1/health"]
      interval: 30s
      timeout: 5s
      retries: 3
bash — Launch Docker Stack
# 1. Build and run in background
docker compose up -d --build

# 2. View real-time container logs
docker compose logs -f hair-studio
settings_system_daydream

6. Linux Systemd Dual Services (Bare-Metal / VM)

Running twin systemd units provides dual listeners: HTTPS (port 8443) for hardware webcam capture and HTTP (port 7860) for standard access.

ini — /etc/systemd/system/hair-studio-https.service
[Unit]
Description=AI Hair Studio — HTTPS Camera Service
After=network.target

[Service]
Type=simple
User=devpatel
WorkingDirectory=/home/devpatel/hair_project/backend
EnvironmentFile=/home/devpatel/hair_project/backend/.env
ExecStart=/home/devpatel/hair_project/.venv/bin/python -m uvicorn app.main:app \
    --host 0.0.0.0 \
    --port 8443 \
    --ssl-keyfile storage/certs/key.pem \
    --ssl-certfile storage/certs/cert.pem
Restart=always
RestartSec=3

[Install]
WantedBy=multi-user.target
bash — Enable and Start Services
sudo systemctl daemon-reload
sudo systemctl enable --now hair-studio-https
sudo systemctl enable --now hair-studio-http
dns

7. Nginx TLS Reverse Proxy (Public Domain)

Recommended for public cloud servers with a domain name and Let's Encrypt SSL certificate.

nginx — /etc/nginx/sites-available/hair-studio
server {
    listen 80;
    server_name studio.yourdomain.com;
    return 301 https://$host$request_uri;
}

server {
    listen 443 ssl http2;
    server_name studio.yourdomain.com;

    ssl_certificate /etc/letsencrypt/live/studio.yourdomain.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/studio.yourdomain.com/privkey.pem;

    client_max_body_size 20M;
    proxy_read_timeout 180s;

    location / {
        proxy_pass http://127.0.0.1:7860;
        proxy_http_version 1.1;
        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;
    }

    location /static/ {
        proxy_pass http://127.0.0.1:7860/static/;
        expires 7d;
        add_header Cache-Control "public, no-transform";
    }
}
tune

8. Environment Variables Reference (.env)

Variable Default Description
GEMINI_API_KEY Required Google Gemini API Key from Google AI Studio. Stays backend-only; never logged or exposed.
GEMINI_DEFAULT_MODEL gemini-3.1-flash-image Default synthesis engine: gemini-3.1-flash-lite-image, gemini-3.1-flash-image, gemini-3-pro-image.
GEMINI_TIMEOUT_SECONDS 180 Generation request timeout before marking synthesis task as failed.
CORS_ALLOWED_ORIGINS * Allowed origins (e.g. * for studio LAN testing, or domain URL).
MAX_UPLOAD_MB 15 Maximum allowed portrait upload file size (in megabytes).
HOST / PORT 0.0.0.0 / 7860 Bind address and default HTTP port.
database

9. Storage & SQLite Hot Backup

All user data, portraits, and generated looks persist under backend/storage/:

bash — Live Online SQLite Backup
# Backup SQLite history.db cleanly without locking the database:
python3 -c "
import sqlite3
src = sqlite3.connect('backend/storage/history.db')
dst = sqlite3.connect('/var/backups/history-backup.db')
src.backup(dst)
src.close()
dst.close()
print('Backup complete.')
"
health_and_safety

10. Health Verification Commands

bash — Verify Health & Connectivity
# 1. Check HTTP server health
curl -s http://127.0.0.1:7860/api/v1/health

# 2. Check HTTPS server health
curl -sk https://127.0.0.1:8443/api/v1/health

# 3. Test Gemini API connection
curl -s http://127.0.0.1:7860/api/v1/settings/test-connection

# 4. Run automated test suite
cd backend && ../.venv/bin/python -m pytest tests/
build

11. Operational Troubleshooting

Observed Issue Root Cause Operational Resolution
Camera does not open on laptop Connected via plain HTTP on a non-localhost IP address. Open https://192.168.29.180:8443/#/studio and click Advanced → Proceed.
[Errno 98] Address already in use A previously started server process is still bound to the port. Run fuser -k 7860/tcp 8443/tcp to free the sockets before restarting.
google-genai not found (502 error) Process launched with system Python rather than .venv. Always execute with ../.venv/bin/python -m uvicorn app.main:app ...
Safety filter NO_IMAGE (422 error) Gemini safety filter flagged input portrait or prompt. The app handles this gracefully; advise user to upload a clear studio portrait.