Docs/Self-Hosting Guide

Self-Hosting Guide

Run StudyMap for your own city. Everything below works from a fork, no coding required beyond editing one config file and your place data.

Get the code

Fork, clone, install

Click "Use this template" at the top of StudentSuite/StudyMap to create your own copy, then clone it.

git clone https://github.com/<your-account>/<your-fork>.git
cd <your-fork>
npm install

Set your region and dataset

One config file for everything region-specific

Everything region- and data-specific lives in studymap.config.ts at the repo root.

cp studymap.config.example.ts studymap.config.ts

Edit it:

center: [lat, lng] for the initial map view
defaultZoom: initial zoom level (11-13 works well for a metro area)
bounds: rough coordinate box around your region, used for data validation and map fitting
cities: display order for the city filter (anything in your data but missing here still shows, just sorted alphabetically after)
places: swap the sample imports for your own data/places/*.json files

The dataset itself follows the schema on Place Data Format. data/places.sample/ has two minimal example entries if you want to start from a clean skeleton instead of the dataset that ships with the template.

Validate as you go:

npm run validate

Environment variables

One required, the rest optional

cp .env.example .env.local

NEXT_PUBLIC_MAPTILER_KEY is required for the map basemap. Free tier, no credit card, at cloud.maptiler.com.
The Supabase variables are optional. Leave them blank and the map, filters, and calendar all work; you just won't get sign-in or the two private features in step 5.

Run it

Confirm your places show up

npm run dev

Open localhost:3000/map and confirm your places show up in the right spot.

Optional: sign-in, saved places, personal events

Needs a free Supabase project

These three features (sign-in, saved custom places, personal calendar events) need a Supabase project. Skip this whole step if you only want the public map and calendar.

Create a free project at supabase.com.
Copy its URL and anon key into .env.local (NEXT_PUBLIC_SUPABASE_URL, NEXT_PUBLIC_SUPABASE_ANON_KEY).
In the Supabase SQL editor, run every file in supabase/migrations/, in filename order. Each one creates its tables with row-level security already scoped to auth.uid(), so users can only ever read or write their own rows.
Enable whichever auth providers you want (email, Google, etc.) under Authentication > Providers.

Deploy

Any standard Next.js host - static export not supported

Deploy like any standard Next.js app, for example on Vercel:

npx vercel

or import the repo at vercel.com/new and set the same environment variables from step 3 in the project settings.

Static export (output: "export") is not supported. Sign-in needs a live server: the OAuth callback route exchanges a code for a session server-side, and middleware refreshes that session on every request. Both are incompatible with a static build. Deploy to a normal server/edge runtime instead - that's the default for Vercel and most other Next.js hosts.

Keeping your fork current

StudyMap doesn't push updates to forks automatically

To pull in upstream fixes, add the original repo as a remote and merge from it:

git remote add upstream https://github.com/StudentSuite/StudyMap.git
git fetch upstream
git merge upstream/main

Your studymap.config.ts, .env.local, and data/places/*.json are yours - upstream changes to shared code (map, calendar, components) merge in without touching them, unless you've also edited those files.