Skip to main content
Version: 5.1

Install ICP

The Integration Control Plane (ICP) is a self-hosted management server that connects to your WSO2 Integrator runtimes and provides centralized monitoring, lifecycle management, and access control. This page walks you through downloading, configuring, and starting ICP on your own infrastructure.

tip

This guide covers manual installation. For evaluation, run via WSO2 Integrator Integration Control Plane (ICP).

Prerequisites
  • Java 25
  • A supported OS: Linux, macOS, or Windows
  • For production deployments: a supported database (PostgreSQL, MySQL, MSSQL, or Oracle Database 19c or later). The default embedded H2 database is suitable for evaluation and development only.

Install​

  1. Download the ICP distribution from the WSO2 Integrator downloads page.

  2. Extract the zip and navigate into the directory.

    unzip wso2-integration-control-plane-<version>.zip
    cd wso2-integration-control-plane-<version>

Configure​

All configuration lives in conf/deployment.toml. The defaults work out of the box for local evaluation.

Essential settings​

The table below covers the settings most commonly changed. All other settings are documented inline in deployment.toml.

SettingDefaultDescription
serverPort9446HTTPS port for the ICP console and API
serverHost0.0.0.0IP address ICP binds to. Restrict to a specific interface in production.
logLevelINFOLog verbosity: DEBUG, INFO, WARN, or ERROR
schedulerIntervalSeconds60How often ICP checks for inactive runtimes and marks them as offline, in seconds.
frontendJwtHMACSecret(default key)JWT signing secret for user sessions. Change this before going to production.

Full reference: Server Configuration.

Database​

ICP uses two embedded H2 databases by default, stored in bin/database/:

  • icp_db.mv.db — runtime data (artifacts, environments, projects)
  • credentials_db.mv.db — user credentials

No configuration is needed for local evaluation or development.

For production, switch to PostgreSQL, MySQL, MSSQL, or Oracle using the steps below.

Step 1: Initialize the schema

The dbscripts/ directory contains init scripts for each supported database. Run the main schema script that matches dbType, and the credentials schema script that matches credentialsDbType. The two databases are independent, so these can be different engines:

DatabaseMain schemaCredentials schema
PostgreSQLpostgresql_init.sqlcredentials_postgresql_init.sql
MySQLmysql_init.sqlcredentials_mysql_init.sql
MSSQLmssql_init.sqlcredentials_mssql_init.sql
Oracleoracle_init.sqlcredentials_oracle_init.sql
note

Run the Oracle scripts with SQL*Plus or SQLcl. They contain PL/SQL blocks terminated by a / on its own line, which not every SQL client executes correctly.

For Oracle, create the schema user before you run the scripts. oracle_init.sql does not create a user, a schema, or a tablespace. It creates its objects in the schema of the user you connect as, so that user needs:

  • CREATE SESSION, and a quota on its default tablespace
  • CREATE TABLE, CREATE VIEW, and CREATE TRIGGER
  • CREATE SEQUENCE, because primary keys use GENERATED BY DEFAULT ON NULL AS IDENTITY

Indexes on the user's own tables need no separate privilege, and CREATE TRIGGER covers the AFTER LOGON ON SCHEMA trigger that the script installs.

The logon trigger pins NLS_TIMESTAMP_FORMAT and NLS_DATE_FORMAT for every session in the schema, which keeps string-to-timestamp conversions deterministic. Connect as this user, not as SYS or SYSTEM, so the objects land in the right schema.

Migrating existing data from MySQL

Oracle applies a UNIQUE constraint to rows whose key columns are only partially null. MySQL treats any null key column as distinct. The unique_group_role_context constraint on group_role_mapping spans four nullable columns, so role assignments that coexist on MySQL can collide on Oracle. Remove the duplicates before you import existing data.

Step 2: Configure the main database

Uncomment and edit the [icp_server.storage] section in deployment.toml:

[icp_server.storage]
dbType                = "postgresql"
dbHost                = "localhost"
dbPort                = 5432
dbName                = "icp_database"
dbUser                = "icp_user"
dbPassword            = "changeme"
maxOpenConnections    = 10
minIdleConnections    = 5
maxConnectionLifeTime = 1800.0

Step 3: Configure the credentials database

The credentials database is configured separately at the top level of deployment.toml, before any [section] header:

credentialsDbType     = "postgresql"
credentialsDbHost     = "localhost"
credentialsDbPort     = 5432
credentialsDbName     = "credentials_db"
credentialsDbUser     = "icp_user"
credentialsDbPassword = "changeme"

Set credentialsDbType to h2, postgresql, mysql, mssql, or oracle. The credentials database is independent of the main database, so the two can use different engines. For Oracle, set credentialsDbName to the service name and add credentialsDbUseTLS = true when the endpoint uses TCPS.

Full reference: Database Configuration.

Start​

./bin/icp.sh

The server logs its startup to the console. Once you see the listener ready message, ICP is available at https://localhost:9446.

info

ICP ships with a self-signed certificate. Your browser will show a security warning on first visit. Accept the warning to proceed.

Sign in​

Once ICP is running, open https://<host>:9446/login in your browser and sign in with the default credentials:

  • Username: admin
  • Password: admin

Click Sign In. The browser redirects to the organization home at https://<host>:9446/organizations/default.

warning

Change the default admin password before using ICP in any non-evaluation environment. Go to Access control > Users, select the admin user, and click Reset Password. See Access Control for details.

For LDAP, SSO, or OIDC authentication, see Authentication Configuration.

What's next​

Last updated on
On this page
Was this page helpful?
Report an issue