# Sandbox

The DBNL sandbox deployment bundles all of the DBNL services and dependencies into a single self-contained Docker container. This container replicates a full DBNL deployment by creating a Kubernetes cluster in the container and using Helm to deploy the DBNL platform and its dependencies (e.g. postgresql, redis, and minio).

{% hint style="warning" %}
The sandbox deployment is not suitable for production environments, it will not scale for large workloads and is missing features like enterprise [Authentication](https://docs.dbnl.com/v0.27.x/platform/authentication) and [Administration](https://docs.dbnl.com/v0.27.x/platform/administration).
{% endhint %}

## Requirements

* Install [docker](https://docs.docker.com/engine/install/).
* Install [`dbnl`](https://pypi.org/project/dbnl/), the DBNL CLI and Python SDK.

Within the sandbox container, [k3d](https://k3d.io/stable/) is used in conjunction with [docker-in-docker](https://www.docker.com/blog/docker-can-now-run-within-docker/) to schedule the containers for the DBNL platform and its dependencies.

* The sandbox container needs access to the following two registries to pull the containers for the DBNL platform and its dependencies.
  * us-docker.pkg.dev
  * docker.io
* **Resource requirements:**
  * **Minimum**: 8 GB RAM, 20 GB disk space
  * **Recommended**: 16 GB RAM, 50 GB disk space
  * **Docker Desktop users**: Ensure Docker is allocated at least 8 GB memory in Docker Desktop settings (Preferences → Resources → Memory)

## Usage

Although the sandbox image can be deployed manually using Docker, we recommend using the dbnl CLI to manage the sandbox container. For more details on the sandbox CLI options, run:

```
$ dbnl sandbox --help
```

### Start the Sandbox

To start the DBNL Sandbox, run:

```
$ dbnl sandbox start
```

This will start the sandbox in a Docker container named `dbnl-sandbox`. It will also create a Docker volume of the same name to persist data beyond the lifetime of the sandbox container.

Once ready, the DBNL UI will be accessible at <http://localhost:8080> with the API being available at [http://localhost:8080/api](http://localhost:8080).

### Stop the Sandbox

To stop the DBNL sandbox, run:

```
$ dbnl sandbox stop
```

This will stop and remove the sandbox container. It does not remove the Docker volume and the next time the sandbox is started, it will remount the existing volume, persisting the data beyond the lifetime of the Sandbox container.

### Get Sandbox Status

To get the status of the DBNL sandbox, run:

```
$ dbnl sandbox status
```

### Get Sandbox Logs

To tail the DBNL sandbox logs, run:

```
$ dbnl sandbox logs
```

This will tail the logs from the container. This does not include the logs from the services that run on the Kubernetes cluster within the container. For this, you will need to use the [exec command](#execute-command-in-sandbox).

### Execute Command in Sandbox

To execute a command in the DBNL sandbox, run:

```
$ dbnl sandbox exec [COMMAND]
```

This will execute `COMMAND` within the DBNL sandbox container. This is a useful tool for debugging the state of the containers running within the sandbox container. For example:

To get a list of all Kubernetes resources, run:

```
$ dbnl sandbox exec kubectl get all
```

To get the logs for a particular pod, run:

```
$ dbnl sandbox exec kubectl logs [POD]
```

### Delete Sandbox Data

{% hint style="warning" %}
This is an irreversible action. All the sandbox data will be lost forever.
{% endhint %}

To delete the sandbox data, run:

```
$ dbnl sandbox delete
```

## Authentication

The sandbox deployment uses username and password authentication with a single user. The user credentials are:

* Username: **admin**
* Password: **password**

## Storage

The sandbox persists data in a Docker volume named `dbnl-sandbox`. This volume is persisted even if the sandbox is stopped, making it possible to later resume the sandbox without losing data.

## Remote Sandbox

If deploying and hosting the sandbox on a remote host, the sandbox `--base-url` option needs to be set on `start`.

{% hint style="info" %}
For more details on how to deploy the sandbox to AWS EC2, Google Compute Engine or Azure Virtual Machines, see the [Remote Sandbox](#remote-sandbox) section below.
{% endhint %}

For example, if hosting the sandbox on `http://example.com:8080`, the sandbox needs to be started with:

```
$ dbnl sandbox start --base-url http://example.com:8080
```

The DBNL sandbox can be deployed to a virtual machine such as [AWS EC2](https://aws.amazon.com/ec2/), [Google Compute Engine](https://cloud.google.com/products/compute) or [Azure Virtual Machines](https://azure.microsoft.com/en-us/products/virtual-machines). This is a good option for sandbox deployments that need to be accessible by multiple users or applications or deployments that need to be persisted for longer periods of time.

{% hint style="warning" %}
The sandbox deployment is not suitable for production environments.
{% endhint %}

## Requirements

* A domain name to host the DBNL sandbox (e.g. dbnl.example.com). This is optional for AWS EC2.

{% hint style="info" %}
Currently, the sandbox does not support being hosted from a subpath (e.g. <http://example.com:8080/dbnl>) or being served from a different port. If those are required, we recommend using a reverse proxy.
{% endhint %}

* A set of DBNL registry credentials to pull the sandbox image.

## Installation

{% tabs %}
{% tab title="AWS" %}
**Create an AWS EC2 instance**

1. Open the [EC2 console](https://console.aws.amazon.com/ec2/) and launch a Linux virtual machine instance (e.g. Amazon Linux, Ubuntu). The steps below assumes an Amazon Linux instance.

{% hint style="info" %}
For anything but a test deployment, we recommend using a memory optimized instance such as an **r7i.large** or above with at least **1 TiB** of **gp3** storage.
{% endhint %}

2. SSH into the instance using the instance public dns name.

```bash
$ ssh -i KEY_FILE ec2-user@INSTANCE_PUBLIC_DNS_NAME
```

**\[Optional] Configure DNS**

1. Add a DNS CNAME record mapping your domain name to the instance public DNS name.

{% hint style="info" %}
This step is optional and the instance public DNS name can be used directly as the deployment domain name.
{% endhint %}

**Configure Security Group**

1. Open the [EC2 console](https://console.aws.amazon.com/ec2/), select the newly created instance and click through to the instance security group under *Security > Security details > Security groups*.
2. Add a **Custom TCP** inbound rule to port **8080** from **My IP**.

{% hint style="info" %}
To allow traffic from more than one IP address, define a **Custom** source. For more details, see [working with security group rules](https://docs.aws.amazon.com/vpc/latest/userguide/working-with-security-group-rules.html).
{% endhint %}

**Install Docker**

1. Install Docker.

```bash
$ sudo dnf install docker
```

2. Start the Docker service.

```bash
$ sudo service docker start
```

3. Add the `ec2-user` to the `docker` group so that you can run Docker commands without using sudo.

```bash
$ sudo usermod -a -G docker ec2-user
```

4. Pick up new permissions by exiting SSH and logging back into the instance via SSH.

**Install DBNL CLI**

1. Install `python` and `pip`.

```bash
$ sudo dnf install python pip
```

2. Install the DBNL CLI.

```bash
$ pip install dbnl
```

**Start DBNL sandbox**

1. Start the sandbox passing the domain name or the instance public DNS name as the base URL.

```bash
$ dbnl sandbox start --base-url http://DOMAIN_NAME:8080
```

{% endtab %}
{% endtabs %}