Getting Started

This guide will get Momo running on your machine in under 10 minutes using Docker Compose.

Prerequisites

This is the fastest way to run Momo. Docker Compose starts the app and a PostgreSQL database together.

Step 1 — Clone the repository

git clone https://github.com/jp1337/momo.git
cd momo

Step 2 — Configure environment variables

cp .env.example .env.local

Open .env.local in your editor and fill in the required values:

# Required
DATABASE_URL=postgresql://momo:password@db:5432/momo
AUTH_SECRET=your-secret-here  # openssl rand -base64 32

# At least one OAuth provider
GITHUB_CLIENT_ID=your-client-id
GITHUB_CLIENT_SECRET=your-client-secret

# Public URL
NEXT_PUBLIC_APP_URL=http://localhost:3000
NEXTAUTH_URL=http://localhost:3000

Production / reverse proxy: If you deploy behind nginx, Caddy, or any Kubernetes ingress, also set AUTH_TRUST_HOST=true. Auth.js v5 requires this to accept proxied requests.

See the Environment Variables reference for all available options.

Step 3 — Generate a secret

openssl rand -base64 32

Paste the output as the value for AUTH_SECRET in .env.local.

Step 4 — Start all services

docker compose up -d

This starts:

Step 5 — Open Momo

Visit http://localhost:3000 in your browser and sign in with your OAuth provider.

Migrations run automatically. The container applies all pending database migrations before the server starts — no manual step needed.

Option 2: Local Development

Use this if you want to edit the code and see changes live.

Prerequisites

Step 1 — Clone and install dependencies

git clone https://github.com/jp1337/momo.git
cd momo
npm install

Step 2 — Configure environment variables

cp .env.example .env.local
# Edit .env.local with your values

For local development, use:

DATABASE_URL=postgresql://momo:password@localhost:5432/momo
NEXT_PUBLIC_APP_URL=http://localhost:3000
NEXTAUTH_URL=http://localhost:3000

Step 3 — Start the database

docker compose up db -d

Step 4 — Run migrations

npx drizzle-kit migrate

Step 5 — Start the development server

npm run dev

The app is available at http://localhost:3000 with hot reload enabled.

First Login

  1. Open http://localhost:3000
  2. Click Sign in and choose your OAuth provider
  3. You’ll be redirected to your dashboard

On first login, a user account is created automatically in the database.

Creating Your First Task

  1. From the dashboard, click New Task
  2. Enter a title and optionally assign it to a Topic
  3. Save — your task appears in the list
  4. Click the task to mark it complete and earn your first coins

Enabling Push Notifications (Optional)

  1. Go to Settings in the navigation
  2. Click Enable Notifications
  3. Allow the browser notification permission prompt
  4. Choose your preferred notification time

You’ll need to configure VAPID keys first — see the Environment Variables page.

Stopping Momo

docker compose down

To also remove the database volume (all data):

docker compose down -v

Next Steps