Skip to content

# Source Code Installation Guide (Docker Compose) ​

This guide is for developers who want to run backend services from source code using Docker Compose. This approach combines the convenience of containerization with the flexibility of building from source, making it ideal for customization and development.

> ⚠️ IMPORTANT: Advanced Users Only

> This installation method is designed for experienced developers with strong knowledge of Docker, Node.js, and backend systems. Due to the complexity and customization potential of building from source:

> - ✋ We cannot provide item support for issues related to this installation method
> - ✋ Self-troubleshooting is required for most configuration and build issues
> - ✋ Production use at your own risk — we recommend the pre-built Docker installation for official support

> If you need guaranteed support, please use the Docker Installation Guide (Pre-built) instead.

## 📋 Overview ​

Unlike the pre-built Docker deployment, this method:

- Builds all services from source code using Docker Compose
- Allows full customization of backend services
- Uses the NX monorepo workspace structure
- Provides hot-reload capabilities for development
- Maintains production-ready containerization

## ✅ Prerequisites ​

Before starting, ensure you have:

- Ubuntu 22.04 LTS (or compatible Linux distribution)
- Static IP address (required for license validation)
- Root or sudo access to the server
- Downloaded package from CodeCanyon (the full source code ZIP)
- At least 4GB RAM and 10GB free disk space

## 🐳 Step 1: Install Docker & Docker Compose ​

If Docker is not already installed on your system, run:

bash

    curl -sSL https://get.docker.com | sh

Verify the installation:

bash

    docker --version
    docker compose version

Enable Docker to start on boot:

bash

    sudo systemctl enable docker
    sudo systemctl start docker

## 📦 Step 2: Extract the Source Code ​

1. Upload the downloaded ZIP from CodeCanyon to your server
2. Extract the package:

bash

    unzip package.zip -d /root
    cd /root

The extracted folder should contain:

- `docker-compose.yaml` (or `docker-compose.yml`)
- `.env.example` (environment template)
- NX workspace structure with `apps/` and `libs/` folders
- `package.json` and workspace configuration files

## ⚙️ Step 3: Configure Environment Variables ​

### Create Your Environment File ​

Copy the example environment file:

bash

    cp .env.example .env

### Edit Critical Configuration ​

Open the `.env` file and update the following required values:

bash

    nano .env

#### 🔑 Essential Variables to Update ​

env

    # ========================================
    # SERVER URLs - Replace 127.0.0.1 with your server's IP
    # ========================================
    GATEWAY_SERVER_URL=http://YOUR_SERVER_IP:3333
    RIDER_SERVER_URL=http://YOUR_SERVER_IP:3001
    DRIVER_SERVER_URL=http://YOUR_SERVER_IP:3002
    ADMIN_SERVER_URL=http://YOUR_SERVER_IP:3000

### 📝 Important Notes ​

- Replace `YOUR_SERVER_IP` with your actual server IP address (e.g., `192.168.1.100` or your public IP)
- Do NOT use `127.0.0.1` or `localhost` in production unless testing locally
- Keep your `.env` file secure — never commit it to version control
- For local development, you can use `127.0.0.1` or `localhost`
- For production, use your static IP or domain name (with SSL setup)

## 🏗️ Step 4: Understanding the Docker Compose Setup ​

The `docker-compose.yaml` file in your package defines all services:

yaml

    services:
      mysql:          # Database service
      redis:          # Cache and queue service
      admin-api:      # Backend for admin panel
      rider-api:      # Backend for customer app
      driver-api:     # Backend for driver app
      payment-gateways: # Payment processor
      nginx:          # Web server and reverse proxy

Each service is configured to build from source using the NX workspace.

## 🚀 Step 5: Build and Start Services ​

### Initial Build ​

Build all services from source (this may take 10-15 minutes on first run):

bash

    docker compose build

### Start All Services ​

bash

    docker compose up -d

The `-d` flag runs services in detached mode (background).

### Verify Services Are Running ​

Check the status of all containers:

bash

    docker compose ps

You should see all services with status `Up` or `healthy`.

### View Logs ​

To monitor service logs:

bash

    # View all logs
    docker compose logs -f

    # View specific service logs
    docker compose logs -f admin-api
    docker compose logs -f rider-api
    docker compose logs -f mysql

Press `Ctrl+C` to stop following logs.

## 🔍 Step 6: Initial Setup & Configuration ​

### Access the Admin Panel ​

Once all services are running, access the admin panel:

text

    http://YOUR_SERVER_IP/admin/

Or if using a domain:

text

    https://yourdomain.com/admin/

### Complete First-Time Setup ​

The admin panel will guide you through:

1. License Validation — Enter your CodeCanyon purchase code
2. Database Migration — Automatic schema creation
3. Admin Account Creation — Set up your first admin user
4. Basic Configuration:
   - Google Maps API key
   - Firebase configuration for push notifications

## 🛠️ Development Workflow ​

### Making Code Changes ​

When you modify code in the source:

1. Edit files in `apps/` or `libs/` directories
2. Rebuild the affected service:

bash

    docker compose build admin-api
    docker compose up -d admin-api

Or rebuild all services:

bash

    docker compose build
    docker compose up -d

### Hot Reload for Development ​

For active development with hot reload, you can run services locally using NX:

1. Stop the Docker service you want to develop:

bash

    docker compose stop admin-api

1. Install dependencies locally:

bash

    npm install

1. Run the service with NX:

bash

    npx nx serve admin-api

This runs the service outside Docker with hot reload enabled.

## 📊 Managing Services ​

### Stop All Services ​

bash

    docker compose stop

### Start Stopped Services ​

bash

    docker compose start

### Restart a Specific Service ​

bash

    docker compose restart rider-api

### Remove All Containers (keeps data) ​

bash

    docker compose down

### Remove Everything Including Volumes (⚠️ deletes database) ​

bash

    docker compose down -v

## 🗄️ Database Management ​

### Access MySQL Console ​

bash

    docker compose exec mysql mysql -u root -p

Enter the password you set in `.env`.

### Backup Database ​

bash

    docker compose exec mysql mysqldump -u root -p bettersuite > backup.sql

### Restore Database ​

bash

    docker compose exec -T mysql mysql -u root -p bettersuite < backup.sql

## 🔧 Troubleshooting ​

### Services Won't Start ​

Check logs for errors:

bash

    docker compose logs

Common issues:

- Port conflicts — Ensure ports 80, 443, 3000-3006, 3306, 6379 are not in use
- Permission errors — Run with `sudo` or add user to docker group
- Memory issues — Ensure at least 4GB RAM available

### License Validation Fails ​

- Verify `PURCHASE_CODE` is correct in `.env`
- Ensure using a static IP address
- Contact support if IP was recently changed

### Database Connection Errors ​

- Check `DB_*` variables in `.env`
- Ensure MySQL container is running: `docker compose ps mysql`
- Check MySQL logs: `docker compose logs mysql`

### Service-Specific Errors ​

Admin API won't start:

bash

    docker compose logs admin-api

Check for:

- Database migration failures
- Missing environment variables
- Port conflicts

Payment gateway issues:

- Verify `payment-gateways` service is running
- Check API credentials in admin panel
- Review payment service logs

### Rebuilding from Scratch ​

If you encounter persistent issues:

bash

    # Stop and remove all containers
    docker compose down

    # Remove all images (forces rebuild)
    docker compose down --rmi all

    # Rebuild and start fresh
    docker compose build --no-cache
    docker compose up -d

## 🔄 Updating the System ​

### Pull Latest Source Code ​

1. Backup your database (see Database Management section)
2. Download new package from CodeCanyon
3. Extract to a new directory or overwrite (backup `.env` first!)
4. Rebuild services:

bash

    docker compose build
    docker compose up -d

Migrations will run automatically on `admin-api` startup.

## 🌐 Production Deployment ​

### Enable HTTPS/SSL ​

For production, configure SSL using:

- Cloudflare (recommended) — See HTTPS & SSL Setup
- Let's Encrypt with Certbot
- Reverse proxy with SSL termination

### Performance Optimization ​

Increase container resources in `docker-compose.yaml`:

yaml

    services:
      admin-api:
        deploy:
          resources:
            limits:
              cpus: '2'
              memory: 2G

Enable production mode in `.env`:

env

    NODE_ENV=production

### Monitoring & Logs ​

Set up log rotation:

bash

    docker compose logs --tail=100 -f > /var/log/bettersuite.log

Monitor resource usage:

bash

    docker stats

## 🎯 Next Steps ​

After successful installation:

1. ✅ Configure regions and pricing in Admin Panel
2. ✅ Set up payment gateways via Settings → Payments
3. ✅ Configure SMS provider for OTP
4. ✅ Set up Firebase for push notifications
5. ✅ Build and deploy mobile apps — See Building & Running Flutter Apps
6. ✅ Configure SSL/HTTPS — See HTTPS & SSL Setup
7. ✅ Test end-to-end workflows with driver and customer apps

## 📞 Support & Assistance ​

> ⚠️ Limited Support Notice

> Source code installations are not covered under standard item support. We cannot provide technical assistance for build issues, custom configurations, or problems arising from this installation method.

### Self-Help Resources ​

If you encounter issues, please refer to:

- 📖 Common Errors & Resolutions — General troubleshooting guide
- 🐳 Docker Documentation — Official Docker resources
- 📦 NX Documentation — NX workspace and monorepo guides
- 🔍 Docker community forums and Stack Overflow

### When Support Is Available ​

Customers may receive guidance for:

- License validation issues (not build-related)

What we do NOT support:

- ❌ Custom code modifications or build errors
- ❌ Environment-specific problems
- ❌ Performance tuning for custom setups
- ❌ Third-party integration issues

### Need Full Support? ​

If you require comprehensive technical support, we strongly recommend using:

- 🚀 Docker Installation Guide (Pre-built) — Officially supported
- 📧 Contact contact@lumeagency.io for Pro Plus upgrade inquiries

Ready for production? Proceed to Deployment Options Overview for mobile app publishing guides.