Self-hosting · MIT
Run the whole stack yourself.
TripMate is MIT licensed and self-hostable on Node.js 20+ with MongoDB. Clone the repository, set the environment variables, run pnpm install and pnpm dev, then open http://localhost:3001.
- Runtime
- Node 20+
- Database
- MongoDB
- Package manager
- pnpm
- License
- MIT
Requirements
Three things before you start.
You need Node.js 20 or newer, pnpm, and a MongoDB database. Everything else is optional: AI planning keys, email delivery, OAuth, and paid map styles can be added later.
Node.js 20+ and pnpm
The repository ships a pnpm lockfile. Run pnpm install from the root; the MCP server uses npm inside mcp/.
MongoDB
Use MongoDB Atlas or a local mongod. The app connects with MONGODB_URI and stores data in the tripmate database.
Optional service keys
Gemini enables planning, Brevo enables OTP email, and Mapbox enables Mapbox-backed routes. The app still boots without them.
Quick start
From clone to localhost.
These five commands are enough for a local instance. Fill in the environment file before the last step, or the app will start without a database connection.
git clone https://github.com/Krithik-m-codes/tripmate.git
cd tripmate
pnpm install
cp .env.example .env.local
# Edit .env.local, then:
pnpm devOn Windows PowerShell, use Copy-Item .env.example .env.local instead of cp. The dev server runs on port 3001.
Clone and install
Use the lockfile so your dependency tree matches the release you are running.
Create .env.local
Start from .env.example. At minimum, set MONGODB_URI and NEXTAUTH_SECRET.
Run pnpm dev
The app starts on http://localhost:3001. Create an account to test auth and the planner.
Build for production
Run pnpm build, then pnpm start. Set the public URL variables before the build.
Environment
The variables that matter.
Only MONGODB_URI is strictly required to boot. Set a real secret and public URL before exposing the app, and add the service keys for the features you want to use.
| Variable | Required | Purpose |
|---|---|---|
MONGODB_URI | Yes | MongoDB connection string. Server-only; never prefix it with NEXT_PUBLIC_. |
NEXTAUTH_SECRET | Production | Secret used to sign sessions. Generate one with openssl rand -base64 32. Auth also accepts BETTER_AUTH_SECRET. |
BETTER_AUTH_URL | Production | Public origin used by auth callbacks, such as https://your-domain.com. Falls back to NEXTAUTH_URL, then NEXT_PUBLIC_APP_URL. |
NEXT_PUBLIC_APP_URL | Recommended | Public origin used by client auth and email links. Set it to the same value as BETTER_AUTH_URL. |
GEMINI_API_KEY | For planning | Google AI Studio key for AI itinerary generation. NVIDIA_API_KEY and OPENROUTER_API_KEY are optional alternatives. |
BREVO_API_KEY | For email OTP | Brevo key for verification email delivery. Pair it with BREVO_SENDER_EMAIL. |
BREVO_SENDER_EMAIL | For email OTP | Verified sender address in Brevo. Without it, sign-up cannot send a code. |
NEXT_PUBLIC_MAPBOX_ACCESS_TOKEN | Optional | Mapbox token used for Mapbox-backed directions and map features. The default open map styles need no key. |
Additional optional variables in .env.example: GOOGLE_CLIENT_ID and GITHUB_CLIENT_ID (plus their secrets) for OAuth, DODO_PAYMENTS_API_KEY and DODO_PAYMENTS_API_URL for Pro checkout, and NEXT_PUBLIC_PIXABAY_API_KEY for destination imagery. Only NEXT_PUBLIC_* values are exposed to the browser.
Database and auth
Two services do the heavy lifting.
MongoDB stores users, itineraries, saved places, and usage counters. better-auth manages sessions and email OTP verification, using the secret and public URL you provide.
MongoDB
Create a database and copy its connection string into MONGODB_URI. The app connects to the tripmate database name by default. If you use Atlas, allow your host’s IP address in the network access list.
Mongoose creates collections on first use, so a fresh install has no general migration step. The repository does include a one-off itinerary migration script under src/scripts.
Auth and email
Set a long random NEXTAUTH_SECRET and point BETTER_AUTH_URL at your public origin. Verification codes are sent through Brevo; if Brevo is not configured, sign-up cannot deliver a code.
In local development the generated OTP is also printed to the server console, so you can finish sign-up without email.
Verify
Check the install before you trust it.
A healthy instance returns the marketing site, a sitemap, and a planner that can generate one itinerary. Walk through these checks in order.
- Open http://localhost:3001 and confirm the homepage renders.
- Open /sitemap.xml and /robots.txt to confirm metadata routes work.
- Create an account. With Brevo configured, the code arrives by email; otherwise read it from the server console.
- Generate one itinerary with a Gemini key to confirm the planner and database writes work.
- Run the MCP smoke test in mcp/ if you also plan to use the server.
To run the MCP server too:
cd mcp
npm install
npm run smokeThen add mcp/server.mjs to your client config. The full MCP server guide has copy-paste blocks for Claude Desktop, Cursor, and Claude Code.
Production
Before you expose it to the internet.
TripMate builds as a standard Next.js app, so any Node host works. Set production values for the public URL and secret, keep server keys out of the client bundle, and terminate TLS at your proxy or platform.
Build and start
Run pnpm build, then pnpm start. The start script listens on port 3001; map it to your platform's port or put a reverse proxy in front.
Set the real origin
Point BETTER_AUTH_URL and NEXT_PUBLIC_APP_URL at your https domain. Auth callbacks and email links use these values.
Protect the database
Keep MONGODB_URI server-side, use a dedicated database user, and restrict network access to your host.
Keep keys off the client
Only NEXT_PUBLIC_* variables reach the browser. Server keys such as GEMINI_API_KEY, BREVO_API_KEY, and MONGODB_URI stay in the server environment.
There is no official Docker image yet. If you containerise the app yourself, run the production build in the image and provide MongoDB and the environment variables at runtime.
Troubleshooting
Common first-run failures.
Most local setup problems trace back to a missing environment variable or a database that is not reachable from your machine.
| Symptom | Fix |
|---|---|
| Missing MONGODB_URI in the logs | Add MONGODB_URI to .env.local and restart the dev server. Confirm the Atlas IP allowlist includes your machine. |
| Sign-up never sends a code | Set BREVO_API_KEY and BREVO_SENDER_EMAIL, or read the generated OTP from the server console in development. |
| Sessions drop after sign-in | Set a stable NEXTAUTH_SECRET and make sure BETTER_AUTH_URL matches the origin in your browser. |
| The planner returns an auth or key error | Add GEMINI_API_KEY (or an alternative provider key) to the server environment and restart. |
| Maps render blank | Check browser access to tiles.openfreemap.org and basemaps.cartocdn.com. The default map styles need no key; a Mapbox token only enables Mapbox-backed features. |
FAQ
Self-hosting questions.
What people ask before running their own instance.
Can I self-host TripMate for free?
+
Yes. The code is MIT licensed and runs on Node.js 20+ with MongoDB. Your only costs are the services you choose, such as MongoDB hosting, Gemini, or Brevo.
What do I need to run TripMate locally?
+
Node.js 20 or newer, pnpm, and a MongoDB connection string. A Gemini API key enables AI planning, and Brevo enables verification email; the app can boot without either.
Is there a Docker image?
+
No official image is published yet. You can run the Node build directly or build your own container from the repository. The app needs Node.js at runtime and a reachable MongoDB instance.
Does self-hosting include the MCP server?
+
Yes. The MCP server lives in the mcp directory of the same repository. It runs separately over stdio and reads GEMINI_API_KEY plus its optional overrides from the environment your MCP client provides.
How do I update a self-hosted instance?
+
Pull the latest changes, run pnpm install, then pnpm build and restart the app. Review the release notes first in case an environment variable or dependency changed.
Own the stack
Clone it, run it, change it.
MIT means you can inspect every line, swap the AI provider, and host it wherever you like. Start with the repository and the MCP guide.