Setup & Run Instructions - soujanya957/arctic-map GitHub Wiki

Setup & Run Instructions

Follow these steps to set up and run the Arctic Map project locally.

Prerequisites

Install the following tools:

Python (>=3.8) and pip

macOS:

brew install python

Windows: Download from https://www.python.org/downloads Check "Add Python to PATH" during installation.

Verify installation:

python --version
pip --version

Node.js and npm

macOS:

brew install node

Windows: Download from https://nodejs.org/

Verify:

node --version
npm --version

Tmux

Used to run all services automatically in split panes, neatly organizing different workflows into separate sections (like tabs, but within one window) and lets you easily switch between different tasks without stopping anything.

macOS:

brew install tmux

Linux:

sudo apt install tmux

Windows: Use Windows Subsystem for Linux (WSL) and follow Linux steps.

Verify:

tmux -V

First-Time Project Setup

1. Clone the repository

git clone https://github.com/soujanya957/arctic-map.git
cd arctic-map

2. Backend setup

cd backend
python3 -m venv venv
source venv/bin/activate   # On Windows: venv\Scripts\activate
pip install -r requirements.txt
mkdir -p zipped_shapefiles bundled_zips

Ensure cpad.sqlite is present inside the backend/ directory.

2a. Set up your custom Google Sheet for layer organization

This app uses a Google Sheet to dynamically organize and fetch information about the available geospatial datasets for the sidebar (themes, subthemes, and dataset order). To enable this feature, you need to prepare your own Google Sheet to organize the information about your project's datasets by following the instructions here.

Make sure your copy of this Google Sheet is publicly accessible (set to Anyone with the link can view.).

Look at the URL of your Google Sheet in your browser's address bar. It will follow this pattern: https://docs.google.com/spreadsheets/d/YOUR_SHEET_ID_HERE/edit#gid=YOUR_GID_HERE

  • YOUR_SHEET_ID_HERE is the SHEET_ID. Copy this long string of characters.

  • YOUR_GID_HERE is the GID (Grid ID) for the specific tab/worksheet you want to use. Copy this number.

Create a .env file in the backend/ directory with these two IDs:

GOOGLE_SHEET_ID=your_actual_sheet_id_goes_here
GOOGLE_SHEET_GID=your_actual_gid_goes_here

3. Frontend setup

cd ../frontend
npm install

Create a .env file in the frontend/ directory with your Mapbox token:

VITE_MAPBOX_ACCESS_TOKEN=pk.your_mapbox_token_here

Get a token at: https://account.mapbox.com/access-tokens

Run the App

From the root arctic-map/ directory:

chmod +x ./run_0.sh
tmux
./run_0.sh

This will:

  • Start both FastAPI backends (ports 8000 and 8001)
  • Start the React frontend (port 5173)
  • Launch each in a tmux pane

Useful tmux Tips

  • If you want to pause work and resume shortly after, detach from tmux: Ctrl + b, then d This means all your servers and processes will continue running even if you close your terminal window or lose your SSH connection.

  • To connect back to the tmux session, reattach:

    tmux attach

  • If you want to stop all processes and close the tmux session, first detach from the session: Ctrl + b, then d. Next:

    tmux kill-server

🗂️ (Optional) Generate Zipped Shapefiles

If you have a directory Arctic_CPAD/ (containing shapefiles) in the same parent folder as arctic-map/, you can run:

cd backend
python zip_shapefiles.py

Output will appear in backend/zipped_shapefiles/.