> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/TinsFox/ai-review/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart

> Run a local AI Review instance and trigger your first automated code review.

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.

<Steps>
  <Step title="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.

    <Note>
      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.
    </Note>
  </Step>

  <Step title="Clone the repository">
    ```bash theme={null}
    git clone https://github.com/TinsFox/ai-review.git
    cd ai-review
    ```
  </Step>

  <Step title="Install dependencies">
    ```bash theme={null}
    pnpm install
    ```
  </Step>

  <Step title="Set up environment variables">
    Copy the example file and fill in the required values:

    ```bash theme={null}
    cp .env.example .env.development
    ```

    Open `.env.development` and set at minimum:

    ```bash theme={null}
    # 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.

    <Note>
      `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.
    </Note>
  </Step>

  <Step title="Initialize the local development environment">
    This single command starts PostgreSQL and Redis via Docker and runs the initial database migrations:

    ```bash theme={null}
    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

    <Note>
      `pnpm env:init` only prepares dependencies and runs migrations. It does **not** start the server or web process — those come next.
    </Note>

    If you need to run only specific steps:

    <CodeGroup>
      ```bash Start only dependencies theme={null}
      pnpm env:deps
      ```

      ```bash Run migrations only theme={null}
      pnpm env:migrate
      ```

      ```bash Reset the development environment theme={null}
      pnpm env:reset
      ```
    </CodeGroup>

    <Warning>
      `pnpm env:reset` deletes all local development data.
    </Warning>
  </Step>

  <Step title="Start the API server">
    In a terminal, start the backend server:

    ```bash theme={null}
    pnpm dev:server
    ```

    The API server starts at `http://localhost:3000`. All routes are available under the `/api` prefix.
  </Step>

  <Step title="Start the web dashboard">
    In a second terminal, start the frontend dev server:

    ```bash theme={null}
    pnpm dev:web
    ```

    The web dashboard starts at `http://localhost:3001`.
  </Step>

  <Step title="Access the dashboard">
    Open [http://localhost:3001](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.
  </Step>

  <Step title="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.

    <Note>
      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.
    </Note>
  </Step>

  <Step title="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](http://localhost:3001).

    You can also check server logs:

    ```bash theme={null}
    tail -f ./data/logs/server.log
    ```
  </Step>
</Steps>

## Port reference

| Service               | Port  | Description                     |
| --------------------- | ----- | ------------------------------- |
| API server            | 3000  | Hono backend, all `/api` routes |
| Web dashboard         | 3001  | React frontend dev server       |
| PostgreSQL            | 15432 | Development database            |
| Redis                 | 16379 | BullMQ task queue               |
| GitLab (optional)     | 18080 | Local GitLab web UI             |
| GitLab SSH (optional) | 12222 | Local GitLab SSH                |

## Troubleshooting

If a port is already in use, check what is occupying it:

```bash theme={null}
lsof -i :15432   # PostgreSQL
lsof -i :16379   # Redis
lsof -i :3000    # API server
lsof -i :3001    # Web dashboard
```

To view Docker container logs:

```bash theme={null}
docker compose -f docker-compose.dev.yml logs db
docker compose -f docker-compose.dev.yml logs redis
```