Skip to content

Installation Guide

This guide covers the supported workflows for this repository:

  • Docker Compose for day-to-day development
  • Terraform for deploying the AWS staging stack

The project is designed so that you normally work inside containers. The dev services mount the source tree and reload on code changes, so you do not need a local Python install for routine application work.

Prerequisites

For local development:

  • Docker
  • Docker Compose

For AWS deployment:

  • Terraform
  • AWS CLI
  • Access to the target AWS account and profile

Local Development With Docker Compose

  1. Clone the repository.
git clone https://github.com/Glimpse-Analytics/tracker-restapi.git
cd tracker-restapi
  1. Set the required environment variables for the development stack.

The Docker Compose services expect the usual application and database credentials to be available in your shell or local environment file workflow.

  1. Start the development stack.
docker compose up -d

This starts the API, admin panel, frontend, database, cache, and worker services defined in compose.yml.

  1. Work against the live-reloading containers.

The development services are bind-mounted into the source tree, so code changes are picked up automatically. In practice, you edit code, save, and refresh the browser.

  1. Run database migrations when needed.
docker compose exec dev alembic upgrade head

  1. Open the development URLs.

  2. API: http://localhost:8100

  3. Admin Panel: http://localhost:3000
  4. Frontend: http://localhost:3100

Deploying To AWS

The AWS stack is managed by Terraform and should be applied staging-first. The current infrastructure docs live in:

1. Configure AWS access

Make sure your AWS CLI profile is pointed at the target account. For staging, that is the project-owned staging environment.

2. Prepare the Terraform backend

The staging backend lives under infra/envs/staging. Copy the backend template before initialization if it is not already present:

cp infra/envs/staging/backend.hcl.example infra/envs/staging/backend.hcl

3. Initialize Terraform

terraform -chdir=infra/envs/staging init -backend-config=backend.hcl

4. Review the plan

terraform -chdir=infra/envs/staging plan

5. Apply the stack

terraform -chdir=infra/envs/staging apply

6. Verify the deployment

Use Terraform outputs and the AWS console or CLI to confirm the ALB, ECS services, database host, and supporting resources are healthy.

Notes

  • The repo still contains some legacy docs for historical migration work, but the supported installation path is Docker-first.
  • Avoid treating local uv/venv installation as the default app workflow unless you are working on a small standalone script or tooling task.