gdotv Documentation

Appearance

Using gdotv on AWS Marketplace ​

Prefer a container deployment?

This page describes the EC2 AMI deployment of gdotv. For container-based deployments, see gdotv on AWS Marketplace (ECS) for the simplest serverless (AWS Fargate) deployment, or gdotv on AWS Marketplace (EKS) for a Kubernetes-based deployment with horizontal scaling and high availability.

Running an older AMI version?

This page describes the current generation of the gdotv AMI. If your instance was launched from a legacy AMI version (up to 3.4x — the stack living under /home/ec2-user/gdotv with start-gdotv.sh/stop-gdotv.sh scripts), see Migrating from a legacy AMI instance.

gdotv 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 for teams, 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. It is also compatible with Google Cloud Spanner Graph, Dgraph, Oracle Graph 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 queries, and run them against your database
  • Write and run Cypher queries on Amazon Neptune, Puppygraph and many more
  • 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 over an EC2 instance, exposing a web service over port 443, protected by username/password authentication, from which you can access our application's web interface.

Deploying a gdotv instance ​

To deploy gdotv, 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 gdotv
  • 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 gdotv. This process may take up to a couple minutes to complete.
  • Click on Continue to Configuration
    • Leave the default fulfillment 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 gdotv EC2 instance to perform operations such as version upgrades 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 gdotv 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. It will be enough storage for any amount of users.
  • Under Advanced Details:
    • On the IAM instance field, follow the instructions at Configuring the IAM role for the instance to create the optional IAM instance profile to run gdotv on EC2
    • Set Metadata response hop limit to 2. gdotv runs in a container, one network hop away from the instance metadata service — with the default hop limit of 1, the application cannot retrieve the instance role's credentials (license checks and Amazon Neptune IAM authentication would silently fail).
  • Click Launch instance

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 instance starts.

Make a note of the EC2 instance id as you will need it to authenticate to gdotv. 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.

Allocate an Elastic IP right after deployment

By default the instance gets a temporary public IPv4 address and DNS name, which change 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, associate an Elastic IP address with the instance right after deployment.

Pricing ​

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

Sizing Guide ​

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

Instance TypeConcurrent usersProduct cost per hour
t3.mediumUp to 3 users$0.32
t3.largeUp to 5 users$0.64
t3.xlargeUp to 10 users$1.28
t3.2xlargeUp to 15 users$2.56
m5.largeUp to 5 users$0.80
m5.xlargeUp to 10 users$1.60
m5.2xlargeUp to 15 users$3.20
m5.4xlargeOver 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 ​

gdotv runs on an Ubuntu 24.04 LTS EC2 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 AMI — 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.

gdotv VM architecture on AWS

Common deployment issues ​

I have deployed gdotv over a public EC2 hostname but I can't reach it on port 443 or 22 (or both) ​

If you cannot access your gdotv instance over its public EC2 instance hostname, you should investigate the following:

I have deployed gdotv but there is no public EC2 hostname assigned to the EC2 instance ​

Your organization may have disabled public endpoints on EC2 by default - you will need to either explicitly enable it in the deployment configuration in the EC2 console when creating a new gdotv instance, or modify your already deployed EC2 instance to enable a public endpoint.

gdotv is failing to retrieve EC2 IAM Instance Profile credentials ​

Failure to retrieve EC2 IAM Instance Profile Credentials is typically due to the Instance Metadata Service Version 2 (IMDSv2) API not beingavailable on your host. IMDSv2 is required for gdotv to retrieve your instance profile credentials as it internally uses AWS SDK v2. To test that the API is available on your host, you can run the following command:

TOKEN=curl -X PUT "<http://169.254.169.254/latest/api/token>" -H "X-aws-ec2-metadata-token-ttl-seconds: 21600" \
&& curl -H "X-aws-ec2-metadata-token: $TOKEN" http://169.254.169.254/latest/meta-data/iam/security-credentials/

If the above request responds with a 404 error, this indicates the API is unavailable on the host and that IMDSv2 is therefore not enabled.

The other common cause is a metadata response hop limit of 1: the request works from the instance shell but not from gdotv's container (one extra network hop). Set the hop limit to 2:

aws ec2 modify-instance-metadata-options --instance-id <id> --http-put-response-hop-limit 2

Accessing gdotv on your web browser ​

Upon completion, the newly created EC2 instance with gdotv 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}.

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 instance starting. Refresh the page.

By default, gdotv 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 gdotv at a specific location on your instance, 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 as follows:

  • Username: gdotv
  • Password: the ID of your EC2 instance (e.g. i-0a25b19de55204410). You can find the ID of your EC2 instance from the EC2 console. The full sign-in details (URL, username and initial password) are also printed to the instance's system log a few minutes after launch — in the EC2 console, select the instance and open Actions → Monitor and troubleshoot → Get system log.

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

When navigating to gdotv while unauthenticated, you will be presented with the following login screen:

gdotv Login Screen

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, please refer to the official Keycloak documentation.

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

  1. Navigate to https://{instance hostname}/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 gdotv EC2 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://{instance hostname}/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).

Configuring the IAM role for the instance ​

gdotv prefers (but does not require) that the EC2 instance has an IAM role with the AWSLicenseManagerConsumptionPolicy policy attached. This role is useful for gdotv to perform checks against AWS License Manager to ensure your license is valid and run from our AWS Marketplace AMI. This role can be further supplemented with policies to enable IAM access to your Amazon Neptune clusters and graphs with IAM authentication enabled, so we recommend taking this configuration step during the initial setup.

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

Selecting or creating an IAM role

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:

Selecting the trusted entity type

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 the role

TIP

Configuring AWSLicenseManagerConsumptionPolicy access is optional, but since Amazon Neptune has its own IAM authorization policy requirements it is recommended to configure an authorization policy spanning Amazon Neptune permissions as well as license checks.

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 gdotv 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 gdotv 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 gdotv 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 and Amazon Neptune Analytics graphs, 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:*",
                "neptune-graph:*"
            ],
            "Resource": [
                "<ENTER COMMA SEPARATED LIST OF AMAZON NEPTUNE ARNs TO ALLOW gdotv 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 or Amazon Neptune Graph 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} (Amazon Neptune) arn:aws:neptune-graph:{region}:{aws-account-number}:graph/{graph-id} (Amazon Neptune Analytics)

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

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.

Setting the EC2 instance role

How gdotv uses the role ​

gdotv's backend uses the AWS SDK's default credential chain: it retrieves the instance role's temporary credentials from the instance metadata service (IMDSv2) automatically — no keys are ever stored on the instance. Two conditions must hold:

  • An IAM instance profile is attached to the instance (it can be attached to a running instance: EC2 console → Actions → Security → Modify IAM role)
  • The metadata response hop limit is 2 — the application runs in a container, one hop away from the metadata service. Check and fix on a running instance with:
    aws ec2 modify-instance-metadata-options --instance-id <id> --http-put-response-hop-limit 2

No application restart is needed after attaching or changing the role — credentials are fetched on demand.

Connecting to your gdotv EC2 Instance via EC2 Instance Connect ​

The gdotv AWS Marketplace AMI has EC2 instance connect binaries installed by default, allowing you to SSH to it directly via the EC2 Console. To use EC2 Instance Connect, please refer to the official AWS documentation.

The username to use for EC2 Instance Connect is ubuntu.

Connecting to your gdotv EC2 Instance via SSH ​

To connect to your gdotv 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 ubuntu

From a terminal, run the following command:

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

Upon login, a welcome message summarizes the essential operations available on the instance: TLS certificate deployment, version upgrades, service management and more.

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 uses a self-signed certificate to serve its web interface over HTTPS. You may wish to configure your own trusted certificate, according to your organization's security policy.

To do so:

  1. Assign a domain name owned by your organization to the instance (we recommend an Elastic IP so the address survives instance stops), 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.

For production deployments we recommend not managing certificate files on the instance at all — see Reference architecture: custom domain with ALB and ACM below, which lets AWS issue and renew the certificate automatically.

Configuring a custom hostname for gdotv ​

For security reasons, Keycloak requires strict validation on its hostname. This means that if you're configuring a custom hostname for your gdotv deployment, you will also need to reflect this configuration change on gdotv.

  1. Create a DNS record pointing your domain at the instance (an Elastic IP is recommended), and wait for it to resolve
  2. SSH into the instance and edit /opt/gdotv/.env (as root), setting:
    GDOTV_HOSTNAME=<your-domain>
    The custom hostname should not include any port or protocol, e.g. application.gdotv.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

To revert the change, set GDOTV_HOSTNAME back to the instance's public hostname and restart again.

Reference architecture: custom domain with ALB and ACM ​

For production deployments, the recommended way to give gdotv a custom domain with a trusted certificate is to put an Application Load Balancer in front of the instance and let AWS manage DNS and TLS end to end:

  • AWS Certificate Manager (ACM) issues the public certificate and renews it automatically — no certificate files to maintain on the instance
  • The ALB terminates public TLS and forwards to the instance over HTTPS; the ALB does not validate the instance's self-signed certificate, so that internal hop needs no configuration
  • Route 53 (or your DNS provider) points your domain at the ALB

Setup:

  1. ACM: request a public certificate for your domain (e.g. gdotv.example.com) with DNS validation, and create the validation CNAME record ACM shows you
  2. Target group: target type Instances, protocol HTTPS, port 443; register the gdotv instance. Health check: protocol HTTPS, path /api/application/is_ready, success code 200 (this endpoint is unauthenticated and only returns 200 once the application is fully up)
  3. Load balancer: internet-facing Application Load Balancer with an HTTPS : 443 listener using the ACM certificate, forwarding to the target group. The selected subnets must include the instance's Availability Zone — otherwise the target shows as unused and requests return 503. Consider raising the idle timeout (e.g. 180 s) for long-running queries.
  4. DNS: create an alias (or CNAME) record pointing your domain at the ALB's DNS name
  5. 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
    The regenerated self-signed certificate only secures the internal ALB → instance hop; browsers only ever see the ACM certificate.
  6. Lock down: edit the instance's security group so port 443 is only reachable from the ALB's security group, and remove the public port-80 rule

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 you may need to perform:

  • Application updates: upgrading the gdotv software itself, in place
  • Amazon Machine Image (AMI) updates: new versions of the AMI published on the Marketplace, carrying operating system and dependency updates

Performing an application update ​

Take note of the latest version number for gdotv, as stated in the update announcement email from AWS, which should be in the x.y.z format. SSH into the instance and run:

sudo gdotv-upgrade <version>

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.

Some releases need an AMI update

gdotv-upgrade replaces the gdotv application only. Some releases also change the components around it (the web proxy, Keycloak, the operating system), and those changes only reach you through a new AMI. The release notes say when this is the case. For example, the MCP server and live dashboard refresh introduced in 3.88.151 need the 3.88.151 AMI: an instance upgraded in place runs the new application without them. For those releases, perform an AMI update instead.

Performing an AMI update ​

To move to a newly published AMI version, you launch a new instance and carry your data and your team's accounts across to it. Your graph databases are not touched.

What moves across

  • Everything gdotv stores: connections, saved queries, dashboards, reports, query history, workspace settings and the audit trail
  • Your team's login accounts, with their passwords and roles. Each account keeps its identity, so everyone finds their own work on the new instance.

What you set up again on the new instance

  • The IAM role, if your instance uses one to reach Amazon Neptune (see Configuring the IAM role for the instance)
  • A custom hostname and TLS certificate, if you configured them (see Configuring a TLS certificate and Configuring a custom hostname for gdotv)
  • Any changes you made to Keycloak beyond adding users: identity providers (single sign-on), groups, email (SMTP) settings, password policies. Recreate them before importing users (step 5), so that users linked to them import cleanly.
  • AI assistants connected to gdotv's MCP server: reconnect them to the new instance

Changes your team makes on the old instance after step 2 are not carried over, so plan a short window in which nobody uses it.

  1. Launch the new instance from the latest AMI version, at the same size or larger, in the same VPC and security group, following Deploying a gdotv instance. Wait for first boot to finish (about three minutes) and check that https://<new-address>/ loads.

  2. Export from the old instance. SSH into the old instance and run:

    bash
    mkdir -p ~/gdotv-migration && chmod 777 ~/gdotv-migration
cd /opt/gdotv
sudo docker exec gdotv-postgres pg_dump -U postgres --no-owner --no-privileges gdotv | gzip > ~/gdotv-migration/gdotv-db.sql.gz
sudo docker compose stop keycloak
sudo docker compose run --rm --no-deps -v ~/gdotv-migration:/migration keycloak \
  export --realm gdotv --users same_file --file /migration/gdotv-realm.json
sudo docker compose start keycloak

    The first command dumps gdotv's database. The others export the gdotv Keycloak realm with its users, which takes Keycloak offline for a few seconds; the export ends with Export finished successfully. The gdotv-migration folder now holds gdotv-db.sql.gz and gdotv-realm.json. The realm file contains your users' password hashes: treat it as a secret.

  3. Copy the folder to the new instance, for example through your workstation:

    bash
    scp -r -i <path-to-ssh-private-key> ubuntu@<old-instance-hostname>:gdotv-migration .
scp -r -i <path-to-ssh-private-key> gdotv-migration ubuntu@<new-instance-hostname>:

  4. Import the data on the new instance:

    bash
    sudo gdotv-migrate-import ~/gdotv-migration/gdotv-db.sql.gz

    Give the path in full, as above. The importer backs up the new instance's own (empty) database, replaces it with your data, restarts gdotv and waits for it to report healthy; if anything fails, it restores the previous state. On first start, gdotv upgrades the data from the old version automatically.

  5. Import the users on the new instance:

    bash
    cd /opt/gdotv
jq '{ifResourceExists: "OVERWRITE",
     users: [.users[] | select(.serviceAccountClientId == null)
             | .realmRoles = ((.realmRoles // []) | map(if . == "admin" then "gdotv-realm-admin" else . end) | unique)]}' \
  ~/gdotv-migration/gdotv-realm.json > ~/gdotv-migration/gdotv-users.json
sudo docker exec -i -e KC_ADMIN_PASSWORD="$(sudo grep ^KEYCLOAK_ADMIN_PASSWORD= .env | cut -d= -f2-)" gdotv-keycloak bash -c '
  kc=/opt/keycloak/bin/kcadm.sh
  cat > /tmp/gdotv-users.json
  $kc config credentials --server http://localhost:8080 --realm master --user admin --password "$KC_ADMIN_PASSWORD"
  $kc create partialImport -r gdotv -f /tmp/gdotv-users.json -o
  rm -f /tmp/gdotv-users.json
  for u in $($kc get roles/gdotv-admin/users -r gdotv -q max=10000 --fields username --format csv --noquotes); do
    $kc add-roles -r gdotv --uusername "$u" --rolename gdotv-realm-admin && echo "gdotv-realm-admin: $u"
  done' < ~/gdotv-migration/gdotv-users.json

    The import reports how many users it added and overwrote. Your old gdotv account replaces the new instance's, so it signs in with its existing password, not the new instance ID. The last lines give every gdotv administrator the gdotv-realm-admin role, which lets them manage users from gdotv's user menu.

  6. Check the new instance: sign in with your usual account, and check that your connections, saved queries and dashboards are there.

  7. Switch your team over. Move your Elastic IP or DNS record to the new instance, or share its new address. If the address changes, see The instance's public address changed.

  8. Clean up. Delete the gdotv-migration folder from both instances and your workstation (sudo rm -rf ~/gdotv-migration). Keep the old instance stopped (not terminated) for a few days as a fallback, then terminate it.

Migrating from a legacy AMI instance ​

Instances launched from legacy AMI versions (up to 3.4x) run an older stack layout: the application lives under /home/ec2-user/gdotv, is managed by start-gdotv.sh/stop-gdotv.sh scripts, and runs five containers including a gdotv-developer application container. The current AMI generation uses a different architecture (one shared PostgreSQL with least-privilege roles, per-instance random secrets, /opt/gdotv managed by systemd), so moving to it is a launch-new-and-migrate upgrade, not an in-place one.

TIP

In-place application updates on a legacy instance keep working — but the legacy stack layout itself is frozen, and new AMI versions will only ship the new architecture. We recommend migrating at your convenience.

To migrate:

  1. Launch a new instance from the latest AMI version (same or larger size). Wait two to three minutes for first boot and verify https://<new-address>/ loads.
  2. On the old instance, dump the gdotv database:
    docker exec gdotv-postgres pg_dump -U postgres --no-owner --no-privileges postgres | gzip > gdotv-legacy.sql.gz
  3. Copy gdotv-legacy.sql.gz to the home directory of the new instance (scp), then on the new instance (give the path in full, as shown):
    sudo gdotv-migrate-import ~/gdotv-legacy.sql.gz
    The importer backs up the new instance's (empty) database first, replaces it with your data, restarts the app and health-checks it — with printed rollback instructions if anything fails.
  4. Recreate your team's login users on the new instance (see Managing users) — Keycloak accounts live in the legacy instance's second PostgreSQL container and are not carried over by the database dump.
  5. Repoint your DNS record or move the Elastic IP (updating GDOTV_HOSTNAME and the TLS certificate as described above), or simply switch to the new instance's public address.
  6. Keep the old instance stopped (not terminated) for a few days as a fallback, then terminate it.

Your graph databases themselves are not touched by any of this — gdotv only stores connection configuration, users' workspace settings and saved queries.

Version note

The import is most predictable when the old instance was last upgraded to the same gdotv version as the new AMI; older dumps are migrated forward automatically by the application's normal schema upgrade on first start.

Backup and restore data ​

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:

  • EBS snapshots (simplest): schedule regular EBS snapshots of the instance's root volume, and restore by creating a new instance from the snapshot. This process is described in the official EC2 documentation.
  • 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:
    sudo docker exec gdotv-postgres pg_dumpall -U postgres | gzip > gdotv-backup-$(date +%F).sql.gz
    and copy it off the instance, for example to an S3 bucket.

Troubleshooting ​

The application is not accessible over port 443 ​

Failure to reach the gdotv web application can be due to:

The application shows "gdotv is starting up" ​

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

The instance's public address changed ​

If the instance was running without an Elastic IP and was stopped and started, it received a new public IPv4 address and DNS name. The instance reconfigures itself for the new address automatically at startup — simply access gdotv at the new address shown in the EC2 console, and associate an Elastic IP so the address stops changing (after associating it, reboot the instance so it picks up the Elastic IP address). 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-public-dns-or-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 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 gdotv application stating the nature of the issue and steps to remediate.

For more details on how to configure gdotv 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.