> For the complete documentation index, see [llms.txt](https://bluebricks.co/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://bluebricks.co/docs/organization-and-security/bluebricks-self-hosted-runner/orchestrator-in-a-box.md).
# 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
Orchestrator in a Box Infrastrcture
## 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 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 ' \
--data '{
"name": "",
"accountId": "",
"collection": "",
"provider": "self-hosted"
}'
```
Be sure to replace the placeholders with your data as described below:
| Placeholder | Replace with | Note |
| --------------------- | ----------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
| `` | JWT that was fetched in the previous step. | |
| `` | A friendly name that will be used later to identify your OIB | |
| `` | A lowercase with no spaces name to identify your OIB in scripts and API calls | |
| `` | 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:
### 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
Connectivity Problems
If the orchestrator cannot connect to the Bluebricks API, verify your network settings and ensure the required domains are whitelisted.
Authentication Failures
Double-check that you're using the correct Static Auth Token.
Resource Constraints
If the K3s cluster or orchestrator pods are terminating unexpectedly, check system resources to ensure the VM has adequate memory and CPU available.
Docker is not Running
Ensure Docker is running before starting the installation by running `docker info`
Port Conflicts
If ports 6443 (Kubernetes API) or 8080 are already in use, you might need to modify the configuration.
Kubernetes Errors
If you encounter Kubernetes-related errors:
```
export KUBECONFIG="$HOME/.kube/orchestrator-in-a-box-config"
kubectl get events --sort-by=.metadata.creationTimestamp
```
## Support
For issues related to Orchestrator in a Box, please get in touch with the Bluebricks support team.
{% embed url="" %}