Using gdotv on Google Cloud Marketplace (Virtual Machine)

Looking for the Kubernetes version?

This page describes the virtual machine deployment of gdotv Team Edition — a single VM running the full application stack, deployed in a few clicks. If you'd rather run gdotv on your own GKE cluster, see gdotv on Google Cloud Marketplace (Kubernetes).

gdotv Team Edition is available as a virtual machine product on the Google Cloud Marketplace.

It's a graph database client for teams, perfect for developers looking to start on a graph project or support an existing one. It is compatible with Google Cloud Spanner Graph, Amazon Neptune, Neo4j, Memgraph, FalkorDB, JanusGraph, Gremlin Server, Dgraph and many more graph databases.

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

With gdotv you can:

• View your graph database's schema in 1 click
• Write and run Gremlin, Cypher, SPARQL, GQL and DQL queries against your database
• Visualize query results across a variety of formats such as graph visualization, JSON and tables
• Explore 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 as a single Compute Engine instance exposing the gdotv web interface over HTTPS (port 443), protected by username/password authentication.

Deploying a gdotv instance

To deploy gdotv from the Google Cloud Marketplace, follow these steps:

1. Navigate to the gdotv Team Edition listing on the Google Cloud Marketplace
2. Click Launch
3. Select or create a GCP project for the deployment
4. Configure the deployment parameters:
   • Deployment name: a name for this gdotv deployment
   • Zone: the zone to deploy into — we recommend using the same region as your database(s)
   • Machine type: e2-standard-4 (4 vCPU, 16 GB) is the recommended default; see the sizing guide. A minimum of 8 GB of memory is required.
   • Boot disk: the default 30 GB balanced persistent disk is enough for any team size
   • Networking: leave the default firewall rules enabled (they allow HTTPS on port 443 and HTTP on port 80, which only redirects to HTTPS). You can optionally restrict the allowed source IP ranges to your organization's addresses.
5. Click Deploy

The deployment is fully automatic. On first boot the instance generates its per-instance secrets and TLS certificate, then starts the application — gdotv is typically ready two to three minutes after the VM starts. The post-deployment page in the Google Cloud console shows the site address and login instructions.

Reserve a static IP right after deployment

The deployment assigns an ephemeral external IP, which changes whenever the instance is stopped and started. The instance re-detects its address at every boot and reconfigures itself (TLS certificate, authentication hostname) automatically — but the URL your team uses still changes, breaking bookmarks and DNS records. To keep the address stable, promote the instance's ephemeral IP to a static one right after deployment (VPC network → IP addresses → Reserve, or gcloud compute addresses create --addresses <current-ip> --region <region>).

Pricing

gdotv Team Edition is priced per hour of VM runtime, based on the instance's vCPU and memory, and billed through your Google Cloud account. Charges only accrue while the instance is running — a stopped instance costs nothing in software fees. Google's standard infrastructure charges (VM, disk, network) are billed separately by Google Cloud.

Sizing Guide

The sizing guide below indicates how many users can use gdotv concurrently for a given machine type, and the corresponding software cost.

Machine type	vCPU / Memory	Concurrent users	Software cost per hour
e2-standard-2	2 vCPU / 8 GB	Up to 5 users	$0.60
e2-standard-4 (recommended)	4 vCPU / 16 GB	Up to 10 users	$1.20
e2-standard-8	8 vCPU / 32 GB	Up to 20 users	$2.40
e2-standard-16	16 vCPU / 64 GB	Over 20 users	$4.80

Regardless of the machine type, the default 30 GB boot disk is enough to run the service smoothly.

Architecture

gdotv runs on an Ubuntu 24.04 LTS Compute Engine instance with four Docker containers managed by Docker Compose and a systemd service (gdotv.service):

• gdotv-team: the gdotv web application
• gdotv-postgres: a PostgreSQL instance storing configuration data for gdotv and Keycloak (in separate databases with least-privilege roles)
• gdotv-keycloak: a Keycloak instance providing gdotv with user authentication and federation features, which can be configured further to enable Single Sign On authentication flows, or username/password/2FA login
• gdotv-nginx: an NGINX reverse proxy fronting the application over port 443, with TLS enabled by default

All container images are baked into the VM image — the instance needs no registry access to start, and no software is downloaded at boot. All secrets (database passwords, Keycloak credentials) are randomly generated per instance at first boot and stored in /opt/gdotv/.env, readable by root only.

Accessing gdotv on your web browser

Once deployed, gdotv is served at the instance's external IP address: https://<external-ip>/. The external IP is shown on the deployment page and in the Compute Engine console.

TIP

If you see a "gdotv is starting up" page right after deployment, the application stack is still initializing — this resolves itself within two to three minutes of the VM starting. Refresh the page.

By default, gdotv uses a self-signed TLS certificate to enable traffic over HTTPS. Since the certificate is self-signed, your browser will warn that the connection may not be private. To proceed, click Advanced, then Proceed to {external-ip} (unsafe).

You can replace the self-signed certificate with your own trusted certificate, as described in Configuring a TLS certificate.

Authenticating to gdotv

gdotv uses username/password authentication via Keycloak to secure access to its interface. The initial credentials are:

• Username: gdotv
• Password: the numeric instance ID of your Compute Engine instance

You can find the instance ID in the Google Cloud console (Compute Engine → VM instances → click your instance → the Instance Id field under Basic information), or with:

gcloud compute instances describe <vm-name> --zone <zone> --format='value(id)'

The initial password is temporary: you will be required to set a new password at first login.

The initial gdotv user is an application administrator (it carries the gdotv-admin role).

Managing users

Keycloak is a powerful Identity & Access Management solution that provides user federation, management and authentication functionality. You can use it to add users for your team, and to configure advanced authentication flows such as Single Sign On via your identity provider. For more details, refer to the official Keycloak documentation.

To manage users, log in to the Keycloak admin console:

1. Navigate to https://<external-ip>/super-admin
2. Log in as user admin, with the password stored as KEYCLOAK_ADMIN_PASSWORD in /opt/gdotv/.env on the instance (see Connecting to your instance via SSH):

   sudo grep KEYCLOAK_ADMIN_PASSWORD /opt/gdotv/.env

3. In the realm selector (top left), switch from master to the gdotv realm
4. Under Users, create a user for each team member. Assign the gdotv-admin realm role to users who should administer gdotv itself.

TIP

https://<external-ip>/admin is a shortcut to the gdotv realm's own admin console. It accepts logins from gdotv realm users that hold the realm's admin role — you can grant that role to a trusted user to delegate user management without sharing the master Keycloak credentials.

We recommend changing the master admin password after initial setup (in the master realm: top-right menu → Manage account → Account security → Signing in).

Service account access to Google Cloud databases

To connect gdotv to Google Cloud databases that authenticate with IAM — such as Spanner Graph — use the service account attached to the instance. gdotv's backend uses Application Default Credentials: it obtains tokens for the attached service account from the metadata service automatically, so no key files are ever stored on the instance.

Two things must both be in place:

1. Access scopes on the instance. Scopes are a legacy ceiling on what the VM's tokens can reach, and the Compute Engine defaults do not include database access. Give the instance the cloud-platform scope (the recommended modern setting — actual permissions are then governed entirely by IAM):

   gcloud compute instances stop <vm-name> --zone <zone>
   gcloud compute instances set-service-account <vm-name> --zone <zone> --scopes cloud-platform
   gcloud compute instances start <vm-name> --zone <zone>

   (Scopes can only be changed while the instance is stopped.)
2. IAM roles on the service account. Grant the attached service account the roles your databases require — for Spanner Graph, roles/spanner.databaseUser on the instances or databases gdotv should access.

You can verify the current scopes with gcloud compute instances describe <vm-name> --zone <zone> --format 'value(serviceAccounts[0].scopes)'. No application restart is needed after IAM changes — credentials are fetched on demand.

Connecting to your gdotv instance via SSH

Day-to-day use of gdotv never requires SSH access — but administrative operations (TLS certificate deployment, version upgrades, custom hostname) do. To connect, use the SSH button next to the instance in the Compute Engine console, or:

gcloud compute ssh <vm-name> --zone <zone>

Upon login, a welcome message summarizes the essential operations available on the instance.

Managing the gdotv service

The application stack is managed by systemd and starts automatically on boot. From an SSH session:

systemctl status gdotv          # service and container status
sudo systemctl stop gdotv       # stop the application
sudo systemctl start gdotv      # start the application
sudo systemctl restart gdotv    # restart (e.g. after configuration changes)
docker ps                       # individual container status
docker logs -f gdotv-team       # follow application logs

Configuring a TLS certificate

By default, gdotv serves its web interface with a self-signed certificate. To use your own trusted certificate:

1. Assign a domain name owned by your organization to the instance's external IP address, and follow Configuring a custom hostname
2. Copy your certificate and private key, in PEM format, over the following files on the instance:
   • Certificate: /opt/gdotv/certs/tls.crt
   • Private key: /opt/gdotv/certs/tls.key
3. Restart the application: sudo systemctl restart gdotv

Startup should complete within a minute.

TIP

We recommend reserving a static external IP for the instance (Compute Engine → IP addresses → Reserve) before creating the DNS record, so the address survives instance stops and starts.

For production deployments, consider not managing certificate files on the instance at all — see Reference architecture: custom domain with a Google-managed certificate.

Configuring a custom hostname for gdotv

For security reasons, Keycloak strictly validates the hostname it is served under. If you assign a custom domain name to your gdotv instance, you must reflect it in the configuration:

1. Create a DNS record pointing your domain at the instance's external IP, and wait for it to resolve
2. SSH into the instance and edit /opt/gdotv/.env (as root), setting:

   GDOTV_HOSTNAME=<your-domain>

   The hostname must not include a protocol or port, e.g. graph.example.com
3. Deploy a TLS certificate valid for that domain as described in Configuring a TLS certificate
4. Restart the application: sudo systemctl restart gdotv

Reference architecture: custom domain with a Google-managed certificate

For production deployments, the recommended way to give gdotv a custom domain with a trusted certificate is to put a global external Application Load Balancer in front of the instance and let Google Cloud manage TLS:

• A Google-managed SSL certificate is issued and renewed automatically — no certificate files to maintain on the instance
• The load balancer terminates public TLS and forwards to the instance over HTTPS; it does not validate the instance's self-signed certificate, so that internal hop needs no configuration

Setup:

1. Instance group: create an unmanaged instance group in the instance's zone, add the gdotv instance, and define a named port https:443
2. Health check: protocol HTTPS, port 443, request path /api/application/is_ready (unauthenticated; returns 200 only once the application is fully up). Add a firewall rule allowing TCP 443 to the instance from 130.211.0.0/22 and 35.191.0.0/16 — the ranges Google's front ends and health checkers connect from
3. Backend service: global, protocol HTTPS, named port https, using the health check; add the instance group as its backend. Raise the backend timeout (e.g. 300 s) for long-running queries
4. Frontend: reserve a global static IP, create a Google-managed SSL certificate for your domain, and create the HTTPS target proxy + forwarding rule on port 443 (the console's Load balancing wizard walks through all of this)
5. DNS: create an A record pointing your domain at the load balancer IP. The managed certificate only becomes ACTIVE once the domain resolves to the load balancer — typically 15–60 minutes
6. On the instance — both steps are required: Keycloak validates the public hostname, and gdotv's internal call to Keycloak validates the instance certificate against it:

   sudo sed -i "s|^GDOTV_HOSTNAME=.*|GDOTV_HOSTNAME=gdotv.example.com|" /opt/gdotv/.env
   sudo rm /opt/gdotv/certs/tls.crt /opt/gdotv/certs/tls.key
   sudo /opt/gdotv/scripts/firstboot.sh    # regenerates the self-signed cert for the new hostname
   sudo systemctl restart gdotv

7. Lock down: remove the deployment's public 443/80 firewall rules — traffic then only reaches the instance through Google's front-end ranges

Upgrading to a new version of gdotv

gdotv receives frequent updates with new features and improvements. We recommend keeping up to date with the latest version. There are two types of upgrades:

• Application updates: upgrading the gdotv software itself, in place
• VM image updates: new versions of the VM image published on the Marketplace, carrying operating system and dependency updates

Performing an application update

SSH into the instance and run:

sudo gdotv-upgrade <version>

with the version number from the update announcement (e.g. 3.79.2). The upgrade tool:

1. Backs up both databases to /var/lib/gdotv/backups/ — and aborts the upgrade if the backup fails
2. Pulls the new application image and applies it
3. Waits for the application to report healthy
4. Rolls back to the previous version automatically if the new version fails to start

Each upgrade is recorded in /var/lib/gdotv/deploy-history.log. Expected downtime is under two minutes.

Performing a VM image update

To move to a newly published VM image version, deploy a new instance following Deploying a gdotv instance, then migrate your data:

1. On the old instance: docker exec gdotv-postgres pg_dump -U postgres --no-owner --no-privileges gdotv | gzip > gdotv-backup.sql.gz
2. Copy the file to the new instance (e.g. gcloud compute scp)
3. On the new instance: sudo gdotv-migrate-import gdotv-backup.sql.gz
4. Recreate your team's login users on the new instance (see Managing users), verify everything works, then delete the old instance

Backup and restore

gdotv only stores connection configurations, user workspace settings, saved queries and dashboards — your graph databases themselves are never stored on the instance. We nonetheless recommend regular backups:

• Disk snapshots (simplest): schedule snapshots of the instance's boot disk in the Google Cloud console. To restore, create a new instance from the snapshot.
• Database dumps (portable): the pre-upgrade dumps in /var/lib/gdotv/backups/ are full backups (pg_dumpall); you can produce one at any time with:

  docker exec gdotv-postgres pg_dumpall -U postgres | gzip > gdotv-backup-$(date +%F).sql.gz

  and copy it off the instance (e.g. to a Cloud Storage bucket).

Troubleshooting

The application is not reachable over port 443

• Verify the instance is running and systemctl status gdotv reports active
• Check that the deployment's firewall rule allowing TCP 443 exists and that its source ranges include your address (VPC network → Firewall)
• If your organization uses VPC Service Controls or restricts external IPs, consult your network administrators

The application shows "gdotv is starting up"

The stack is initializing — normal for two to three minutes after the VM starts or restarts. If it persists beyond five minutes, SSH in and check systemctl status gdotv and docker logs gdotv-team.

The instance's external IP address changed

If the instance was running on an ephemeral external IP and was stopped and started, it received a new IP. The instance reconfigures itself for the new address automatically at startup — simply access gdotv at the new IP shown in the console, and promote it to a static IP so the address stops changing. Automatic re-alignment deliberately never touches a custom hostname you configured.

If the application is still configured for the old address (for example on an instance created before this behavior shipped), re-align manually — SSH in and run:

sudo sed -i "s|^GDOTV_HOSTNAME=.*|GDOTV_HOSTNAME=<new-external-ip>|" /opt/gdotv/.env
sudo rm /opt/gdotv/certs/tls.crt /opt/gdotv/certs/tls.key
sudo /opt/gdotv/scripts/firstboot.sh    # regenerates the TLS certificate for the new address
sudo systemctl restart gdotv

The application is stating that license verification failed

The instance verifies it is running from a Google Cloud Marketplace image. If verification fails, the application displays instructions describing the issue. This can happen if the VM was created by copying the disk to a non-Marketplace image rather than deploying through the Marketplace. Contact us at support@gdotv.com if you believe verification is failing incorrectly.

Additional support

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