Install on Linux Natively

Using systemd and rsyslog to provide reliable service

Operating System Compatibility

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

This guide will walk through installing GRAX from scratch natively on a Linux operating system. It will configure a service to automatically restart GRAX if it fails, and create a rsyslog helper service to copy logs from stdout to a log retention file. Optional steps as take-home exercises would include log rotation, and syslog streaming.

WARNING:

Never set up a publicly-accessible instance of the GRAX application without modifying the ADMIN_PASSWORD in the configuration away from these examples

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, simply request it from GRAX HQ:

$ curl https://hq.grax.com/api/v2/pkg/graxinc/grax/master -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 as a gzipped tar, meaning you will need to expand it to get the contained binaries:

$ unzip grax.zip

Archive:  grax.zip
  inflating: github_event.json
  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 .env file with a valid configuration by creating secret values, using your DB connection string, and adding the domain name of your web server. In most cases, this domain name is of the format https://grax.department.customer.com, but can be decided by your networking team.

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
GRAX_TEMPLATE_VERSION=aws-sm:1.0.0
DATABASE_URL=postgres://username:[email protected]:5432/database-name
WEB_APP_URL=https://grax.department.customer.com
SECRET_STORE_BASE=[GENERATE]
ADMIN_PASSWORD=[GENERATE]

Create a GRAX Service Configuration

Use systemd to ensure GRAX stays running as a background service. Ensure you replace the paths in this configuration with the proper pathes to the executable and environment files created above:

$ vim /lib/systemd/system/grax.service

[Install]
WantedBy=multi-user.target
[Service]
EnvironmentFile=/home/ec2-user/.env
ExecStart=/home/ec2-user/grax
Restart=always
Type=simple
[Unit]
Description=grax daemon

Create a Log Capture Configuration

To write the stdout logs of the GRAX process into a dedicated file, use rsyslog with the given configuration:

$ vim /etc/rsyslog.d/grax-logs.conf

$umask 0000
$FileCreateMode 0644
:programname, isequal, "grax" /var/log/grax.log
& stop

Start all the Services in Order

Before we start the services, "touch" the log file to avoid any timing errors:

$ touch /var/log/grax.log

[no output expected]

To start everything in the proper order, run the systemctl commands like this:

$ systemctl daemon-reload; systemctl restart rsyslog.service; systemctl enable grax.service; systemctl restart grax.service; tail -f /var/log/grax.log

[json structured logs streaming here]

The services should now be online.

Next Steps

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