Gantabya

Gantabya is a travel companion app for group trips and city-to-city travel. Plan and share trails, see them on a map, and keep your group coordinated and safe on the road.

https://github.com/user-attachments/assets/fbbb3edc-397b-421f-961c-1315e499b2cd

Features

Available now

• Accounts with email/password sign-in (JWT)
• Trail definition: create, edit and share travel trails on a Mapbox map
• Shareable, server-rendered trail pages (/trails/[id])
• Photo uploads for trails and profiles (Cloudflare R2, with a local-disk fallback in development)
• Realtime updates over socket.io

Coming soon

• Trips and groups
• Live location sharing
• Threaded (Reddit-style) in-app chat
• Notifications
• Weather along trails
• Nearby facilities via OpenStreetMap
• SOS alerts
• Google sign-in
• PWA / offline support

Tech stack

Area	Tech
Frontend	Next.js 15 (App Router), React, TypeScript, Mapbox GL, Vitest
Backend	Node.js 20, Express, TypeScript, socket.io, Vitest
Data	PostgreSQL (Drizzle ORM), Redis (optional: socket.io adapter and shared rate limits)
Storage	Cloudflare R2 (S3-compatible), disk fallback in dev
Hosting	Netlify (frontend), Render (API + Postgres + Key Value)
CI	GitHub Actions, Dependabot

Repo layout

.
├── frontend/              Next.js 15 app (App Router, TypeScript)
│   └── src/app/           routes, incl. trails/[id]
├── server/                Express + socket.io API (TypeScript)
│   ├── src/modules/       feature modules (routes, controllers, models)
│   ├── src/sockets/       socket.io event handlers
│   └── Dockerfile         multi-stage production image
├── docs/
│   └── ARCHITECTURE.md    request flow, auth, storage, realtime
├── .github/               CI workflow and Dependabot config
├── docker-compose.yml     local Postgres + Redis + API
├── render.yaml            Render blueprint (API + Postgres + Key Value)
├── netlify.toml           Netlify build config for the frontend
└── .nvmrc                 Node version (20)

Quick start (Docker)

Requires Docker with Compose v2 and Node 20 (nvm use).

# 1. API + Postgres + Redis on http://localhost:5000
docker compose up --build

# 2. Frontend on http://localhost:3000 (in another terminal)
cd frontend
cp .env.example .env.local   # set NEXT_PUBLIC_MAPBOX_TOKEN
npm install
npm run dev

Compose works without a server/.env. Uploads are stored on disk unless you add R2 keys to server/.env (see Cloudflare R2). Check the API with curl http://localhost:5000/health.

Manual setup (without Docker)

You need Node 20, a PostgreSQL database and, optionally, Redis. Migrations run automatically when the server starts; npm run seed loads demo data.

# API
cd server
cp .env.example .env         # set DATABASE_URL and JWT_SECRET at minimum
npm install
npm run dev                  # http://localhost:5000

# Frontend
cd frontend
cp .env.example .env.local
npm install
npm run dev                  # http://localhost:3000

Environment variables

Server (server/.env)

Variable	Required	Default	Description
DATABASE_URL	yes		Postgres connection string
DATABASE_SSL	no	on in production	Set false for internal/local connections without TLS
JWT_SECRET	yes		Secret for signing JWTs. Use a long random value
NODE_ENV	no	development	development, test or production
PORT	no	5000	HTTP port
JWT_EXPIRES_IN	no	7d	Token lifetime
CLIENT_URL	no		Comma-separated list of allowed frontend origins (CORS and socket.io)
PUBLIC_API_URL	no		Public base URL of this API, used to build /media/* links
R2_ENDPOINT	no	https://cef3bc5e60493c2cde2fa645dac8c39f.r2.cloudflarestorage.com	R2 S3 endpoint
R2_BUCKET	no	gantabya	R2 bucket name
R2_ACCESS_KEY_ID	for R2		R2 API token access key. Without it, uploads go to local disk
R2_SECRET_ACCESS_KEY	for R2		R2 API token secret
RESEND_API_KEY	in production		Resend key for verification and password reset emails. Without it (dev only), emails are printed to the server log
EMAIL_FROM	no	Gantabya <[email protected]>	Sender address. Use an address on a domain verified in Resend; the default test sender only delivers to your own Resend account

Frontend (frontend/.env.local, Netlify env)

Variable	Required	Description
NEXT_PUBLIC_API_URL	yes	Base URL of the API, e.g. http://localhost:5000
NEXT_PUBLIC_MAPBOX_TOKEN	yes	Mapbox public token (pk.…), restricted to your domains

Scripts

Server (cd server)
npm run dev	Start with hot reload (tsx watch)
npm run build	Compile TypeScript to dist/
npm start	Run the compiled server (dist/server.js)
npm run lint / npm run typecheck	ESLint / tsc --noEmit
npm test	Vitest
npm run migrate:uploads	One-off: move legacy uploads to R2

Frontend (cd frontend)
npm run dev	Next.js dev server
npm run build / npm start	Production build / serve it
npm run lint / npm run typecheck	ESLint / tsc --noEmit
npm test	Vitest

Testing

cd server && npm test      # uses PGlite (in-process Postgres), no services needed
cd frontend && npm test

CI (.github/workflows/ci.yml) runs lint, typecheck, test and build for both apps on every push and pull request, then builds the server Docker image.

以上为 README 的开头部分。其余内容请阅读原文。 查看完整 README ↗