Ctrlk
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Start Running your BEACON Today

Choose your preferred deployment method and start running a Blockcast BEACON node today.

A BEACON node participates in the Blockcast network by running the gateway software and submitting attestations. Choose your preferred deployment method below.

Deployment

Using Docker

  1. Make sure you have Docker installed and running in the background

  2. Retrieve the Blockcast Beacon Docker Compose Manifest

    1. Download the Blockcast BEACON docker compose file from our git repo.

    2. Or run git clone https://github.com/Blockcast/beacon-docker-compose.git

  3. Launch and start running Blockcast Beacon

    1. Start running your Blockcast BEACON with command docker compose up -d from the folder where docker-compose.yml is saved

    2. Verify everything is up and healthy with docker compose ps

      NAME                                 COMMAND                  SERVICE             STATUS              PORTS
beacond                              "envdir /var/opt/mag…"   beacond             running
blockcastd                           "/usr/bin/blockcastd…"   blockcastd          running
control_proxy                        "/usr/bin/control_pr…"   control_proxy       running

    3. Otherwise check the logs of the service that is not Up with docker compose logs <NAME> you can share with us for support.

  4. Generate hardware and challenge key

    1. When BEACON runtime is up

      1. Change your pwd to this folder: cd ~/.blockcast/compose

      2. Run docker compose exec blockcastd blockcastd init

      3. It would generate an output that contains your device's Hardware ID, Challenge Key and a Registration URL:

        Hardware ID:
------------
c6ff0e6f-bc4d-4151-47c3-07df0e3cf53f

Challenge Key:
--------------
MCowBQYDK2VwAyEAXP49l4pBK1V5qy7vbRJYv3etRdEr7ycsQAvrgS+hQY0=

Register URL:
-------------
https://app.blockcast.network/register?hwid=c6ff0e6f-bc4d-4151-47c3-07df0e3cf53f&challenge-key=MCowBQYDK2VwAyEAXP49l4pBK1V5qy7vbRJYv3etRdEr7ycsQAvrgS%2BhQY0%3D

      4. Note:

        1. Hardware ID is a unique public identifier for your device.

        2. Challenge Key is a Solana formatted public key that is unique to your device.

        3. Backup your private key (in ~/.blockcast/certs/gw_challenge.key) and keep it safe with the hardware ID, otherwise you will lose the ability to prove ownership of this device.

  5. Register your node on the web portal

    1. Go to our web portal https://app.blockcast.network/ and log in/register

    2. Copy and paste the Registration URL from the console output with your pre-filled Hardware ID and Challenge Key into your browser, OR

    3. Go to Manage Nodes page, press Register Node button, and manually enter your keys in the portal registration flow

    4. You will need to enable location access from your browser. Here is how to enable it on Chrome. If you are using other browsers, it might look different.

    5. Confirm your instance is online and healthy

      1. If your node is registered successfully and running, your node should show Healthy status in a few minutes in the node list table on the /manage-nodes page.

      2. Clicking on the node entry in the node list table lands you onto the node details page, you should be able to see the uptime, connectivity, rewards info of that particular node. The nodes need to be online for 6 hours in order for the first connectivity test to run. The first batch of rewards does not kick in until 24 hours of being continuously online.

Using Helm

If you prefer to run your BEACON on Kubernetes, Blockcast provides official Helm charts.

Prerequisites

  • Kubernetes 1.25+

  • Helm 3.12+

  • Cluster admin credentials for the initial setup step

  • Gateway API CRDs — the experimental channel is required because the relay uses TCPRoute and UDPRoute:

Add the Helm repository:

All chart versions use pre-release SemVer suffixes (e.g. 1.8.8-15529.de614275). You must pass --devel to all Helm commands — without it Helm will find no installable chart.

Step 1 — Install cluster prerequisites (admin, once per namespace)

This installs the ClusterRole, ClusterRoleBinding, and GatewayClass the gateway needs. Requires cluster-admin credentials.

If your gateway release name is not blockcastd, pass --set releaseName=<your-release-name>.

Verify before continuing — silently skipping this step is the most common cause of a broken install:

Both should return non-empty results. If the GatewayClass is missing or the gateway later shows PROGRAMMED=Unknown, re-run this step.

Step 2 — Install the gateway

Run helm show values blockcast/cdn-gateway to see all available configuration options.

Step 3 — Register the gateway

Once the pods are running, retrieve the registration URL:

Copy the printed URL and complete registration in the Blockcast portal. Until registered, blockcastd will not receive a configuration and no dynamic services will start.

After registering, confirm the connection by checking the logs:

Look for a configuration received message and dynamic services starting up (e.g. beacond).

Upgrades

The gateway upgrades itself automatically once running. To manually upgrade the Helm release:

The prereqs chart rarely changes — re-run Step 1 only if instructed in the release notes.

Troubleshooting

Gateway stuck on PROGRAMMED=Unknown ("Waiting for controller")

This almost always means the prereqs chart was skipped or applied to the wrong namespace. Check:

If either is empty, re-run Step 1. To force reconciliation immediately:

helm search repo returns no results

Pre-release chart versions require --devel:

Uninstall

PVCs (blockcastd-certs and the snowflake PVC) are retained by default. Delete them manually if needed — otherwise reinstalling in the same namespace will reuse the existing certificate and snowflake state.

PreviousBEACON
NextBEACON Common Questions

Last updated