Skip to main content

​
Prerequisites

Before you begin, make sure you have the following installed:
  • Node.js v18 or later
  • Yarn v1.22 (npm install -g yarn)
  • Docker and Docker Compose (for the database and mail server)

​
Setup

1

Clone the repository

Clone the monorepo and move into the project root.
git clone <your-repo-url> fleet-management-system
cd fleet-management-system
2

Install dependencies

Install all workspace dependencies from the monorepo root. The -W flag targets the workspace root.
yarn install -W
3

Configure environment variables

Copy the example environment file for the backend (and optionally the mobile and desktop apps).
cp packages/backend/.env.example packages/backend/.env
cp packages/mobile/.env.example packages/mobile/.env
cp packages/desktop/.env.example packages/desktop/.env
The backend .env contains the following variables. The defaults work for local development without any changes.
packages/backend/.env
PORT=3001
NODE_ENV=development
DB_SYNC=false
DB_SEED=true
DATABASE_URL=postgresql://postgres:[email protected]:5432/fleet_management?schema=public
DB_HOST=127.0.0.1
DB_PORT=5432
DB_NAME=fleet_management
DB_USER=postgres
DB_PASSWORD=postgres
JWT_SECRET=change-me
DEFAULT_LOGIN_PASSWORD=changeme123
SMTP_HOST=127.0.0.1
SMTP_PORT=1025
SMTP_SECURE=false
SMTP_USER=
SMTP_PASS=
EMAIL_FROM=[email protected]
Change JWT_SECRET to a long, random string before deploying to any non-local environment. The default value change-me is intentionally insecure and must not be used in production.
4

Start PostgreSQL and Mailpit

Use Docker Compose to start the PostgreSQL database (port 5432) and Mailpit mail catcher (SMTP on port 1025, web UI on port 8025).
docker-compose up -d
You can open the Mailpit web UI at http://localhost:8025 to view emails sent by the backend (inspection PDFs, notifications, etc.).
5

Sync the database

Run the database sync script to create all tables and load the demo seed data.
yarn workspace backend db:sync
This creates tables for Users, Fleets, Vehicles, Assignments, Inspections, MaintenanceTypes, and VehicleMaintenance, then seeds them with demo records.
6

Start the backend

Start the API server. It listens on port 3001 by default.
yarn workspace backend dev
Verify it is running by checking the health endpoint:
curl http://localhost:3001/api/health
# {"ok":true}
7

Start the mobile app

Launch the Expo development server for the React Native mobile app used by technicians.
yarn workspace mobile start
Scan the QR code with the Expo Go app on your iOS or Android device, or press i / a to open a simulator.
8

Start the desktop app

Start the Electron desktop app used by fleet administrators. This runs a Vite renderer on port 5174 and opens the Electron window automatically.
yarn workspace desktop dev
9

Log in with demo credentials

Use either of the seeded demo accounts to explore the system.
RoleEmailPassword
Admin[email protected]changeme123
Technician[email protected]changeme123
Log in through the desktop app as admin to manage fleets and vehicles, or through the mobile app as tech to view your assigned vehicle and submit inspections.

​
Next steps

Architecture

Understand how the backend, mobile, and desktop apps are structured and how they communicate.

Admin guide

Create fleets, register vehicles, and manage technician assignments.

Technician guide

Submit your first vehicle inspection from the mobile app.

API reference

Explore the full REST API, including authentication and all endpoints.

Build docs developers (and LLMs) love

Get started for freeTalk to us