GitHub ↗

Getting Started

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

Prerequisites

  • Docker Engine 24+ and Docker Compose v2 — Install Docker
  • At least one OAuth app — you need GitHub, Discord, Google, Microsoft (private accounts only), or an OIDC provider configured so you can log in. See the OAuth Setup guide.
  • A terminal on Linux, macOS, or WSL on Windows.

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. Make sure NEXT_PUBLIC_APP_URL and NEXTAUTH_URL point at your real public HTTPS origin — both drive OAuth callbacks, notification links, and SEO output (robots.txt, sitemap.xml, Open Graph tags).

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:

  • app — the Momo Next.js application on port 3000
  • db — PostgreSQL 18 on port 5432

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

  • Node.js 20+ — Install Node.js
  • npm (included with Node.js)
  • Docker (for the PostgreSQL database)

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. A short onboarding wizard walks you through the basics: Momo’s core concepts, creating your first topic and tasks, and enabling notifications. Every step can be skipped.
  4. After onboarding, you land on the dashboard

On first login, a user account is created automatically in the database. The onboarding wizard appears only once — skip it or finish it, and it never returns.

Creating Your First Task

If you completed the onboarding wizard, you already have a topic and a few tasks. Otherwise:

  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

Tip — skip the blank page: if you are facing a bigger project (a move, a tax return, a new workout habit), open the Topics page and press 📋 From template. Momo ships with four curated starter topics — Moving, Tax Return, Workout Routine and Household (recurring chores) — that import a fully populated task list in one click, no typing required. See the Features guide for details.

Once you’ve signed in, you can lock your Momo account down with a second factor — or skip the OAuth round-trip entirely with a passkey.

  • Passkeys (WebAuthn) — register your Face ID, Touch ID, Windows Hello, Android biometrics or a hardware key (YubiKey, SoloKey) under Settings → Two-factor authentication → Passkeys. After that, the Sign in with a passkey button on /login lets you skip the OAuth provider entirely. The same passkey works as your second factor too. Read the guide →
  • TOTP — enable an authenticator-app code (Aegis, 2FAS, Google Authenticator, Authy, 1Password, …) under the same settings section. Save the 10 backup codes you’re given — they’re your safety net if you lose your phone. Read the guide →

You can use either, both, or neither. Self-hosters can require a second factor for everyone with REQUIRE_2FA=true (see Self-Hosting).

Enabling Notifications (Optional)

Momo supports five notification channels and you can use as many as you like in parallel:

  1. Browser Push — go to Settings → Notifications, click Enable Notifications, allow the browser permission prompt, and pick your reminder time. Requires VAPID keys on the server (see Environment Variables).
  2. ntfy.sh, Pushover, Telegram, Email — open Settings → Additional Notification Channels and click the channel you want. Each has a one-page configuration form and a Send test button. The Email channel only appears if your instance has SMTP configured (SMTP env vars).

If a notification doesn’t arrive, check Settings → Notification History — it shows the last 50 delivery attempts with status and error details.

Once you have at least one channel configured, you can enable the Morning Briefing in Settings → Morning Briefing — a single daily digest that replaces the individual quest and due-today reminders with one compact message. See the Features guide for details.

See the Features guide for setup details on each channel.

Voice Control with Alexa (Optional)

Momo has an Alexa skill that lets you add tasks, manage your wishlist, and hear your Daily Quest without touching your phone.

Example commands:

  • “Alexa, ask Momo to add call the dentist”
  • “Alexa, ask Momo to add milk to the shopping list”
  • “Alexa, ask Momo what is my quest?”
  • “Alexa, ask Momo to list my tasks”

Account linking is handled automatically — when you tap “Link Account” in the Alexa app, you log in to Momo and an API key is created for you. No manual copy-paste required.

The skill runs on AWS Lambda (free tier) and connects to your self-hosted Momo instance via the REST API. Full setup takes about 30 minutes.

Full Alexa Skill guide →

Stopping Momo

docker compose down

To also remove the database volume (all data):

docker compose down -v

Next Steps