# Technical Reference Quilt is a versioned data portal for AWS. A Quilt *instance* is a private portal that runs in your virtual private cloud (VPC). Each instance consists of a password-protected web catalog on your domain, backend services, a secure server to manage user identities, and a Python API. ## Installation Instructions We encourage users to contact us before deploying Quilt. We will make sure that you have the latest version of Quilt, and walk you through the CloudFormation deployment. We recommend that all users do one or more of the following: * [Schedule a Quilt engineer](https://www.meetingbird.com/m/quilt-install) to guide you through the installation * [Join Quilt on Slack](https://slack.quiltdata.com/) to ask questions and connect with other users * [Email Quilt](mailto://contact@quiltdata.io) ## Before you install Quilt You will need the following: 1. **An AWS account** 2. **IAM Permissions** to run the CloudFormation template (or Add products in Service Catalog). The `AdministratorAccess` policy is sufficient. (Quilt creates and manages a VPC, containers, S3 buckets, a database, and more.) If you wish to create a service role for the installation, visit `IAM > Roles > Create Role > AWS service > CloudFormation` in the AWS console. The following service role is equivalent to `AdministratorAccess`: ```javascript { "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": "*", "Resource": "*" } ] } ``` 3. The **ability to create DNS entries**, such as CNAME records, for your company's domain. 4. **An SSL certificate in the same region as your Quilt instance** to secure the domain where your users will access your Quilt instance. For example, to make your Quilt catalog available at `https://quilt.mycompany.com`, you require a certificate for `*.mycompany.com` in the [AWS Certificate Manager](https://aws.amazon.com/certificate-manager/). You may either [create a new certificate](https://docs.aws.amazon.com/acm/latest/userguide/gs-acm-request-public.html), or [import an existing certificate](https://docs.aws.amazon.com/acm/latest/userguide/import-certificate.html). 5. For maximum security, Quilt requires **a region that supports** [**AWS Fargate**](https://aws.amazon.com/about-aws/global-infrastructure/regional-product-services/). As of this writing, all U.S. regions support Fargate. 6. **An S3 Bucket** for your team data. This may be a new or existing bucket. The bucket should not have any notifications attached to it (S3 Console > Bucket > Properties > Events). Quilt will need to install its own notifications. Installing Quilt will modify the following Bucket characteristics: * Permissions > CORS configuration (will be modified for secure web access) * Properties > Versioning (will be enabled) * Properties > Object-level logging (will be enabled) * Properties > Events (will add one notification) 7. A **subdomain that is as yet not mapped in DNS** where users will access Quilt on the web. For example `quilt.mycompany.com`. 8. Available **CloudTrail Trails** in the region where you wish to host your stack ([learn more](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/WhatIsCloudTrail-Limits.html)). 9. An active subscription to Quilt Business on AWS Marketplace. Click `Continue to Subscribe` on the [Quilt Business Listing](https://aws.amazon.com/marketplace/pp/B07QF1VXFQ) to subscribe then return to this page for installation instructions. **The CloudFormation template and instructions on AWS Marketplace are infrequently updated and may be missing critical bugfixes.** ### AWS Marketplace You can install Quilt via AWS Marketplace. As indicated above, we recommend that you [contact us first](#installation-instructions). ### AWS Service Catalog 1. Email with your AWS account ID to request access to Quilt through the AWS Service Catalog and to obtain a license key. 2. Click the service catalog link that you received from Quilt. Arrive at the Service Catalog. Click IMPORT, lower right. ![](https://1207316453-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LDNT6ZcFbSZLsyC6aK9%2Fsync%2F7257e8742c4e122978ed79df62b107da47a750a6.png?generation=1589593548535027\&alt=media) 3. Navigate to Admin > Portfolios list > Imported Portfolios. Click Quilt Enterprise. ![](https://1207316453-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LDNT6ZcFbSZLsyC6aK9%2Fsync%2F5a5d4d584a781e7636e21681599c79d1a9d6b41f.png?generation=1589593547785766\&alt=media) 4. On the Portfolio details page, click ADD USER, GROUP OR ROLE. Add any users, **including yourself**, whom you would like to be able to install Quilt. ![](https://1207316453-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LDNT6ZcFbSZLsyC6aK9%2Fsync%2Fb2f98d016544531ea874d94c747ee6fa2e3d8165.png?generation=1589593550186919\&alt=media) 5. Click Products list, upper left. Click the menu to the left of Quilt CloudFormation Template. Click Launch product. (In the future, use the same menu to upgrade Quilt when a new version is released.) ![](https://1207316453-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LDNT6ZcFbSZLsyC6aK9%2Fsync%2Fae16b59bf43bab84c1425900242601a42b578d81.png?generation=1589593553313942\&alt=media) 6. Continue to the [CloudFormation](#CloudFormation) section. Note: the following screenshots may differ slightly fromm what you see in Service Catalog. ### CloudFormation 1. Specify stack details in the form of a stack *name* and CloudFormation *parameters*. Refer to the descriptions displayed above each text box for further details. Service Catalog users require a license key. See [Before you install Quilt](#before-you-install-quilt) for how to obtain a license key. ![](https://1207316453-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LDNT6ZcFbSZLsyC6aK9%2Fsync%2F9c920a79bbb347019a2770662aa3c860ae28a095.png?generation=1589593550808340\&alt=media) 2. Service Catalog users, skip this step. Under Stack creation options, enable termination protection. ![](https://1207316453-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LDNT6ZcFbSZLsyC6aK9%2Fsync%2Ff65cd5627411dbcd03b08cb99bd49a338a995c4b.png?generation=1589593549844949\&alt=media) This protects the stack from accidental deletion. Click Next. 3. Service Catalog users, skip this step. Check the box asking you to acknowledge that CloudFormation may create IAM roles, then click Create. ![](https://1207316453-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LDNT6ZcFbSZLsyC6aK9%2Fsync%2F35d0a4d989ad0e1f0f7da1b444d9c94ab75b9822.png?generation=1589593550796529\&alt=media) 4. CloudFormation takes about 30 minutes to create the resources for your stack. You may monitor progress under Events. Once the stack is complete, you will see `CREATE_COMPLETE` as the Status for your CloudFormation stack. ![](https://1207316453-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LDNT6ZcFbSZLsyC6aK9%2Fsync%2F60acd4eb799d81d7a858ddb180c86d350c90f051.png?generation=1589593550440652\&alt=media) 5. To finish the installation, you will want to view the stack Outputs. ![](https://1207316453-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LDNT6ZcFbSZLsyC6aK9%2Fsync%2Fa5387152515869895b27782b89458ab1e9bd6637.png?generation=1589593550470678\&alt=media) In a separate browser window, open the DNS settings for your domain. Create the following `CNAME` records. **Replace italics** with the corresponding stack Outputs. | CNAME | Value | | ---------------------- | --------------------- | | *QuiltWebHost Key* | *LoadBalancerDNSName* | | *RegistryHostName Key* | *LoadBalancerDNSName* | | *S3ProxyHost Key* | *LoadBalancerDNSName* | 6. Quilt is now up and running. You can click on the *QuiltWebHost* value in Outputs and log in with your administrator password to invite users. ## Advanced configuration The default Quilt settings are adequate for most use cases. The following section covers advanced customization options. ### Use Google to sign into Quilt You can enable users on your Google domain to sign in to Quilt. Refer to [Google's instructions on OAuth2 user agents](https://developers.google.com/identity/protocols/OAuth2UserAgent) and create authorization credentials to identify your Quilt stack to Google's OAuth 2.0 server. ![](https://1207316453-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LDNT6ZcFbSZLsyC6aK9%2Fsync%2Fa2166badaa06c348c8bacce5916c72671d8ee75a.png?generation=1589593550880101\&alt=media) In the template menu (CloudFormation or Service Catalog), select Google under *User authentication to Quilt*. Enter the domain or domains of your Google apps account under *SingleSignOnDomains*. Enter the *Client ID* of the OAuth 2.0 credentials you created into the field labeled *GoogleClientId* ![](https://1207316453-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LDNT6ZcFbSZLsyC6aK9%2Fsync%2F74d7e3b960a6578d7ab6731d6e400fc299605e4e.png?generation=1589593549721109\&alt=media) ### Preparing an AWS Role for use with Quilt These instructions document how to set up an existing role for use with Quilt. If the role you want to use doesn't exist yet, create it now. Go to your Quilt stack in CloudFormation. Go to `Outputs`, then find `RegistryRoleARN` and copy its value. It should look something like this: `arn:aws:iam::000000000000:role/stackname-ecsTaskExecutionRole`. Go to the IAM console and navigate to `Roles`. Select the role you want to use. Go to the `Trust Relationships` tab for the role, and select `Edit Trust Relationship`. The statement might look something like this: ```javascript { "Version": "2012-10-17", "Statement": [ "... one or more statements" ] } ``` Add an object to the beginning of the Statement array with the following contents: ```javascript { "Effect": "Allow", "Principal": { "AWS": "$YOUR_REGISTRY_ROLE_ARN" }, "Action": "sts:AssumeRole" }, ``` Note the comma after the object. Your trust relationship should now look something like this: ```javascript { "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Principal": { "AWS": "$YOUR_REGISTRY_ROLE_ARN" }, "Action": "sts:AssumeRole" }, "... whatever was here before" ] } ``` You can now configure a Quilt Role with this role (using the Catalog's admin panel, or `quilt3.admin.create_role`).