Self-Host Anywhere

Consumer Installation Guide

Choose your deployment environment below to get your self-hosted photo cloud up and running in minutes. No proprietary lock-in.

One-Line Automated Script

Automates Docker installation, directory creation, cryptographic key generation, and service startup on any Debian, Ubuntu, or Fedora Linux system.

Fastest (60s)

Hardware Configuration & AI Model Allocation

Select your system resource profile (Low 2GB, Medium 4GB, High 8GB+) to tune worker threads and face recognition models.

Prerequisites

A Linux VPS or local PC (Ubuntu 20.04+, Debian 11+, or Fedora)
Root or sudo privileges
At least 4 GB RAM and 10 GB free disk space

Command Line

curl -sL https://photobackend.app/install.sh | FACE_MODEL=buffalo_m WORKER_THREADS=2 bash

Step-by-Step Setup

Run the Installer Command

Open your terminal and paste the curl command above. The installer will verify Docker and docker-compose availability.

Wait for Container Initialization

Pre-built multi-arch images will be pulled from GitHub Container Registry (GHCR) and started automatically.

Access the Web App

Open http://localhost:8080 (or your server's IP) to set up your admin account and start uploading photos.

PRO / ADVANCED100% Local-Only Capable

Advanced Configuration & .env Reference

Complete environment variable manual for homelab administrators, custom reverse proxies, and isolated air-gapped deployments.

No Cloud Account Required (Local-Only Architecture)

Photo-Backend never phones home by default. If you prefer to expose your instance using your own domain, reverse proxy (Nginx, Traefik, Caddy), or a private VPN (WireGuard, Tailscale), simply omit HUB_API_KEY. The mobile app features a dedicated "Skip website configuration (Direct Register)" option to connect straight to your local IP or reverse proxy domain without creating a commercial account.

Environment Variables Directory

Variable	Category	Default Value	Description
DATABASE_URL	Database	postgres://photo_user:secret@db:5432/photo_db	PostgreSQL connection string with pgvector extension enabled.
SERVER_PORT	Core	8080	HTTP port where the Rust Actix-Web backend listens for requests.
STORAGE_PATH	Core	/app/storage	Root directory path on disk where original media, thumbnails, and cache are saved.
JWT_SECRET	Security	change_to_a_random_32_char_secret_key	Cryptographic secret used to sign and verify user authentication JWT tokens.
FACE_MODEL	AI & Performance	buffalo_m	InsightFace model tier: buffalo_s (Low/2GB), buffalo_m (Medium/4GB), or buffalo_l (Pro/8GB).
AI_SERVICE_URL	AI & Performance	http://ai-service:8000	Internal network URL used by the backend to communicate with the Python AI sidecar.
APP_URL	Networking	http://localhost:8080	Public URL of the backend instance, used for CORS headers and public sharing links.
HUB_API_KEYoptional	Networking	—	Encrypted P2P relay connection key. Omit entirely for 100% offline or local-only operation.
TOTAL_THREAD_NUMBERoptional	AI & Performance	4	CPU thread pool allocation for backend HTTP workers and async task pipelines.
LOG_LEVELoptional	Core	info	Logging verbosity level (trace, debug, info, warn, error).

Complete Sample .env File

# ==============================================================
# Photo-Backend Configuration (.env)
# ==============================================================

# Database (PostgreSQL with pgvector)
DATABASE_URL=postgres://photo_user:secure_password_here@db:5432/photo_db

# Security & Authentication (Generate with: openssl rand -hex 32)
JWT_SECRET=please_generate_a_random_secret_at_least_32_chars_long

# Storage & Paths
STORAGE_PATH=./data/storage
LOG_PATH=./data/logs
LOG_LEVEL=info

# Network & Server Port
SERVER_PORT=8080
APP_URL=https://photos.yourdomain.com

# AI Microservice (Sidecar)
AI_SERVICE_URL=http://ai-service:8000
FACE_MODEL=buffalo_m
TOTAL_THREAD_NUMBER=4

# --------------------------------------------------------------
# Local-Only / Air-Gapped Mode:
# Leave HUB_API_KEY empty to disable all external cloud relay.
# --------------------------------------------------------------
# HUB_API_KEY=

Custom Reverse Proxy Setup (Nginx Example)

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

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

    client_max_body_size 500M; # Support large camera video uploads

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

Next Steps

Post-Installation Verification

Follow these 4 quick steps after your containers are healthy to ensure production security and mobile sync readiness.

1. Create Administrator Account

Open http://localhost:8080 or your NAS IP address in your browser. Complete the initial registration wizard to establish the primary admin user.

2. Configure HTTPS / Reverse Proxy

For secure remote access, place Caddy, Nginx Proxy Manager, or Traefik in front of port 8080 to provide automatic Let's Encrypt SSL certificates.

Caddy one-liner: photo.yourdomain.com { reverse_proxy 127.0.0.1:8080 }

3. Connect Central Hub API Key (Free)

In Admin Console > Settings > Hub Setup, enter your free HUB_API_KEY to activate STUN NAT traversal for remote mobile sync without open ports.

4. Pair Mobile Devices

Download the Photo-Backend app from Apple App Store or Google Play Store. On first launch, connect to your server to start your 7-day free trial.