OneCX Local Environment - Getting Started - Run OneCX locally

This document provides instructions on how to set up and run OneCX Local Environment for local development and testing purposes. It covers the prerequisites, setup steps, importing initial data, and spinning up the environment with different profiles.

Prerequisites

Supported Operating Systems

onecx-local-env fully supports Linux and Windows 10/11 via WSL2. While macOS is also supported, running OneCX images on Apple Silicon devices currently requires some additional workarounds.

Linux

No additional setup steps are required for now. Continue following the instructions in this document.

Windows

Verify that WSL2 is installed by running the following command in PowerShell or Command Prompt: wsl -l -v.

If you encounter an error, see no output, or your distributions are listed as version 1, follow the official Microsoft guide to install WSL2 or upgrade from WSL1 before proceeding: https://learn.microsoft.com/en-us/windows/wsl/install

macOS

You can continue with the instructions below, but pay close attention to the section [preparing-onecx-local-env-for-use-on-apple-silicon-devices], as additional steps are required to ensure proper functionality.

Checkpoint

By now, you should have confirmed your operating system compatibility. To recap:

  • Ensure you are on Linux, Windows 10/11 with WSL2, or macOS.

  • If on Windows, run wsl -l -v and confirm WSL2 is active.

  • If on macOS, note that additional steps will be required later for Apple Silicon.

Docker & Docker Compose

onecx-local-env requires both Docker and Docker Compose to be installed directly on your system or inside WSL2 for Windows users.

The functionality of onecx-local-env has been tested with the following versions:

  • Docker version 28.1.1

  • Docker Compose version v2.35.1

To ensure that all used features work correctly, please make sure to, at least, use Docker Compose version v2.20.0. If you are running into issues that aren’t obviously related to your onecx-local-env itself, please try to update Docker and Docker Compose to the latest versions.

Checkpoint

By now, you should have supported versions of Docker and Docker Compose installed. To verify:

  • Run docker --version and confirm it is returning some version information. As stated above, version 28.1.1 and above are known to work. Older versions may work but were not tested.

  • Run docker compose version and ensure it returns a version greater than or equal to v2.20.0.

  • If you are on Windows, ensure Docker is installed inside WSL2 and not just on Windows itself.

Select which version of OneCX Local Environment to use

onecx-local-env contains multiple versions inside the versions directory. Instructions for running services, importing initial data and other relevant information may differ between versions. It is therefore important to select a specific version of onecx-local-env before following the any other instructions in this document.

The current latest version of onecx-local-env is v2. We recommend this version for most users. Other versions, namely v1, still exist to avoid breaking existing workflows, but may not receive new features in the future. If you are unsure which version to use, please start with v2.

For more information on the versions please refer to the version-specific documentation:

Make all relevant scripts executable

After you selected a version of onecx-local-env, please ensure that all .sh scripts in the root directory of the repository, the imports directory and the versions/<selected-version> directory are executable with ls -l command.

  • e.g. -rwxr-xr-x import-onecx.sh

If any of the scripts are not executable, please run the following command for each non-executable script: chmod +x <file name>

Checkpoint

At this point, you should have ensured all relevant scripts are executable. To verify:

  • Run ls -l in the root, imports, and versions/<selected-version> directories.

  • Confirm all .sh scripts show -rwxr-xr-x or similar permissions.

  • If any scripts are missing execute permissions, run chmod +x <file name>.

Configure Hosts file

In order to expose multiple services on the same local port, OneCX Local Environment uses the traefik reverse proxy. Traefik will be available via your host’s port 80, and will route traffic to containers based on hostnames.

To ensure that these hostnames resolve to your local machine and requests reach the traefik proxy, you need to add a few OneCX-specific entries to your system’s hosts file.

Locate your hosts file

  • Windows: c:\Windows\System32\drivers\etc\hosts

  • Linux: /etc/hosts

  • macOS: /etc/hosts

Open the hosts file with administrator privileges

Editing the hosts file will require administrator privileges on most systems. Please open the file with a tool that has the necessary permissions (e.g. sudo nano /etc/hosts on Linux/macOS or Notepad as Administrator on Windows).

Add entries to hosts file

Once you located and opened your hosts file, please add the following entries to the end of the file:

127.0.0.1   local-proxy
127.0.0.1   keycloak-app
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-user-profile-bff
127.0.0.1   onecx-user-profile-svc
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-iam-kc-svc
127.0.0.1   onecx-iam-bff
127.0.0.1   onecx-tenant-svc
127.0.0.1   onecx-tenant-bff
127.0.0.1   onecx-parameter-svc
127.0.0.1   onecx-parameter-bff

If you are using Windows with WSL2, please restart WSL2 after modifying the hosts and check if the entries were automatically added to the WSL2 hosts file located at /etc/hosts. If not, please add the entries manually to the WSL2 hosts file as well.

Checkpoint

At this point, you should have added all necessary entries to your system hosts file. To verify:

  • Confirm the listed OneCX hostnames are added to your system hosts file.

  • If using Windows with WSL2, restart WSL2 and check /etc/hosts inside WSL2 to ensure entries were synced from Windows.

  • If entries are missing in WSL2, add them manually by following the "Linux" instructions above.

Preparing OneCX Local Environment for use on Apple Silicon devices

To be able to run OneCX Local Environment on Apple Silicon devices, the images specified in versions/<selected-version>/.env have to be adjusted slightly.

Please open the file and adjust each OneCX image to use the main tag instead of main-native. For example, change: ONECX_SHELL_BFF=${DOCKER_REPO}/onecx-shell-bff:main-native to ONECX_SHELL_BFF=${DOCKER_REPO}/onecx-shell-bff:main. This will ensure that Docker Compose uses OneCX’s JVM-based images which support the ARM architecture used by Apple Silicon devices.

Checkpoint

If you are on Apple Silicon, you should now have updated all OneCX image tags. To verify:

  • Open versions/<selected-version>/.env and confirm all OneCX images use the :main tag instead of :main-native.

Import Initial Data

Before using the selected version of onecx-local-env, initial data must be imported to set up the environment correctly. Please refer to the version-specific documentation for instructions on how to import the initial data:

The respective import scripts will import all data located in the ./imports directory. The structure of the imports directory is as follows:

  • tenant - import for the tenants

  • theme - import for the themes

  • permissions - import for permissions

  • workspace - import for workspaces

  • assignments - import of the assignments from role to permission

  • product-store - import for all of the product/application store objects:

    • products - import for products/applications

    • microfrontends - import for microfrontends

    • microservices - import for microservices

    • slots - import for slots

Checkpoint

At this point, you should have imported the initial data for your selected version of onecx-local-env. To verify:

  • Ensure that the logs of the import scripts indicate successful completion without errors.

  • Ensure that the expected data is present in the database (e.g., by accessing pgAdmin).

  • If you encounter issues, follow the troubleshooting steps in the version-specific documentation.

Running OneCX Local Environment

For instructions on how to run your selected version of onecx-local-env, please refer to the version-specific documentation:

After running all desired services as per the version-specific instructions, you can access the OneCX Shell via this URL: http://local-proxy/onecx-shell/admin. The default user created by the previously-executed import scripts is onecx with the password onecx.

If there are any issues while running services, please try to:

  • delete the volume or

  • clear the database and

  • start everything again from scratch

Checkpoint

At this point, certain services of OneCX Local Environment should be running on your machine. To verify:

  • Run docker ps and confirm that the expected containers are up and running.

  • Access the OneCX Shell at http://local-proxy/onecx-shell/admin and log in with the default credentials (onecx / onecx).

  • If any services are not running or you cannot access the OneCX Shell, refer to the troubleshooting steps linked in the version-specific documentation.