Skip to content

1. Getting Started

Jump to bottom
Gabriel Ernesto Mora edited this page Dec 7, 2025 · 1 revision

Setup Dependencies

Downloading Postgres

You must have a postgres server running locally in order to run TripView. Download version 18.0. Download links and instructions for postgres are below.:

On Windows: https://www.postgresql.org/download/windows/

  • Run the provided installer
  • Install all components
  • Use any directories you want
  • Use any superuser password you want
  • Use port 5432
  • Use default locale

We will create the database later.

On Mac:

  • Run brew install postgresql
    • If this does not work, just go to the postgres website and follow instructions above for Windows

Downloading and Configuring Android Studio

Install Python 3

On Windows:

These instructions were written with Python 3.13. Later versions should not pose issues.

  • Go to https://www.python.org/downloads/
  • Click into the latest release
  • Download the Windows installer (64-bit)
  • Install using downloaded installer. Use all defaults.

Environment Setup

Clone the Repository

Clone the repository using a method of your choice. From the CLI, you can run git clone git@github.com:MetisArom/the-clankers.git or git clone https://github.com/MetisArom/the-clankers.git. By default, the repository will clone into a new folder titled the-clankers.

Get API keys

To run an instance of TripView, you will need two API keys, both from Google.

The first key you'll need is a Google Maps API Key. To obtain one, follow these steps:

  • Go to https://console.cloud.google.com/google/maps-apis/ and finish account setup.
    • Google will ask for payment information. As long as you do not exceed the 10k request limit monthly for the Places API, you will not invoke any costs. If you are worried about costs and want to be 100% sure you are not charged, don't enable "Places API (New)" for your key when later instructed to do so. This ensures you are using only free APIs as of December 2025. The only feature this impacts within TripView app is stop information, which will not work without the Places API.
  • Create a project on Google Cloud. Instructions by Google on how to do this are here: https://developers.google.com/workspace/guides/create-project
  • Once you've created a project and have it selected, go into "APIs & Services" and hit "Enable APIs and services". Enable the Maps SDK for Android, and Places API (New).
  • Once those APIs are enabled, go into the "Credentials" sub menu of "APIs & Services" and create an API key. You should restrict this key to the Maps SDK for Android and Places API (New) APIs.
    • You can also restrict this key to the IP address of your server here if desired.

The second key you'll need is a Gemini API Key. Instructions for getting a Gemini key are here: https://ai.google.dev/gemini-api/docs/api-key. It does not matter whether you use the default project to obtain your key or not.

Write down both of these keys in some form of temporary scratchpad, like Notepad for Windows. You will need them in the following section.

Setup backend .env file

  • Open the the-clankers/backend directory.
  • Find the file .env.example and make a copy.
  • Rename your copy to .env
  • Enter .env copy and change DB_PASSWORD=password to DB_PASSWORD=[the password for postgres on your machine]
  • Change MAPS_API_KEY=Your_MAPS_API_KEY to MAPS_API_KEY=[Your Maps API Key]. This key must have Places API (New) and the Maps SDK for Android APIs enabled (unless you've opted not to enable Places API, as discussed in the previous section).
  • You must also change GEMINI_API_KEY=Your_GEMINI_API_KEY to GEMINI_API_KEY=[Your GEMINI API KEY] to use AI features.

Setup Python venv

You will want to create a Python virtual environment to install all your dependencies in. To do this, follow these steps:

  • Open a Terminal in the the-clankers/backend directory.
  • Run python -m venv env
    • If Python was not found, try python3 -m venv env.
  • Run ./env/Scripts/activate on Windows or source env/bin/activate on Mac/Linux to start working in the virtual environment
    • You must do this every time you want to do anything in the virtual environment like run the backend
  • Run pip install -r requirements.txt to install all needed libraries

Creating the Database

Once you're in the virtual environment and all libraries are installed, run python setup_db.py

This script also resets the database if you need.

Open Project in Android Studio

In Android Studio, navigate to the File > Open button and select the-clankers/TripView in the folder selection dialog.

Run the App

Running the Backend

In a terminal within the the-clankers/backend directory, run python app.py

  • Alternatively, you can use a pre-hosted demo backend by commenting line 7 and uncommenting line 11 in TripView/app/src/main/java/theclankers/tripview/core/Constants.kt:
image

This demo backend will be shut down once the project is open-sourced.

Testing

To test all is working, run curl http://localhost:5000/. On Windows, visit in a web browser. You should see the following:

{"message": "TripView API is running and connected to PostgreSQL!"}

Building and Running Frontend in Android Studio

Your copy of the frontend will likely take a minute to do a gradle sync when you first open it. Once that is done, you should see a green run button in the top bar. Click this and the frontend will build and run on an emulated device. You may need to create and select a device within the Device Manager.

Adding another Maps API Key

Earlier, when setting up the backend, you would have created a Maps API Key for the backend to use. This same type of key is also used on the frontend for displaying maps in the navigation feature. To set this up on the frontend, create a copy of the key you made earlier, disable all other APIs besides the Maps SDK for Android, and restrict this key to Android apps using your personal SHA1 Debug certificate fingerprint and package name "theclankers.tripview". Restricting this key is imperative as it will be exposed to users of the app.

Once you have the key set up, go into AndroidManifest.xml and replace "AIzaSyCtZrjkDgUY3trothFO7Q_DExylAoRrw_M" with your key in the "com.google.android.geo.API_KEY" metadata tag at the bottom of the file.

Dependencies List

Below is a list of all 3rd-party tools, libraries, SDKs, and/or APIs our project we may rely on directly:

  • Google Maps / Navigation SDK: for interactive maps and trip destination information
    • LLM API: Gemini (for handling prompts from user input (text, image, location data), image recognition, and generating responses)
  • Google OAuth Provider: For authentication and user identification via email
  • OSRM API: for getting driving directions between destinations
  • PostgreSQL

Clone this wiki locally