Skip to main content

Native Local Setup

Guide to running Orange without Docker by installing all dependencies directly on your machine.

When to Use Native Setup​

✅ Good for:

  • Learning how each component works
  • Debugging system-level issues
  • Performance-critical development
  • Working offline without Docker Desktop

⚠️ Consider Docker instead if:

  • You want faster setup (5 minutes vs 30+ minutes)
  • Team needs consistent environments
  • You're on Windows (PostgreSQL/Redis are Linux-native)

Prerequisites​

  • Admin/sudo access - For installing system packages
  • Command-line tools - Terminal/PowerShell familiarity
  • ~2GB disk space - For all dependencies

Installation Guide​

Choose your operating system:

macOS​

1. Install Homebrew (if not installed)​

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

2. Install PostgreSQL​

# Install PostgreSQL 16
brew install postgresql@16

# Start PostgreSQL service
brew services start postgresql@16

# Verify installation
psql --version
# Should output: psql (PostgreSQL) 16.x

3. Install Redis​

# Install Redis 7
brew install redis

# Start Redis service
brew services start redis

# Verify installation
redis-cli --version
# Should output: redis-cli 7.x

4. Install Python 3.11​

# Install Python 3.11
brew install python@3.11

# Verify installation
python3.11 --version
# Should output: Python 3.11.x

5. Install uv​

curl -LsSf https://astral.sh/uv/install.sh | sh

# Verify installation
uv --version

Linux (Ubuntu/Debian)​

1. Update Package Manager​

sudo apt update
sudo apt upgrade -y

2. Install PostgreSQL​

# Install PostgreSQL 16
sudo apt install -y postgresql-16 postgresql-contrib-16

# Start PostgreSQL service
sudo systemctl start postgresql
sudo systemctl enable postgresql

# Verify installation
psql --version

3. Install Redis​

# Install Redis 7
sudo apt install -y redis-server

# Start Redis service
sudo systemctl start redis-server
sudo systemctl enable redis-server

# Verify installation
redis-cli --version

4. Install Python 3.11​

# Add deadsnakes PPA for Python 3.11
sudo apt install -y software-properties-common
sudo add-apt-repository -y ppa:deadsnakes/ppa
sudo apt update

# Install Python 3.11 and dev tools
sudo apt install -y python3.11 python3.11-venv python3.11-dev

# Verify installation
python3.11 --version

5. Install System Dependencies​

# Required for building Python packages
sudo apt install -y build-essential libpq-dev git curl

6. Install uv​

curl -LsSf https://astral.sh/uv/install.sh | sh

# Add to PATH (if not automatic)
export PATH="$HOME/.cargo/bin:$PATH"

# Verify installation
uv --version

Windows​

1. Install PostgreSQL​

  1. Download installer: https://www.postgresql.org/download/windows/
  2. Run installer (PostgreSQL 16 recommended)
  3. Set password for postgres user during installation
  4. Add PostgreSQL to PATH when prompted
  5. Verify installation:
psql --version

2. Install Redis​

Redis doesn't have official Windows support. Use WSL2 or memurai:

Option A: WSL2 (Recommended)

# Install WSL2
wsl --install

# Inside WSL2:
sudo apt update
sudo apt install redis-server
redis-server --daemonize yes

Option B: Memurai (Redis-compatible)

  1. Download: https://www.memurai.com/
  2. Install and start service
  3. Compatible with Redis commands

3. Install Python 3.11​

  1. Download: https://www.python.org/downloads/
  2. Run installer
  3. ✅ Check "Add Python to PATH"
  4. Verify installation:
python --version

4. Install uv​

powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

# Verify installation
uv --version

Database Setup​

Create Database and User​

macOS/Linux​

# Connect as postgres user
sudo -u postgres psql

# Or on macOS:
psql postgres
-- Create user
CREATE USER orange_user WITH PASSWORD 'orange_password';

-- Create database
CREATE DATABASE orange_db OWNER orange_user;

-- Grant privileges
GRANT ALL PRIVILEGES ON DATABASE orange_db TO orange_user;

-- Exit
\q

Windows​

# Connect as postgres user
psql -U postgres

# Enter password set during installation
-- Same SQL as above
CREATE USER orange_user WITH PASSWORD 'orange_password';
CREATE DATABASE orange_db OWNER orange_user;
GRANT ALL PRIVILEGES ON DATABASE orange_db TO orange_user;
\q

Verify Database Connection​

# Test connection
psql -U orange_user -d orange_db -h localhost

# Should connect without errors
# Exit with \q

Project Setup​

1. Clone Repository​

git clone https://github.com/equalcollective/santra-be.git
cd santra-be

2. Configure Environment​

# Copy environment template
cp .env.example .env

Edit .env file:

# Database (using local PostgreSQL)
DATABASE_URL=postgresql://orange_user:orange_password@localhost:5432/orange_db
POSTGRES_USER=orange_user
POSTGRES_PASSWORD=orange_password
POSTGRES_DB=orange_db
POSTGRES_SERVER=localhost
POSTGRES_PORT=5432

# Redis (using local Redis)
REDIS_URL=redis://localhost:6379/0

# Security (generate a secure random string)
SECRET_KEY=your-secret-key-here-change-in-production

# Azure Blob Storage (required for file uploads)
AZURE_STORAGE_CONNECTION_STRING=your-connection-string
AZURE_STORAGE_CONTAINER_NAME=report-uploads

# Create first admin user
FIRST_SUPERUSER_EMAIL=admin@example.com
FIRST_SUPERUSER_PASSWORD=changeme

# Disable OpenTelemetry for local dev (optional)
OTEL_ENABLED=false

3. Install Python Dependencies​

# Create virtual environment and install dependencies
uv sync

This creates .venv/ directory with all dependencies installed.

4. Run Database Migrations​

# Apply all migrations
uv run alembic upgrade head

5. Start the API Server​

# Start FastAPI with auto-reload
uv run uvicorn app.main:app --reload --host 0.0.0.0 --port 8000

API available at: http://localhost:8000

6. Start Celery Worker (Optional)​

For background tasks:

# In a new terminal
uv run celery -A app.celery_app worker --loglevel=info

Service Management​

PostgreSQL​

Start/Stop:

# macOS
brew services start postgresql@16
brew services stop postgresql@16

# Linux
sudo systemctl start postgresql
sudo systemctl stop postgresql

# Windows
net start postgresql-x64-16
net stop postgresql-x64-16

Check Status:

# macOS/Linux
pg_isready

# View logs
# macOS
tail -f /usr/local/var/postgresql@16/server.log

# Linux
sudo journalctl -u postgresql -f

Redis​

Start/Stop:

# macOS
brew services start redis
brew services stop redis

# Linux
sudo systemctl start redis-server
sudo systemctl stop redis-server

# Manual start (all platforms)
redis-server

Check Status:

redis-cli ping
# Should return: PONG

View logs:

# macOS
tail -f /usr/local/var/log/redis.log

# Linux
sudo journalctl -u redis-server -f

Uninstalling​

macOS​

brew uninstall postgresql@16
brew uninstall redis
rm -rf /usr/local/var/postgresql@16
rm -rf /usr/local/var/log/redis.log

Linux​

sudo apt remove --purge postgresql-16 redis-server
sudo rm -rf /var/lib/postgresql
sudo rm -rf /var/lib/redis

Windows​

Use Windows "Add or Remove Programs" to uninstall:

  • PostgreSQL
  • Python (if not needed)

Next Steps​