OneCX Local Env - Versions - v2 - Migrate to v2

This guide highlights the key differences between OneCX Local Env 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.