Using G.V() on AWS Marketplace

G.V() is available as a web version on the AWS Marketplace at https://aws.amazon.com/marketplace/pp/prodview-lifzpx4adcwsq.

It's a graph database client, perfect for developers looking to start on a graph project or support an existing one. It is compatible with Amazon Neptune's Gremlin and Cypher API, as well as Apache TinkerPop enabled graph databases such as JanusGraph, Gremlin Server and Aerospike Graph.

We provide state of the art development tools with advanced autocomplete, syntax checking and graph visualization.

With G.V() you can:

• View your graph database's schema in 1 click
• Write and run Gremlin queries, and run them against your database
• Write and run Cypher queries on Amazon Neptune and Puppygraph
• Visualize query results across a variety of formats such as graph visualization, JSON and tables
• Explorer your data interactively with our no-code graph database browser
• Debug Gremlin queries step by step, and access profiling tools for Gremlin and Cypher

It is deployed over an EC2 instance, exposing a web service over port 443, protected via basic authentication, from which you can access our application's web interface.

Deploying a G.V() instance

To deploy G.V(), follow these steps:

• Navigate to https://aws.amazon.com/marketplace/pp/prodview-lifzpx4adcwsq.
• Click on View Purchase Options or Try for free if this is your first time deploying G.V()
• Click on Accept Terms after reviewing our terms and conditions (standard contract for AWS Marketplace). Upon accepting, AWS License Manager will issue a new license for your AWS account to use G.V(). This process may take up to a couple minutes to complete.
• Click on Continue to Configuration
  • Leave the default fulfilment option
  • Select the latest version of the software
  • Select your region - we recommend using the same region as your database(s)
  • Click Continue to Launch
• Under Choose Action, select Launch through EC2, and click Launch
• Enter a name for the EC2 instance that will be launched
• Under Instance Type, select one of our available instance types according to our sizing guide
• Under Key pair (login), select an SSH key pair to authenticate to your EC2 instance via SSH. You will occasionally need to SSH into your G.V() EC2 instance to perform operations such as password change, version updates or TLS certificate deployment.
• Under Network settings, follow these instructions:
  • Leave the default VPC setting selection unless your Amazon Neptune instance (or other database) that you want to connect G.V() to is deployed to a specific VPC
  • Select your subnet or leave the default selection
  • Set Auto-assign public IP to Enable
  • Leave the Firewall (security groups) settings as default unless to restrict access to port 22 and 443 to specific IP address(es).
• Under Configure storage, set the Root volume size to 30gb, the free tier eligible limit. It will be enough storage for any amount of user.
• Under Advanced Details, on the IAM instance field, follow the instructions at Configuring the IAM role for the instance to create the necessary IAM instance profile to run G.V() on EC2
• Click Launch instance

The deployment process is fully automatic and the G.V() application should be ready within 2 minutes.

Make a note of the EC2 instance id as you will need to authenticate to G.V(). In the EC2 console, click on the newly created EC2 instance to display its public IPv4 DNS which you will need to enter in your browser to access the deployed product.

Pricing

G.V() is priced using the hourly model on the AWS marketplace. Charges only incur for instances of G.V() that are up and running. For pricing details as well as sizing advice, see the sizing guide below.

Sizing Guide

G.V() can be deployed on EC2 instance types with varying levels of performance. The sizing guide below indicates how many users can use G.V() concurrently for a given EC2 instance type.

Instance Type	Concurrent users	Product cost per hour
t3.small	Up to 1 user	$0.24
t3.medium	Up to 3 users	$0.32
t3.large	Up to 5 users	$0.64
t3.xlarge	Up to 10 users	$1.28
t3.2xlarge	Up to 15 users	$2.56
m5.large	Up to 5 users	$0.80
m5.xlarge	Up to 10 users	$1.60
m5.2xlarge	Up to 15 users	$3.20
m5.4xlarge	Over 20 users	$6.40

Regardless of the EC2 instance type you choose or the amount of concurrent users, a root volume size of 30gb for the instance will be enough to run the service smoothly.

Architecture

G.V() runs on an Amazon Linux 2023 EC2 instance with 3 Docker containers configured and started via docker-compose. Our AMI comes pre-bundled with all the binaries and configurations necessary to run the application via Docker.

The Docker containers are as follows:

• gdotv-developer: The G.V() web application
• gdotv-postgres: a PostgresSQL database storing configuration details for the G.V() web application
• gdotv-nginx: an NGINX reverse-proxy fronting the application over port 443 on the EC2 instance, with TLS enabled by default

The architecture of the application is as shown below:

Accessing G.V() on your web browser

Upon completion, the newly created EC2 instance with G.V() running will be accessible at the instance's public IPv4 DNS over port 443. To access the application, navigate on your browser to https://{instance-public-hostname}.

By default, G.V() uses a self-signed TLS certificate to enable traffic over HTTPS. Since the certificate is self-signed, you will be notified in your web browser that the connection may be insecure.

To trust the certificate, in your browser, click on Advanced, then click on Proceed to {instance hostname} (unsafe).

You can configure your own TLS certificate for the application by assigning a domain name owned by your organization to the EC2 instance's public IP address, then generating a TLS certificate to be used by G.V() at a specific location on your instance, as described in (Configuring a TLS certificate)[#configuring-a-tls-certificate]

Authenticating to G.V()

G.V() uses basic authentication to secure access to its interface. The default credentials are as follows:

• Username: admin
• Password: the ID of your EC2 instance (e.g. i-0a25b19de55204410). You can find the ID of your EC2 instance from the EC2 console.

Configuring the IAM role for the instance

In order to fully function, G.V() requires that the EC2 instance has an IAM role with the AWSLicenseManagerConsumptionPolicy policy attached. This role is necessary for G.V() to perform checks against AWS License Manager to ensure your license is valid and ran from our AWS Marketplace AMI.

The role configuration is simple and should take no more than two minutes.

You'll be prompted to either select an existing IAM instance profile or create a new one. If you have previously created this instance profile, select it in the IAM Instance Profile dropdown. Otherwise, click on Create new IAM profile

You'll be redirected to the Identity and Access Management (IAM) console. From there, click on Create role at the top right of the screen.

You'll next be prompted to select a Trusted entity type. Select AWS service, then under Use case, select EC2 in the Service or use case dropdown, and check EC2 under the Use case subsection, as shown below:

Click on Next. You'll now be prompted to add permissions to the new role. In the search bar, enter AWSLicenseManagerConsumptionPolicy, enable the policy and click on Next.

Adding permissions to one or more Amazon Neptune instance

Per Amazon Neptune's security guidelines, it is recommended to always enable IAM authentication on your database. If you're planning to use G.V() with an IAM-enabled Amazon Neptune instance, you can configure the EC2 instance's IAM profile to allow access to your database. Whilst adding permissions to your role, enable the following policies:

• NeptuneFullAccess: Provides the G.V() EC2 instance with access to your Amazon Neptune database instances. You can further restrict this access by filtering on the resources that are granted access using their ARN
• CloudWatchLogsReadOnlyAccess: Provides the G.V() EC2 instance with access to your Cloudwatch logs, enabling our Slow Query and Audit Logs functionality. This is entirely optional.

If you would prefer creating a more restricted and fine grained set of permissions to your Amazon Neptune DB instances, we recommend using the following JSON inline policy instead of AWS's NeptuneFullAccess default policy:

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "AllowPassRoleForNeptune",
            "Effect": "Allow",
            "Action": "iam:PassRole",
            "Resource": "*",
            "Condition": {
                "StringEquals": {
                    "iam:passedToService": "rds.amazonaws.com"
                }
            }
        },
        {
            "Sid": "AllowDataAccessForNeptune",
            "Effect": "Allow",
            "Action": [
                "neptune-db:*"
            ],
            "Resource": [
                "<ENTER COMMA SEPARATED LIST OF AMAZON NEPTUNE ARNs TO ALLOW G.V() READ/WRITE ACCESS TO>"
            ]
        }
    ]
}

Note that you will also be prompted to specify a name for the inline policy.

TIP

Make sure to replace the resource list in the policy above with your actual Amazon Neptune ARNs. Alternatively if you would like to grant access to all your Amazon Neptune databases, use:

"Resource": [
    "*"
]

We recommend always following your organization's best practice in security, which should mandate least privilege access to resources.

TIP

You can find your Amazon Neptune DB cluster ARN from the Neptune console on the AWS website, under the Configuration section.

Your ARN should have the following structure: arn:aws:rds:{region}:{aws-account-number}:cluster:{neptune-cluster-name}

Finally, you'll be prompted to set a name and description for the role. We recommend using the following values:

• Name: gdotv-aws-marketplace-role
• Description: Allows the G.V() AWS Marketplace AMI to perform license checkouts against AWS License Manager. It is also configured to read/write access to one or more Amazon Neptune instances, and their Cloudwatch logs. For more information, refer to https://gdotv.com/docs/aws-marketplace/#configuring-the-iam-role-for-the-instance

Once the name and description are set, click on Create Role.

Now that the role is created, you can return to the EC2 launch configuration page to select it. Note that you may need to refresh the role dropdown.

Connecting to your G.V() EC2 instance via SSH

To connect to your G.V() EC2 instance, you will need the SSH private key configured on your EC2 instance as stated in the EC2 console, as well as the hostname of the instance. You also need to ensure that your instance's inbound network rules allow you access to port 22 of the server.

The SSH username to use is ec2-user

From a terminal, run the following command:

ssh -i {path-to-ssh-private-key} ec2-user@{instance hostname}

Once connected, you will be able to perform operations such as modifying your credentials, setting a new TLS certificate or upgrading G.V() to a new version.

Modifying the G.V() authentication credentials

To modify the credentials used by G.V(), you will first need to SSH into the deployed EC2 instance using the key pair that you have configured for the instance.

Once you have SSH'd into the instance, run the following commands to modify the username/password:

cd /home/ec2-user/gdotv/scripts
./set-credentials.sh <new username> <new password>

The credentials update takes effect immediately and doesn't require a restart of the application. You will be prompted for the new credentials when navigating to G.V().

Configuring a TLS certificate

By default, G.V() uses a self-signed certificate to serve its web interface over HTTPS. You may wish to configure your own trusted certificate, according to your organisation's security policy.

To do so, copy your certificate public and private key files in PEM format to the following locations on the EC2 instance (assuming you are SSH'd in as ec2-user):

• Public Key: /home/ec2-user/gdotv/data/certs/certificate.crt
• Private Key: /home/ec2-user/gdotv/data/certs/private.key

Once the files have been replaced, you will need to restart the G.V() application for the changes to take effect. Whilst SSH'd to your EC2 instance as ec2-user, run the following commands:

/home/ec2-user/gdotv/scripts/stop-gdotv.sh
/home/ec2-user/gdotv/scripts/start-gdotv.sh

Startup of the application should result in a downtime of no more than 30 seconds.

Alternatively, you can reboot the EC2 instance itself from the EC2 console to restart the G.V() application.

Upgrading to a new version of G.V()

G.V() receives frequent updates with new features and improvements. We recommend keeping up to date with the latest version.

Upgrading your G.V() version is a straight forward process that can be achieved in a few minutes. There are two types of upgrades you may need to perform:

• Container updates: updates to the G.V() software itself by means of pulliing the latest version of our Docker image
• Amazon Machine Image (AMI) updates: updates to the AMI wrapping the G.V() deployment, for access to the latest security and feature patches from Amazon Linux 2023

Performing a container update

To perform a container update, take note of the latest version number for G.V(), as stated in the update announcement email from AWS, which should be in the x.y.z format.

SSH into your G.V() EC2 instance as ec2-user, with the key pair associated with your EC2 instance as described in Connecting to your G.V() EC2 instance via SSH.

Run the following commands:

echo "{new-gdotv-version-number}" ? /home/ec2-user/gdotv/conf/gdotv_version
cd /home/ec2-user/gdotv/scripts
./stop-gdotv.sh
./start-gdotv.sh

Once the application is restarted, you can continue using G.V() on the latest version directly from your browser.

Performing an AMI update

To perform an AMI update, you will first need to deploy a new EC2 instance for G.V() following the instructions at (Deploying a G.V() instance)[#deploying-a-g-v-instance].

Once the new instance is deployed, you need to migrate the G.V() database files to the new instance. This involves copying the local database storage files from the old instance to the new one. The database storage files contain user preferences and database configurations, as well as saved queries, folders and stylesheets.

Follow these steps to migrate the data:

• SSH into your old EC2 instance as ec2-user
• Stop the G.V() application by running the following commands:

cd /home/ec2-user/gdotv/scripts && ./stop-gdotv.sh

• Navigate to the Postgres data folder: cd /home/ec2-user/gdotv/data
• Compress the postgres-data directory: sudo tar -zcvf postgres-data.tar.gz postgres-data
• Transfer postgres-data.tar.gz to your new instance, either directly between EC2 instances, or via your local machine, as detailed below:
  • Copy the database backup from the old instance to your local machine: scp -i {private-key-ssh-file} ec2-user@{old-instance-hostname}:/home/ec2-user/gdotv/data/postgres-data.tar.gz .
  • Copy the database backup from your local machine to the new instance: scp -i {private-key-ssh-file} postgres-data.tar.gz ec2-user@{old-instance-hostname}:/home/ec2-user/gdotv/data/postgres-data.tar.gz
• SSH into your new EC2 instance and stop the G.V() application as instructed above.
• Remove the current postgres-data folder in the new EC2 instance: sudo rm -r /home/ec2-user/gdotv/data/postgres-data
• Unzip the copied postgres-data.tar.gz file: tar -xvzf postgres-data.tar.gz
• Restart the G.V() application: cd /home/ec2-user/gdotv/scripts && ./start-gdotv.sh

Your data has been successfully migrated to the new instance. Terminate the old EC2 instance to finalize the upgrade. Note that the password on the new EC2 instance will be reset to the instance ID by default, so you may need to change the password following instructions at Modifying the G.V() authentication credentials

Backup and restore data

We recommend backing up your G.V() data regularly in the event of a failure in region or availability zone to allow you to quickly recover from such scenario. There are two approaches you can take to backup and restore G.V() data which we describe below.

Backup and restore using EBS snapshots

The simplest way of configuring a backup process for the G.V() application is to schedule regular EBS snapshots for the root volume of the G.V() EC2 instance.

Doing so allows you to backup all database and configuration files on the root volume and easily restore them to a separate EC2 instance (or the current) one using the EC2 console's built-in EBS snapshot functionality.

This process is described in details in the official EC2 documentation.

Backup and restore using S3

An alternative method to backup and restore G.V()'s database is to regularly copy the Postgres data to an S3 bucket which can b used to restore the data from.

For more details on how to access the G.V() instance's Postgres data please refer to (Performing an AMI Update)[#performing-an-ami-update] in which we outline a process to transfer data between instances.

Troubleshooting

The application is not accessible over port 443

Failure to reach the G.V() web application can be due to:

• an inbound network configuration on your EC2 instance not allowing or blocking access to port 443. To check what rules are configured on your EC2 instance, refer to [https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-security-groups.html].
• one or more G.V() application containers being stopped. Rebooting the EC2 instance will restart the application. Should the issue persist, contact us at support@gdotv.com.

The application is stating that AWS Marketplace License Validation failed

Should the EC2 instance be misconfigured and not permit access to AWS License Manager for license verification purposes, clear instructions will be displayed directly on the G.V() application stating the nature of the issue and steps to remediate.

For more details on how to configure G.V() at launch to allow license validation, check Configuring the IAM role for the instance

Additional support

For any support queries, email us at support@gdotv.com. Support is free and we answer all queries within one business day.