Install on Linux

This guide is written with RHEL or Amazon Linux 2023 in mind. If you are running a different distribution of Linux, steps may vary.

This guide walks through installing GRAX from scratch natively on a Linux operating system. It configures a service to automatically restart GRAX if it fails, and creates a rsyslog helper service to copy logs from stdout to a log retention file. If you do not have infrastructure set up to run GRAX, see our technical requirements and architecture guides for more information first.

Never set up a publicly accessible copy of the GRAX Application without modifying the ADMIN_PASSWORD in the configuration or removing it entirely.

Installation Steps

Before you begin the steps below, many of them require root access. Start by logging in as root or elevating your session to a point where you have sudo capabilities.

Download and Expand GRAX Executable

To download the GRAX Application, download the proper build from GRAX HQ for your architecture. Builds are only available for Linux running on ARM64 and AMD64 architectures. The following example determines which of the builds to download based on the architecture of a supported machine:

$ CPU=$(uname -m); case "$CPU" in x86_64) CPU="amd64" ;; aarch64) CPU="arm64" ;; esac
$ curl https://hq.grax.com/api/v2/download/graxinc/grax/main/linux/$CPU -L --output grax.zip

  % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
                                 Dload  Upload   Total   Spent    Left  Speed
100    67  100    67    0     0    740      0 --:--:-- --:--:-- --:--:--   797
100 47.5M    0 47.5M    0     0  5738k      0 --:--:--  0:00:08 --:--:-- 7915k

GRAX HQ serves this download in a compressed format, meaning you need to expand it to get the contained binaries:

$ unzip grax.zip

Archive:  grax.zip
  inflating: grax
  inflating: graxctl

Mark the resultant files executable for later use:

$ chmod +x grax graxctl

[no output expected]

Create a Configuration File

Create a configuration file with a valid key=value list. The GRAX Application loads configuration values from the environment at time of boot; to use this configuration, the values must be loaded into the execution environment prior to calling the GRAX binary. Normally, this is done via the EnvironmentFile argument of a systemd service configuration. As a result of using such a tool to load the file into the environment, the name and location of this file is arbitrary. We specify a .env file located in the app directory as an example below.

The configuration file includes your server's public domain name (WEB_APP_URL). In some cases, this domain name is of the format https://grax.department.customer.com, but can be decided by your networking team. The app's port is also adjustable via ADDR, but keep in mind that a change here may result in necessary changes in your load balancers, security groups, and/or monitoring.

Generate a secure random value for each of the values marked [GENERATE] below. A length of at least 30 characters each is recommended. You can generate such a value with openssl rand -base64 48 | tr "+/" "-_" | tr -d = in most Linux distributions.

$ vim .env

ADDR=:8000
SELFSIGNEDCERT=1
DATABASE_URL=postgres://username:[email protected]:5432/database-name
WEB_APP_URL=https://grax.department.customer.com
SECRET_STORE_BASE=[GENERATE]
ADMIN_PASSWORD=[GENERATE]
GRAX_REGISTRATION_KEY=[FROM https://platform.grax.com OR GRAX SUPPORT]

SELFSIGNEDCERT is only required in cases where you wish to terminate TLS at a Load Balancer or gateway, but still encrypt the traffic between the Load Balancer and the GRAX Application. This is not required if you are using custom certificates installed on the machine.

If your disk configuration dictates that GRAX cache data in a location other than your OS-default TMPDIR (usually /tmp), you can override that value by adding TMPDIR=/new/path to the above. For more information, see here.

Create a GRAX Service Configuration

Use systemd to ensure GRAX stays running as a background service.

$ cat <<EOT >> /lib/systemd/system/grax.service
[Install]
WantedBy=multi-user.target
[Service]
User=ec2-user
Group=ec2-user
EnvironmentFile=/home/ec2-user/.env
ExecStart=/home/ec2-user/grax
Restart=always
RestartSec=30s
StartLimitInterval=0
StartLimitBurst=0
Type=simple
MemoryHigh=80%
MemoryMax=90%
[Unit]
Description=grax daemon
EOT

This service configuration assumes standard file locations on Amazon Linux 2023 and runs GRAX as the standard EC2 user. If you are running on a different distribution or as a different user, adjust the paths and user/group accordingly.

Logging (Optional)

By default, systemd writes the stdout and stderr streams from services to the journal, accessible with journalctl. The journal automatically handles log retention to ensure that disk space does not fill up, but GRAX logs may be co-mingled in the journal with other services making them harder to consume. To separate GRAX logs into a dedicated file, you can use rsyslog to copy the logs from the journal to a file. This can often make integrations with third party monitoring tools or log aggregators easier.

First, create the rsyslog configuration to read grax service output from the journal and write it to /var/log/grax.log:

$ cat <<EOT >> /etc/rsyslog.d/grax.conf
$umask 0000
$FileCreateMode 0644
:programname, isequal, "grax" /var/log/grax.log
& stop
EOT

Next, create a logrotate configuration to rotate the log file daily and keep only 7 days of logs:

$ cat <<EOT >> /etc/logrotate.d/grax
 /var/log/grax.log
{
  missingok
  daily
  copytruncate
  rotate 7
}
EOT

Start all the Services in Order

The services defined above, and the configurations that control them, need to be started/restarted to operate as intended after the updates:

$ systemctl daemon-reload && systemctl restart rsyslog.service && systemctl enable --now grax.service

The services should now be online and logs should be written to /var/log/grax.log shortly.

Next Steps

To proceed with connecting GRAX to Salesforce and your storage platform of choice, start with our connection documentation.