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.

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

2b. Add your datasets' information (metadata)

To make sure others can understand your datasets when they use this app, you'll need to provide metadata for them. This app requires your datasets' information to be in a web page file, AKA an HTML file.

Crucial Formatting for Your Metadata HTML Each dataset's information in your metadata HTML file must begin with a clear title line, formatted exactly like this:

Title: Your Dataset Name

The Your Dataset Name part should be the exact name that matches the corresponding shapefile layer in the project's database.

If you have your datasets' metadata written in a word processor (e.g., Google Docs, Microsoft Word), you'll need to save or convert that document into this web page (HTML) format.

  • Google Docs: File > Download > Web Page (.html, zipped)

  • Microsoft Word: "Save As" option > select "Web Page" or "HTML Document" as the file type

  • Rename this downloaded HTML file to metadata.html.

  • Open your computer's file browser (Finder on macOS or File Explorer on Windows) and drag and drop the metadata.html file into the backend/ folder.


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/.

⚠️ **GitHub.com Fallback** ⚠️