Skip to main content

Local Development Setup

Complete guide for setting up your local development environment.

Prerequisites​

Required Software​

SoftwareVersionPurpose
Node.js18+Frontend development
Python3.11+Backend development
PostgreSQL14+Database (optional - can use remote)
GitLatestVersion control
  • VS Code with Python and TypeScript extensions
  • Postman or Insomnia for API testing
  • pgAdmin or DBeaver for database management

Backend Setup​

1. Clone and Navigate​

git clone <repository-url>
cd tellus/tellus-ehs-hazcom-service

2. Create Virtual Environment​

python3 -m venv venv
source venv/bin/activate  # macOS/Linux
# OR
.\venv\Scripts\activate   # Windows

3. Install Dependencies​

pip install -r requirements.txt

4. Configure Environment​

Create .env file:

# Database
DATABASE_URL=postgresql://tellus_ehs_dev_user:PASSWORD@host:25060/tellus_ehs_dev

# Supabase Auth
SUPABASE_URL=https://mwvqgmowzphjmphvndju.supabase.co
SUPABASE_ANON_KEY=your-anon-key
SUPABASE_SERVICE_KEY=your-service-key

# JWT
JWT_SECRET_KEY=your-secret-key

# CORS
ALLOWED_ORIGINS=http://localhost:5174,http://localhost:3000

# AWS (for S3/SDS storage)
AWS_ACCESS_KEY_ID=your-key
AWS_SECRET_ACCESS_KEY=your-secret
AWS_REGION=us-west-2
S3_BUCKET_NAME=tellus-sds-documents

# OpenAI (for AI features)
OPENAI_API_KEY=your-openai-key

5. Run Database Migrations​

alembic upgrade head

6. Start Development Server​

# Option 1: Direct Python
python -m app.main

# Option 2: Uvicorn with reload
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000

API available at: http://localhost:8000 API docs: http://localhost:8000/api/docs

Frontend Setup​

1. Navigate to Frontend​

cd tellus/tellus-ehs-hazcom-ui

2. Install Dependencies​

npm install

3. Configure Environment​

Create .env.local:

VITE_API_URL=http://localhost:8000
VITE_SUPABASE_URL=https://mwvqgmowzphjmphvndju.supabase.co
VITE_SUPABASE_ANON_KEY=your-anon-key

4. Start Development Server​

npm run dev

Frontend available at: http://localhost:5174

Background Service Setup​

1. Navigate to Service​

cd tellus/tellus-ehs-background-service

2. Setup Virtual Environment​

python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

3. Configure Environment​

Same .env as main backend service, plus:

# LLM for SDS parsing
ANTHROPIC_API_KEY=your-anthropic-key
# OR
OPENAI_API_KEY=your-openai-key

# Job Configuration
SDS_PARSE_BATCH_SIZE=5
SDS_PARSE_MAX_RETRIES=3

4. Run Service​

python -m app.main

Database Access​

Development Database​

PGPASSWORD="your-password" psql \
  -h db-host.ondigitalocean.com \
  -p 25060 \
  -U tellus_ehs_dev_user \
  -d tellus_ehs_dev

Common Commands​

# List tables
\dt

# Describe table
\d table_name

# Run query
SELECT * FROM companies LIMIT 5;

VS Code Configuration​

  • Python (Microsoft)
  • Pylance
  • ESLint
  • Prettier
  • Tailwind CSS IntelliSense
  • Thunder Client (API testing)

Settings (.vscode/settings.json)​

{
  "python.defaultInterpreterPath": "./venv/bin/python",
  "python.formatting.provider": "black",
  "editor.formatOnSave": true,
  "[python]": {
    "editor.defaultFormatter": "ms-python.black-formatter"
  },
  "[typescript]": {
    "editor.defaultFormatter": "esbenp.prettier-vscode"
  }
}

Troubleshooting​

Backend Issues​

Port already in use:

lsof -i :8000
kill -9 <PID>

Database connection failed:

  • Check VPN if using remote database
  • Verify credentials in .env
  • Check database host is accessible

Frontend Issues​

Module not found:

rm -rf node_modules package-lock.json
npm install

Type errors after pull:

npm run build  # Catches type errors

Migration Issues​

Alembic head mismatch:

alembic current
alembic stamp head  # Reset to current
alembic upgrade head