Installation

Ledger runs as a Next.js application backed by PostgreSQL. Getting it running locally is the standard four-step flow most JavaScript projects follow: clone the repository, install dependencies, point it at a database, and start the dev server. The whole sequence takes a few minutes on a clean development machine, and most of the elapsed time is npm install.

Prerequisites#

Before starting, confirm you have a recent Node.js, a running PostgreSQL instance, and an OAuth client to sign in against. Ledger uses third-party authentication so you don't have to manage passwords yourself; in development the simplest choice is whichever OAuth provider you already have an account with.

Node.js 20+
PostgreSQL 15+
A Google, Twitter, or Discord OAuth app (for authentication)

Clone and install#

Clone the repository and install the JavaScript dependencies. The dependency tree is large but standard for a Next.js project — most of the install time is download and compilation of native modules.

bash

git clone https://github.com/atlas-labs-systems/ledger
cd ledger
npm install

Environment setup#

Ledger reads its configuration from .env.local, the same convention every Next.js project uses. The repository ships an .env.example with every supported variable documented; copying it gives you a starting point that needs only a few values filled in to run.

bash

cp .env.example .env.local

The minimum-viable set of variables points at your database and gives Ledger an OAuth client to authenticate against. Everything else — sync intervals, RPC overrides, CEX integrations — has defaults that work for local development.

env

DATABASE_URL="postgresql://user:password@localhost:5432/ledger"
AUTH_SECRET="generate-with-openssl-rand-base64-32"
GOOGLE_CLIENT_ID=""
GOOGLE_CLIENT_SECRET=""

Database setup#

Apply the schema migrations to your database before starting the app for the first time. The optional seed step adds the reference data you need to log in and create a portfolio without manually populating tables.

bash

npm run db:migrate    # run migrations
npm run db:seed       # seed initial data (optional)

Start the dev server#

With the schema in place, start the dev server and open the app in your browser. Sign in with whichever OAuth provider you configured and you'll land on the dashboard, ready to create your first portfolio.

bash

npm run dev

Open http://localhost:3000. Sign in with one of the OAuth providers and you'll land on your dashboard.

Was this page helpful?