Docker Quick Start

Get Bliss running locally in under 5 minutes.

Prerequisites

• Docker and Docker Compose installed
• No other services on ports 8080, 3000, 3001, or 5432

Start everything

git clone https://github.com/danielvsantos/bliss.git && cd bliss
./scripts/setup.sh          # prompts for LLM provider, generates secrets, creates .env
docker compose up           # pulls images and starts all 5 services

During setup.sh you’ll be asked to pick an LLM provider (Gemini / OpenAI / Anthropic) and paste its API key. An LLM is required for AI classification and financial insights — without one, new transactions won’t be auto-categorized. You can skip the key prompt and add it to .env later, but the app will run in degraded mode until you do. See Choosing Your External Services for the comparison.

Open http://localhost:8080  once all containers are healthy. The database is auto-migrated and seeded with reference data (countries, currencies, banks) on first boot.

Contributing? Use docker compose up --build to build images from source instead of pulling from Docker Hub. This lets you test your local code changes.

Create your account

1. Click Sign Up and fill in email, password, and tenant name (this is your workspace).
2. The onboarding wizard asks you to select your countries and currencies.
3. After onboarding, you land on an empty dashboard.

What’s running

Data persistence

Your data lives in Docker named volumes (postgres_data, redis_data, uploads_data). It survives docker compose stop and docker compose down. Only docker compose down -v destroys volumes.

Database GUI

Adminer is included at http://localhost:8888 . Log in with system PostgreSQL, server postgres, username bliss, and the POSTGRES_PASSWORD from your .env.

Google OAuth

Google Sign-In is optional. Email/password sign-in works in all configurations. To enable Google OAuth:

1. Create OAuth 2.0 credentials in Google Cloud Console .
2. Add <NEXTAUTH_URL>/api/auth/callback/google as an Authorized Redirect URI.
3. Set GOOGLE_CLIENT_ID and GOOGLE_CLIENT_SECRET in .env.

HTTPS is required. Google’s OAuth policy does not allow plain-HTTP redirect URIs (the only exception is http://localhost for development). For a self-hosted deployment to support Google Sign-In, it must run behind HTTPS. Email/password sign-in is not affected and works over HTTP.

Local Development (Without Docker)

If you prefer running services directly for development:

Prerequisites

Installing pgvector

macOS (Homebrew):

brew install pgvector

Ubuntu / Debian:

sudo apt install postgresql-16-pgvector

After installation, enable the extension inside your database:

CREATE EXTENSION IF NOT EXISTS vector;

Setup

git clone https://github.com/danielvsantos/bliss.git && cd bliss
cp .env.example .env
./scripts/setup.sh          # generates secrets
pnpm install

Edit .env and set DATABASE_URL and REDIS_URL for your local setup.

createdb bliss
psql bliss -c 'CREATE EXTENSION IF NOT EXISTS vector;'
pnpm exec prisma migrate deploy --schema=prisma/schema.prisma
pnpm exec prisma db seed
pnpm dev                    # starts all services

Troubleshooting

pgvector extension not found — Connect to your database and run CREATE EXTENSION IF NOT EXISTS vector;. If this fails, pgvector is not installed at the system level (see prerequisites above).

Port conflicts — The defaults are 8080, 3000, 3001, and 5432. Make sure nothing else is bound to those ports.

Redis connection refused — Verify Redis is running and REDIS_URL in .env points to the correct host.

Prisma migration issues — Reset the database during development with pnpm exec prisma migrate reset --schema=prisma/schema.prisma (destroys all data).

Next steps

• Choosing Your External Services — required for AI classification and insights (Gemini, OpenAI, or Anthropic)
• Initial Account Setup — set up accounts, banks, and categories
• Choosing Your External Services — configure Twelve Data, Plaid, CurrencyLayer
• Import transactions — bring in your CSV/XLSX data
• Connect a bank — automatic sync with Plaid