> For the complete documentation index, see [llms.txt](https://docs.bluerock.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.bluerock.io/bluerock-dashboard/installation-and-setup.md).

# Installation and Setup

## Overview

This guide describes how to set up the BlueRock Dashboard, configure the required SSL certificate and network access, connect an existing BlueRock Host, and verify that telemetry is reaching the Dashboard.

### Prerequisites

Before beginning the installation, ensure that you have:

* An Ubuntu Linux VM for the BlueRock Dashboard.
* A BlueRock Host that is already deployed and running.

  <div data-gb-custom-block data-tag="hint" data-style="info" data-icon="notes" class="hint hint-info"><p><strong>Note:</strong> </p><p>The BlueRock Host must already be deployed and running. For instructions on deploying the BlueRock Host, see the <a href="/deployment-guides/aws-deployments.md">BlueRock Host deployment guide</a>.</p></div>
* SSH access to the required VMs.
* Access to the BlueRock container registry and the Dashboard container image for the required release.
* Permission to configure the required network access rules.
* A hostname or IP address for the Dashboard.
* An SSL certificate for the Dashboard, or the information required to create one.

***

### 1. Prepare the BlueRock Dashboard VM

The BlueRock Dashboard runs on a generic Ubuntu Linux VM provided by the selected cloud platform.

Provision the BlueRock Dashboard VM using the AWS CLI and an Ubuntu Linux image.

Use the following command to create the VM:

{% tabs %}
{% tab title="AWS" %}
Provision the BlueRock Dashboard VM using the AWS CLI and an Ubuntu Linux image.

Use the following command to create the VM:

{% code title="" overflow="wrap" expandable="true" %}

```bash
aws ec2 run-instances \
  --region <AWS_REGION> \
  --image-id <UBUNTU_24_04_AMI_ID> \
  --instance-type t3.2xlarge \
  --key-name <EC2_KEY_PAIR_NAME> \
  --subnet-id <SUBNET_ID> \
  --security-group-ids <SECURITY_GROUP_ID> \
  --block-device-mappings \
    'DeviceName=/dev/sda1,Ebs={VolumeSize=100,VolumeType=gp3,DeleteOnTermination=true}' \
  --metadata-options \
    'HttpTokens=required,HttpEndpoint=enabled' \
  --tag-specifications \
    'ResourceType=instance,Tags=[{Key=Name,Value=bluerock-dashboard}]' \
  --count 1
```

{% endcode %}

Ensure that SSH access on port `22` is allowed for connection from the administrator desktop so that the administrator can SSH to the VM.
{% endtab %}

{% tab title="Azure" %}
Provision the BlueRock Dashboard VM using the Azure CLI and an Ubuntu Linux image.

Use the following command to create the VM:

{% code title="" overflow="wrap" expandable="true" %}

```bash
az vm create \
  --resource-group <RESOURCE_GROUP> \
  --name <INSTANCE_NAME> \
  --image "Canonical:ubuntu-24_04-lts:server:latest" \
  --admin-username <ADMIN_USERNAME> \
  --ssh-key-values <SSH_PUBLIC_KEY_PATH> \
  --size <INSTANCE_TYPE> \
  --os-disk-size-gb <STORAGE_SIZE_GB> 
```

{% endcode %}

Ensure that SSH access on port `22` is allowed from the approved administrator IP addresses so that you can connect to the VM.
{% endtab %}

{% tab title="GCP" %}
Provision the BlueRock Dashboard VM using the GCP CLI and an Ubuntu Linux image.

Use the following command to create the VM:

{% code title="" overflow="wrap" expandable="true" %}

```bash
gcloud compute instances create <VM_NAME> \
  --zone <ZONE> \
  --machine-type n2-standard-2 \
  --image-family ubuntu-2404-lts-amd64 \
  --image-project ubuntu-os-cloud \
  --boot-disk-size 40GB \
  --boot-disk-type pd-standard \
  --tags <NETWORK_TAG> \
  --scopes=https://www.googleapis.com/auth/cloud-platform \
  --metadata=ssh-keys="<SSH_USERNAME>:$(cat ~/.ssh/id_rsa.pub)"
```

{% endcode %}

Ensure that SSH access on port `22` is allowed from the approved administrator IP addresses so that you can connect to the VM.
{% endtab %}
{% endtabs %}

***

### 2. Connect to the Dashboard VM

Connect to the Dashboard VM using SSH.

{% tabs %}
{% tab title="AWS" %}
{% code title="" overflow="wrap" expandable="true" %}

```bash
ssh -i <PRIVATE_KEY> <ADMIN_USERNAME>@<DASHBOARD_VM_IP>
```

{% endcode %}
{% endtab %}

{% tab title="Azure" %}
{% code title="" overflow="wrap" expandable="true" %}

```bash
ssh <ADMIN_USERNAME>@<DASHBOARD_HOSTNAME>
```

{% endcode %}
{% endtab %}

{% tab title="GCP" %}
{% code title="" overflow="wrap" expandable="true" %}

```bash
gcloud compute ssh <DASHBOARD_VM_NAME> \  --zone=<GCP_ZONE>
```

{% endcode %}
{% endtab %}
{% endtabs %}

***

### 3. Install Docker

The BlueRock Dashboard runs inside a Docker container.

Install Docker on the Dashboard VM:

{% code overflow="wrap" expandable="true" %}

```bash
curl -fsSL https://get.docker.com | sudo sh
```

{% endcode %}

Add the current user to the Docker group:

{% code overflow="wrap" expandable="true" %}

```bash
sudo usermod -aG docker $USER
```

{% endcode %}

Apply the group change:

{% code overflow="wrap" expandable="true" %}

```
newgrp docker
```

{% endcode %}

Verify the Docker installation:

{% code overflow="wrap" expandable="true" %}

```bash
docker --version
```

{% endcode %}

***

### 4. Authenticate to the Container Registry and Pull the Dashboard Image

The BlueRock Dashboard container image is hosted in a private container registry.

{% hint style="danger" %}
**Important:** To access the BlueRock container images, get in touch with BlueRock Support.
{% endhint %}

Authenticate to the private container registry using the credentials or authentication method provided by BlueRock Support.

After authentication, pull the Dashboard image for the required release:

{% code overflow="wrap" expandable="true" %}

```bash
docker pull <IMAGE_URL>:<RELEASE_TAG>
```

{% endcode %}

Verify that the image is available:

{% code overflow="wrap" expandable="true" %}

```bash
docker images
```

{% endcode %}

***

### 5. Configure SSL Certificate

BlueRock Dashboard uses HTTPS to secure communication between the Dashboard and BlueRock Hosts.

You can use either:

* A self-signed SSL certificate for internal testing
* An SSL certificate issued by a trusted Certificate Authority (CA) for production deployments

#### Self-signed SSL Certificate

Use a self-signed SSL certificate for internal testing only.

{% hint style="info" icon="notes" %}
**Note:**&#x20;

Self-signed SSL certificates are intended for internal testing only and are not recommended for production deployments.
{% endhint %}

Create a directory for the certificate:

{% code overflow="wrap" expandable="true" %}

```bash
mkdir -p ~/bluerock/certs
```

{% endcode %}

Generate the self-signed certificate:

```bash
openssl req -x509 -newkey rsa:2048 -sha256 -days 360 -nodes \
  -keyout ~/bluerock/certs/server.key \
  -out ~/bluerock/certs/server.crt \
  -subj "/CN=brdashboard/0=example org" \
  -addext "subjectAltName=DNS:localhost,IP:127.0.0.1,<IP_OR_DNS_ENTRY>"
```

Replace `<IP_OR_DNS_ENTRY>` with the IP address or hostname used to access the BlueRock Dashboard. Prefix an IP address with `IP:` and a hostname with `DNS:`.

**Example — IP address**

If you access the Dashboard using an IP address, replace the placeholder with `IP:` followed by the address.

```bash
-addext "subjectAltName=DNS:localhost,IP:127.0.0.1,IP:192.0.2.10"
```

**Example — Hostname**

If you access the Dashboard using a hostname, replace the placeholder with `DNS:` followed by the hostname.

{% code overflow="wrap" expandable="true" %}

```bash
-addext "subjectAltName=DNS:localhost,IP:127.0.0.1,DNS:dashboard.example.com"
```

{% endcode %}

Set the appropriate permissions on the private key:

{% code overflow="wrap" expandable="true" %}

```bash
chmod 600 ~/bluerock/certs/server.key
```

{% endcode %}

Verify the generated certificate:

{% code overflow="wrap" expandable="true" %}

```bash
openssl x509 -in ~/bluerock/certs/server.crt \
  -noout -subject -issuer -dates
```

{% endcode %}

The certificate and private key are mounted when the Dashboard container is started.

Because the certificate is self-signed, the BlueRock Host must add the server certificate to the ca-certificates trust store to ensure successful HTTPS connection with the Dashboard.

Copy `server.crt` to the BlueRock Host:

```bash
sudo cp server.crt /usr/local/share/ca-certificates/
```

Update the certificate trust store:

```bash
sudo update-ca-certificates
```

#### Trusted SSL Certificate

For production deployments, use an SSL certificate issued by a trusted Certificate Authority (CA).

You can obtain a certificate from any trusted CA. Let's Encrypt is one example of a CA that provides publicly trusted certificates.

Obtain a publicly trusted certificate for the hostname used to access the BlueRock Dashboard.

Store the certificate and private key on the Dashboard VM as:

```
~/bluerock/certs/server.crt
~/bluerock/certs/server.key
```

Where:

* `server.crt` is the SSL certificate.
* `server.key` is the corresponding private key.

Verify the certificate:

```bash
openssl x509 -in ~/bluerock/certs/server.crt \  
-noout -subject -issuer -dates
```

The certificate and private key are mounted when the Dashboard container is started.

If the certificate is issued by a trusted CA, the BlueRock Host does not require additional certificate configuration, provided that the CA is already trusted by the host.

If the certificate uses an intermediate CA, install the required certificate chain on the BlueRock Host.

{% hint style="info" %}
**Note:** Ensure that the certificate matches the hostname used to access the BlueRock Dashboard.
{% endhint %}

***

### 6. Start the BlueRock Dashboard

Create the persistent data directory:

{% code title="" overflow="wrap" expandable="true" %}

```bash
mkdir -p ~/bluerock/data
```

{% endcode %}

Start the Dashboard container:

{% code title="" overflow="wrap" expandable="true" %}

```bash
docker run -d \
  --name bluerockccpd \
  --restart=unless-stopped \
  -p 0.0.0.0:443:443 \
  -p 0.0.0.0:4318:4318 \
  -p 0.0.0.0:8443:8443 \
  -v ~/bluerock/data:/data \
  -v ~/bluerock/certs:/certs:ro \
  -e BLUEROCK_DEV_NO_AUTH=true \
  -e AUTH_ENABLED=false \
  -e TELEMETRY_ENABLED=true \
  <IMAGE_URL>:<RELEASE_TAG>
```

{% endcode %}

***

### 7. Configure Network Access

After the Dashboard container is running, configure the required network access for the Dashboard VM.

The following application ports are exposed for inbound connection from external clients:

| Port   | Purpose             | Access                     |
| ------ | ------------------- | -------------------------- |
| `443`  | Dashboard HTTPS     | Authorized Dashboard users |
| `4318` | OTLP telemetry      | BlueRock Hosts             |
| `8443` | Policy distribution | BlueRock Hosts             |

Configure the corresponding firewall, security group, or network security group rules according to your cloud platform.

Allow access only from the trusted client source address and subnets.

{% hint style="danger" %}
**Security:** Restrict ports `4318` and `8443` to trusted BlueRock Host networks or CIDR ranges.
{% endhint %}

{% hint style="info" %}
**Note:** SSH access on port `22` is required for VM administration and should already be allowed from the approved administrator IP addresses.
{% endhint %}

***

### 8. Verify the Dashboard

Verify that the Dashboard container is running:

```bash
docker ps
```

Check the Dashboard container logs:

```bash
docker logs bluerockccpd --tail 20
```

The container should be running without errors.

Open the Dashboard using the HTTPS hostname or IP address configured for your deployment:

```bash
https://<DASHBOARD_HOSTNAME>
```

Verify that the Dashboard loads successfully.

***

### 9. Configure BlueRock Host Connectivity

The BlueRock Host must already be deployed and running.

Ensure that the BlueRock Host can reach the Dashboard on the following ports:

| Port   | Purpose             |
| ------ | ------------------- |
| `4318` | OTLP telemetry      |
| `8443` | Policy distribution |

Update the `bluerockd.toml` configuration on the BlueRock Host with the Dashboard endpoint provided for your deployment.

Configure the following Dashboard endpoints:

* **OTLP endpoint:** Used to send telemetry from the BlueRock Host to the Dashboard.
* **Policy endpoint:** Used to retrieve policies from the Dashboard.

Replace `<DASHBOARD_ENDPOINT>` with the Dashboard hostname or IP address configured for your deployment.

Replace `<POLICY_CHANNEL>` with the policy channel configured for your deployment.

Update `bluerockd.toml` as follows:

```bash
[runtime]
metrics_timer = 1800
state_dir = "/var/lib/bluerockd/"

[policy]
public_key = "https://<DASHBOARD_ENDPOINT>:8443/guardrail-trex-pub.pem"
poll_period = 100

[policy.source]
location = "https://<DASHBOARD_ENDPOINT>:8443/guardrail-policy/channels/dev/<POLICY_CHANNEL>"
policy = "policy.json"
policy_sig = "policy.json.sig"

[policy.engine]
augment_events = true

[otlp]
file = "/var/log/bluerockd/otel-events.log"

[otlp.http]
url = "https://<DASHBOARD_ENDPOINT>:4318/"
```

Save the configuration after updating the Dashboard endpoint and policy channel.

***

### 10. Restart the BlueRock Service

After updating `bluerockd.toml`, restart the `bluerockd` service:

```bash
sudo systemctl restart bluerockd
```

Verify that the service is running:

```bash
sudo systemctl status bluerockd --no-pager
```

***

### 11. Verify Telemetry

Verify that telemetry is being transferred from the BlueRock Host to the BlueRock Dashboard.

Check the `bluerockd` logs:

```bash
sudo journalctl -u bluerockd -f --no-pager
```

Verify that there are no certificate or connectivity errors.

Open the BlueRock Dashboard and navigate to **Graph Explorer** to verify that activity from the BlueRock Host is being received.

#### Troubleshoot Dashboard Connectivity

If telemetry is not reaching the Dashboard or a connectivity error occurs, use the following command to troubleshoot the OTLP endpoint from the BlueRock Host:

```bash
curl https://<DASHBOARD_ENDPOINT>:4318/v1/logs \
  -X POST \
  -H 'Content-Type: application/json' \
  -d '{"resourceLogs":[]}'
```

A successful response returns:

```
HTTP 200
```

If the request fails, check for certificate or connectivity errors.

For a self-signed certificate, verify that `server.crt` has been added to the BlueRock Host trust store and that the certificate trust store has been updated.

For a trusted certificate, if the certificate is issued by an intermediate CA, ensure the certificate chain is added to the BlueRock Host trust store.

<figure><img src="https://1983702018-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FCNnVnPvaRpvlLmPT6IAN%2Fuploads%2FDiN9opeNIENcCMQqdiFb%2Fhome%20policy.png?alt=media&amp;token=fec91522-c6d5-48aa-ae34-4e520ab5dd68" alt=""><figcaption></figcaption></figure>

***


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.bluerock.io/bluerock-dashboard/installation-and-setup.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.