AWS Marketplace (Legacy)#

Note

This documentation refers to the legacy version of Grist on the AWS Marketplace, based on Grist Omnibus. You can find the documentation for the current offering here. Also consult, our transitioning notes.

First run setup#

After deploying the instance, Grist should be instantly available through the HTTP protocol on an autogenerated domain such as ec2-3-94-254-105.compute-1.amazonaws.com (labeled Public IPv4 DNS by AWS).

Default credentials:

  • email: admin@example.getgrist.com
  • password: [instance-id]*

* Instance ID can be found on the EC2 page in the AWS Console: AWS Instance ID screenshot

Custom domain and SSL setup for HTTPS access#

Custom domains are required for secure access to Grist. If you already have an SSL certificate, you can use your own (as described in the grist-omnibus README). If not, Grist can generate a certificate from Let’s Encrypt. For that, a valid domain and email must be configured:

  1. Point the domain to the IP address of the Grist EC2 instance. If you don’t use the Elastic IP service, the instance can have a different public IPv4 address each time it’s started.
  2. Log in to the Grist EC2 instance.
  3. Set the URL parameter in the grist/gristParameters file. You need administrator privileges to perform this action, so you can open an editor by running sudo nano grist/gristParameters.
  4. Run the restartGrist script with sudo ~/grist/restartGrist.

Once the above steps are completed, you should be able to access Grist on your custom domain.

Authentication setup#

Once you have your Microsoft or Google client ID and secret, you’ll need to pass them to the gristParameters file inside the Grist EC2 instance:

  1. Log in to the Grist EC2 instance.
  2. Open ~/grist/gristParameters.
  3. Update the CLIENT_ID and CLIENT_SECRET sections for the relevant provider(s).
    • If you’re using only one provider, leave the second section commented out.
  4. Update ADMIN_EMAIL in the same file. It should correspond to the email you will use to log in via your authentication provider. For example: ADMIN_EMAIL=frank@your-organization.com
    • If you want to change your team’s name, update TEAM_NAME in the same file.
  5. Run restartGrist with the clean flag using sudo ~/grist/restartGrist clean to clear old login data. Important: This will delete all Grist documents!

Once the above has been configured, you should be able to log in with your Google/Microsoft credentials.

Running Grist in a separate VPC#

grist-omnibus is designed to work on each account-default VPC. To make it run on a custom VPC, you’ll need to properly configure all VPC elements. For more information on this configuration, read here. To run Grist on a VPC, the following must be properly set up:

  • Assigning a public DNS name to the Grist EC2 instance is allowed.
  • The VPC can be accessed from the internet (allowing internet gateway and routing tables to handle traffic).
  • A security group connection from ports 22 (SSH for configuration), 80 (HTTP connection) and 433 (HTTPS connection) is allowed.

Updating grist-omnibus#

The packaged version of grist-omnibus will auto-update before each launch. To update grist-omnibus manually, restart the Grist EC2 instance or log in via SSH and call sudo ~/grist/restartGrist.

Other important information#

  • Grist stores all the data in the ~/grist-persist directory. Deleting this folder will result in a loss of all data from all documents.
  • Do not delete ~/grist-persist/acme.json, as it contains a private key from Let’s Encrypt. Deleting it too often can result in Let’s Encrypt denying issuing further certificates from your domain.