Install and Set Up RudderStack

Detailed documentation on installing and setting up RudderStack from scratch on your platform of choice

This guide is aimed at helping you install and set up RudderStack correctly on a variety of platforms. Please feel free to contact us in case you are stuck anywhere in the process, or want more information on any of the topics covered below.

The easiest way to get started with RudderStack is to sign up for free on RudderStack Cloud Free.

You can also set up and use RudderStack on your platform of choice:

If you are planning to use RudderStack in production, we strongly recommend using the Kubernetes Helm charts. We update our Docker images with bug fixes more frequently than our GitHub repository (where we release once a month).

What is a Data Plane URL? Where do I get it?

For routing and processing the events to the RudderStack backend, a Data Plane URL is required. **Here's how to get the data plane URL:

  • If you're using the open-source version of RudderStack, you are required to set up your own data plane by installing and setting up RudderStack in your preferred dev environment.

  • If you're using the enterprise version of RudderStack, please contact us for the data plane URL with the email ID you used to sign up for RudderStack.

How to Check the Status of Your Data Plane

To check the status of your data plane, simply run the following command:


A sample command to check the data plane status is as shown:


The output is as follows:

{"server":"UP", "db":"UP","acceptingEvents":"TRUE","routingEvents":"TRUE","mode":"NORMAL","goroutines":"15364", "backendConfigMode": "API", "lastSync":"2020-12-01T04:20:33Z", "lastRegulationSync":"2020-11-30T21:40:27Z"}

The RudderStack server supports two running modes:

  • Normal ("mode": "NORMAL"): In this mode, the RudderStack server runs as expected, and there are no issues.

  • Degraded ("mode": "DEGRADED"): The RudderStack server enters the degraded mode if it keeps crashing while processing the events, after a threshold number of restarts is reached. In this mode, RudderStack still receives and stores the events but does not process them and route them to your specified destinations.

For more information on the RudderStack Server running modes, refer to our High Availability guide.

How to Send Test Events

Before sending test events to verify your RudderStack installation, you will first need to clone our Github repository using the following command:

git clone

Once you have installed and set up RudderStack on your target machine, please follow the steps below to test your RudderStack installation:

  • If you already have a Google Analytics account, keep the tracking ID handy. If not, please create one and get the tracking ID. The Google Analytics account needs to have a WebProperty (Web+App doesn't seem to work)

  • Create one source and a Google Analytics destination for the same with the above tracking ID.

Please follow our guide on How to Add a Source and Destination in RudderStack to add a source and destination in RudderStack.

  • We have bundled a shell script that can generate test events. Get the source writeKey from the RudderStack dashboard and then run the following command:

./scripts/generate-event <YOUR_WRITE_KEY>
Sending Test Events

The write key is different from your workspace token. The former is associated with the source, while the latter is for your RudderStack account.

Workspace token vs Write Key
  • You can then login to your Google Analytics account and verify that events are delivered. Go to MainPage -> RealTime -> Events. RealTime view is important as the other dashboards can sometimes take 24 to 48 hours to refresh.

  • You can use our JavaScript, Android, or iOS SDKs for sending events from your app.

Why do I need a RudderStack account?

A RudderStack account is not required, but our dashboard (control plane) is the easiest way to setup sources, destinations and transformations. RudderStack hosts the control plane free for Open Source users. You can also choose to use our open-source config-generator if you don't want to use the hosted control plane, but the config generator lacks certain features like Transformations and Live Debugger.

The hosted control plane is only used for configuration and does not have access to your data or data plane. The LiveDebugger can temporarily stream events from your data plane for debugging but only for a limited time, and it does not persist your data.

Contact Us

To know more about installing and setting up RudderStack, please feel free to contact us. You can also start a conversation on our Slack channel - we will be happy to talk to you.