# Virtual Machine

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

{% endtab %}

{% tab title="GCP" %}

#### Create a Google Cloud Compute instance

1. Open the [Cloud Compute console](https://console.cloud.google.com/compute/instances) and launch a Linux virtual machine instance (e.g. Debian, Ubuntu). The steps below assumes a Debian instance.

{% hint style="info" %}
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.
{% endhint %}

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

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

#### Configure DNS

1. Open the IP [addresses console](https://console.cloud.google.com/networking/addresses/), click *Reserve external static IP address* and create an IP address with:
   1. **Attached to:** Instance name
   2. **Name:** `dbnl-sandbox`&#x20;
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](https://console.cloud.google.com/compute/instances), select the newly created instance, click *Edit* and under *Networking* set:
   1. **Network tags:** `dbnl-sandbox`&#x20;
2. Open the [Firewall policies console](https://console.cloud.google.com/net-security/firewall-manager/firewall-policies/), click *Create firewall rule* to create a firewall rule with:&#x20;
   1. **Name:** `dbnl-sandbox`
   2. **Target tag:** `dbnl-sandbox` &#x20;
   3. **Source IPv4 range:** [your IP](https://whatismyipaddress.com/)
   4. **Target:** TCP port 8080

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

2. Start the Docker service.

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

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

```bash
$ sudo usermod -a -G docker CURRENT_USER
```

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

#### Install DBNL CLI

1. Install `python`, `venv` and `pip`.

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

2. Create a virtual environment.

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

3. Install the DBNL CLI.

```bash
$ pip install dbnl
```

#### Start DBNL sandbox

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

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

{% endtab %}

{% tab title="Azure" %}

#### Create a Google Cloud Compute instance

1. Open the [Azure Virtual Machines console](https://portal.azure.com/#view/Microsoft_Azure_ComputeHub/ComputeHubMenuBlade/~/virtualMachinesBrowse) and launch a Linux virtual machine instance (e.g. Debian, Ubuntu). The steps below assumes a Debian instance.

{% hint style="info" %}
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.
{% endhint %}

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

```bash
$ 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](https://portal.azure.com/#view/Microsoft_Azure_ComputeHub/ComputeHubMenuBlade/~/virtualMachinesBrowse), 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

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

2. Start the Docker service.

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

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

```bash
$ sudo usermod -a -G docker azureuser
```

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

#### Install DBNL CLI

1. Install `python`, `venv` and `pip`.

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

2. Create a virtual environment.

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

3. Install the DBNL CLI.

```bash
$ pip install dbnl
```

#### Start DBNL sandbox

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

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

{% endtab %}
{% endtabs %}