Altair GraphQL Client on AWS User Guide

Overview

Altair GraphQL Client is an open-source, self-hosted GraphQL IDE for building, sending and inspecting GraphQL requests. It gives you a full-featured query editor with syntax highlighting, autocompletion and inline documentation driven by live schema introspection, so you can explore an API's types, queries, mutations and subscriptions as you write. Set custom headers and variables, run real-time subscriptions, view formatted responses, keep a searchable history, and organise reusable requests into collections. The self-hosted build is a purely client-side web app: it runs entirely in your own browser and connects directly to whatever GraphQL endpoint you point it at, so nothing you send passes through a third party.

The cloudimg image serves the official pre-built Altair bundle with nginx on port 80, hardened and ready on first boot. Because Altair's self-hosted build has no authentication of its own, this image is secure by default: nginx gates the whole app behind per-instance HTTP Basic-Auth, and a unique password is generated on the first boot of every instance and written to a root-only file, so no two instances share a credential. A public, unauthenticated health endpoint is exposed at /healthz. Built from the official altair-static distribution (Altair 8.5.7, MIT), backed by 24/7 cloudimg support.

What is included:

• Altair GraphQL Client 8.5.7 static bundle, from the official altair-static distribution, served from /var/www/altair
• nginx on :80 as the single public listener, gating the app behind per-instance HTTP Basic-Auth
• A public, unauthenticated health endpoint at /healthz
• A first-boot service that generates a unique admin password into a root-only 0600 file
• nginx.service + altair-graphql-firstboot.service as systemd units, enabled on every boot
• 24/7 cloudimg support

Prerequisites

An AWS account, an EC2 key pair in the target region, and a VPC subnet. Altair serves static files and is light on resources; the recommended instance type is m5.large. Security group inbound: allow 22/tcp from your management network and 80/tcp for the IDE. Altair serves plain HTTP on port 80; for production, terminate TLS in front of it with your own certificate or an Application Load Balancer, and restrict the security group to trusted source IP ranges.

Connecting to your instance

Connect over SSH on port 22 as the default login user for the OS variant you launched:

ssh ubuntu@<instance-public-ip>

Step 1 - Subscribe and launch from AWS Marketplace

Find the Altair GraphQL Client listing by cloudimg on AWS Marketplace and choose Continue to Subscribe, then Continue to Configuration and Continue to Launch. Pick the Ubuntu 24.04 AMI version, an m5.large instance type, your VPC subnet and key pair, and a security group that allows 22/tcp (from your network) and 80/tcp. Launch the instance.

To launch from the AWS CLI instead, subscribe to the product in the console first, then:

aws ec2 run-instances \
  --image-id <altair-graphql-ami-id> \
  --instance-type m5.large \
  --key-name <your-key-pair> \
  --security-group-ids <sg-allowing-22-and-80> \
  --subnet-id <your-subnet> \
  --tag-specifications 'ResourceType=instance,Tags=[{Key=Name,Value=altair-graphql}]'

Step 2 - Confirm the service is running

Altair is served by nginx, and a one-shot first-boot service prepares the per-instance login. Confirm both, and that nginx is the only public listener:

systemctl is-active nginx.service altair-graphql-firstboot.service
ss -tln | grep ':80 '
test -f /var/lib/cloudimg/altair-graphql-firstboot.done && echo "first boot complete"

nginx.service and altair-graphql-firstboot.service both report active, nginx is listening on :80, and the sentinel confirms first boot finished:

active
active
LISTEN 0      511          0.0.0.0:80        0.0.0.0:*
LISTEN 0      511             [::]:80           [::]:*
first boot complete

Step 3 - Verify the authentication gate

Altair has no login of its own, so nginx gates the whole app behind HTTP Basic-Auth. The public /healthz endpoint returns 200 without credentials, the app returns 401 without credentials, and 200 with the per-instance login:

curl -s -o /dev/null -w 'health: %{http_code}\n' http://127.0.0.1/healthz
curl -s -o /dev/null -w 'unauth: %{http_code}\n' http://127.0.0.1/
sudo bash -c 'U=$(grep ^ALTAIR_USERNAME= /var/lib/cloudimg/altair-credentials.txt | cut -d= -f2-); P=$(grep ^ALTAIR_PASSWORD= /var/lib/cloudimg/altair-credentials.txt | cut -d= -f2-); curl -s -o /dev/null -w "auth: %{http_code}\n" -u "$U:$P" http://127.0.0.1/'

You see health: 200, unauth: 401 and auth: 200 - proof the app is reachable only with the per-instance credential:

health: 200
unauth: 401
auth: 200

Step 4 - Read your per-instance login

The unique per-instance credential (username admin) is written to a root-only file on first boot. Check its mode, then read it:

sudo stat -c 'file mode: %a  owner: %U:%G' /var/lib/cloudimg/altair-credentials.txt

file mode: 600  owner: root:root

Read the file with sudo cat /var/lib/cloudimg/altair-credentials.txt. Its contents look like this (your password is unique to your instance):

# Altair GraphQL Client 8.5.7 on Ubuntu 24.04 (cloudimg AWS Marketplace image)
# Per-VM HTTP Basic-Auth credentials - UNIQUE to this instance, minted at first boot.

ALTAIR_URL=http://<instance-public-ip>/
ALTAIR_USERNAME=admin
ALTAIR_PASSWORD=<your-unique-password>

Step 5 - Open Altair

Browse to http://<instance-public-ip>/ in any modern browser. Your browser prompts for the HTTP Basic-Auth login: enter admin and the password from Step 4. Altair opens on its main IDE view - a GraphQL query editor on the left, a results panel on the right, and a sidebar for headers, history, variables and collections.

Step 6 - Run a query

Enter your GraphQL endpoint URL in the address bar at the top, type a query in the editor, and press Send Request (or Cmd/Ctrl + Enter). Altair sends the request straight from your browser to that endpoint and shows the formatted JSON response, the HTTP status and the round-trip time. In the example below the query { countries { code name emoji capital currency } } is run against a public GraphQL API and returns 200 with the data rendered in the results panel.

Step 7 - Explore the schema

Click Docs to open the schema documentation panel. Altair introspects the connected endpoint and lets you browse its root types, queries, mutations, fields and directives, with a search box to jump to any type. Combined with in-editor autocompletion, this makes it easy to explore an unfamiliar GraphQL API as you write.

Maintenance

• Data: Altair is client-side; every request is sent from your browser to the endpoint you choose and nothing is stored server-side. There is no database to back up.
• Change the login: the per-instance password lives in the nginx htpasswd file. To set your own, run sudo htpasswd -B /etc/nginx/.altair-htpasswd admin and follow the prompts, then sudo systemctl reload nginx.
• TLS and network: Altair serves plain HTTP on port 80; terminate TLS in front of it with your own certificate or an Application Load Balancer, and restrict the security group to trusted source IP ranges, before production use.
• Restart: sudo systemctl restart nginx.service if you need to bounce the web server.
• Security patches: unattended-upgrades remains enabled so the OS continues to receive security updates automatically.

Support

cloudimg provides 24/7 expert support for this image. Contact support@cloudimg.co.uk.

Altair GraphQL Client is open-source software released under the MIT License. cloudimg is not affiliated with, endorsed by, or sponsored by the Altair GraphQL project or its authors. This image packages the open-source Altair software for convenient deployment on AWS. All trademarks are the property of their respective holders.