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.

  Note: The BlueRock Host must already be deployed and running. For instructions on deploying the BlueRock Host, see the BlueRock Host deployment guide.

• 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:

AWS

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

Use the following command to create the VM:

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

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

Azure

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

Use the following command to create the VM:

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 100

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

GCP

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

Use the following command to create the VM:

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 100GB \
  --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)"

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

---

2. Connect to the Dashboard VM

Connect to the Dashboard VM using SSH.

AWS

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

Azure

ssh <ADMIN_USERNAME>@<DASHBOARD_HOSTNAME>

GCP

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

---

3. Install Docker

The BlueRock Dashboard runs inside a Docker container.

Install Docker on the Dashboard VM:

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

Add the current user to the Docker group:

sudo usermod -aG docker $USER

Apply the group change:

newgrp docker

Verify the Docker installation:

docker --version

---

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

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

Important: To access the BlueRock container images, get in touch with BlueRock Support.

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:

docker pull <IMAGE_URL>:<RELEASE_TAG>

Verify that the image is available:

docker images

---

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.

Note: Self-signed SSL certificates are intended for internal testing only and are not recommended for production deployments.

Create a directory for the certificate:

mkdir -p ~/bluerock/certs

Generate the self-signed certificate:

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

Replace <DASHBOARD_IP_OR_HOSTNAME> with the hostname or IP address used to access the BlueRock Dashboard.

Set the appropriate permissions on the private key:

chmod 600 ~/bluerock/certs/server.key

Verify the generated certificate:

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

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:

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

Update the certificate trust store:

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:

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.

Note: Ensure that the certificate matches the hostname used to access the BlueRock Dashboard.

---

6. Start the BlueRock Dashboard

Create the persistent data directory:

mkdir -p ~/bluerock/data

Start the Dashboard container:

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>

---

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.

Security: Restrict ports 4318 and 8443 to trusted BlueRock Host networks or CIDR ranges.

Note: SSH access on port 22 is required for VM administration and should already be allowed from the approved administrator IP addresses.

---

8. Verify the Dashboard

Verify that the Dashboard container is running:

docker ps

Check the Dashboard container logs:

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:

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:

[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:

sudo systemctl restart bluerockd

Verify that the service is running:

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:

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:

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.

---