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.

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:

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

Mark the resultant files executable for later use:

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.

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 .

Create a GRAX Service Configuration

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

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:

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

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:

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 .

Heroku is a PaaS (Platform as a Service) that allows you to deploy applications without worrying about the underlying infrastructure.

The trial installation includes all of the resources needed to enable GRAX backups and the GRAX datalake.

If you are new to GRAX, we recommend starting with the trial as you can always upgrade and migrate resources and data later.

If you are setting up GRAX for production, we recommend deploying GRAX to Heroku .

Trial Installation

To quickly and easily deploy a GRAX trial on Heroku click the "Deploy to Heroku" button below:

This will provision the following resources:

1. A Heroku dyno with the GRAX Application

2. A Heroku Postgresql Add-on for GRAX Application state

3. An S3 Storage Add-on for CRM data

4. A GRAX Add-on to setup the datalake

Maintenance

The GRAX Application installed on Heroku takes advantage of GRAX's automatic update tools, meaning that it automatically updates to the latest version of GRAX every day. This ensures that you always have the latest features and bug fixes without needing to manually update the application. Short of configuration changes or database maintenance, you should not need to interact with the Heroku application directly.

Accessing the Application

By default, Heroku applications generate a random URL at which the application will be hosted. This can be discovered by clicking the "Open App" button on the Heroku application's dashboard. If you are interested in setting up a custom domain, this can be accomplished via the Heroku application's "settings" page whenever you'd like.

At a high level, the following are the rules for GRAX network access:

1. GRAX Application talks to Salesforce

2. GRAX Application talks to hq.grax.com

3. GRAX Application talks to Database

4. GRAX Application talks to Storage

5. End users talk to GRAX Application's APIs

6. (Optional) Salesforce talks to GRAX Application

7. hq.grax.com talks to Salesforce

Communication Details

Best practices suggest exposing your GRAX Application to public traffic via an Application Load Balancer of some form with additional filtering for security. However, GRAX doesn't support API gateways that modify payloads, terminate or modify authentication, enforce third-party schemas/protocols, or filter requests based on path, payload, or parameters. GRAX doesn't guarantee alignment with any published API standard, nor promise stability of the API interface for external use at this time.

Egress Network Connections

The following are descriptions of the rules related to traffic that flows outward from the compute resource running your GRAX Application.

GRAX → Salesforce

To query, update, or insert information in Salesforce, GRAX uses the public Salesforce REST and Composite APIs (and never uses the Salesforce Bulk API). Allow, at a minimum, at least one static IP for your GRAX Application to communicate out to Salesforce.

This may include allowing , as well as allowing the traffic to leave the VPC or other infrastructure network.

GRAX → HQ

For software updates, telemetry, and license monitoring, GRAX communicates with GRAX HQ. Allow the GRAX Application to access hq.grax.com over HTTPS on port 443. A static IP for this communication isn't currently available. For more information on this communication, see .

GRAX → Database

For metadata storage, search indexing, and storage optimizations, GRAX uses Postgres. Allow the GRAX Application to access your configured Postgres database.

GRAX → Storage

For longterm storage, GRAX uses blob storage platforms. Allow the GRAX Application to access your chosen blob storage bucket/platform.

Ingress Network Connections

The following are descriptions of the rules related to traffic that flows towards the compute resource running your GRAX Application.

End Users → GRAX

End users of GRAX access the GRAX Application via a web browser. This traffic originates from their local IPs unless using a VPN or proxy. To allow your users to use GRAX, allow their IPs to hit the public endpoint for your GRAX Application. If all of your users share a network segment (VPN, corporate network, etc.), allowing that network segment access may be sufficient.

(Optional) Salesforce → GRAX

Lightning Web Components and Embedded Pages are all driven by Salesforce-to-GRAX traffic. Salesforce publishes their global IP ranges. Allow, at a minimum, the to access the GRAX Application API.

NOTE: this traffic is optional based on feature usage. If your use case for GRAX doesn't necessitate using LWC or iFrames, Salesforce won't make requests to your GRAX Application.

Independent Network Connections

The following are descriptions of the rules related to traffic that flows entirely independently from the compute resource running your GRAX Application, but which may impact its operation.

GRAX HQ → Salesforce

GRAX HQ's static egress IPs appear in the Integration User's login history after connecting the app to Salesforce due to the nature of the GRAX OAuth process. Please add 3.232.229.75 to your whitelist/allowlist addresses on the Integration User's profile to allow the GRAX Application to connect to your org. In addition, you need to add the static IP addresses for each of your specific environments to ensure there are no IP restrictions.

Installation Steps

Setup Docker Desktop

First download, install, and run Docker Desktop.

Get a GRAX Trial Key

Next, sign into the and get a registration key.

Go to "Backends," then "New," then "GRAX for Docker Desktop," then "Create Key." You can then see a "Registration Key" in your list of backends. This key can only be activated once.

Download and Configure GRAX Docker Compose Files

Download , unzip them, and configure it with your registration key.

Start Up GRAX with Docker Compose

After 30 seconds, GRAX is running alongside a database and storage service. You can go to the "Backend URL" from , e.g:

You can pause GRAX with:

And resume again with docker-compose up -d.

Resetting Everything

You can destroy all Docker resources with:

Then, sign into the , go to "Backends," and "Delete" your previously activated backend and registration key.

The following is an architecture example for Azure deployments. This is the architecture that the Azure Terraform module follows when deploying GRAX.

While the GRAX Application interface is the main interface to backing up, protecting, and retaining your data, it's all powered by a single-tenant backend service that depends on an array of infrastructure components to perform successfully.

For a recap of GRAX features, business cases, or deployment options, see our product documentation.

High-Level Components

The basic architecture of GRAX is:

1. Compute

2. Persistent Blob Storage

3. Persistent Indexed Storage

4. External Connectivity

5. Network Security Management

The specific implementations of these simplistic labels can vary in both substance and complexity depending on deployment path chosen, platform of choice, and restrictions/regulations in place on all involved parties.

The guides in this section help explain the options you have in deploying GRAX, as well as enable your team to design, implement, and support the infrastructure yourself if so required.

High-Level Constraints

Operating outside the scope of these limitations causes issues with data integrity, data loss, contractual agreements, and general service availability:

• Only one GRAX Application may be running for a given license.

• Only one GRAX Application may be talking to the storage bucket and the Database.

• Egress to hq.grax.com must be available at all times.

• Storage bucket performance must be on par with documented S3 performance metrics.

What You Need to Bring

GRAX requires network accessibility (domain and certificate), compute resources, a PostgreSQL database, and a storage bucket at a bare-minimum.

Network Accessibility

Base Costs

GRAX-Managed minimum requirements are a VM with 4 vCPUs and 16 GB of RAM, as well as a Postgres database server with dedicated capacity. These minimum requirements support small Salesforce orgs with 20 GB of data.

On AWS a base deploy costs $260.65 / mo for the recommended m8g.xlarge EC2 instance and Aurora Postgres Serverless:

• $131.05 / mo (m8g.xlarge)

• $129.60 / mo (1.5 Aurora Capacity Units)

Note that Aurora Serverless auto scales and is billed based on consumption.

On Azure a base deploy costs $384 / mo for the recommended Standard_D4s_v3 VM and an GP_Standard_D4s_v3 Azure PostgreSQL Flexible Server:

• $138.24 / mo (Standard_D4s_v3)

• $246.24 / mo (GP_Standard_D4s_v3)

On Heroku a base deploy costs $700 / mo for the recommended Performance L dyno and Premium 0 Heroku Postgres:

• $500 / mo (Performance L dyno)

• $200 / mo (Premium 0 Heroku Postgres)

Note that you may also want a Heroku Private Space which adds extra base costs.

Larger Salesforce orgs may need to use a larger VM or database to process data without issues. Therefore your final costs may vary. Please work with your cloud provider or contact for help estimating the cost for the system requirements for your org.

Cloud Cost, Usage and Optimization

GRAX takes full advantage of the public cloud to support Salesforce orgs of any size and volume: automatic high availability, effortless vertical scaling, and consumption-based pricing.

GRAX proactively monitors the health of your data, alerts you to problems affecting backups. GRAX also provides one-click tools to vertically scale your VM or database when needed for GRAX-managed environments.

The only tradeoff is that your cloud costs may vary over time and are hard to predict.

We highly recommend deploying GRAX with the minimum requirements, starting backups, then reviewing your cost and usage after 30 and 60 days. After this time your Salesforce data will be fully protected and your average cloud costs will be fully understood.

If the cost of resources is deemed too high after this time, you can:

• work with your cloud provider to buy reservations at a discount

• work with your Salesforce admin to reduce data change volumes

• work with GRAX Support to discuss deployment and product optimizations

And of course at any time you can discontinue your use of GRAX and stop all cloud resources and costs.

Cloud Providers

Amazon Estimate Calculator

A pre-configured estimate of the high-level AWS resources necessary for GRAX is available .

All prices set by AWS are subject to change by AWS at any time, see their for more information. GRAX isn't responsible for changes to AWS pricing.

Azure Estimate Calculator

A pre-configured estimate of the high-level Azure resources necessary for GRAX is available .

Self-Managed

GRAX Self-Managed supports whatever cloud architecture your company requires for security and compliance reasons. The architecture and related costs are ultimately up to you; we can only offer guidance on minimizing costs.

Never Route Storage Publicly

Never route your storage traffic external to the VPC or cloud provider. Traffic leaving the VPC crosses the NAT Gateway and incurs much higher costs; GRAX reads many Terabytes of data as it so this difference adds up. This includes traffic from an AWS EC2 instance to Azure storage, or any other similar mismatch in infrastructure providers.

Always Provide Cache Space

Low cache size, in both memory and disk, can lead to extremely frequent read operations from storage and thus drive up overall data transfer. In infrastructures where this incurs cost, this can become very expensive. See our for GRAX hardware to ensure you're operating within safe limits.

FAQ

What contributes to base or static costs?

Costs that can be determined prior to usage, like the hourly cost of an EC2 instance given a 24x7x52 uptime, are considered static. These sections of the estimate aren't expected to change, regardless of GRAX features used or data processed.

What contributes to variable costs?

Many networking and storage services in the public cloud bill entirely based on usage. When it comes to GRAX's usage of RDS, S3, and NAT Gateway services, there is no exception. The estimate above includes best-attempt estimations of usage when under a typical app load. GRAX provides no guarantees as to the accuracy, in either direction, of these estimates.

There are many factors that can affect total realized costs:

• Usage of specific GRAX features

• Total Salesforce org Size

• Turnover Rate of Salesforce Records (created + changed per hour)

• Number of Files in Salesforce (each file gets downloaded and stored)

The GRAX Application requires several secret values specified in the environment (normally sourced from .env). These include a valid Postgres connection string, an administrator password, and a key base for encryption of the DB-based Secrets Store used for SFDC and storage connection secrets (SECRET_STORE_BASE). Rotation of secrets is mostly external to the GRAX Application, with one exception.

Rotating Database Connection String or Administrator Password

To rotate the connection string used to connect to the Postgres database cluster manually, perform the following steps:

1. Stop the GRAX services

2. Update the configuration source/file with your editor of choice:

3. Start the GRAX services

If you have interest in automating this behavior, the automation needs to preserve or recreate the other necessary values for the configuration.

Rotating SECRET_STORE_BASE

The SECRET_STORE_BASE is used to encrypt the SFDC and Storage secrets in the database. Changing this value between reboots without proper care results in these secrets being irrecoverable and the GRAX Application being unable to start properly; a manual reset of configuration information in the database is the only recovery option. If this issue occurs, please contact for assistance clearing the configuration.

To properly rotate this value, perform the following steps:

1. Stop the GRAX services

2. Update the SECRET_STORE_BASE to the new value with your editor of choice

3. Update the SECRET_STORE_BASE_PREV to the previous value with your editor of choice

4. Start the GRAX services

At this point, the GRAX Application reads the configuration secrets with the old key and writes them with the new key on first boot. It is not necessary to remove the SECRET_STORE_BASE_PREV value from the configuration file. If you desire the removal of the old value, you can do so after the GRAX Application has been started successfully for two minutes; stop the services, update the .env, and start the services again.

The GRAX Application 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 for assistance if interested.

The following is an architecture example for AWS deployments. This is the architecture that the AWS Marketplace offering provisions upon deployment.

Whether you design and deploy the infrastructure for GRAX yourself or use GRAX-provided designs/templates, installing GRAX often means running cloud infrastructure within your own environment. This infrastructure isn't accessible or manageable by the GRAX team for the sake of safety, security, and compliance. Automated monitoring policies can help ensure that issues with this infrastructure are noticed quickly and downtime of your app remains low.

The GRAX Application is built for longterm, near-infinite retention of your Salesforce object data. To facilitate fast, reliable, and scalable storage of this data, GRAX uses AWS S3 and recommends comparable options across Azure and GCP. To understand more about how GRAX uses this storage, storage growth expectations, why we don't recommend cross-cloud usage, and supported lifecycle processes, see the sections below.

Supported Cloud Blob-Storage Platforms

• AWS S3

• Azure Blob Storage

• GCP Cloud Storage

Supported Storage Types

On AWS, GRAX only supports the standard storage class. GRAX won't work with Intelligent Tiers, Glacier, or Outposts.

On Azure, GRAX only supports the standard (GPv2) storage account tier and the access tier must be "Hot." Both Azure Blob Storage and Azure Data Lake (gen2) Storage are supported. Premium storage accounts or containers won't work with GRAX.

On GCP, GRAX only supports standard storage. Nearline, Coldline, or Archive storage plans/containers won't work with GRAX.

Unsupported Activities

Direct access, modification, or removal of data from the GRAX bucket isn't supported. Attempts to rename, remove, or modify blobs within the storage bucket cause data loss and GRAX availability issues. GRAX isn't responsible for partial or complete loss of your backup dataset if this restriction is violated.

In conjunction with the above, we also don't support the following:

• Lifecycle rules triggering blob deletion

• Lifecycle rules moving blobs to alternative storage tiers/classes

• Restoration via blob versioning

For targeted record deletion (like GDPR compliance), see our .

Required Permissions

AWS S3 Permissions

At a minimum, GRAX requires the s3:ListBucket, s3:GetObject, s3:PutObject, and s3:DeleteObject permissions on the bucket. If you're using KMS encryption, GRAX also requires the kms:DescribeKey, kms:Decrypt, kms:Encrypt, kms:GenerateDataKey, and kms:ReEncrypt* permissions on the KMS key resource.

Azure Blob Storage Permissions

GRAX only supports Storage Account Access Keys for Azure Blob Storage. As such, granular permissions aren't currently available.

GCP Cloud Storage Permissions

At a minimum, GRAX requires the storage.objects.create, storage.objects.delete, storage.objects.get, storage.objects.list, and storage.objects.update permissions on the bucket. The best practice is to use the Storage Object User role, as it grants all necessary permissions (plus a small number of extras) without the ability to modify access controls.

How GRAX Stores Your Data

GRAX's primary storage layer consists of compressed blobs in a proprietary format. Based on leading big-data storage practices, our storage layer provides write-optimized and scalable performance useful for data backup.

To facilitate this write-optimized performance, GRAX initially writes data with minimal compression and de-duplication. That data is then processed asynchronously to compress, de-duplicate, and sort the contained records over the hours following initial backup. We'll call this "compaction." This process is transparent to the GRAX user, as access to the data isn't limited during this process.

Compaction produces immutable storage blobs. As data is compacted past the original written state, new blobs are written to represent that data and the source blobs are marked for deletion. 14 days after being marked as such, those non-compacted blobs are deleted from storage as the data within them is represented elsewhere in "better" blobs. This process repeats as your dataset grows, meaning that compaction is a permanent and recurring background process that maintains your dataset.

Also for consideration, the vast majority of load on the GRAX Application occurs in the first few weeks of operation in which you connect GRAX and we capture a snapshot of the entire exposed Salesforce dataset. This means that data can build up temporarily until compaction and then deletion catches up.

With the above process in consideration, we can plot the expected data storage usage on a generalized curve (specific values, units, and time frames depend on your environment):

How Much GRAX Storage Costs

Data stored in GRAX takes up significantly less space than the same data would take up in Salesforce. Cloud storage is also vastly cheaper than Salesforce storage; most users hardly notice the cost of data-at-rest in a GRAX environment. Here are some breakdowns of real-world costs of data-at-rest in AWS S3.

• Average Case:

  • Production environments, on average, consume a low amount of storage

  • 216 GB consumed by average environment

  • $4.97 per month at standard S3 data-at-rest rates

Frequently Asked Questions

Where can I get more information?

For information on how to connect your GRAX Application to a bucket for the first time (or change your existing storage connection), review our .

Can I use Azure Premium Storage for my storage container?

No. GRAX does not support the premium blob storage tier or API from Microsoft Azure. Use the standard storage tier instead.

What are the data prefixes/folders written by GRAX?

With the exception of the parquet folder, these storage locations contain data stored in a proprietary format and are designed to be read/written solely by the connected GRAX Application.

As mentioned , attempts to rename, remove, or modify data within the storage bucket cause data loss and GRAX availability issues. GRAX isn't responsible for partial or complete loss of your backup dataset if this restriction is violated.

Can Versioning be enabled in my storage bucket/container?

No. GRAX does not support versioning in the storage bucket or container. GRAX stores data in a proprietary format that keeps track of all record versions internally. Storage blobs/objects are not updated in place - they're rewritten as a new blob when replaced. The old blobs are then removed once no longer representative of the dataset. Enabling versioning thus has no affect on data safety but keeps these deleted blobs around indefinitely as a "non-current version." This will increase storage consumption and costs significantly beyond the documented expectations.

How can I clean deleted data from a bucket that had versioning enabled?

First, ensure that Versioning is now disabled or suspended indefinitely in the bucket. Next, use provider-specific tools to automatically remove the "non-current versions" for deleted objects from the bucket. AWS S3 supports that can be used to automatically remove old versions of objects, and clean up delete markers left behind. A rule needs to be created to do the following:

1. Non-current Version Expiration - This removes the non-current versions of objects after a specified number of days. The rule should be configured to remove non-current versions after 1 day.

2. Remove Expired Object Delete Markers - This removes the delete markers left behind after the non-current versions are removed.

An example of a Lifecycle Rule that will remove non-current versions and delete markers after 1 day is shown below:

XML

JSON

Can replication be enabled in my storage bucket/container?

GRAX does not natively support S3 bucket replication, nor does the app support failover to a replicated bucket.

While replication is technically possible on any bucket if you set it up yourself, bucket replication introduces unsupported configuration and significant complexity and cost, especially due to S3 Versioning and Delete Marker behavior.

Replicated data is not reliable for failover, is not guaranteed to be consistent or recoverable in the event of failure and offers no immediate operational value in disaster recovery scenarios.

What are the limitations of GRAX-hosted Storage?

GRAX is designed for you to retain ownership of your sensitive data. For this reason GRAX requires that you bring a storage bucket that you own. However, if circumstances are such that you are unable to provide a bucket, contact to discuss an exception (GRAX-hosted bucket).

GRAX-hosted storage supports backup, archive, and restore on AWS only. It does not support Data Lake or Data Lake House. It does not offer access to the underlying storage account and configuration. It is subject to storage, request, and bandwidth limits and may incur overage fees or require purchasing additional blocks of storage.

In all scenarios, bringing your own storage account is better for data security, cost, and data reuse.