For the complete documentation index, see llms.txt. This page is also available as Markdown.

Network Requirements

The network rules GRAX needs to function, how end users and Salesforce reach your GRAX Application, and how its traffic is encrypted.

Traffic Rules

These rules are required unless marked optional.

Direction
From → To
Protocol and port
Required
Notes

Egress

GRAX → Salesforce

HTTPS 443

Yes

REST and Composite APIs, never Bulk API; OAuth 2.0

Egress

GRAX → hq.grax.com

HTTPS 443

Yes

Basic auth; updates, licensing, telemetry; no static IP available

Egress

GRAX → PostgreSQL

PostgreSQL 5432 (default)

Yes

Your configured database; username and password

Egress

GRAX → Storage

HTTPS 443

Yes

Your chosen bucket or platform; provider API

Ingress

End users → GRAX

HTTPS 443

Yes

Allow user IPs, or a shared network segment such as a VPN or corporate network

Ingress

Salesforce → GRAX

HTTPS 443

Optional

Only for LWC and embedded pages; allow your Salesforce instance region's IP ranges

Independent

hq.grax.com → Salesforce

HTTPS 443

Yes

OAuth 2.0; allow 3.232.229.75 on the Integration User profile

Application URL

The Application URL is the registered domain name that end users and Salesforce use to reach GRAX, without depending on resources that may change or be replaced during the life of the app. How it's managed depends on how GRAX is deployed.

GRAX Cloud
Secure endpoint
Your own domain

Used by

GRAX Cloud (GRAX-hosted)

GRAX-managed (Platform) AWS and Azure deployments

GRAX template and self-managed deployments (except Heroku)

URL

Subdomain of hosted.graxapp.com, provided by GRAX

Unique subdomain of secure.grax.io

Domain you register and manage

Ingress infrastructure you run

None

None beyond the app server

DNS, load balancer, certificate

Custom domain, WAF, DDoS protection

Contact GRAX Support

On request to GRAX Support

You provide and manage them

For GRAX Cloud, GRAX registers, renews, and removes the URL when it's no longer needed, and a GRAX team member gives you the URL once provisioning is complete and the app is ready for use.

Secure Endpoints

A secure endpoint exposes a GRAX-managed AWS or Azure application at a controlled domain name through the third-party service ngrok, with no ingress infrastructure on your side. ngrok's compliance and security information is on its trust site. Secure endpoints apply to GRAX-managed deployments only.

How It Works

  1. An application is designated to use a secure endpoint when it's created in GRAX Platform.

  2. When the infrastructure deployment completes, the application checks in with hq.grax.com for licensing, telemetry, and secure endpoint management.

  3. Using data from hq.grax.com, the application connects to ngrok through the ngrok Agent SDK for Go, creates a tunnel, and starts serving at its unique secure.grax.io subdomain, which it generates when it first starts. This repeats every time the application launches.

  4. When the application is offline, ngrok shows a default error page to anyone visiting the subdomain.

The subdomain is unique to the application and is secured with a globally unique set of credentials.

Security

  • Zero infrastructure ingress. The application server isn't reachable from outside its security group or VPC/VNET, and data stores are accessible only from the application server. Exposing an attack surface would take substantial changes to network security resources, not a mere security group misconfiguration.

  • No static bound port. The application never binds to a static, predetermined port, so a malicious service can't take over that port and serve traffic from your ALB.

  • Per-application secrets. The application creates, maintains, and protects the tunnel as part of its lifecycle. The secrets that establish the tunnel are unique to the application and aren't stored on the server.

Only the application server is needed to serve traffic, in place of a public domain name, an application load balancer, a DNS entry, and a web application firewall. For features such as custom domains, an integrated WAF, or DDoS protection, contact GRAX Support.

Your Own Domain

GRAX Template Apps

For apps running in AWS and based on GRAX templates, register the Application URL in Route53 and relate it to a hosted zone. Registering a domain manually in AWS creates a related hosted zone automatically. Registering a new domain in AWS is the simplest path, but it means any corporate domain registrations won't be used, so check with your network management or IT teams first. To use an already-registered domain with a GRAX template, delegate DNS for the new subdomain into Route53 from your registrar.

Self-Managed Apps

Self-managed applications built without a GRAX template can use URLs in any reasonable fashion. Nearly every public cloud has capabilities equivalent to Route53, and you can register and manage domains with your registrar of choice and delegate as required.

Heroku Apps

On Heroku, including GRAX-managed Heroku deployments and older GRAX environments, there's no secure endpoint and you don't register a domain: Heroku assigns and manages the URL, which includes herokuapp in the domain. GRAX-managed Heroku apps can also use your own domain. Secure custom URLs may be used case by case through the Heroku management interface. Contact GRAX Support if you're interested.

TLS/SSL Certificates

The GRAX backend supports TLS encryption by default using a self-signed certificate. This encrypts all traffic regardless of its source (for example a load balancer or the public internet). To use your own certificate for a custom domain, set these two environment variables:

They tell GRAX where the certificate and key are located. Standard GRAX installs include a /home/grax/.env file where you can add them. For example:

Generate a TLS/SSL Certificate

TLS/SSL Certificate File and Password Management

Installing TLS certificate files and supplying a key password (if any) is supported on self-managed GRAX, but it's a customization you're responsible for in your infrastructure provisioning or OS service management configuration.

Provide the password to your GRAX Application with a command during setup. GRAX encrypts it and stores it in the GRAX database like other secrets.

If the certificate isn't encrypted (no passphrase), use -pass ''.

Then restart GRAX so it uses the password to decrypt the key file.

TLS Configuration Precedence

GRAX looks first for TLS configuration in the secrets store, then in the environment file under the TLS_CERT_FILE and TLS_KEY_FILE variables. Encrypted certificates (using a passphrase) can only be set using the secrets store.

Last updated

Was this helpful?