> ## Documentation Index
> Fetch the complete documentation index at: https://docs.learnway.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# Quick Start

> Get the LearnWay backend running locally in under 10 minutes.

## Prerequisites

Before you begin, ensure you have the following installed:

| Tool       | Minimum Version | Notes                              |
| ---------- | --------------- | ---------------------------------- |
| Node.js    | v18             | v20 LTS recommended                |
| npm        | v9              | Comes with Node.js                 |
| PostgreSQL | v12             | v15 recommended                    |
| Redis      | v6              | v7 recommended                     |
| Docker     | Any recent      | Optional — for containerised setup |

***

## 1. Clone the Repository

```bash theme={null}
git clone https://github.com/learnwayxyz/learnway-backend.git
cd learnway-backend
```

***

## 2. Install Dependencies

```bash theme={null}
npm install
```

***

## 3. Configure Environment Variables

The app reads from a file at `config/env/.env` (resolved relative to `process.cwd()`).

```bash theme={null}
cp config/env/.env.example config/env/.env
```

Open `config/env/.env` and fill in **at minimum** the required variables:

```bash theme={null}
# Core
NODE_ENV=dev
PORT=3000

# Database
DB_HOST=localhost
DB_PORT=5432
DB_USERNAME=postgres
DB_PASSWORD=your_password
DB_NAME=learnway

# Redis
REDIS_URL=redis://localhost:6379

# JWT
JWT_SECRET=change_me_to_a_long_random_string

# ImageKit (required — get a free account at imagekit.io)
IMAGEKIT_PUBLIC_KEY=your_public_key
IMAGEKIT_PRIVATE_KEY=your_private_key
IMAGEKIT_URL_ENDPOINT=https://ik.imagekit.io/your_id

# Blockchain (Lisk testnet for dev)
BLOCKCHAIN_RPC_URL=https://rpc.api.lisk.com
CHAIN_ID=1135
LEARNWAY_MANAGER_CONTRACT_ADDRESS=0x...
BADGES_NFT_CONTRACT_ADDRESS=0x...
GEM_CONTRACT_ADDRESS=0x...
XP_CONTRACT_ADDRESS=0x...
PRIVATE_KEY=0x...

# Fonbnk Payments
FONBNK_CLIENT_ID=your_client_id
FONBNK_CLIENT_SECRET=your_base64_secret
FONBNK_WEBHOOK_SECRET=your_webhook_secret

# Misc — required by schema validation
UNSUBSCRIBE_TOKEN_SECRET=change_me
CMC_API_KEY=your_coinmarketcap_key
```

<Note>
  See [Environment Variables](/guides/environment-variables) for a full
  reference of every variable and which are optional.
</Note>

***

## 4. Set Up the Database

Make sure your PostgreSQL instance is running, then create the database:

```sql theme={null}
CREATE DATABASE learnway;
```

***

## 5. Run Database Migrations

```bash theme={null}
npm run migration:run:dev
```

This applies all TypeORM migrations from `db/migration/` to your database.

***

## 6. (Optional) Seed an Admin User

```bash theme={null}
npm run seed:admin:dev
```

This creates a default admin account so you can access the admin API and dashboard.

***

## 7. Start the Development Server

```bash theme={null}
npm run start:dev
```

The server starts with hot-reload on `http://localhost:3000`.

<Check>
  Open `http://localhost:3000/api/v2/docs` — you should see the Swagger UI for
  the user-facing API.
</Check>

***

## Using Docker (Alternative)

If you prefer Docker, a `Dockerfile` is included.

```bash theme={null}
# Create the shared network
docker network create learnway-network

# Start PostgreSQL
docker run -d \
  --name learnway-db \
  --network learnway-network \
  -e POSTGRES_USER=postgres \
  -e POSTGRES_PASSWORD=your_password \
  -e POSTGRES_DB=learnway \
  -p 5432:5432 \
  postgres:15

# Start Redis
docker run -d \
  --name learnway-redis \
  --network learnway-network \
  -p 6379:6379 \
  redis:7

# Build and run the API
docker build -t learnway-backend .
docker run -d \
  --name learnway-api \
  --network learnway-network \
  -p 3000:3000 \
  --env-file config/env/.env \
  learnway-backend
```

***

## Useful Scripts

| Command                          | Description                                |
| -------------------------------- | ------------------------------------------ |
| `npm run start:dev`              | Start in watch mode (development)          |
| `npm run start:debug`            | Start in debug mode                        |
| `npm run build`                  | Compile TypeScript to `dist/`              |
| `npm run start:prod`             | Run compiled production build              |
| `npm run migration:run:dev`      | Apply pending DB migrations (dev)          |
| `npm run migration:generate:dev` | Generate new migration from entity changes |
| `npm run migration:revert:dev`   | Rollback last migration                    |
| `npm run seed:admin:dev`         | Seed admin user                            |
| `npm run lint`                   | Run ESLint                                 |
| `npm run format`                 | Format code with Prettier                  |
| `npm test`                       | Run unit tests                             |
| `npm run test:cov`               | Run tests with coverage                    |

***

## What's Next?

<CardGroup cols={2}>
  <Card title="Architecture Overview" icon="sitemap" href="/architecture/overview">
    Understand how all systems fit together
  </Card>

  <Card title="API Reference" icon="code" href="/api-reference/overview">
    Explore every endpoint
  </Card>

  <Card title="Environment Variables" icon="gear" href="/guides/environment-variables">
    Full env var reference
  </Card>

  <Card title="Admin Guide" icon="shield" href="/guides/admin-guide">
    Manage users, content and config
  </Card>
</CardGroup>