Edition - v1

Disclaimer

This page was created for an older edition of OneCX Local Environment and may not reflect the current state of the project. It is kept for historical reference and to provide information for users who are still using v1, but it might contain outdated information.

v1 was the initial edition of the local development environment for OneCX. Although it continues to function and will be maintained to avoid disrupting existing workflows, some significant improvements have been implemented in the current edition. We therefore encourage new users to start with the current edition.

To migrate from v1 to v2, please refer to the Migrate to v2 guide.

It is strongly recommended for new users to start with the current edition of OneCX Local Environment instead of v1, as it contains many improvements and new features that are not available in v1. The current edition also receives regular updates and maintenance, while v1 only receives critical fixes to avoid disrupting existing workflows.
Start here for the latest edition: OneCX Local Environment.

Overview

v1 contains services for Traefik, Postgres, Keycloak and all currently existing OneCX products (SVC, BFF, UI). Some of these services are started by default, while others can only be started via specific profiles.

Running v1

To start a minimal local development environment (Traefik, Postgres and Keycloak) together with OneCX Shell, OneCX Workspace and their dependencies, run one of the following commands:

From the repository root
docker compose -f versions/v1/docker-compose.v1.yaml up -d
From the versions/v1 directory
docker compose up -d

To additionally start the OneCX Parameter product, use the --profile parameter flag:

From the repository root
docker compose -f versions/v1/docker-compose.v1.yaml --profile parameter up -d
From the versions/v1 directory
docker compose --profile parameter up -d

To start all services defined in the compose file, use the --profile all flag:

From the repository root
docker compose -f versions/v1/docker-compose.v1.yaml --profile all up -d
From the versions/v1 directory
docker compose --profile all up -d

After starting the services, please wait until all services are healthy before accessing the environment. You can check the status of the services by running docker ps and looking at the "STATUS" column.

Stopping v1

To stop the started services, run one of the following commands:

From the repository root
docker compose -f versions/v1/docker-compose.v1.yaml down
Stop specific profile from the repository root
docker compose -f versions/v1/docker-compose.v1.yaml --profile <profile-name> down
From the versions/v1 directory
docker compose down
Stop specific profile from the versions/v1 directory
docker compose --profile <profile-name> down

Importing initial data

When starting OneCX Local Environment v1 for the first time, some initial data has to be imported to set up the environment correctly. To import the initial data, please follow these steps:

  1. Start the environment using the all profile (see Running v1).

  2. Wait for all services to be healthy.

  3. Wait for at least 30 seconds to ensure that all services are fully initialized and operational.

  4. Run the import script:

    From the repository root
    ./versions/v1/import-onecx.v1.sh

  5. Ensure that status messages for each step are green and indicate success.

    • If any step of the import fails, please verify that all services required for the import (Traefik, Postgres, Keycloak and all OneCX SVCs) are running and healthy.

    • If they are, please check the logs of the service that failed the import for potential issues. To do so run docker ps to get the container ID and docker logs <container-id> to view the logs.

    • If they are not, please start the missing services and wait until they are healthy before re-running the import script.

  6. After the script has completed successfully, all initial data has been imported and the environment is ready to use.

Components

Services

  • traefik

  • postgresdb

  • pgadmin

  • keycloak-app

  • OneCX Product Services:

    • Shell: onecx-shell-ui, onecx-shell-bff

    • Theme: onecx-theme-svc, onecx-theme-bff, onecx-theme-ui

    • Workspace: onecx-workspace-svc, onecx-workspace-bff, onecx-workspace-ui

    • Permission: onecx-permission-svc, onecx-permission-bff, onecx-permission-ui

    • Product Store: onecx-product-store-svc, onecx-product-store-bff, onecx-product-store-ui

    • User Profile: onecx-user-profile-svc, onecx-user-profile-bff, onecx-user-profile-ui

    • IAM: onecx-iam-kc-svc, onecx-iam-bff, onecx-iam-ui

    • Tenant: onecx-tenant-svc, onecx-tenant-bff, onecx-tenant-ui

    • Welcome: onecx-welcome-svc, onecx-welcome-bff, onecx-welcome-ui

    • Help: onecx-help-svc, onecx-help-bff, onecx-help-ui

    • Parameter: onecx-parameter-svc, onecx-parameter-bff, onecx-parameter-ui

Profiles

OneCX Local Environment v1 contains a few profiles that can be used to start additional services on top of the default set of services:

  • parameter — starts the OneCX Parameter product services

  • all — starts all services defined in the compose file

For details on how to use profiles, please refer to the [running-onecx-local-env-v1] section of this document.

Environment variables

All services are based on images defined in the .env file in the versions/v1 directory. Services might also reference additional environment variables from the .env, common.env, svc.env and bff.env files in the versions/v1 directory.

The .env file is always loaded automatically, while other env files are referenced by some services via the env_file directive.

Some services also define additional environment variables directly in the compose file.

Networks

  • example — primary network used by OneCX Local Environment v1. All services connect via this network.

Volumes

OneCX Local Environment v1 mounts one global volume:

  • postgres — volume used by postgresdb to persist its data across container restarts.

Additionally, some services (traefik, postgresdb, pgadmin and keycloak-app) mount local directories for initialization data.