Tailcall

Search the Marketplace for Tailcall on Ubuntu 24.04 and choose your VM size. Attach an NSG that allows TCP 22 (SSH) from your management network. Allow TCP 80 and 443 (the GraphQL endpoint) from the networks and applications that need to query it. In production, front port 80 with TLS (see Step 8).

RG="tailcall-prod"; LOCATION="eastus"; VM_NAME="tailcall-01" IMAGE_URN="sac1647283583153:tailcall-ubuntu-24-04:default:latest" SSH_KEY="$(cat ~/.ssh/id_rsa.pub)" az group create --name "$RG" --location "$LOCATION" az network vnet create -g "$RG" --name tailcall-vnet --address-prefix 10.90.0.0/16 --subnet-name tailcall-subnet --subnet-prefix 10.90.1.0/24 az network nsg create -g "$RG" --name tailcall-nsg az network nsg rule create -g "$RG" --nsg-name tailcall-nsg --name allow-ssh --priority 100 \
  --source-address-prefixes "<your-mgmt-cidr>" --destination-port-ranges 22 --access Allow --protocol Tcp az network nsg rule create -g "$RG" --nsg-name tailcall-nsg --name allow-web --priority 110 \
  --source-address-prefixes "<your-mgmt-cidr>" --destination-port-ranges 80 443 --access Allow --protocol Tcp
# Accept the Marketplace terms once per subscription (required before the first CLI deploy)
az vm image terms accept --urn sac1647283583153:tailcall-ubuntu-24-04:default:latest
az vm create -g "$RG" --name "$VM_NAME" --image "$IMAGE_URN" \
  --size Standard_B2s --storage-sku StandardSSD_LRS \
  --admin-username azureuser --ssh-key-values "$SSH_KEY" \
  --vnet-name tailcall-vnet --subnet tailcall-subnet --nsg tailcall-nsg --public-ip-sku Standard

ssh azureuser@<vm-ip>

Tailcall listens on loopback 127.0.0.1:8000, and nginx fronts it on port 80. nginx serves the health endpoint directly, so it always answers when the proxy is up.

sudo systemctl start tailcall nginx 2>/dev/null || true
sudo systemctl is-active tailcall nginx ss -tln | grep -E ':80 |127.0.0.1:8000' echo "GET /health -> HTTP $(curl -s -o /dev/null -w '%{http_code}' http://127.0.0.1/health) $(curl -s http://127.0.0.1/health)"

Both services report active, the two listening sockets appear, and GET /health -> HTTP 200 ok.

The starter config exposes a Query type backed by the public demo REST API, plus an offline greet resolver. POST a GraphQL query to /graphql, and the gateway resolves each field by calling the upstream.

curl -s -H 'Content-Type: application/json' \
  -d '{"query":"{ posts { id title } }"}' http://127.0.0.1/graphql | head -c 400; echo
curl -s -H 'Content-Type: application/json' \
  -d '{"query":"{ greet }"}' http://127.0.0.1/graphql

The first query returns a JSON data.posts array of { id, title } objects. Tailcall fetches them from the REST upstream and reshapes them into GraphQL. The second query returns {"data":{"greet":"Hello World!"}} from the offline @expr resolver. Together they show that the gateway serves both remote and local fields.

Tailcall's strength is stitching data together. In the starter config, Post.user is resolved with @call. A single GraphQL query therefore joins each post to its author, who lives at a different REST endpoint. You can also fetch a single record by argument.

curl -s -H 'Content-Type: application/json' \
  -d '{"query":"{ posts { id title user { id name email } } }"}' http://127.0.0.1/graphql | head -c 500; echo
curl -s -H 'Content-Type: application/json' \
  -d '{"query":"{ user(id: 1) { id name email } }"}' http://127.0.0.1/graphql

The first query returns posts with a nested user object joined from the users endpoint. The second returns a single user selected by the id argument. One GraphQL request triggers several upstream calls, which Tailcall batches and caches for you.

/etc/tailcall/config.graphql drives the gateway entirely. Point the @http directives at your own REST endpoints, add types and fields, and use @grpc, @call and @expr as needed. Validate the config before you restart, so a typo never takes the gateway down.

sudo cat /etc/tailcall/config.graphql | sed -n '13,20p'
sudo -u tailcall /usr/local/bin/tailcall check /etc/tailcall/config.graphql

tailcall check reports Config ... ok when the schema is valid. After you edit the file, apply the change with a restart:

sudo systemctl restart tailcall
sudo systemctl is-active tailcall

For the full directive reference (@http, @grpc, @graphQL, @call, @expr, @server, @upstream), see the Tailcall documentation at https://github.com/tailcallhq/tailcall.

nginx fronts the gateway on port 80 and is ready for TLS. Point a DNS record at the VM, then obtain a certificate with certbot. Certbot configures nginx for port 443.

sudo apt-get update && sudo apt-get install -y certbot python3-certbot-nginx
sudo certbot --nginx -d your-domain.example.com

After the certificate is issued, restrict the NSG so that only port 443 (and port 22 from your management network) is reachable. Then POST your queries to https://your-domain.example.com/graphql.