Sandbox

Instructions for managing a DBNL Sandbox deployment.

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).

The sandbox deployment is not suitable for production environments, it will not scale for large workloads and is missing features like enterprise Authentication and Administration.

Requirements

• Install docker.

• Install dbnl, the DBNL CLI and Python SDK.

Within the sandbox container, k3d is used in conjunction with docker-in-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.

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

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

This is an irreversible action. All the sandbox data will be lost forever.

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.

For more details on how to deploy the sandbox to AWS EC2, Google Compute Engine or Azure Virtual Machines, see the Remote Sandbox section below.

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, Google Compute Engine or Azure 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.

The sandbox deployment is not suitable for production environments.

Requirements

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

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.

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

Installation

AWS

Create an AWS EC2 instance

1. Open the EC2 console and launch a Linux virtual machine instance (e.g. Amazon Linux, Ubuntu). The steps below assumes an Amazon Linux instance.

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.

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

$ 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.

This step is optional and the instance public DNS name can be used directly as the deployment domain name.

Configure Security Group

1. Open the EC2 console, 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.

To allow traffic from more than one IP address, define a Custom source. For more details, see working with security group rules.

Install Docker

1. Install Docker.

$ sudo dnf install docker

1. Start the Docker service.

$ sudo service docker start

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

$ sudo usermod -a -G docker ec2-user

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

Install DBNL CLI

1. Install python and pip.

$ sudo dnf install python pip

1. Install the DBNL CLI.

$ pip install dbnl

Start DBNL sandbox

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

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