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 scale dbnl deployment by creating a Kubernetes cluster in the container and using Helm to deploy the dbnl platform and its dependencies (postgresql, redis and minio).

The sandbox deployment is not suitable for production environments.

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

• The sandbox container needs sufficient memory and disk space to schedule the k3d cluster and the containers for the dbnl platform and its dependencies.

Registry Credentials

The dbnl sandbox image and the dbnl platform images are stored in a private registry. For access, please reach out to our team.

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 -p ${REGISTRY_PASSWORD}

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.

To use the dbnl Sandbox, set your API URL to http://localhost:8080/api, either through environment variables or through the SDK.

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 containers. 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, such as on EC2 or Compute Engine, the sandbox --base-url option needs to be set on start.

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

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.