Control plane setup

Self-host your control plane using Control Plane Lite.

RudderStack’s control plane provides a UI that lets you manage your source and destination configurations.

The easiest way to manage your configurations is through the RudderStack-hosted control plane, that is, RudderStack Cloud. RudderStack Cloud does not require development to set up, and offers additional features such as Live Events and Transformations.

To self-host your source-destination configurations, you can use the open source Control Plane Lite utility to set up your own control plane. Control Plane Lite lets you manage your data pipelines locally by exporting or importing your configurations from a JSON file.

Control Plane Lite is no longer actively maintained by RudderStack. We encourage contributions from the open source community but note some RudderStack Cloud features may not be available in your self-hosted control plane, and that we do not plan to support new functionality.

Setting up the control plane

Before setting up your self-hosted control plane, make sure you have installed Node.js.

Use Node.js v14 for the best experience as the higher versions are not supported.

To set up your self-hosted control plane using Control Plane Lite, follow these steps:

  1. Clone the RudderStack Control Plane Lite repository.
  2. Open your terminal and navigate to the Config Generator folder. Then, run the following commands:
npm install
npm start
  1. After the setup is complete, you can access the dashboard at http://localhost:3000 by default.
Control Plane Lite dashboard

Exporting workspace configuration

After adding the required sources and destinations in the dashboard, you can export your workspace configuration by clicking the EXPORT button. The configuration is then exported and saved as a JSON file. This file is required to start the RudderStack server.

Starting RudderStack server with the workspace configuration file

For RudderStack to pick up the exported workspace configuration file, follow the steps in the below sections depending on your setup method.


  1. Download and open rudder-docker.yml.
  2. In the environment section under backend service, uncomment the following lines:
  - RSERVER_BACKEND_CONFIG_CONFIG_JSONPATH=<workspace_config_filepath_in_container>
  1. Then, replace <workspace_config_filepath_in_container> in the above line with your container file path. By default, you can set it to /etc/rudderstack/workspaceConfig.json.
  2. In the volumes section under the backend service, uncomment the following line:
  - <absolute_path_to_workspace_config>:<workspace_config_filepath_in_container>
  1. Next, replace <absolute_path_to_workspace_config> with the local path of your workspaceConfig.json(where your workspace configuration file is saved locally). Also, replace <workspace_config_filepath_in_container> with the container file path that you set in Step 3.
The value for <workspace_config_filepath_in_container> should be the same as the value provided for the RSERVER_BACKEND_CONFIG_CONFIG_JSONPATH variable. Otherwise, your workspace configuration will not be loaded and you will get an error.
  1. At this stage, your rudder-docker.yml should look like the following:
Rudder Docker YML file
  1. Finally, navigate to the directory where you want to install RudderStack and run the following command:
docker-compose -f rudder-docker.yml up

Once you have completed these steps above successfully, send test events to verify your installation.


  1. Clone the repository containing the RudderStack Helm chart by running the following command:
git clone
  1. Navigate to the folder containing the Helm chart:
cd rudderstack-helm/
  1. Open the values.yaml file.
  2. Set the parameter controlPlaneJSON to true.
  3. Export the workspace configuration from the dashboard by following the steps in the Exporting workspace configuration section above. Place the exported file in the rudderstack-helm folder.
  4. Finally, run the following command:
helm install my-release ./ --set backend.controlPlaneJSON=true
Refer to the Configurable parameters section for information on the parameters that can be configured during deployment.

Once you have completed these steps above successfully, send test events to verify your installation.

Developer machine setup

  1. First, set up the database in your preferred directory using the following commands:
createdb jobsdb
createuser --superuser rudder
psql "jobsdb" -c "alter user rudder with encrypted password 'rudder'";
psql "jobsdb" -c "grant all privileges on database jobsdb to rudder";
  1. Next, clone the RudderStack server repository.
  2. Then, run git submodule init and git submodule update to fetch the rudder-transformer repository.
  3. Next, navigate to the rudder-transformer directory:
cd rudder-transformer
  1. Install the dependencies using the command npm i . Then, start the destination transformer using the following command:
node destTransformer.js
  1. Navigate back to the main directory using the command cd rudder-server.
  2. Next, copy the sample.env to the main directory:
cp config/sample.env .env
  1. Then, go to the config folder and open config.yaml.
  2. Under [BackendConfig], look for configFromFile and set it to true.
  3. Also, change the value of configJSONPath to the local path of your workspaceConfig.json(where your workspace configuration file is saved locally):
RudderStack config JSON path
  1. Finally, run the RudderStack server using the following command:
go run main.go

Once you have completed these steps above successfully, send test events to verify the installation.

Using SDK sources set up in self-hosted control plane

To use the RudderStack SDKs set up as sources in the self-hosted control plane, follow these steps:

  1. Set up the control plane using the Control Plane Lite utility.
  2. Go to the dashboard, set up your source, and export the source configuration by clicking the EXPORT SOURCE CONFIG button:
Export source config option
  1. Host the exported file on your server such that it can be accessed via the path <CONTROL_PLANE_URL>/sourceConfig.
  2. Provide the base URL of your server (<CONTROL_PLANE_URL>) serving this file in your SDK initialization code snippet. For more information on SDK initialization, refer to the following sections in the respective SDK guides:
The RudderStack SDKs automatically fetch the configuration by appending /sourceConfig to the base server URL provided above. For example, {CONTROL_PLANE_URL}/sourceConfig.

A sample source configuration exported from the dashboard is shown below:

  "source": {
    "config": {},
    "id": "1im8yfXQsocRBGcQLXAaq5M8dYV",
    "name": "test-JS",
    "writeKey": "1im8yk2sz8oyHVCGVqViSNfKVDF",
    "enabled": true,
    "sourceDefinitionId": "1TW48i2bIzEl1HPf825cEznfIM8",
    "deleted": false,
    "createdAt": "Mon Oct 12 2020 16:51:54 GMT+0530 (India Standard Time)",
    "updatedAt": "Mon Oct 12 2020 16:51:54 GMT+0530 (India Standard Time)",
    "sourceDefinition": {
      "id": "1TW48i2bIzEl1HPf825cEznfIM8",
      "name": "JavaScript",
      "displayName": "JavaScript",
      "category": null,
      "createdAt": "2019-11-12T12:39:19.885Z",
      "updatedAt": "2020-06-18T11:54:06.114Z"
  "metadata": {
    "version": "1.0.2"

Questions? Contact us by email or on Slack