Skip to main content
This guide walks you from zero to a running local AI Review instance. By the end, you will have the server and web dashboard running locally and be ready to configure your first project.
1

Prerequisites

Ensure the following are installed on your machine before continuing:
  • Node.js 18+
  • pnpm 10+
  • Docker (used to run PostgreSQL, Redis, and optionally a local GitLab)
PostgreSQL and Redis are started automatically via Docker in the next step — you do not need to install them separately.
The server’s task queue is powered by BullMQ and requires a running Redis instance. There is no in-memory fallback, so REDIS_URL must be set.
2

Clone the repository

git clone https://github.com/TinsFox/ai-review.git
cd ai-review
3

Install dependencies

pnpm install
4

Set up environment variables

Copy the example file and fill in the required values:
cp .env.example .env.development
Open .env.development and set at minimum:
# Required: PostgreSQL connection string
DATABASE_URL="postgresql://ai_review:ai_review@localhost:15432/ai_review"

# Required: at least 32 characters
BETTER_AUTH_SECRET=your-secret-at-least-32-characters-long

# Required: Redis for BullMQ task queue
REDIS_URL="redis://localhost:16379"
The example DATABASE_URL and REDIS_URL match the ports used by the local Docker services started in the next step.
ROOT_EMAIL and ROOT_PASSWORD in .env.development let you bootstrap an initial admin account on first startup. Set them now if you want to skip manual account creation.
5

Initialize the local development environment

This single command starts PostgreSQL and Redis via Docker and runs the initial database migrations:
pnpm env:init
What it does:
  • Starts the db (PostgreSQL on port 15432) and redis (port 16379) Docker containers
  • Runs pnpm db:migrate:dev to apply all schema migrations
pnpm env:init only prepares dependencies and runs migrations. It does not start the server or web process — those come next.
If you need to run only specific steps:
pnpm env:deps
pnpm env:reset deletes all local development data.
6

Start the API server

In a terminal, start the backend server:
pnpm dev:server
The API server starts at http://localhost:3000. All routes are available under the /api prefix.
7

Start the web dashboard

In a second terminal, start the frontend dev server:
pnpm dev:web
The web dashboard starts at http://localhost:3001.
8

Access the dashboard

Open http://localhost:3001 in your browser.If you set ROOT_EMAIL and ROOT_PASSWORD, log in with those credentials. Otherwise, complete the sign-up flow to create your first account.
9

Complete the onboarding flow

After logging in, the onboarding flow guides you through the required configuration steps:
  1. Platform configuration — connect a GitLab or GitHub instance and provide credentials so AI Review can receive webhooks and post comments.
  2. AI configuration — configure your AI provider. The currently activated provider is Volcengine (Doubao); set VOLCENGINE_API_KEY and VOLCENGINE_ENDPOINT in your environment file.
  3. Project — sync and add a repository that AI Review will monitor.
Although the environment file contains keys for other providers (OpenAI, Anthropic, Azure, Moonshot), only the volcengine runtime is active in the current codebase. Configure Volcengine credentials to enable AI review and chat functionality.
10

Trigger a test review

With a project configured, open a merge request (GitLab) or pull request (GitHub) in the connected repository. The platform webhook sends an event to http://localhost:3000/api/webhook/*, which enqueues a review task.Monitor the review in the Review History page of the dashboard at http://localhost:3001.You can also check server logs:
tail -f ./data/logs/server.log

​
Port reference

ServicePortDescription
API server3000Hono backend, all /api routes
Web dashboard3001React frontend dev server
PostgreSQL15432Development database
Redis16379BullMQ task queue
GitLab (optional)18080Local GitLab web UI
GitLab SSH (optional)12222Local GitLab SSH

​
Troubleshooting

If a port is already in use, check what is occupying it: 
lsof -i :15432   # PostgreSQL
lsof -i :16379   # Redis
lsof -i :3000    # API server
lsof -i :3001    # Web dashboard
To view Docker container logs: 
docker compose -f docker-compose.dev.yml logs db
docker compose -f docker-compose.dev.yml logs redis

Build docs developers (and LLMs) love

Get started for freeTalk to us