Installation

This guide will walk you through setting up Unisync on your local development environment.

Prerequisites

Make sure you have the following installed:

• Node.js (v18 or higher)
• Yarn package manager
• Docker and Docker Compose
• Expo CLI (for mobile development)

1. Start Backend Services

Start PostgreSQL and Hasura using Docker Compose:

docker-compose up -d

This will start:

• PostgreSQL: Port 9200
• Hasura Console: http://localhost:9203/console (admin secret: 123)

2. Set Up the Database

Apply Hasura migrations and metadata:

cd hasura
hasura migrate apply --database-name default
hasura metadata apply

3. Configure the Server

Create a .env file in the server directory:

cd server
cp env.example .env

Edit the .env file with your configuration. Key variables:

NODE_ENV=development
PORT=9201
HASURA_ENDPOINT=http://localhost:9203/v1/graphql
HASURA_ADMIN_SECRET=123
JWT_SECRET=reallySecretKey
JWT_ACCESS_TOKEN_EXPIRY=1h
JWT_REFRESH_TOKEN_EXPIRY=30d

# OTP Configuration
OTP_EXPIRY_MINUTES=5
OTP_MAX_ATTEMPTS=5
OTP_LENGTH=6

# SMS Provider Configuration (via Database)
# See Provider Configuration Guide for details
BULK_SMS_API_KEY=your_api_key_here
BULK_SMS_SECRET_KEY=your_secret_key_here
BULK_SMS_CALLER_ID=your_sender_id

# Email Provider (not yet implemented)
EMAIL_PROVIDER=console

# Optional: Sentry Error Tracking
SENTRY_DSN=

4. Start the Server

Install dependencies and start the server:

cd server
yarn install
yarn dev

The server will run on http://localhost:9201

API endpoint: http://localhost:9201/api/v1

5. Start the Mobile App

Configure and start the mobile app:

cd mobile
yarn install
yarn start

Then press:

• i for iOS simulator
• a for Android emulator
• Scan QR code with Expo Go app for physical device

Verify Installation

Check Server Health

curl http://localhost:9201/api/v1/health

You should see:

{
  "data": {
    "status": "OK",
    "uptime": 123.456,
    "environment": "development",
    "version": "1.0.0"
  },
  "meta": {
    "message": "Server is healthy",
    "timestamp": "2025-10-19T...",
    "duration": 5
  }
}

Check Hasura

Visit http://localhost:9203/console and verify you can access the GraphQL console with admin secret 123.

Check Database

Verify containers are running:

docker ps

You should see unisync-postgres and unisync-hasura running.

Troubleshooting

Port Already in Use

If port 9201, 9200, or 9203 is already in use:

# Find the process using the port
lsof -i :9201

# Kill the process
kill -9 <PID>

Docker Issues

If containers fail to start:

# Stop all containers
docker-compose down

# Remove volumes and restart
docker-compose down -v
docker-compose up -d

Hasura Migration Issues

If migrations fail:

cd hasura
hasura migrate status --database-name default
hasura migrate apply --database-name default --skip-execution

Development Workflow

Running Tests

cd server
yarn test

GraphQL Code Generation

Generate TypeScript types from GraphQL schema:

cd server
yarn codegen

Configure OTP Providers

To enable SMS OTP delivery, you'll need to configure a provider. See the Provider Configuration Guide for detailed instructions on:

• Setting up BulkSMS Bangladesh
• Adding new SMS providers
• Email provider implementation status

Next Steps

• Provider Configuration
• API Reference
• Authentication Guide