Networking in OneCX Local Environment

This document explains how networking is configured and managed in the OneCX local development environment.

Overview

The OneCX local environment uses a sophisticated networking setup that combines:

Traefik as the central reverse proxy and API gateway
Docker Compose networks for service-to-service communication
Host file configuration for domain name resolution
Service discovery through Docker labels
Environment-based configuration for flexible deployment

Architecture Components

Traefik Reverse Proxy

Traefik serves as the central entry point for all HTTP traffic in the OneCX environment. It acts as:

Reverse Proxy: Routes incoming requests to appropriate backend services
Load Balancer: Distributes traffic across service instances
Service Discovery: Automatically detects new services through Docker labels
API Gateway: Provides a single entry point for all microservices

Traefik Configuration

The Traefik configuration is split across multiple files:

init-data/traefik/traefik-conf.yml: Main Traefik configuration
init-data/traefik/traefik-services.yml: Static service definitions
Docker labels in docker-compose.v<version>.yaml: Dynamic service registration

Key Traefik Settings

traefik-conf.yml

entryPoints:
  web:
    address: ":80"  # HTTP entry point

providers:
  docker:
    endpoint: unix:///var/run/docker.sock  # Docker socket for service discovery
  file:
    filename: /etc/traefik/services.yml    # Static service definitions

Service Discovery and Routing

Traefik Labels

Services register themselves with Traefik using Docker labels:

General Traefik Label Patterns

labels:
  # Define the service port (required for all services)
  - "traefik.http.services.<service-name>.loadbalancer.server.port=<port>"

  # Backend services (BFF/SVC) and Infrastructure services - simple host-based routing
  - "traefik.http.routers.<service-name>.rule=Host(`<service-name>`)"

  # Frontend applications - path-based routing through local-proxy
  - "traefik.http.routers.<ui-service>.rule=Host(`local-proxy`)&&PathPrefix(`/<app-path>/`)"

Routing Rules

Different routing patterns are used for different service types:

Backend Services (BFF/SVC) and Infrastructure Services:

Host(`service-name`)

Frontend Applications (UI):

Host(`local-proxy`)&&PathPrefix(`/app-path/`)

Host File Configuration

For proper domain resolution in development, the following entries should be added to your local hosts file (/etc/hosts on Linux/macOS, C:\Windows\System32\drivers\etc\hosts on Windows):

# OneCX Local Environment
127.0.0.1 local-proxy
127.0.0.1 keycloak-app
127.0.0.1 postgresdb
127.0.0.1 pgadmin
127.0.0.1 onecx-shell-bff
127.0.0.1 onecx-theme-svc
127.0.0.1 onecx-theme-bff
127.0.0.1 onecx-workspace-svc
127.0.0.1 onecx-workspace-bff
127.0.0.1 onecx-permission-svc
127.0.0.1 onecx-permission-bff
127.0.0.1 onecx-product-store-svc
127.0.0.1 onecx-product-store-bff
127.0.0.1 onecx-user-profile-svc
127.0.0.1 onecx-user-profile-bff
# Add other OneCX services as needed

Port Mapping Strategy

External Ports (Host → Container)

Key external ports exposed to the host:

Service	Host Port	Purpose
Traefik HTTP	80	Main HTTP entry point
Traefik Dashboard	8082	Web UI for Traefik management
Keycloak	8080	Identity and access management
PostgreSQL	5432	Database direct access

Service

Host Port

Purpose

Traefik HTTP

Main HTTP entry point

Traefik Dashboard

8082

Web UI for Traefik management

Keycloak

8080

Identity and access management

PostgreSQL

5432

Database direct access

Internal Ports (Container → Container)

Services communicate internally using standard ports:

Web Services: Port 8080 (Quarkus default)
PostgreSQL: Port 5432
Frontend Applications: Port 8080 (Nginx)

Docker Compose Networks

Default Network

All services are connected to the default (docker-compose.v2.yaml) or example (docker-compose.v1.yaml) Docker Compose network, which enables:

Service-to-Service Communication: Services can communicate using container names as hostnames
Automatic DNS Resolution: Docker provides built-in DNS for container name resolution
Network Isolation: Traffic is isolated from the host network and other Docker networks

Network Communication Patterns

Services communicate using these patterns:

Communication Type Example URL Pattern

Communication Type	Example	URL Pattern
Frontend to BFF	Shell UI → Shell BFF	`http://onecx-shell-bff:8080`
BFF to Service	Shell BFF → Theme Service	`http://onecx-theme-svc:8080`
Service to Database	Theme Service → PostgreSQL	`jdbc:postgresql://postgresdb:5432/onecx_theme`
Service to Keycloak	Any Service → Keycloak	`http://keycloak-app:8080`

Frontend to BFF

Shell UI → Shell BFF

http://onecx-shell-bff:8080

BFF to Service

Shell BFF → Theme Service

http://onecx-theme-svc:8080

Service to Database

Theme Service → PostgreSQL

jdbc:postgresql://postgresdb:5432/onecx_theme

Service to Keycloak

Any Service → Keycloak

http://keycloak-app:8080

Environment Configuration

Common Environment Variables

Key networking-related shared environment variables in common.env:

common.env

KC_REALM=onecx
QUARKUS_OIDC_AUTH_SERVER_URL=http://keycloak-app:8080/realms/${KC_REALM}
QUARKUS_OIDC_TOKEN_ISSUER=http://keycloak-app/realms/${KC_REALM}

Service-Specific Configuration

BFF Environment (bff.env):
- Currently empty - BFF services inherit their networking configuration from common.env.
Service Environment (svc.env):

TKIT_DATAIMPORT_ENABLED=true
ONECX_TENANT_CACHE_ENABLED=false

Database connection URLs and authentication endpoints are typically configured directly in the docker-compose.v2.yaml file within each service’s environment section, using internal Docker network hostnames like postgresdb:5432 and keycloak-app:8080.

Access Patterns

External Access (Browser → Services)

OneCX Shell (Main Entry Point)

Shell Admin Interface: http://local-proxy/onecx-shell/admin
- Default credentials: username onecx, password onecx
- All OneCX applications are accessed through the Shell workspace navigation

Application Access Through Shell

Applications are accessed via the Shell workspace navigation. For example:

Workspace Management: http://local-proxy/onecx-shell/admin/workspace
The workspace UI is served from: http://local-proxy/mfe/workspace/
Where the path can be found in the path prefix:
- "traefik.http.routers.<ui-service>.rule=Host(\`local-proxy\)&&PathPrefix(`/mfe/workspace/\`)"`

Infrastructure Services

Keycloak: http://keycloak-app:8080 or http://localhost:8080
PgAdmin: http://pgadmin
Traefik Dashboard: http://localhost:8082

Internal Communication

Services communicate internally using container names:

BFF calls services: http://service-name:8080
Services call databases: jdbc:postgresql://postgresdb:5432/db_name
All services authenticate via: http://keycloak-app:8080

Development Workflow

Local Development Integration

The networking setup supports local development through:

Host Integration:

extra_hosts:
  - "host.docker.internal:host-gateway"

Static Service Definitions (traefik-services.yml):

http:
  services:
    local_bff:
      loadBalancer:
        servers:
          - url: "http://host.docker.internal:8585/"
    local_mfe:
      loadBalancer:
        servers:
          - url: "http://host.docker.internal:4200/"

With this configuration, the local MFE/UI must run on port 4200 and the respective BFF must run on port 8585. Refer to this different ports note section for more details on changing to different ports.