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.
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.
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). |
3. Hardware Camera & HTTPS Security
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).
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):
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
5. Docker & Docker Compose Deployment
Containerized production deployment provides full process isolation and automatic restart capabilities.
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
# 1. Build and run in background
docker compose up -d --build
# 2. View real-time container logs
docker compose logs -f hair-studio
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.
[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
sudo systemctl daemon-reload
sudo systemctl enable --now hair-studio-https
sudo systemctl enable --now hair-studio-http
7. Nginx TLS Reverse Proxy (Public Domain)
Recommended for public cloud servers with a domain name and Let's Encrypt SSL certificate.
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";
}
}
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. |
9. Storage & SQLite Hot Backup
All user data, portraits, and generated looks persist under backend/storage/:
# 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.')
"
10. Health Verification Commands
# 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/
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. |