> For the complete documentation index, see [llms.txt](https://documentation.grax.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://documentation.grax.com/technology/requirements/network-requirements.md). # 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. ![](https://609800358-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F65JiuVU9UKdqlui90FHW%2Fuploads%2Fgit-blob-81e34055ff44cfd9ffee419fdb571017d2b69221%2Fnetwork-requirements.drawio.svg?alt=media) | 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](/technology/security/telemetry.md); 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](https://help.salesforce.com/s/articleView?id=000321501\&type=1) | | Independent | `hq.grax.com` → Salesforce | HTTPS 443 | Yes | OAuth 2.0; allow `3.232.229.75` on the Integration User profile | {% hint style="warning" %} Best practice is to expose your GRAX Application to public traffic through an Application Load Balancer of some form with additional filtering. GRAX doesn't support API gateways that modify payloads, terminate or modify authentication, enforce third-party schemas or protocols, or filter requests by path, payload, or parameters. GRAX doesn't guarantee alignment with any published API standard, nor stability of the API interface for external use at this time. {% endhint %} ## 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](https://ngrok.com/), with no ingress infrastructure on your side. ngrok's compliance and security information is on its [trust site](https://trust.ngrok.com/). 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](https://platform.grax.com). 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](https://pkg.go.dev/golang.ngrok.com/ngrok), 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](https://documentation.grax.com/support/get-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. * [Domain registration in AWS](https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/domain-register.html) * [DNS delegation in Route53](https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/CreatingNewSubdomain.html) ### 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](https://documentation.grax.com/support/get-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: ```bash TLS_CERT_FILE TLS_KEY_FILE ``` 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: ```bash # .env file containing full paths to the files TLS_CERT_FILE=/home/grax/certs/grax-example.com.cer TLS_KEY_FILE=/home/grax/certs/grax-example.com.key ``` ### Generate a TLS/SSL Certificate ```bash openssl req -x509 -sha256 -nodes -newkey rsa:4096 -keyout /home/grax/certs/grax-example.com.key -out /home/grax/certs/grax-example.com.cer ``` ### 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. ```bash # Update 'graxctl' ./graxctl update # The 'graxctl' command is located in the GRAX installation directory, usually under /home/grax # NOTE: Make sure to change 'passphrase1' to the actual passphrase. ./graxctl secrets -tls -cert 'cert1.pem' -key 'key1.pem' -pass 'passphrase1' ``` If the certificate isn't encrypted (no passphrase), use `-pass ''`. ```bash graxctl secrets -tls -cert 'cert1.pem' -key 'key1.pem' -pass '' ``` Then restart GRAX so it uses the password to decrypt the key file. ```bash systemctl restart grax.service ``` ### 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.