Virtual Machine

Instructions for deploying the sandbox on a virtual machine

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 \
    -p DBNL_REGISTRY_PASSWORD \
    --base-url http://DOMAIN_NAME:8080

GCP

Create a Google Cloud Compute instance

1. Open the Cloud Compute console and launch a Linux virtual machine instance (e.g. Debian, Ubuntu). The steps below assumes a Debian instance.

For anything but a test deployment, we recommend using a memory optimized instance such as an n2-highmem-2 or above with at least 1 TiB of balanced persistent disk storage.

1. SSH into the instance using the instance name, project id and zone.

$ gcloud compute ssh --zone ZONE INSTANCE_NAME --project PROJECT_ID

Configure DNS

1. Open the IP addresses console, click Reserve external static IP address and create an IP address with:

   1. Attached to: Instance name

   2. Name: dbnl-sandbox

2. Add a DNS A record mapping your domain name to the external static IP address created in step 1.

Configure Firewall

1. Open the Cloud Compute console, select the newly created instance, click Edit and under Networking set:

   1. Network tags: dbnl-sandbox

2. Open the Firewall policies console, click Create firewall rule to create a firewall rule with:

   1. Name: dbnl-sandbox

   2. Target tag: dbnl-sandbox

   3. Source IPv4 range: your IP

   4. Target: TCP port 8080

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 apt-get install docker.io

1. Start the Docker service.

$ sudo service docker start

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

$ sudo usermod -a -G docker CURRENT_USER

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

Install DBNL CLI

1. Install python, venv and pip.

$ sudo apt-get install python-is-python3 python3-pip python3-venv

1. Create a virtual environment.

$ python -m venv venv
$ source venv/bin/activate

1. Install the DBNL CLI.

$ pip install dbnl

Start DBNL sandbox

1. Start the sandbox passing the instance public dns name as the base URL.

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

Azure

Create a Google Cloud Compute instance

1. Open the Azure Virtual Machines console and launch a Linux virtual machine instance (e.g. Debian, Ubuntu). The steps below assumes a Debian instance.

For anything but a test deployment, we recommend using a memory optimized instance such as an E2s_v6 or above with at least a 1 TiB P30 disk storage.

1. SSH into the instance using the instance public IP address.

$ ssh -i KEY_FILE azureuser@INSTANCE_PUBLIC_IP_ADDRESS

Configure DNS

1. Add a DNS A record mapping your domain name to the public IP address of the instance.

Configure Firewall

1. Open the Azure Virtual Machines console, select the newly created instance and under Networking > Network settings > Rules > Create port rule > Inbound port rule add an inbound port rule with:

   1. Source: My IP address

   2. Source port ranges: *

   3. Destination port ranges: 8080

   4. Protocol: TCP

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 apt-get update
$ sudo apt-get install docker.io

1. Start the Docker service.

$ sudo service docker start

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

$ sudo usermod -a -G docker azureuser

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

Install DBNL CLI

1. Install python, venv and pip.

$ sudo apt-get update
$ sudo apt-get install python-is-python3 python3-pip python3-venv

1. Create a virtual environment.

$ python -m venv venv
$ source venv/bin/activate

1. Install the DBNL CLI.

$ pip install dbnl

Start DBNL sandbox

1. Start the sandbox passing the instance public dns name as the base URL.

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