Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/soker90/finper/llms.txt

Use this file to discover all available pages before exploring further.

This guide walks you through running Finper locally from a fresh clone. By the end you will have the API listening on port 3008, the React frontend on port 5173, and an initial user account ready to log in with.

​
Prerequisites

Before you start, make sure the following tools are available on your machine:
ToolRequired versionNotes
Node.js≥ 24Check with node -v
pnpm10The repo enforces pnpm; npm/yarn will be rejected
makeanyPre-installed on macOS/Linux; available via winget or WSL on Windows
Docker (optional)anyOnly needed if you want to run the API in a container
No external database server is required — persistence is handled by a local SQLite file that the API creates automatically on first start.

​
Steps

1

Clone the repository and install dependencies

Clone the monorepo and run the root install, which resolves all workspace packages in one shot:
git clone https://github.com/soker90/finper.git
cd finper
pnpm install
Alternatively, use the Makefile shorthand:
make install
2

Configure your environment

Copy the provided example file to create your local .env at the repo root:
cp .env.example .env
Open .env and set the two required variables at minimum:
# Required — secret used to sign all JWT tokens
JWT_SECRET=replace_with_a_long_random_string

# Required — bcrypt cost factor for password hashing (10 is a sensible default)
SALT_ROUNDS=10
All other variables are optional for local development. See the Configuration page for the full reference.
3

Build the shared packages

The API depends on the compiled output of @soker90/finper-types and @soker90/finper-db. Build them in order:
make build-types
make build-db
You only need to rerun these commands when you change code inside packages/types/ or packages/db/.
4

Start the API

Launch the Express server. The API compiles TypeScript, then starts listening on port 3008. Drizzle migrations are applied automatically on every startup — no manual migration step is needed.
make start-api
You should see output confirming the server is running. Leave this terminal open.
5

Start the frontend

Open a new terminal in the same repo root and start the Vite dev server. The React client is served on port 5173:
make start-client
The client reads the API base URL from packages/client/.env. The default value (http://localhost:3008/api/) matches the API you just started.
6

Create your first user

Use the seed script to create an initial admin account. Replace the values with your chosen credentials:
make seed-user USERNAME=admin PASSWORD=mypassword
Username rules: 3–15 characters. Password rules: minimum 5 characters. The script is idempotent — if the user already exists it exits cleanly without error.You can now open http://localhost:5173 in your browser and log in.

​
Verify the API is healthy

After starting the API, confirm it is responding correctly with the built-in health endpoint: 
curl http://localhost:3008/api/monit/health
A successful response confirms the server is up and the database connection is active.
Ready to deploy Finper to a server or customise its behaviour? Head to the Configuration page for the complete environment variable reference, including CORS settings, optional Loki logging, and the finper-bot ticket integration.

Build docs developers (and LLMs) love

Get started for freeTalk to us