URL Registration for GRAX

The GRAX app must be reachable by end users and Salesforce to provide backup, archive, and restore capabilities. To achieve access without a dependency on resources that may change or be replaced during the lifetime of the app, a registered domain name is utilized. We'll refer to this as the "Application URL"/"URL" below. As GRAX can be installed in many ways, the manner by which this URL is managed varies by environment.

GRAX Legacy Heroku Apps

For older GRAX environments that run on Heroku, URLs are decided and managed by Heroku. These URLs include herokuapp in the path. Secure custom URLs may be used on a case-by-case basis via the Heroku management interface. Please contact GRAX Support for assistance if interested.

GRAX Hosted Apps

For hosted GRAX applications, GRAX creates URLs via a standard template and handles registering, renewing, and/or destroying it if no longer needed. URLs are registered as subdomains under a GRAX-owned second-level domain. Your URL is provided by a GRAX team member once provisioning is complete and the app is ready for use.

GRAX Template Apps

Application URLs for apps both running in AWS and based on GRAX templates must be registered within Route53 and related to a hosted zone. Registering a domain manually in AWS automatically creates a related hosted zone. Registering a new domain within AWS is the recommended path for simplicity, but means that any potential corporate domain registrations won't be used. Check with your network management/IT teams prior to making this decision. If you are interested in utilizing an already-registered URL and a GRAX template, you need to delegate DNS for the new subdomain into Route53 from your registrar.

Guidance on domain registration in AWS can be found here.
Guidance on DNS delegation in Route53 can be found here.

Self-Managed GRAX Apps

Self-managed applications built without utilizing a GRAX template may achieve usage of URLs in any reasonable fashion. Equivalent capabilities to Route53 exist in nearly every public cloud. Domains may be registered and handled with your registrar of choice and delegated as required.

TLS/SSL Certificates

The GRAX backend supports TLS encryption by default using a self-signed certificate. This ensures all traffic is encrypted no matter the source (for example from a load balancer or public internet). Optionally, users may want to provide their own certificates for a custom domain. In that case, GRAX supports the following two environment variables:

TLS_CERT_FILE
TLS_KEY_FILE

These environment variables tell GRAX where the custom certificate and key are located. Standard GRAX installs include a /home/grax/.env file where these variables can be added. For example:

# .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 TLS/SSL Certificate

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 is a customization you are responsible for in your infrastructure provisioning or OS service management configuration.

The password can be provided to your GRAX application via a command during setup. It's then encrypted and stored in the GRAX database as other secrets.

# 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 ''.

graxctl secrets -tls -cert 'cert1.pem' -key 'key1.pem' -pass ''

After submitting the above command, you can restart GRAX to make it start using the provided password to decrypt the key file.

systemctl restart grax.service

TLS configuration precedence

GRAX looks first for TLS configuration in the secrets store. Then, if not found, on the environment file, under the TLS_CERT_FILE and TLS_KEY_FILE vars

TLS encrypted certificates (using a passphrase) can only be set using the secrets store.

Support

If you require assistance or have any remaining questions after reviewing the above, contact GRAX Support) with any available details.