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.x - If running the Flask 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¶

Create a file named .env in the project root and copy the contents of example.env into it, then adjust values as needed.

# Flask Configuration, a long random string of integers and characters
FLASK_SECRET_KEY=8f3c9b7a2e5d1f4a6b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a

# LocationIQ API Key (Get your own free key at https://locationiq.com)
LOCATIONIQ_API_KEY=pk.abcdefghijklmnopqrstuvwxyz1234567890

# PostgreSQL Configurations / user details
POSTGRES_USER=crestr_dev
POSTGRES_PASSWORD=secure_hiking_pass_2025
POSTGRES_DB=crestr_hiking

# pgAdmin
PGADMIN_EMAIL=random_email
PGADMIN_PASS=random_password
PGADMIN_SERVER_MODE=False
PGADMIN_MASTER_REQ=False
PGADMIN_PORT=5050

# Graph used for pathfinding
# Can be used to point at alternative regions as desired
# Graphs can be generated by sourcing .osm.pbf files from Geofabrik and elevation
# files from the elevation library — see ./graph_generation and its docs
GRAPH_PATH=graph_generation/elevation_populated_graph.pkl

# Database Connection URIs
DATABASE_URI=postgresql://crestr_dev:secure_hiking_pass_2025@db:5432/crestr_hiking
LOCAL_DATABASE_URI=postgresql://crestr_dev:secure_hiking_pass_2025@localhost:5432/crestr_hiking

# Umami (analytics)

# Specific Website ID provided by Umami
UMAMI_WEBSITE_ID=get_ID_from_umami

# Umami script.js url, defaults to localhost:3000
UMAMI_SCRIPT_URL=http://localhost:3000/script.js

# Umami Database
UMAMI_DB_PASSWORD=change_this_to_a_strong_password

# Umami Application Secret (generate a strong one)
UMAMI_APP_SECRET=your_very_long_random_secret_here

The app will work fine with these values unchanged, aside from the area search feature, which requires your own LOCATIONIQ_API_KEY from LocationIQ.

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

Only the db and web services load example.env directly, via their env_file blocks. The umami-db, umami, and pgadmin services instead reference variables with ${VAR} syntax directly in docker-compose.yml (e.g. ${UMAMI_DB_PASSWORD}, ${PGADMIN_EMAIL}). Docker Compose only resolves this interpolation syntax from a .env file in the project root (or your shell environment), this means it will not pick these up from example.env.

This means that even though example.env is checked into the repo, you must create your own .env file at the project root (as described above) or the umami, umami-db, and pgadmin services will fail to start / start with blank credentials.

If you only need the core app and database (web + db) and don't care about analytics or pgAdmin, example.env alone is sufficient since those two services load it directly via env_file. For everything else, .env is required.

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, uncomment the debugging environment variables under the web service in docker-compose.yml:

# - FLASK_DEBUG=1
# - LOAD_GRAPH_ON_IMPORT=0    # 0 skips graph loading on import for fast hot-reloads
# - FLASK_ENV=development     # deprecated, likely to switch to checking FLASK_DEBUG instead

You'll also want to swap the command: on the web service from the gunicorn prod command to the Flask dev server for easier debugging:

### command: gunicorn -c src/gunicorn.config.py src.app:app ### prod
command: flask run --host=0.0.0.0 --port=5000 --debug ### dev — better logs/errors

Option B — Flask app run 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 Flask app
cd src
python app.py

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.

Other local services: - Umami analytics: localhost:3000 - pgAdmin: localhost:5050 (or whatever PGADMIN_PORT you set)

5. Common Issues + Troubleshooting¶