Quick start

Getting Started · 5 min read

Two ways to run gleaned. Docker is recommended for anything you want to keep running — it handles the database, restarts, and optional TLS for you. Local dev is for exploring the code or contributing.

These docs reflect the state of gleaned at the time of writing. Commands depend on third-party tools (Docker, Node.js, pnpm) that change independently. Run everything at your own risk and verify against the official docs of each tool if something doesn't work.

Option 1 — Docker

gleaned ships as a single container. All data is stored in a SQLite file mounted via a named volume, so it survives container restarts and updates.

Runs on http://localhost:3000. Good for a local server or behind your own reverse proxy.

Clone the repo and generate secrets
Terminal
```
$ git clone https://github.com/gleaned-app/gleaned.git
$ cd gleaned
$ sh docker/setup.sh
```
The setup script generates a docker/.env file with random secrets. Never commit this file.

Start the container

Terminal

$ docker compose -f docker/compose.yml up -d

Open the app

Visit http://localhost:3000. On first launch you'll be prompted to set your password.

Runs on your own domain with automatic TLS via Let's Encrypt. Recommended for anything internet-facing.

Clone and generate secrets

Terminal

$ git clone https://github.com/gleaned-app/gleaned.git
$ cd gleaned
$ sh docker/setup.sh

Set your domain

Open docker/.env and set the DOMAIN variable to your domain (e.g. gleaned.example.com). Point your DNS A record to your server's IP before continuing.
Pull and start
Terminal
```
$ docker compose -f docker/compose.traefik.yml pull
$ docker compose -f docker/compose.traefik.yml up -d
```
Traefik will obtain a Let's Encrypt certificate on first start. This may take up to a minute.
Open your domain

Visit https://your-domain.com and set your password on first launch.

Single account. gleaned supports exactly one registration per instance. Once a password is set, the setup endpoint returns 409 for any further attempts. Two people means two separate containers.

Option 2 — Local development

No Docker needed. gleaned uses a local SQLite file (gleaned.db in the project root) in dev mode.

Prerequisites
You need Node.js ≥ 22 and pnpm. If you don't have pnpm:
Terminal
```
$ npm install -g pnpm
```

Install dependencies

Terminal

$ git clone https://github.com/gleaned-app/gleaned.git
$ cd gleaned
$ pnpm install

Run migrations and start

Terminal

$ pnpm db:migrate
$ pnpm dev
# → http://localhost:3000

Set your password

Open http://localhost:3000. On first launch gleaned asks you to set a password. This password derives your encryption key via PBKDF2 — it cannot be recovered if lost.

Running tests

Terminal

$ pnpm test          # unit tests (Vitest, watch mode)
$ pnpm test --run    # single run
$ pnpm e2e           # Playwright end-to-end (requires pnpm dev running)