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

For production deployments, Docker Compose is the recommended method for running the Tracker System.

Using Docker Compose

For Production:

# Using environment variable
export COMPOSE_PROFILES=prod
docker compose up -d

# Or using --profile flag
docker compose --profile prod up -d

# Or inline
COMPOSE_PROFILES=prod docker compose up -d

# Check the status of the services
docker compose ps

# View logs
docker compose logs -f

This will start the following services:

Stopping the Services

docker compose down

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

# Using environment variable
export COMPOSE_PROFILES=dev
docker compose up

# Or using --profile flag
docker compose --profile dev up

# Or inline
COMPOSE_PROFILES=dev 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:
# Using environment variable
export COMPOSE_PROFILES=dev
docker compose up

# Or using --profile flag
docker compose --profile dev up

# Or inline
COMPOSE_PROFILES=dev 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:
# Using environment variable
export COMPOSE_PROFILES=dev
docker compose up

# Or using --profile flag
docker compose --profile dev up

# Or inline
COMPOSE_PROFILES=dev 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:

docker compose logs api

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:

docker compose logs admin

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