Development Environment Setup¶

Complete guide for setting up Certana development environment.

System Requirements¶

Minimum Specifications¶

CPU: 4-core processor (8-core recommended)
RAM: 8GB (16GB recommended)
Storage: 50GB free space
Network: Stable internet connection

Supported Operating Systems¶

macOS 12+
Ubuntu 20.04+
Windows 10/11 (with WSL2)

Installation¶

1. System Dependencies¶

macOS¶

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

# Install required tools
brew install python@3.11 postgresql redis node nvm git

# Start PostgreSQL
brew services start postgresql

# Start Redis
brew services start redis

Ubuntu¶

# Update system
sudo apt-get update && sudo apt-get upgrade -y

# Install dependencies
sudo apt-get install -y \
  python3.11 python3.11-venv \
  postgresql postgresql-contrib \
  redis-server \
  nodejs npm \
  git curl build-essential

# Start services
sudo systemctl start postgresql
sudo systemctl start redis-server

Windows (WSL2)¶

# Install WSL2 first
wsl --install -d Ubuntu-22.04

# Then follow Ubuntu instructions

2. Clone Repository¶

git clone https://github.com/your-org/certana.git
cd certana

# Create main directories
mkdir -p data logs

3. Backend Setup¶

cd backend

# Create and activate virtual environment
python3.11 -m venv venv
source venv/bin/activate  # macOS/Linux
# venv\Scripts\activate    # Windows

# Install dependencies
pip install -r requirements.txt

# Copy environment template
cp .env.example .env

# Edit .env with your settings
nano .env

4. Frontend Setup¶

cd ../frontend

# Install Node dependencies
npm install

# Create .env file
cp .env.example .env

# Edit .env
nano .env

5. Extension Setup¶

cd ../browser

# Install Node dependencies
npm install

# Create .env file
cp .env.example .env

# Edit .env
nano .env

Development Workflow¶

Starting Services¶

Terminal 1: PostgreSQL & Redis¶

# Already running via system services
# Verify:
pg_isready
redis-cli ping

Terminal 2: Backend¶

cd backend
source venv/bin/activate
python -m uvicorn src.main:app --reload --host 0.0.0.0 --port 8000

Terminal 3: Frontend¶

cd frontend
npm start

Terminal 4: Extension¶

cd browser
npm run dev

All-in-One Docker Setup¶

# From project root
docker-compose up -d

# Check status
docker-compose ps

# View logs
docker-compose logs -f

# Stop
docker-compose down

Code Style & Quality¶

Python (Backend)¶

Format Code¶

# Install tools
pip install black isort

# Format
black src/ tests/
isort src/ tests/

Linting¶

pip install flake8 pylint

# Check
flake8 src/
pylint src/

Type Checking¶

pip install mypy

# Check
mypy src/

Pre-commit Hooks¶

pip install pre-commit

# Install hooks
pre-commit install

# Run manually
pre-commit run --all-files

Create .pre-commit-config.yaml:

repos:
  - repo: https://github.com/psf/black
    rev: 23.1.0
    hooks:
      - id: black

  - repo: https://github.com/PyCQA/isort
    rev: 5.12.0
    hooks:
      - id: isort

  - repo: https://github.com/pre-commit/pre-commit-hooks
    rev: v4.4.0
    hooks:
      - id: trailing-whitespace
      - id: end-of-file-fixer

TypeScript (Frontend & Extension)¶

Formatting¶

npm install --save-dev prettier

# Format
npx prettier --write src/

Linting¶

npm install --save-dev eslint @typescript-eslint/eslint-plugin

# Check
npm run lint

Create `.eslintrc.json`¶

{
  "extends": [
    "eslint:recommended",
    "plugin:@typescript-eslint/recommended"
  ],
  "parser": "@typescript-eslint/parser",
  "rules": {
    "no-console": "warn",
    "no-unused-vars": "off",
    "@typescript-eslint/no-unused-vars": "error"
  }
}

Testing¶

Backend Tests¶

cd backend

# Install test dependencies
pip install pytest pytest-asyncio pytest-cov

# Run all tests
pytest

# Run with coverage
pytest --cov=src --cov-report=html

# Run specific test file
pytest tests/test_assets.py -v

# Run with markers
pytest -m unit  # Only unit tests
pytest -m integration  # Only integration tests

Create pytest.ini:

[pytest]
testpaths = tests
python_files = test_*.py
python_classes = Test*
python_functions = test_*
markers =
    unit: Unit tests
    integration: Integration tests
    slow: Slow tests

Frontend Tests¶

cd frontend

# Install testing library
npm install --save-dev @testing-library/react-native jest

# Run tests
npm test

# With coverage
npm test -- --coverage

Extension Tests¶

cd browser

# Run tests
npm test

# With coverage
npm test -- --coverage

Debugging¶

Backend Debugging¶

Using VSCode¶

Create .vscode/launch.json:

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Backend",
      "type": "python",
      "request": "launch",
      "module": "uvicorn",
      "args": [
        "src.main:app",
        "--reload",
        "--host", "0.0.0.0",
        "--port", "8000"
      ],
      "cwd": "${workspaceFolder}/backend",
      "env": {
        "PYTHONPATH": "${workspaceFolder}/backend"
      }
    }
  ]
}

Using pdb¶

import pdb; pdb.set_trace()

Using Logger¶

import logging
logger = logging.getLogger(__name__)
logger.debug("Message", extra={"key": "value"})

Frontend Debugging¶

React DevTools¶

# Browser extension: https://react-devtools-tutorial.vercel.app/

Console Logging¶

console.log("Debug message", value);
console.error("Error:", error);
console.table(data);  // Pretty print arrays/objects

Database Debugging¶

# Connect to PostgreSQL
psql -U certana -d certana

# List tables
\dt

# Describe table
\d assets

# Run query
SELECT * FROM assets LIMIT 10;

# View indexes
\di

# Analyze query
EXPLAIN ANALYZE SELECT * FROM assets WHERE content_hash = 'xxx';

Git Workflow¶

Branch Strategy¶

# Main branches
main           # Production-ready
develop        # Development

# Feature branches
feature/feature-name
bugfix/bug-name
docs/doc-name

Commit Messages¶

feat: Add new feature
fix: Fix bug
docs: Update documentation
style: Code style changes
refactor: Refactor code
test: Add tests
chore: Build, deps, config

Workflow¶

# Create feature branch
git checkout -b feature/my-feature develop

# Make changes
git add .
git commit -m "feat: Add my feature"

# Push to remote
git push origin feature/my-feature

# Create pull request
# (Create on GitHub/GitLab UI)

# After approval, merge to develop
git checkout develop
git merge --no-ff feature/my-feature
git push origin develop

Environment Variables¶

Backend (.env)¶

# See backend/installation.md

Frontend (.env)¶

REACT_APP_API_URL=http://localhost:8000/v1
REACT_APP_ENV=development

Extension (.env)¶

VITE_API_URL=http://localhost:8000/v1
VITE_ENV=development

Documentation¶

Generate API Docs¶

# Backend Swagger (automatic)
# Visit: http://localhost:8000/docs

# ReDoc (automatic)
# Visit: http://localhost:8000/redoc

Generate MkDocs¶

cd docs

# Install MkDocs
pip install mkdocs mkdocs-material

# Build and serve
mkdocs serve

# Build static site
mkdocs build

IDE Setup¶

VSCode¶

Extensions¶

Python
Pylance
PyLance
Better Comments
REST Client
Thunder Client
ES7+ React/Redux/React-Native
Vue Language Features
TypeScript Vue Plugin

Settings (`.vscode/settings.json`)¶

{
  "python.linting.enabled": true,
  "python.linting.pylintEnabled": true,
  "python.formatting.provider": "black",
  "editor.formatOnSave": true,
  "editor.defaultFormatter": "esbenp.prettier-vscode",
  "[python]": {
    "editor.defaultFormatter": "ms-python.python"
  },
  "python.testing.pytestEnabled": true,
  "python.testing.pytestArgs": ["tests"]
}

PyCharm¶

Open project
Configure interpreter: Settings > Project > Python Interpreter
Select virtual environment: backend/venv
Enable type checking: Settings > Editor > Inspections

Troubleshooting¶

Common Issues¶

Port Already in Use¶

# Find process using port
lsof -i :8000

# Kill process
kill -9 <PID>

Database Connection Error¶

# Check PostgreSQL
pg_isready

# Restart PostgreSQL
brew services restart postgresql  # macOS
sudo systemctl restart postgresql  # Linux

Virtual Environment Issues¶

# Recreate venv
rm -rf venv
python3.11 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

Node Module Issues¶

# Clear cache and reinstall
rm -rf node_modules package-lock.json
npm install

Development Environment Setup¶

System Requirements¶

Minimum Specifications¶

Supported Operating Systems¶

Installation¶

1. System Dependencies¶

macOS¶

Ubuntu¶

Windows (WSL2)¶

2. Clone Repository¶

3. Backend Setup¶

4. Frontend Setup¶

5. Extension Setup¶

Development Workflow¶

Starting Services¶

Terminal 1: PostgreSQL & Redis¶

Terminal 2: Backend¶

Terminal 3: Frontend¶

Terminal 4: Extension¶

All-in-One Docker Setup¶

Code Style & Quality¶

Python (Backend)¶

Format Code¶

Linting¶

Type Checking¶

Pre-commit Hooks¶

TypeScript (Frontend & Extension)¶

Formatting¶

Linting¶

Create .eslintrc.json¶

Testing¶

Backend Tests¶

Frontend Tests¶

Extension Tests¶

Debugging¶

Backend Debugging¶

Using VSCode¶

Using pdb¶

Using Logger¶

Frontend Debugging¶

React DevTools¶

Console Logging¶

Database Debugging¶

Git Workflow¶

Branch Strategy¶

Commit Messages¶

Workflow¶

Environment Variables¶

Backend (.env)¶

Frontend (.env)¶

Extension (.env)¶

Documentation¶

Generate API Docs¶

Generate MkDocs¶

IDE Setup¶

VSCode¶

Extensions¶

Settings (.vscode/settings.json)¶

PyCharm¶

Troubleshooting¶

Common Issues¶

Port Already in Use¶

Database Connection Error¶

Virtual Environment Issues¶

Node Module Issues¶

Performance Tips¶

Backend¶

Frontend¶

Database¶

Next Steps¶

Create `.eslintrc.json`¶

Settings (`.vscode/settings.json`)¶