Developers

Last updated: July 2026

Follow this guide to set up and run Crestr locally for development.

Prerequisites¶

Before starting, ensure you have the following installed:

• Git - To clone the repository Download Git
• Docker & Docker Compose - The app runs locally via Docker containers
• Docker Desktop: Install Docker
• Docker Compose is included with Docker Desktop (v2+)
• Python 3.11+ - If running the FastAPI app outside of Docker

1. Clone the Repository¶

# Clone the project
git clone https://github.com/abdlfc11/Crestr-Hiking-App.git

# Navigate into the project folder
cd Crestr-Hiking-App

You should see a project structure similar to this:

Crestr-Hiking-App/
├── docker-compose.yml
├── Dockerfile
├── src/
│   ├── app.py
│   ├── pathfinder.py
│   └── config.py
|   └── ...
├── data/
├── README.md
└── requirements.txt
└── .env.example
└── ...

2. Set Up Your .env File¶

Copy the example configuration:

cp example.env .env

Then edit the values you wish to change.

At minimum you'll need to replace:

• LOCATIONIQ_API_KEY
• POSTGRES_PASSWORD
• PGADMIN_PASS
• UMAMI_APP_SECRET

Important: docker-compose.yml reads from .env, not example.env¶

Docker Compose expects a .env file in the project root for variable interpolation. Therefore, after cloning the repository, copy example.env to .env before starting the stack via the command below

cp example.env .env

Without this file, services such as pgAdmin and Umami will fail to start correctly

3. Build and Start the App¶

Option A — Full stack via Docker (recommended for working on the full app, DB, analytics, pgAdmin)¶

docker-compose up --build

Useful variants:

docker-compose up --build -d          # build and start in the background (detached)
docker-compose up --build --force-recreate  # force rebuild and restart all services
docker-compose logs -f                # follow logs in real time

For faster local iteration, you'll also want to swap the command: on the web-fastapi service from the gunicorn prod command to the Uvicorn command for easier debugging:

### command: gunicorn -c src/gunicorn.config.py fastapi_app:app # Prod
command: uvicorn fastapi_app:app --reload --host 0.0.0.0 --port 5001 # DEVELOPERS: use this command

Option B: Run FastAPI natively (no Docker), useful for fast backend-only iteration¶

You'll still need Postgres running (e.g. via docker-compose up db), then:

# Create a virtual environment
python -m venv venv

# Activate it
# Windows:
venv\Scripts\activate
# macOS/Linux:
source venv/bin/activate

# Install dependencies
pip install -r requirements.txt

# Run the FastAPI app
uvicorn src.fastapi_app:app --reload --host 0.0.0.0 --port 5001

Make sure LOCAL_DATABASE_URI in your .env points at localhost (not the db service hostname), since you're running outside the Docker network.

4. Access the App¶

Once containers/services are up, the app is accessible at localhost:5000, opening on the map.

Create an account to save routes and points at localhost:5000/register-page.

Other local services:

• Umami analytics: localhost:3000
• pgAdmin: localhost:5050 (or whatever PGADMIN_PORT you set)

5. Common Issues + Troubleshooting¶