Local Development Setup

Local Development Setup

This guide will walk you through setting up the entire Merq platform on your local machine.

Prerequisites

Before you begin, ensure you have the following software installed.

Core

• Go: 1.25+
• Node.js: 24+ (for Web) or 18+ (for Mobile)
• pnpm: 9+ (for Web)
• Yarn: 1.22+ (for Mobile)
• Docker & Docker Compose

Mobile (Optional)

• Ruby: 3.0+ (for iOS)
• Xcode: 15+ (for iOS)
• Android Studio (for Android)

1. Clone the Monorepo

   Clone the main project repository which contains merq-backend, merq-web, and merq-mobile.

   git clone <your-repository-url>
   cd merq

2. Set Up Infrastructure (Database & Cache)

   The backend requires a PostgreSQL database and a Redis instance. The easiest way to run these is with Docker.

   From the merq-backend directory, start the required services:

   cd merq-backend
   docker-compose -f docker-compose.local.yml up -d

   This command will start PostgreSQL on port 5432 and Redis on port 6379.

3. Configure Environment Variables

   Each project has its own environment file. You need to create them from the provided examples and fill in the required values.

   • Backend:

     cd merq-backend
     cp env.example .env

     Edit .env and set DB_PASSWORD, JWT_SECRET, etc.

   • Web Dashboard:

     cd ../merq-web
     cp .env.example .env.local

     Ensure VITE_API_BASE_URL points to your backend (default: http://localhost:8080/api).

   • Mobile App:

     cd ../merq-mobile
     cp .env.example .env.dev

     Set API_BASE_URL and a STORAGE_ENC_KEY.

   Tip

   Refer to the Environment Variables documentation for a detailed explanation of each variable.

4. Set Up and Run the Backend

   With the database running and .env configured, you can set up the backend using the provided scripts.

   cd merq-backend
   
   # Install Go dependencies
   go mod download
   
   # Run database migrations (goose SQL migrations)
   ./scripts/migrate.sh up
   
   # Run database seeder (creates initial workspace, roles, super admin)
   ./scripts/seed.sh
   
   # Start the server
   ./scripts/dev.sh

   Or run everything in one command:

   ./scripts/dev.sh --migrate --seed

   The backend API will be running at http://localhost:8080.

   Tip

   All scripts support --env=FILE to switch between env files. For example:

   ./scripts/migrate.sh --env=.env.development up
   ./scripts/dev.sh --env=.env.development --watch

   See Dev Scripts for full documentation.

5. Set Up and Run the Web Dashboard

   cd ../merq-web
   
   # Install dependencies
   pnpm install
   
   # Start the development server
   pnpm dev

   The web dashboard will be running at http://localhost:3000. You can now log in with the user created by the backend seeder.

6. Set Up and Run the Mobile App (Optional)

   Setting up the mobile app is more involved due to native dependencies.

   cd ../merq-mobile
   
   # Install dependencies
   yarn install
   
   # For iOS, install pods
   cd ios && pod install && cd ..

   To run on Android:

   • Make sure an Android emulator is running or a device is connected.
   • If using a physical device, ensure API_BASE_URL in .env.dev is your computer’s local network IP address.

   yarn android

   To run on iOS (macOS only):

   • Make sure an iOS simulator is running or a device is connected.

   yarn ios