---
description: >-
  Step-by-step guide on setting up your self-hosted control plane using the
  Control Plane Lite utility.
---

# Control Plane Setup

RudderStack's control plane manages the configuration of your sources and destinations.

For more information on the control plane, refer to RudderStack's [Architecture](https://rudderstack.com/docs/get-started/rudderstack-architecture/#control-plane).

The easiest way to manage these configurations is through RudderStack's [self-hosted control plane](https://app.rudderstack.com/). It is free, requires no setup, and has some useful features like [Live Events](https://www.rudderstack.com/docs/rudderstack-cloud/live-events/) and [Transformations](https://rudderstack.com/docs/transformations/).

If you don't wish to sign up for RudderStack and want to self-host these configurations instead, you can use the open-source **Control Plane Lite** utility to set up your own control plane. You can then manage the source and destination configurations locally by exporting or importing from a JSON file.

The control plane set up using Control Plane Lite does not support Live Events and Transformations.

## Setting up the control plane

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

Make sure you have [Node.js](https://nodejs.org/en/download/) installed before setting up your self-hosted control plane.

1. Clone the [RudderStack Control Plane Lite](https://github.com/rudderlabs/config-generator) repository.
2. Open your terminal and navigate to the **Config Generator** folder. Then, run the following commands:

```bash
  npm install
  npm start
```

1. Upon successful setup, you can access the dashboard at `http://localhost:3000` by default.

![Control Plane Lite dashboard](https://876606571-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-Lq5Ea6fHVg3dSxMCgyQ%2Fuploads%2Fgit-blob-64ba917e5d8d3d18c6bd6ceed0567babb99bbe69%2Fcontrol-plane-lite-dashboard.png?alt=media)

## Exporting workspace configuration

After adding the required sources and destinations in the dashboard, you can export your workspace configuration by clicking on 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 for your preferred RudderStack setup.

### Docker

1. Download and open [`rudder-docker.yml`](https://raw.githubusercontent.com/rudderlabs/rudder-server/master/rudder-docker.yml).
2. In the `environment` section under `backend` service, uncomment the following lines:

```yaml
  - RSERVER_BACKEND_CONFIG_CONFIG_FROM_FILE=true
  - 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:

```yaml
  - <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](https://876606571-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-Lq5Ea6fHVg3dSxMCgyQ%2Fuploads%2Fgit-blob-7c02ae14d709525446ad343984177dca76ecb16e%2Frudder-docker-yml-file.png?alt=media)

1. Finally, navigate to the directory where you want to install RudderStack and run the following command:

```bash
  docker-compose -f rudder-docker.yml up
```

Once you have completed these steps above successfully, [send test events](https://rudderstack.com/docs/rudderstack-open-source/installing-and-setting-up-rudderstack/sending-test-events) to verify your installation.

### Kubernetes

1. Clone the [repository](https://github.com/rudderlabs/rudderstack-helm) containing the RudderStack Helm chart by running the following command:

```bash
git clone git@github.com:rudderlabs/rudderstack-helm.git
```

1. Navigate to the folder containing the Helm chart, as shown:

```bash
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](#exporting-workspace-configuration) section above. Place the exported file in the `rudderstack-helm` folder.
4. Finally, run the following command:

```bash
helm install my-release ./ --set backend.controlPlaneJSON=true
```

Refer to the [Configurable parameters](https://rudderstack.com/docs/rudderstack-open-source/installing-and-setting-up-rudderstack/kubernetes/#configuration) section for information on the parameters that can be configured during deployment.

Once you have completed these steps above successfully, [send test events](https://rudderstack.com/docs/rudderstack-open-source/installing-and-setting-up-rudderstack/sending-test-events) to verify your installation.

### Developer machine setup

1. First, set up the database in your preferred directory using the following commands:

```bash
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](https://github.com/rudderlabs/rudder-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:

```bash
cd rudder-transformer
```

1. Install the dependencies using the command `npm i` . Then, start the destination transformer using the following command:

```bash
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, as shown:

```bash
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), as shown:

![RudderStack config JSON path](https://876606571-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-Lq5Ea6fHVg3dSxMCgyQ%2Fuploads%2Fgit-blob-d24d67c291ba2cb7b27579e722a979d5fd38adba%2Frudder-config-1.png?alt=media)

1. Finally, run the RudderStack server using the following command:

```bash
go run main.go
```

Once you have completed these steps above successfully, [send test events](https://rudderstack.com/docs/rudderstack-open-source/installing-and-setting-up-rudderstack/sending-test-events) to verify the installation.

## Using hosted control plane for device mode destinations

RudderStack's web and mobile SDKs expect the source configurations and the associated device mode destination configurations for initialization. If you are self-hosting the control plane, you will need to host these configurations on your own server such that the source configuration is available at `<CONTROL_PLANE_URL>/sourceConfig`.

To know more about the difference between cloud mode and device mode in RudderStack, read the [RudderStack Connection Modes](https://rudderstack.com/docs/rudderstack-cloud/rudderstack-connection-modes/) guide.

For RudderStack Cloud, the SDKs fetch this source configuration from `https://api.rudderlabs.com/sourceConfig`.

### Control plane URL

Since the RudderStack SDKs need the source configuration and the backend/SDKs are not aware of it by default, you must serve the configuration on your web servers and point the SDKs to the same. This configuration must be available at `<CONTROL_PLANE_URL>/sourceConfig`. To do so, follow these steps:

1. Set up your 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, as shown:

![Export source config option](https://876606571-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-Lq5Ea6fHVg3dSxMCgyQ%2Fuploads%2Fgit-blob-4864af4817036bb499b07417e5591e52432709e9%2Fexport-source-config.png?alt=media)

1. Host the exported file on your own server at `/sourceConfig`. Provide the base URL of your server that is serving this file in the SDK initialization code snippet. For more information, refer to the following sections in the respective SDK guides:

* [JavaScript SDK instructions](https://github.com/rudderlabs/rudder-sdk-js#self-hosted-control-plane)
* [Android SDK instructions](https://rudderstack.com/docs/stream-sources/rudderstack-sdk-integration-guides/rudderstack-android-sdk/#configuring-your-rudderstack-client)
* [iOS SDK instructions](https://rudderstack.com/docs/stream-sources/rudderstack-sdk-integration-guides/rudderstack-ios-sdk/#configuring-the-rudderstack-client)
* [React Native SDK instructions](https://www.rudderstack.com/docs/stream-sources/rudderstack-sdk-integration-guides/rudderstack-react-native-sdk/#configuring-your-rudderstack-client)
* [Flutter SDK instructions](https://rudderstack.com/docs/stream-sources/rudderstack-sdk-integration-guides/rudderstack-flutter-sdk/#configuring-your-rudderstack-client)

The RudderStack SDKs fetch the configuration by appending the `/sourceConfig` path to the base URL provided above.

The SDKs will then fetch the config from `<CONTROL_PLANE_URL>/sourceConfig`. A sample exported source configuration is shown below:

```json
{
  "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"
    },
    "destinations": [
      {
        "id": "1im927dBatOkbj1oPCV5JntGMj7",
        "name": "test-HJ",
        "enabled": true,
        "config": {
          "siteID": "dd41289"
        },
        "destinationDefinition": {
          "config": {
            "destConfig": {
              "web": [
                "useNativeSDK"
              ],
              "defaultConfig": [
                "siteID"
              ]
            },
            "secretKeys": [],
            "excludeKeys": [],
            "includeKeys": [
              "siteID"
            ],
            "supportedSourceTypes": [
              "web"
            ]
          },
          "id": "1SxbQXdfQ2NzIdqNO3GceshF4V0",
          "name": "HOTJAR",
          "displayName": "Hotjar",
          "createdAt": "2019-10-31T07:49:37.450Z",
          "updatedAt": "2020-09-05T10:02:39.744Z"
        }
      }
    ]
  },
  "metadata": {
    "version": "1.0.2"
  }
}
```

## FAQs

### For a self-hosted environment, how do I obtain the control plane URL?

To use the control plane URL to initialize your SDKs, follow these steps:

1. [Set up](#setting-up-the-control-plane) the control plane using the Control Plane Lite utility.
2. Go to dashboard, configure the source, and export the source configuration by clicking the **EXPORT SOURCE CONFIG** button as shown:

![Export source config option](https://876606571-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-Lq5Ea6fHVg3dSxMCgyQ%2Fuploads%2Fgit-blob-4864af4817036bb499b07417e5591e52432709e9%2Fexport-source-config.png?alt=media)

1. Host the exported file on your own server such that the configuration is available at `<CONTROL_PLANE_URL>/sourceConfig`.

This solution assumes that you have already set up the RudderStack data plane (backend) locally.

## Contact us

If you across any issues while setting up your self-hosted control plane using the Control Plane Lite utility, [contact us](mailto:%20docs@rudderstack.com) or start a conversation in our [Slack](https://rudderstack.com/join-rudderstack-slack-community) community.
