Development Guide#

Guides for developers working on the ops-db-api codebase.

Overview#

This section covers:

  • Testing: Running and writing tests

  • Debugging: Troubleshooting buffering and replication

  • Redis Inspection: Examining cache and buffer state

  • Contributing: Code style and PR process

Development Environment#

See Installation for setting up your development environment.

Quick Start#

# Clone repository
git clone https://github.com/ccatobs/ops-db-api.git
cd ops-db-api

# Create virtual environment
python3 -m venv venv
source venv/bin/activate

# Install in development mode
pip install -e .

# Run tests
pytest

# Start development server
uvicorn ccat_ops_db_api.main:app --reload

Development Tokens#

The system automatically creates development API tokens when initializing the database in development mode. These tokens are reusable across database resets and are only valid in development environments.

Automatic Creation#

Development tokens are automatically seeded when:

  1. Running opsdb_init with data_archive_mode="development"

  2. Starting the API with ENVIRONMENT=development (fallback if not seeded during init)

Token Format#

Development tokens are prefixed with ops_api_token_dev_ to clearly identify them:

ops_api_token_dev_<hash>

Default Tokens#

Two tokens are created by default:

  • service_dev-pipeline: For data pipeline automation - Scopes: read:observations, write:observations, read:data, write:data

  • service_dev-cli: For CLI tools and scripts - Scopes: read:*, write:*

Using Development Tokens#

After database initialization, tokens are printed to the console. Save them in your development environment:

export DEV_PIPELINE_TOKEN="ops_api_token_dev_..."
export DEV_CLI_TOKEN="ops_api_token_dev_..."

Use in Python scripts:

import os
import requests

token = os.getenv("DEV_PIPELINE_TOKEN")
headers = {"Authorization": f"Bearer {token}"}

response = requests.get(
    "http://localhost:8000/api/observations",
    headers=headers
)

Use in cURL:

curl -H "Authorization: Bearer $DEV_PIPELINE_TOKEN" \
     http://localhost:8000/api/observations

Customization#

Set the DEV_TOKEN_SECRET environment variable to customize token generation:

export DEV_TOKEN_SECRET="your-custom-secret"

This ensures tokens are deterministic but unique to your development setup.

Troubleshooting#

Tokens not created? - Verify data_archive_mode="development" when running opsdb_init - Check that ENVIRONMENT=development is set for API startup fallback - Check logs for seeding errors

Token rejected? - Verify environment is set to development/dev/local - Check that token starts with ops_api_token_dev_ - Review logs for security warnings

Token not found after database reset? - Tokens are recreated automatically on next initialization - Same DEV_TOKEN_SECRET = same tokens (deterministic) - Check console output during initialization for token values

Next Steps#