# Orchestrator in a Box

**Bluebricks Orchestrator in a Box (OIB)** provides a streamlined solution for deploying the Bluebricks Self-Hosted Runner on a single VM using a lightweight Kubernetes environment.

## Overview

The Orchestrator in a Box solution creates a lightweight Kubernetes environment using [K3s](https://k3s.io/), which runs inside Docker containers using k3d, and then deploys the Bluebricks Deployments Controller. This makes it ideal for:

* Environments with limited Kubernetes expertise
* Simpler deployments with minimal infrastructure requirements
* Quick setup for testing or evaluation purposes
* Resource-constrained environments

<figure><img src="/files/5KMYUeqMnOAoU68xmtI9" alt=""><figcaption><p>Orchestrator in a Box Infrastrcture</p></figcaption></figure>

## System requirements

* **Operating System**: Ubuntu Linux (20.04+ recommended)
* **Resources**:
  * 4 GB RAM minimum (8GB+ recommended)
  * 20 GB storage minimum
  * 2 CPUs minimum
* **Software Requirements**:
  * Docker Engine
  * curl
* **Network Requirements**:
  * Complies with Bluebricks [Network Access Requirements](/docs/organization-and-security/netwrok-access-requirements.md)
    * If using a proxy, ensure environment variables are set (`HTTP_PROXY` and `HTTPS_PROXY`)

## Installation

### Download and prepare installation files

```bash
curl -O https://brickscli.s3.eu-west-1.amazonaws.com/releases/latest/orchestrator-in-a-box/install.sh
curl -O https://brickscli.s3.eu-west-1.amazonaws.com/releases/latest/orchestrator-in-a-box/config.yaml
chmod +x install.sh
```

### Execute the installation script

```bash
./install.sh
```

The installation script will:

1. Check system prerequisites
2. Install k3d (if not already installed)
3. Create a single-node K3s cluster inside Docker
4. Install the required Kubernetes components
5. Deploy the Bluebricks Orchestrator using Helm
6. Configure the Kubernetes environment
7. Display access information

## Configure the self-hosted orchestrator

The configuration includes setting up the collection, generating a static authentication token, and establishing communication between the Bluebricks Control Plane and the Orchestrator in a Box.

### Create a collection

This collection will be used to manage the deployments handled by your self-hosted orchestrator. Follow the '[Create a Collection](/docs/orchestration/collections/create-an-environment.md)' article to connect the self-hosted Orchestrator you created.

{% hint style="info" %}
At this point, go to <https://app.bluebricks.co/collections> and validate that the created collection is listed. If listed, proceed to generate your Static Auth Token.
{% endhint %}

### Generate static auth token

The Static Auth Token is a one-time activity that generates a unique token to be used by the Orchestreator in a Box. This token will be registered in Bluebricks Control Plane and ensure secure communication.

#### Fetch JWT from bricks CLI

You're going to use Bluebricks API, which is protected by a JWT. We'll use the assigned JWT that was created when you logged in to bricks.

{% hint style="info" %}
If you haven't signed into bricks CLI already, please open your terminal and type `bricks login`. If you haven't installed the bricks CLI, please refer to [this article](/docs/bricks-cli/bricks-cli.md#install-bricks-command-line).
{% endhint %}

Once signed in, fetch your JWT by typing the following command:

```
cat ~/.bricks/credentials.yaml | grep 'token:' | awk '{print $3}'
```

#### Call Bluebricks API

Open a terminal and execute the following API request using curl to generate the Static Auth Token

```bash
curl https://api.bluebricks.co/api/v1/cloud \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <YOUR_BEARER_TOKEN>' \
  --data '{
  "name": "<DISPLAY_NAME>",
  "accountId": "<UNIQUE_NAME>",
  "collection": "<COLLECTION_SLUG>",
  "provider": "self-hosted"
}'
```

Be sure to replace the placeholders with your data as described below:

| Placeholder           | Replace with                                                                  | Note                                                                                                               |
| --------------------- | ----------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
| `<YOUR_BEARER_TOKEN>` | JWT that was fetched in the previous step.                                    |                                                                                                                    |
| `<DISPLAY_NAME>`      | A friendly name that will be used later to identify your OIB                  |                                                                                                                    |
| `<UNIQUE_NAME>`       | A lowercase with no spaces name to identify your OIB in scripts and API calls |                                                                                                                    |
| `<COLLECTION_SLUG>`   | The slug of the created collection from the previouse steps                   | Collection slug is listed on Bluebricks Control Plane on [Collections Page](https://app.bluebricks.co/collections) |

The response shall include a `static_auth_token` value, which you'll use to authenticate your orchestrator:

```json
{
  "id": "cloud-xxxx",
  "static_auth_token": "YourOrchestratorAuthToken",
  "name": "my-orchestrator-in-a-box",
  "status": "active"
}
```

### Assign identity to the OIB

Use the following `install.sh` script to add the generated Static Auth Token

```
/install.sh --orchestrator-token "YourOrchestratorAuthToken"
```

## Verifying installation

After installation completes, you can verify the orchestrator is running by checking the Kubernetes pods:

```bash
export KUBECONFIG="$HOME/.kube/orchestrator-in-a-box-config"
kubectl get pods -n bluebricks
```

You should see pods running the Bluebricks orchestrator components.

* Check the logs using the following command:

```bash
kubectl logs -n bluebricks deployment/bluebricks-deployments-controller-bdc
```

You can also use the Kubernetes dashboard if it was enabled during installation:

```bash
export KUBECONFIG="$HOME/.kube/orchestrator-in-a-box-config"
kubectl proxy
```

Then access the dashboard at: <http://localhost:8001/api/v1/namespaces/kubernetes-dashboard/services/https:kubernetes-dashboard:/proxy/>

### Using kubectl with the K3s Cluster

Interact with your K3s cluster using the following commands:

```bash
export KUBECONFIG="$HOME/.kube/orchestrator-in-a-box-config"
kubectl get nodes
kubectl get namespaces
```

## Customization

### Using a custom configuration

You can customize the K3s cluster and orchestrator deployment by editing the `config.yaml` file before installation, or by providing a custom configuration file:

```bash
./install.sh --config-file my-custom-config.yaml
```

### Advanced options

```
Options:
  -h, --help                 Show this help message
  --config-file FILE         Values configuration file
  --orchestrator-token TOKEN Orchestrator API token for Bluebricks API integration
  --k3s-version VERSION      K3s version to install
  --namespace NAMESPACE      Kubernetes namespace to install the orchestrator
  --release-name NAME        Helm release name
  --uninstall                Uninstall Orchestrator in a Box
```

## Uninstallation

To completely remove the orchestrator and K3s cluster, execute the following command.

```bash
./install.sh --uninstall
```

Uninstallation script will do the following:

1. Uninstall the orchestrator Helm release
2. Delete the K3s cluster
3. Remove the kubeconfig file
4. Clean up any temporary files

## Troubleshooting

<details>

<summary>Connectivity Problems</summary>

If the orchestrator cannot connect to the Bluebricks API, verify your network settings and ensure the required domains are whitelisted.

</details>

<details>

<summary>Authentication Failures</summary>

Double-check that you're using the correct Static Auth Token.

</details>

<details>

<summary>Resource Constraints</summary>

If the K3s cluster or orchestrator pods are terminating unexpectedly, check system resources to ensure the VM has adequate memory and CPU available.

</details>

<details>

<summary>Docker is not Running</summary>

Ensure Docker is running before starting the installation by running `docker info`

</details>

<details>

<summary>Port Conflicts</summary>

If ports 6443 (Kubernetes API) or 8080 are already in use, you might need to modify the configuration.

</details>

<details>

<summary>Kubernetes Errors</summary>

If you encounter Kubernetes-related errors:

```
export KUBECONFIG="$HOME/.kube/orchestrator-in-a-box-config"
kubectl get events --sort-by=.metadata.creationTimestamp
```

</details>

## Support

For issues related to Orchestrator in a Box, please get in touch with the Bluebricks support team.

{% embed url="<https://forms.fillout.com/t/tyoNtKLYDdus>" %}


---

# Agent Instructions: 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:

```
GET https://bluebricks.co/docs/organization-and-security/bluebricks-self-hosted-runner/orchestrator-in-a-box.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.