> For the complete documentation index, see [llms.txt](https://docs.blockcast.network/main/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.blockcast.network/main/getting-started/how-do-i-participate-in-the-network/beacon/start-running-your-beacon-today.md). # Start Running your BEACON 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**](https://docs.docker.com/get-started/introduction/get-docker-desktop/) **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](https://github.com/Blockcast/beacon-docker-compose). 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 ` 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 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](https://gateway-api.sigs.k8s.io/guides/#install-standard-channel) — the **experimental channel** is required because the relay uses `TCPRoute` and `UDPRoute`: ```bash kubectl apply -f https://github.com/kubernetes-sigs/gateway-api/releases/download/v1.2.0/experimental-install.yaml ``` Add the Helm repository: ```bash helm repo add blockcast https://blockcast.github.io/helm-charts/stable helm repo update ``` > 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. ```bash helm upgrade --install blockcastd-prereqs blockcast/cdn-gateway-orc8r-prereqs \ -n \ --create-namespace \ --devel ``` > If your gateway release name is not `blockcastd`, pass `--set releaseName=`. Verify before continuing — silently skipping this step is the most common cause of a broken install: ```bash helm list -n | grep blockcastd-prereqs kubectl get gatewayclass ats- ``` 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** ```bash helm upgrade --install blockcastd blockcast/cdn-gateway \ -n \ --devel \ -f my-values.yaml ``` 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: ```bash kubectl exec -n deploy/blockcastd-blockcastd -- blockcastd -s ``` Copy the printed URL and complete registration in the [Blockcast portal](https://app.blockcast.network/). Until registered, `blockcastd` will not receive a configuration and no dynamic services will start. After registering, confirm the connection by checking the logs: ```bash kubectl logs -n deploy/blockcastd-blockcastd -f ``` 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: ```bash helm repo update helm upgrade blockcastd blockcast/cdn-gateway -n --devel -f my-values.yaml ``` 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: ```bash helm list -n | grep blockcastd-prereqs kubectl get gatewayclass ats- ``` If either is empty, re-run Step 1. To force reconciliation immediately: ```bash kubectl rollout restart deployment/blockcastd-relay -n ``` *`helm search repo` returns no results* Pre-release chart versions require `--devel`: ```bash helm search repo blockcast/cdn-gateway --devel ``` **Uninstall** ```bash helm uninstall blockcastd -n helm uninstall blockcastd-prereqs -n ``` > 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. --- # 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 dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.blockcast.network/main/getting-started/how-do-i-participate-in-the-network/beacon/start-running-your-beacon-today.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. 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.