Skip to content

Installation Guide

This guide will walk you through the process of installing and setting up the Tracker System, which includes both the API and Admin Panel.

Prerequisites

Before you begin, ensure you have the following installed:

  • Python 3.8 or higher
  • PostgreSQL with PostGIS and TimescaleDB extensions
  • Node.js 20 or higher (for admin panel development)
  • Docker and Docker Compose (recommended for both development and production)

Installation Methods

There are two main ways to install and run the Tracker System:

  1. Using Docker Compose (recommended for both production and development)
  2. Local installation (alternative for development)

Using Docker Compose

Docker Compose provides a simple way to set up the entire application stack, including the API, Admin Panel, PostgreSQL database, and other services.

Step 1: Clone the Repository

git clone https://github.com/yourusername/tracker-api.git
cd tracker-api

Step 2: Configure Environment Variables

Create a .env file in the root directory with your configuration:

cp .env.example .env

Edit the .env file to set your desired configuration values.

Step 3: Start the Services

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

This will start the following services:

For Development:

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

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

# Or inline
COMPOSE_PROFILES=dev docker compose up -d

This will start:

Step 4: Run Database Migrations

For Production:

docker compose exec api alembic upgrade head

For Development:

docker compose exec dev alembic upgrade head

Local Installation

For local development, you can install the API and Admin Panel directly on your system.

Step 1: Clone the Repository

git clone https://github.com/yourusername/tracker-api.git
cd tracker-api

Step 2: Set Up a Virtual Environment

Using uv (recommended):

uv venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

Using venv:

python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

Step 3: Install Dependencies

Using uv:

uv pip install -e .

Using pip:

pip install -e .

For development, you can install additional dependencies:

uv pip install -e ".[dev]"

Step 4: Configure Environment Variables

Create a .env file in the root directory with your configuration:

cp .env.example .env

Edit the .env file to set your desired configuration values.

Step 5: Set Up the Database

Ensure PostgreSQL is running with PostGIS and TimescaleDB extensions installed.

Create a database for the application:

createdb tracker

Run the database migrations:

alembic upgrade head

Step 6: Run the API

uvicorn app.main:app --reload

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

Step 7: Install and Run the Admin Panel

# Navigate to the admin panel directory
cd tracker-admin

# Install dependencies
npm install

# Start the development server
npm run dev

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

Verifying the Installation

To verify that the installation was successful, open your browser and navigate to:

For the Admin Panel, you should be able to log in with the default admin credentials:

  • Email: admin@example.com
  • Password: admin123

If you're using the development setup, make sure the API is running and accessible from the Admin Panel.