Skip to content

Running the Tracker System

This guide explains how to run the Tracker System, including both the API and Admin Panel, in various environments.

Running in Production

Production is deployed through Terraform into AWS ECS, not via Docker Compose.

Running in Development

For development, you can use the development services provided by Docker Compose, or run the services locally.

Using Docker Compose for Development

docker compose up

# Check the status of the services
docker compose ps

# View logs
docker compose logs -f

This will start the following services:

The development services include:

  • Live code reloading for both the API and Admin Panel
  • Debugging support for the API
  • Development tools and utilities

Running Locally

You can also run the API and Admin Panel locally for development.

Running the API Locally

# Activate the virtual environment
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Run the API with live reloading
uvicorn app.main:app --reload --port 8000

The API will be available at http://localhost:8000.

Running the Admin Panel Locally

# Navigate to the admin panel directory
cd tracker-admin

# Install dependencies (if not already installed)
npm install

# Run the development server
npm run dev

The Admin Panel will be available at http://localhost:3000.

Debugging

Debugging the API

The API includes support for remote debugging with VSCode. To debug the API:

  1. Start the development service:
docker compose up
  1. Attach the VSCode debugger:
  2. Open the project in VSCode
  3. Go to the "Run and Debug" view (Ctrl+Shift+D or Cmd+Shift+D on macOS)
  4. Select "Python: Remote Attach" from the dropdown menu
  5. Click the green play button or press F5

VSCode will attach to the running container, and the application will start. You can now set breakpoints in your code and debug as usual.

Debugging the Admin Panel

The Admin Panel includes support for debugging with browser developer tools:

  1. Start the development service:
docker compose up
  1. Open the Admin Panel in your browser:
  2. Navigate to http://localhost:3000
  3. Open the browser developer tools (F12 or Ctrl+Shift+I or Cmd+Option+I on macOS)
  4. Go to the "Sources" tab
  5. Set breakpoints in your code

You can also use the React Developer Tools extension for Chrome or Firefox to inspect and debug React components.

Monitoring

Monitoring the API

The API includes a performance monitoring middleware that logs request times and other metrics. You can view these logs using:

docker compose logs -f api

Monitoring the Admin Panel

The Admin Panel includes React Query DevTools for monitoring API requests and cache state. To enable the DevTools:

  1. Open the Admin Panel in your browser
  2. Press Ctrl+Shift+Q or Cmd+Shift+Q on macOS to toggle the DevTools

Common Issues

API Not Starting

If the API fails to start, check the logs for errors. Use dev for the local development stack:

docker compose logs dev

Common issues include:

  • Database connection errors
  • Missing environment variables
  • Port conflicts

Admin Panel Not Starting

If the Admin Panel fails to start, check the logs for errors. Use admin-dev for the local development stack:

docker compose logs admin-dev

Common issues include:

  • Node.js version incompatibility
  • Missing dependencies
  • Port conflicts

CORS Errors

If you encounter CORS errors when the Admin Panel tries to connect to the API, check that:

  1. The API is configured to allow requests from the Admin Panel's origin
  2. The Admin Panel is using the correct API URL

See the CORS Error Handling guide for more information.

Performance Tuning

API Performance

To improve API performance:

  1. Enable Redis caching by setting the REDIS_CACHE_TTL environment variable
  2. Increase the number of workers by setting the WORKERS_PER_CORE environment variable
  3. Use connection pooling for database connections

Admin Panel Performance

To improve Admin Panel performance:

  1. Enable production mode by setting the NODE_ENV environment variable to production
  2. Use code splitting to reduce bundle size
  3. Implement caching strategies for API responses

VSCodium Test Setup

If you want VSCodium to run unit tests against a local Python environment, use the project's local virtual environment and the existing Docker Compose services for the database and cache. The editor should use venv/bin/python, which points at the same environment as .venv.

1. Create the local Python environment

uv venv
source .venv/bin/activate
uv pip install -e ".[dev]"
ln -s .venv venv

2. Start the supporting services

docker compose up -d db dragonfly

3. Configure VSCodium

  • Select venv/bin/python as the interpreter
  • Enable pytest discovery
  • Point coverage tools at the generated coverage.xml
  • If VS Code keeps using another project's interpreter, see VS Code Python Interpreter Reset

4. Run tests

pytest tests/ --cov=app --cov-report=xml -v

5. Optional coverage HTML

pytest tests/ --cov=app --cov-report=html -v
open htmlcov/index.html

Testing Approach

The project favors behavioral tests:

  • Organize tests around user workflows and business scenarios
  • Keep small unit tests for simple utilities and configuration
  • Use integration tests for cross-feature workflows
  • Track coverage, but do not test only by file structure

When writing tests, mock external dependencies but prefer real application code, database interactions, and service logic. Over-mocking our own code makes tests pass without validating real behavior.