Merge pull request #309 from gristlabs/marketplace

adding marketplace content

help/install/aws-marketplace.md

@@ -0,0 +1,82 @@
+AWS Marketplace {: .tag-core .tag-ee }
+============
+
+Grist on the AWS Marketplace has what you need to run a self-hosted Grist instance with minimal setup, and is based on [`grist-omnibus`](https://github.com/gristlabs/grist-omnibus). Below are the complete configuration steps, including authentication via OpenID.
+
+## 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: [email protected]
+* password: [instance-id]\*
+
+\* Instance ID can be found on the EC2 page in the AWS Console:
+![AWS Instance ID screenshot](../images/aws-instance.png)
+
+### How to log in to the Grist instance
+
+During deployment, you should have been asked about creating or using key pairs. You can use this pair to log in via SSH from your terminal/bash. The default user for the Grist EC2 instance is named “ubuntu”, and you can log in to `ubuntu@[ec2-instance-public-ip]`.
+
+**Note:** You need to use the `*.pem` file you received while generating key pairs on AWS. Details about connecting via SSH can be found in the following places: 
+
+* Windows: [https://learn.microsoft.com/en-us/windows/terminal/tutorials/ssh](https://learn.microsoft.com/en-us/windows/terminal/tutorials/ssh)
+* Linux: [https://www.ssh.com/academy/ssh/command](https://www.ssh.com/academy/ssh/command)
+* macOS: [https://www.servermania.com/kb/articles/ssh-mac](https://www.servermania.com/kb/articles/ssh-mac)
+
+If you don’t want to connect via SSH, AWS provides the option to connect from within the AWS console using the “Connect” button:
+
+![AWS Connect screenshot](../images/aws-connect.png)
+
+## 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](https://github.com/gristlabs/grist-omnibus/)). 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](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/elastic-ip-addresses-eip.html), 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
+
+We support Google or Microsoft as OpenID providers. For configuring other authentication providers, please refer to the [dex documentation](https://dexidp.io/docs/getting-started/).
+
+To configure Grist authentication with Google or Microsoft, you must have an application registered with the corresponding provider:
+
+* Microsoft: [https://learn.microsoft.com/en-us/power-pages/security/authentication/openid-settings](https://learn.microsoft.com/en-us/power-pages/security/authentication/openid-settings)
+* Google: [https://support.google.com/cloud/answer/6158849?hl=en](https://support.google.com/cloud/answer/6158849?hl=en)
+
+Once you have your 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: `[email protected]`
+    * 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](https://docs.aws.amazon.com/vpc/latest/userguide/what-is-amazon-vpc.html). 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`.
+
+There are currently no plans to support the Grist AWS Marketplace environment outside of `grist-omnibus`.
+
+## Other important information 
+
+* The Grist EC2 instance should have the “Persistent store” option checked.
+* 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.

help/self-managed.md

@@ -54,9 +54,7 @@ describe how using [Docker](https://www.docker.com/),
 but there are many other tools and services for running
 containers.
 
-To try Grist out,
-make an empty directory for Grist to store material in
-(say `~/grist`) and then for Grist Core you can do:
+To try Grist out using Docker, make an empty directory for Grist to store material in (say `~/grist`) and then for Grist Core you can do:
 
 ```
 docker run -p 8484:8484 \
@@ -99,6 +97,10 @@ take at least the following steps:
 	and a [special authentication method](self-managed.md#are-there-other-authentication-methods) for custom cases.
   * Consider enabling [snapshot support](self-managed.md#how-do-i-set-up-snapshots) if you want Grist to handle document backups.
 
+#### Grist on AWS
+
+You can also host Grist on AWS. Full instructions on this hosting method are available on the Grist [AWS Marketplace page](install/aws-marketplace.md).
+
 ### How do I sandbox documents? {: .tag-core .tag-ee }
 
 Grist allows for very powerful formulas, using Python.  We recommend

mkdocs.yml

@@ -84,6 +84,7 @@ nav:
     - Forwarded headers: install/forwarded-headers.md
     - Cloud storage: install/cloud-storage.md
     - GristConnect: install/grist-connect.md
+    - AWS Marketplace: install/aws-marketplace.md
     - Telemetry:
       - Overview of Telemetry: telemetry.md
       - Limited Telemetry: telemetry-limited.md