Running Backend Services Locally

This guide explains how front-end developers can start the backend services their application depends on using Docker Compose.

Overview

Each front-end gateway application provides Docker Compose configurations in src/main/docker/ for local development:

`dev.yml`	Full stack - Gateway, Admin Service, and MySQL database
`admin-service.yml`	Admin Service and MySQL only (for local Gateway development)
`mysql.yml`	MySQL database only

Quick Start

For front-end developers who need all backend services running:

# Install npm dependencies
npm install

# Start all backend services
npm run docker:backend:up

# Start Angular dev server
npm start

NPM Script Commands

All projects provide consistent npm scripts for Docker operations:

Table 1. Backend Service Commands (dev.yml)
Command	Description
`npm run docker:backend:up`	Start all backend services (Gateway, Admin Service, MySQL)
`npm run docker:backend:down`	Stop all backend services
`npm run docker:backend:logs`	Stream logs from all services
`npm run docker:backend:restart`	Restart all backend services
`npm run docker:backend:reset`	Stop, remove volumes, and restart (fresh database)

Table 2. Admin Service Only Commands (admin-service.yml)
Command	Description
`npm run docker:admin-service:up`	Start Admin Service and MySQL only
`npm run docker:admin-service:down`	Stop Admin Service and MySQL
`npm run docker:admin-service:restart`	Restart Admin Service and MySQL
`npm run docker:admin-service:reset`	Stop, remove volumes, and restart (fresh database)

Table 3. Database Commands (mysql.yml)
Command	Description
`npm run docker:db:up`	Start MySQL database only
`npm run docker:db:down`	Stop MySQL and remove volumes

Development Scenarios

Front-end Development Only

When working exclusively on Angular code, start all backends in Docker:

npm run docker:backend:up
npm start

Access the application via the Angular dev server (typically http://localhost:9000 or http://localhost:9001).

Local Gateway Development

When modifying the Java Gateway code, run only the Admin Service in Docker while running the Gateway locally:

# Start Admin Service and MySQL
npm run docker:admin-service:up

# Run Gateway locally from IDE or command line
./mvnw

# Start Angular dev server
npm start

Database Reset

To start fresh with an empty database:

npm run docker:backend:reset

This removes all Docker volumes (including database data) and restarts the services. Liquibase migrations will re-run, and if the faker context is enabled, test data will be regenerated.

Interactive Setup Scripts

For guided setup with port conflict detection, use the provided scripts:

Windows (PowerShell)

.\scripts\setup-backend.ps1

macOS / Linux

./scripts/setup-backend.sh

These scripts:

Check Docker installation and daemon status
Detect port conflicts (MySQL on 3306, services on their respective ports)
Offer options when a local MySQL is detected
Start services and display access URLs

Port Assignments

Each application uses specific ports to avoid conflicts:

Service	Port	Notes
MySQL	3306	Shared across all applications
Admin Service	12504	Core API backend
Registration Portal Gateway	12505
Membership UI Gateway	12506
Event Admin UI Gateway	12503

Common Issues and Solutions

Port Already in Use

If you see "port is already allocated" errors:

Check if another Docker container is using the port: docker ps
Stop conflicting containers: docker stop <container-id>
Or use docker:backend:reset to clean up all containers

MySQL Connection Refused

If services cannot connect to MySQL:

Ensure MySQL container is healthy: docker ps should show "healthy"
MySQL may take 30-60 seconds to initialize on first start
Check MySQL logs: docker compose -f src/main/docker/mysql.yml logs

Using Local MySQL Instead of Docker

If you prefer using a locally installed MySQL:

Create the required databases:

CREATE DATABASE IF NOT EXISTS `<application-database>`;
CREATE DATABASE IF NOT EXISTS `admin-service`;

Create a dev-local-mysql.yml override file that removes the MySQL service dependency
Run with the override: docker compose -f src/main/docker/dev.yml -f src/main/docker/dev-local-mysql.yml up -d

Services Start But Application Fails

Common causes:

Missing database password secret: The Docker Compose uses empty passwords for development
Spring profiles not set: Ensure SPRING_PROFILES_ACTIVE includes dev
Liquibase migration failures: Check application logs for migration errors

Docker Compose File Structure

dev.yml Structure

name: <application-name>
services:
  <gateway-service>:
    image: christhonie/<image>:<version>
    depends_on:
      mysql:
        condition: service_healthy
      admin-service:
        condition: service_healthy
    # ... environment variables, ports, healthcheck

  admin-service:
    image: christhonie/event-admin-service:<version>
    depends_on:
      mysql:
        condition: service_healthy
    # ... environment variables, ports, healthcheck

  mysql:
    extends:
      file: ./mysql.yml
      service: mysql

The extends pattern allows reusing the MySQL configuration across different compose files while keeping configurations DRY.