Getting started

Last updated: June 2026

Follow this detailed guide to set up and run Crestr on your local machine.

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+)

Users¶

1. Clone the Repository¶

Open your terminal and run:

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

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

2. After cloning set up the .env file¶

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
└── ...

Follow the steps below to set up a .env file¶

Make a file named '.env' and copy the contents from the 'example.env' file¶

The contents of the example.env file is shown below

# 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 by self hosters to use alternative regions as desired
# Graphs can be generated by sourcing .osm.pbf files from Geofabric and sourcing elevation files from the elevation library
# See either the docs on how to use this or view the graph generation files directly in ./graph_generation
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 excepting the searching for an area feature, as this is achieved via the LOCATIONIQ_API_KEY of which you will need to retrieve your own from their website

3. Build and Start the App¶

Run the following command to build the Docker image and start all services

docker-compose up --build

Useful commands¶

docker-compose up --build -d # this builds and starts services in the background (detached mode)
docker-compose --build --force-recreate # this force builds everything and restarts services
docker-compose logs -f # this allows you to follow logs in real time

4. Access the App¶

Wait until the containers are running
Once they are, the app should be accessible via localhost:5000, opening on the map. You may want to make an account to save routes and points by visiting localhost:5000/register

5. Common Issues + Troubleshooting¶

Issue	Solution
Port 5000 already in use	Change the port in docker-compose.yml
Docker permission error	Run with sudo (linux) or ensure Docker Desktop is operational
Build fails	run docker system prune -f and try again