Quick Start

Get DepthSight running in minutes — from zero to a fully operational algorithmic trading platform. This page walks you through every deployment path, from a one-command production install to a local development setup for hacking on the codebase.

---

Architecture at a Glance

Before you deploy, it helps to understand which services you're spinning up and how they interact. DepthSight runs eight containerized services orchestrated by Docker Compose, with Caddy as the reverse proxy and TLS terminator.

Each service connects to Redis with its own ACL user and password, ensuring isolation even within a single Docker network. The Market Data Service owns all exchange WebSocket connections and fans out data to bot workers via a dedicated Redis instance — this is the production path (MARKET_DATA_FANOUT_MODE=redis). For local development, you can skip this service entirely and let the bot stream data directly (MARKET_DATA_FANOUT_MODE=direct).

---

System Requirements

DepthSight is enterprise-grade infrastructure, not a lightweight script. The minimum requirements reflect the concurrent load of real-time market data processing, ML inference, and multi-user API serving.

Resource	Minimum	Recommended	Notes
CPU	6 modern cores	8+ cores	Bot workers, Celery, and ML pipelines run concurrently
RAM	16 GB	32 GB	Redis, PostgreSQL, and Python workers each consume significant memory
Disk	40 GB SSD	100 GB SSD	Market data snapshots and logs grow over time
OS	Ubuntu 22.04+	Ubuntu 24.04 LTS	One-click deploy script targets Debian/Ubuntu
Docker	24.0+	Latest	Required for all deployment paths
Python	3.11+	3.12	Backend runtime; 3.12-slim used in production images

DepthSight automatically provisions a 4 GB swap file during one-click deployment to prevent OOM kills during peak market volatility. If you're deploying manually, ensure your host has adequate swap configured.

---

Service Map and Ports

Understanding which service lives on which port helps you verify health after deployment and troubleshoot connectivity issues.

Service	Container Name	Internal Port	Exposed	Purpose
Caddy	depthsight_caddy	80, 443	✅ Host	Reverse proxy, auto-SSL, static asset serving
API	depthsight_api	8000	Via Caddy	FastAPI REST + Swagger docs at /docs
WebSocket	depthsight_websocket	8765	Via Caddy	Real-time trade and bot events
Frontend	depthsight_frontend	80	Via Caddy	React web dashboard
PWA	depthsight_pwa	80	Via Caddy	Mobile-optimized client at /pwa/
PostgreSQL	depthsight_postgres	5432	❌ Internal	Persistent relational storage
Redis (System)	depthsight_redis	6379	❌ Internal	JWT sessions, quotas, Celery broker
Redis (Market)	depthsight_redis_market	6379	❌ Internal	High-throughput HFT pub/sub
Market Data	depthsight_market_data	n/a	❌ Internal	Central exchange stream fan-out
Bot Runner	depthsight_bot	n/a	❌ Internal	Trading engine runtime
Celery Worker	depthsight_celery_worker	n/a	❌ Internal	Background jobs (8 concurrent workers)

In production, Caddy is the only service that binds to host ports. All other services communicate over the internal Docker network. In local development mode, the API and frontend bind directly to localhost ports.

---

Deployment Paths

Choose the deployment path that matches your use case:

Path	Best For	Time	Complexity
One-Click Deploy	Production servers, first-time users	~5 min	⭐
Manual Docker	Custom infrastructure, homelab	~10 min	⭐⭐
Local Development	Contributing code, debugging	~15 min	⭐⭐⭐

---

Path 1: One-Click Production Deploy

The fastest path to a running instance. A single command installs Docker, generates all cryptographic secrets, configures networking, sets up the firewall, and starts every service.

curl -sL "https://raw.githubusercontent.com/DepthSight-Pro/DepthSight/main/deploy.sh" | sudo bash

The interactive installer will prompt you for three decisions:

1. Domain Name: The domain where Caddy will configure SSL (e.g. trading.yourdomain.com).
2. Environment: Select testnet or mainnet configuration defaults.
3. Default Credentials: Configure the administrator username and password.

After the script completes, your instance is available at the displayed URL. The installer also sets up a host-side cron job that checks for a .update_trigger file every minute, enabling secure one-click updates from the web UI without exposing root privileges to the container.

---

Path 2: Manual Docker Compose

For when you need full control over the deployment environment — homelab setups, custom orchestration, or air-gapped networks.

Step 1 — Clone and configure environment:

git clone https://github.com/DepthSight-Pro/DepthSight.git
cd DepthSight
cp .env.example .env

Step 2 — Replace all placeholder secrets:

The .env.example file ships with change_me_* placeholders. Every one of these must be replaced before exposing the instance to any network:

Variable Group	Variables	How to Generate
JWT & Auth	JWT_SECRET_KEY, CONFIRMATION_SECRET_KEY, API_KEY_SECRET	openssl rand -base64 32
Encryption	API_ENCRYPTION_KEY	Fernet key: python3 -c "import os,base64; print(base64.urlsafe_b64encode(os.urandom(32)).decode())"
PostgreSQL	POSTGRES_USER, POSTGRES_PASSWORD, POSTGRES_DB	Choose strong values
Redis ACL	REDIS_PASSWORD, REDIS_API_PASSWORD, REDIS_WEBSOCKET_PASSWORD, REDIS_BOT_PASSWORD, REDIS_CELERY_PASSWORD, REDIS_MARKET_DATA_PASSWORD	openssl rand -hex 12 (one per service)

The Redis container builds ACL users at startup from the service-specific password variables. REDIS_PASSWORD is only a fallback when a service-specific password isn't set. For production, always configure unique passwords per service to maintain isolation.

Step 3 — Build and start all services:

docker compose up -d --build

The API container's entrypoint (docker-startup.sh) automatically runs alembic upgrade head with a file lock before starting the application — database migrations are applied on first boot, so no manual migration step is needed.

Step 4 — Verify all services are healthy:

docker compose ps

You should see all containers in a running or healthy state. Access the API documentation at http://localhost:8000/docs and the frontend at http://localhost:5173.

---

Path 3: Local Development (Without Docker)

For contributors who need hot-reload, debugger attachment, and fast iteration cycles. This path runs each service directly on the host.

Step 1 — Create a virtual environment and install dependencies:

python -m venv .venv
source .venv/bin/activate        # .venv\Scripts\activate on Windows
pip install -r requirements.txt

Step 2 — Configure environment:

cp .env.example .env
# Edit .env: set POSTGRES_HOST=localhost, REDIS_HOST=localhost
# Provide all required secrets as listed in the Environment section below

Step 3 — Run database migrations:

alembic upgrade head

Step 4 — Start each service in a separate terminal:

Terminal	Service	Command
1	API	uvicorn api.depthsight_api:app --host 0.0.0.0 --port 8000 --reload
2	WebSocket	uvicorn api.websocket_server:app --host 0.0.0.0 --port 8765 --reload
3	Bot Runner	python bot_runner.py
4	Celery	celery -A tasks.celery_app worker --loglevel=info --pool=prefork -c 2
5	Frontend	cd frontend && npm install && npm run dev
6	PWA	cd pwa && npm install && npm run dev

For the bot runner, use MARKET_DATA_FANOUT_MODE=direct in your .env to skip the Market Data Service entirely — the bot will open exchange WebSocket streams directly. To test the production fan-out path locally, set MARKET_DATA_FANOUT_MODE=redis and start the service in an additional terminal:

python market_data_service.py
python bot_runner.py

---

Environment Configuration

The .env file is the central configuration surface for the entire platform. Here's what you need for a minimal local run versus a full production deployment.

Minimum Required (Local Run)

These variables must be set for the backend to start at all:

Variable	Purpose	Example / Value
POSTGRES_USER	Database user	depthsight
POSTGRES_PASSWORD	Database password	(strong random value)
POSTGRES_DB	Database name	depthsight
POSTGRES_HOST	Database host	localhost (local) / postgres (Docker)
POSTGRES_PORT	Database port	5432
REDIS_HOST	Redis host	localhost (local) / redis (Docker)
REDIS_PORT	Redis port	6379
REDIS_USERNAME	Redis ACL user	api (Docker) / (empty for local)
REDIS_PASSWORD	Redis fallback password	(strong random value)
JWT_SECRET_KEY	Token signing key	openssl rand -base64 32
CONFIRMATION_SECRET_KEY	Email confirmation key	openssl rand -base64 32
API_KEY_SECRET	API key signing	openssl rand -base64 32
API_ENCRYPTION_KEY	Fernet key for secrets	(base64-encoded 32-byte key)

Market Data Fan-Out Mode

This single variable controls a critical architectural behavior:

Value	Behavior	When to Use
direct	Bot opens exchange WebSocket streams directly	Local development, single-user, no Redis market instance
redis	Market Data Service owns exchange connections; fans out via Redis Pub/Sub	Production, multi-worker scaling, reduced exchange connection count

Exchange Credentials (Live Trading)

To connect to exchanges for live or paper trading, set the environment selector and corresponding API keys:

# Which environment to use
ACTIVE_TRADING_ENVIRONMENT=testnet    # Start here first!
TRADING_MARKET_TYPE=futures_usdtm     # or 'spot'
 
# Testnet credentials (always test here first)
TESTNET_BINANCE_SPOT_API_KEY=your_key
TESTNET_BINANCE_SPOT_API_SECRET=your_secret
TESTNET_BINANCE_FUTURES_API_KEY=your_key
TESTNET_BINANCE_FUTURES_API_SECRET=your_secret

The configuration loader in bot_module/config.py automatically selects the correct credential set based on ACTIVE_TRADING_ENVIRONMENT. Always verify your entire workflow on testnet before switching to mainnet.

---

Post-Deployment Verification

After any deployment path, run through this checklist to confirm everything is operational:

Step	Verification	Expected Result
1	Visit http://YOUR_HOST/docs (or /api/docs via Caddy)	FastAPI Swagger UI loads successfully
2	Visit http://YOUR_HOST:5173 (local) or https://YOUR_DOMAIN (production)	React dashboard renders login screen
3	Open browser DevTools → Network → WS	WebSocket connects to /ws without errors
4	Run docker compose ps (Docker)	All containers display a running or healthy state
5	Check docker compose logs api --tail 20	No python stack traces; database migrations confirmed
6	Register a user account via the frontend	Account created successfully; JWT token issued

---

Keeping DepthSight Updated

DepthSight provides two update mechanisms:

• Web UI Update (Recommended): Click the "Update" button in the admin dashboard. This writes a .update_trigger file to the shared data/ volume. A host-side cron job (installed by deploy.sh) detects the trigger file and executes the update script — no root access is exposed to the container.
• Manual CLI Update:

  sudo bash /opt/depthsight/update.sh

The update script pulls the latest main branch, rebuilds containers, applies database migrations, and prunes stale Docker images. Your .env and data/ volumes are preserved across updates.

---

Troubleshooting

Symptom	Likely Cause	Resolution
API container crashes on startup	Missing .env variables	Verify all required secrets are set; check docker compose logs api for detail
alembic upgrade head fails	PostgreSQL not ready	Ensure postgres container is healthy before API starts; Docker healthchecks handle this automatically
Bot cannot connect to exchange	Invalid API keys or wrong environment	Confirm ACTIVE_TRADING_ENVIRONMENT matches your credential set; test with testnet first
WebSocket disconnects frequently	Redis connection issue	Verify REDIS_WEBSOCKET_PASSWORD matches the ACL user defined in the Redis container
Frontend shows blank page	VITE_API_URL mismatch	Ensure the frontend build arg matches your actual API URL; rebuild with --build
Caddy SSL certificate errors	DNS not pointing to server	Verify domain DNS records; ensure ports 80 and 443 are open for ACME challenges

---

Where to Go Next

Now that DepthSight is running, here's the logical reading path to deepen your understanding:

1. Architecture Overview — Understand how the eight services interact, the data flow from exchange to dashboard, and the design principles behind the system.
2. Strategy and Signal System — Learn how to build trading strategies using the visual builder and the weighted foundations system.
3. Dual Backtesting Engines — Validate your strategies with the fast vector engine or the detailed candle/tick-level simulator before risking real capital.
4. Dynamic Risk Management — Configure the intelligent risk engine that adapts position sizing per trading pair.