OneCX Local Environment - Versions - v2 - Migrate to v2

This guide highlights the key differences between OneCX Local Environment v1 and v2, and explains how you can adapt your setup to ensure that it seamlessly works with v2.

Network Rename

In v1, the network that all services connected to was named example. In v2, this network is now named default.

If you have any custom services that need to attach to the same network as OneCX, make sure they connect to default from now on.

Service Startup Behavior

In v1:

  • Some core services started automatically when running: docker compose up -d

  • Additional services could be started using the two existing profiles: all and parameters.

  • This approach gave developers very little control over which apps were started, making it hard to, for example, run only a small subset of apps and one OneCX product.

In v2:

  • The system is fully profile-based.

  • Nothing starts by default when you run: docker compose up -d

  • You must explicitly specify at least one profile, for example:

docker compose --profile base up -d

  • Profiles allow fine-grained control over which services run.

  • For details on available profiles, see the v2 documentation.

Data Import Script Improvements

In v1:

  • The data import script had the sole purpose of sending data to services to trigger the import.

  • This caused issues if containers were not running, unhealthy, or still starting up.

In v2:

  • The import script now:

    • Starts all required services.

    • Waits for them to become healthy and operational.

    • Imports the data.

    • Spins down the started services afterward.

This improves reliability for most developers. However, if you use the script inside another script that needs containers to remain running after import, you can disable container management by running the script using:

SKIP_CONTAINER_MANAGEMENT=true ./import-onecx.sh

This ensures the script does not start or stop any containers, allowing you to manage them manually. Please be aware that in this mode, it’s your responsibility to ensure that all required containers (Traefik, Postgres, Keycloak and all OneCX SVCs) are running and healthy before executing the script.

Moved ENV Files

Before the creation of v2, all environment variable files were located in the root directory of the project. To allow for better organization and scoped environment variables per version, all environment variable files are now located in the directory of the version they belong to (e.g., ./versions/v2/ for v2). As of right now, ./versions/v1/ and ./versions/v2/ contain identical .env, bff.env and svc.env files, but this may change in the future (e.g. if different image tags have to be used for different versions). If you or any of your scripts reference these files, please update the paths accordingly.

Checkpoint

After reading all sections of this document you should be able to make all necessary adjustments to migrate from v1 to v2 of the OneCX Local Environment. To recap, the main necessary adjustments are:

  • Change any custom services that connect to the example network to connect to the default network instead.

  • Change any scripts or commands that start services to use profiles instead of relying on default behavior.

  • Adjust import scripts if you need to manage container states manually.

  • Update paths to any .env, bff.env or svc.env files to point to the new locations in the respective version directory.