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 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. Optional steps as take-home exercises include log rotation, and syslog streaming. If you do not have infrastructure set up to run GRAX, see our technical specifications and architecture guides for more information first.
Never set up a publicly accessible instance of the GRAX app without modifying the ADMIN_PASSWORD in the configuration away from these examples
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
To download the GRAX app, simply request it from GRAX HQ:
$ curl https://hq.grax.com/api/v2/download/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 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 with a valid
key=value list. The GRAX app 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 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] GRAX_REGISTRATION_KEY=[FROM https://platform.grax.com OR GRAX SUPPORT]
If your disk configuration dictates that GRAX cache data in a location other than your OS-default
/tmp), you can override that value by adding
TMPDIR=/new/path to the above. For more information, see here.
Use systemd to ensure GRAX stays running as a background service. Ensure you replace the paths in this configuration with the proper paths 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
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 && journalctl -f -u grax.service [json structured logs streaming here]
The services should now be online.
To proceed with connecting GRAX to Salesforce and your storage platform of choice, start with our connection documentation.
Updated about 4 hours ago