Get OneCX

Welcome to OneCX. This guide gives you a clear, reliable path to set up the local development environment, run core products, and develop microfrontends roductively. It is grounded in the OneCX Local Environment. See also: OneCX Local Environment.

What You’ll Set Up

  • Core infrastructure: Traefik (routing), Postgres (database), Keycloak (auth)

  • Core products and UIs (Shell, Workspace, Theme, etc.) via Docker Compose profiles

  • A development loop for local microfrontends proxied by Traefik

Prerequisites

  • Docker and Docker Compose

  • Git

  • Node.js (for frontends) and Java (for services), as required by specific apps

  • Linux shell (adapt commands to your OS if needed)

Initialize the Local Environment

Move into the local environment folder and start essential services.

cd environments/onecx-local-env_main
# Start Traefik (reverse proxy + dashboard)
docker compose up -d traefik
# Start the base profile (Keycloak, Postgres, core UIs)
docker compose up -d --profile base
# Optional: start everything
docker compose up -d --profile all
# Traefik dashboard (accessible within the Docker network)
# http://traefik:8082/dashboard/

Compose profiles let you start focused sets of services. Common profiles include base, all, and data-import.

Accessing Applications

Apps are exposed through Traefik on the local-proxy host using path prefixes: - Shell UI: /onecx-shell/ - Product UIs: /mfe/<product>/ (e.g., /mfe/workspace/, /mfe/theme/) Routes become available once their containers are healthy.

Develop a Microfrontend Locally

Run a microfrontend on your host and proxy it under the same path prefix used by the container UI. Align the base href to the product path.

# Example: Workspace MFE on port 5025 (Angular)
ng serve --port 5025 --base-href /mfe/workspace/ --deploy-url /mfe/workspace/

  • Use a shared base href (/mfe/<app>/) for both local and container UI to avoid path mismatches.

  • After changing Traefik file-provider configs, run docker compose restart traefik to reload.

Build & Run Products

Start specific services or products selectively as needed.

# List services and health
docker compose ps
# Start a single product
docker compose up -d onecx-workspace-ui

Import Seed Data (optional)

The local environment provides scripts to preload products and configuration for a realistic setup.

# From environments/onecx-local-env_main
./import-onecx.sh

Troubleshooting & Health

  • Check Traefik routes and service health in the dashboard.

  • Ensure services expose the expected port and respond on / for health checks.

  • Use Compose profiles to scope startup and reduce resource usage.

Next Steps

  • Create your first Angular microfrontend: CLI Setup or Manual Setup

  • Enable hot reload: Hot Reload

  • Explore core applications and their services via the Applications section.

Happy building!