| sidebar_position | 2 |
|---|---|
| toc_max_heading_level | 2 |
Deploying FormKiQ into your AWS account with CloudFormation.
Deploy and configure FormKiQ in your AWS account in approximately 15 minutes using AWS CloudFormation. The automated setup process provisions and connects all required resources through a streamlined installation workflow.
import Head from '@docusaurus/Head';
{/* VideoObject Schema for the embedded YouTube video */}
<script type="application/ld+json"> {JSON.stringify({ "@context": "https://schema.org", "@type": "VideoObject", "name": "Deploying FormKiQ Core's Document Management Platform into Your AWS Account", "description": "Learn how to deploy and configure FormKiQ in your AWS account in approximately 15 minutes using AWS CloudFormation.", "thumbnailUrl": "https://i.ytimg.com/vi/G5R6ldbHYKs/hqdefault.jpg", "uploadDate": "2023-01-01T08:00:00+08:00", "contentUrl": "https://www.youtube.com/watch?v=G5R6ldbHYKs", "embedUrl": "https://www.youtube.com/embed/G5R6ldbHYKs" })} </script>
{/* HowTo Schema for the installation process */}
<script type="application/ld+json"> {JSON.stringify({ "@context": "https://schema.org", "@type": "HowTo", "name": "How to Deploy FormKiQ in Your AWS Account", "description": "Step-by-step guide to deploy FormKiQ document management platform in your AWS account using CloudFormation.", "step": [ { "@type": "HowToStep", "name": "Check Prerequisites", "text": "Ensure you have an AWS account with administrator access, AWS Lambda Concurrent Executions, and AWS Service Role for ECS enabled." }, { "@type": "HowToStep", "name": "Select Installation Link", "text": "Choose the installation link for your AWS region to launch the CloudFormation template." }, { "@type": "HowToStep", "name": "Configure Stack", "text": "Set stack name and configure installation parameters including admin email and app environment." }, { "@type": "HowToStep", "name": "Create Stack", "text": "Review configuration and create the CloudFormation stack." }, { "@type": "HowToStep", "name": "Configure Admin Password", "text": "Check admin email for verification link and set admin password." } ] })} </script>For this quickstart you will need access to an AWS account with administrator access to ensure proper permissions for creating required AWS services.
If you do not have a AWS account, you can sign up for one at https://aws.amazon.com.
Concurrent executions refer to the number of function invocations being handled simultaneously. AWS Lambda generally defaults to 10 concurrent executions per region, but this limit may be higher for some customers and accounts. It's best to request an increase to 1000 before installation.
Run aws cli command:
aws service-quotas get-service-quota --service-code lambda \
--quota-code L-B99A9384 --region <AWS_REGION>Resulting Value shows the AWS Lambda Concurrent executions.
{
"Quota": {
"ServiceCode": "lambda",
"ServiceName": "AWS Lambda",
"QuotaCode": "L-B99A9384",
"QuotaName": "Concurrent executions",
"Value": 1000.0,
"Unit": "None",
...
}
}:::note Request this increase for each region where you'll deploy FormKiQ. :::
Request through the Service Quotas Dashboard:
| AWS Region | Location | Request Increase Link |
|---|---|---|
| us-east-1 | N. Virginia | Request Increase |
| us-east-2 | Ohio | Request Increase |
| us-west-2 | Oregon | Request Increase |
| ca-central-1 | Canada (Central) | Request Increase |
| eu-central-1 | Frankfurt | Request Increase |
| eu-west-1 | Ireland | Request Increase |
| eu-west-3 | Paris | Request Increase |
| ap-south-1 | Mumbai | Request Increase |
| ap-southeast-1 | Singapore | Request Increase |
| ap-southeast-2 | Sydney | Request Increase |
| ap-northeast-2 | Seoul | Request Increase |
| sa-east-1 | São Paulo | Request Increase |
For more information, see the AWS Tutorial on Requesting a Quota Increase.
Verify that AWSServiceRoleForECS is enabled on your AWS Account before installation.
Run aws cli command:
aws iam create-service-linked-role --aws-service-name ecs.amazonaws.com:::note An error message "Service role name AWSServiceRoleForECS has been taken in this account" indicates this step is already complete. :::
For installation support, feedback, or updates, please join our FormKiQ Slack Community
:::note Ensure you've completed the prerequisites and enabled AWSServiceRoleforECS. :::
The FormKiQ installation uses AWS CloudFormation to automate resource creation and management.
Select your AWS region from the installation links below:
| AWS Region | Location | Install Link |
|---|---|---|
| us-east-1 | N. Virginia | Install FormKiQ |
| us-east-2 | Ohio | Install FormKiQ |
| us-west-2 | Oregon | Install FormKiQ |
| ca-central-1 | Canada (Central) | Install FormKiQ |
| eu-central-1 | Frankfurt | Install FormKiQ |
| eu-west-1 | Ireland | Install FormKiQ |
| eu-west-3 | Paris | Install FormKiQ |
| ap-south-1 | Mumbai | Install FormKiQ |
| ap-southeast-1 | Singapore | Install FormKiQ |
| ap-southeast-2 | Sydney | Install FormKiQ |
| ap-northeast-2 | Seoul | Install FormKiQ |
| sa-east-1 | São Paulo | Install FormKiQ |
:::note
- For unlisted regions, use SAM CLI installation
- FormKiQ Core supports AWS GovCloud (US) West but not East
- AWS China installations are not currently supported
- FormKiQ Essentials, Advanced, and Enterprise users: use your custom CloudFormation template links provided by the FormKiQ team :::
After selecting your region, you'll see the AWS CloudFormation Console with the FormKiQ installation URL pre-populated.
Click Next to continue.
Name your stack using the format formkiq-core-<app_environment> (e.g., formkiq-prod).
:::note For production, we recommend using AWS Organizations and separate accounts for different environments. :::
Configure your installation:
- AdminEmail: Administrator email address
- AppEnvironment: Environment identifier (prod, staging, dev, etc.)
- CapacityProvider: AWS Fargate capacity provider (for Typesense)
- EnablePublicUrls: Enable public endpoints (default: false)
- PasswordMinimumLength: Minimum password length
- Password Requirements: Several properties to configure requirements for length, lowercase, numbers, symbols, and uppercase
- TypesenseApiKey: API key for Typesense
- TypesenseMemory: Typesense memory allocation
- VpcStackName: VPC stack name (used for Typesense or OpenSearch)
Select ALL checkboxes at the bottom.
Click Next to proceed.
Review your configuration and click Submit.
:::info
- Installation takes 15-30 minutes
- You'll receive an admin email when complete :::
- Check your admin email for the verification link
- Click "Verify Email" to set your password
- Set your admin password
- Access the FormKiQ Console
:::note AWS GovCloud (US) requires manual admin user creation. :::
For Typesense or OpenSearch, install the VPC stack:
Select your region's VPC template:
| AWS Region | Location | Install Link |
|---|---|---|
| us-east-1 | N. Virginia | Install VPC |
| us-east-2 | Ohio | Install VPC |
| us-west-2 | Oregon | Install VPC |
| ca-central-1 | Canada (Central) | Install VPC |
| eu-central-1 | Frankfurt | Install VPC |
| eu-west-1 | Ireland | Install VPC |
| eu-west-3 | Paris | Install VPC |
| ap-south-1 | Mumbai | Install VPC |
| ap-southeast-1 | Singapore | Install VPC |
| ap-southeast-2 | Sydney | Install VPC |
| ap-northeast-2 | Seoul | Install VPC |
| sa-east-1 | São Paulo | Install VPC |
After selecting your VPC installation link and logging in, you'll see the CloudFormation Create Stack console with the pre-populated FormKiQ VPC installation URL.
Click the Next button to move to the next page.
The stack name uniquely identifies your FormKiQ VPC deployment within AWS CloudFormation.
We recommended to use the naming convention formkiq-vpc.
The following is description of the VPC installation parameters:
If you are using OpenSearch, you need to enable enterprise features, which automatically setups VPC endpoints.
:::note This is not required for FormKiQ Core. :::
The VPC sets up 3 public, and 3 private subnets.
When creating the VPC, you need to specify an IPv4 network range for the VPC, in CIDR notation. For example, 10.1.0.0/16.
:::note We recommend choosing a CIDR block that you know is not being used by any existing AWS resources in your AWS Organization. Ideally, each AWS account (one for each environment) is using its own CIDR range, e.g., 10.10.0.0/16 for dev, 10.20.0.0/16 for test/qa, etc. :::
The label added to the created VPC. This will be visible in the AWS Management Console when viewing your VPCs, and will help identify this VPC in future.
Scroll down to the bottom of the page, select ALL the checkboxes.
Click the Next button to move to the next page.
Scroll down to the bottom.
Click the Submit button to start the VPC installation.
:::info Once the installation has completed, you will need to attach this Stack to your FormKiQ installation, by updating the VpcStackName parameter. :::
This step is essential in order to enable access to Typesense or OpenSearch
After creating the VPC stack, the main FormKiQ CloudFormation stack needs to be updated. Select the FormKiQ CloudFormation stack and then click the Update button.
When updating the stack you will want to choose Use existing template.
For the VpcStackName parameter, set the value to the same value you used for the VPC stack you created above; in our example, it was formkiq-vpc.
Click the Next button to move to the next pages. On the last page click the Submit button to update the FormKiQ stack. After the Stack completes updating, the FormKiQ installation will have the VPC features enabled.
FormKiQ Core was built using the AWS Serverless Application Model (SAM) framework.
The Serverless Application Model Command Line Interface (SAM CLI) is an extension of the AWS CLI that adds functionality for deploying serverless applications.
To use SAM CLI, you will need to install the following tools:
- AWS CLI - Install the AWS CLI (https://aws.amazon.com/cli/)
- SAM CLI - Install the SAM CLI (https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/serverless-sam-cli-install.html)
The latest version of FormKiQ Core can be found on the https://github.com/formkiq/formkiq-core/releases page on Github.
Download the file with the naming convention of: formkiq-core-X.X.X.zip
Once downloaded, unzip the file in its own directory.
INSTALL.md
LICENSE
template.yaml
...
To deploy FormKiQ Core, run the following command in the same folder as the template.yaml file.
sam deploy --guided --capabilities CAPABILITY_IAM CAPABILITY_AUTO_EXPAND CAPABILITY_NAMED_IAMThe command will package and deploy your application to AWS, with a series of prompts:
| Argument | Description | Default Value |
|---|---|---|
| Stack Name | The name of the stack to deploy to CloudFormation. This should be unique to your account and region | formkiq-core-<AppEnvironment> |
| AdminEmail | Set the admin email address. During the FormKiQ installation, this email address will be automatically set up with administrator access. | |
| AppEnvironment | AppEnvironment is a unique identifier for FormKiQ installations. The identifier should provider context to what kind of information is contained in the installation, IE: prod, staging, dev. | prod |
| EnablePublicUrls | Whether to enable "/public" endpoints. | false |
| PasswordMinimumLength | Minimum Password Length | 8 |
| PasswordRequireLowercase | Whether Password requires a lowercase letter | false |
| PasswordRequireNumbers | Whether Password requires a number | false |
| PasswordRequireSymbols | Whether Password requires a symbol | false |
| PasswordRequireUppercase | Whether Password requires a uppercase letter | false |
| VpcStackName | Optional: The name of the FormKiQ VPC CloudFormation stack | null |
| TypesenseApiKey | Optional: API Key to access the Typesense server | null |
| CapacityProvider | Optional: CapacityProvider used by AWS Fargate service | FARGATE_SPOT |
- Confirm changes before deploy: If set to yes, any change sets will be shown to you before execution for manual review. If set to no, the AWS SAM CLI will automatically deploy application changes.
- Allow SAM CLI IAM role creation: FormKiQ Core's AWS SAM templates create AWS IAM roles required for the AWS Lambda function(s) included to access AWS services. The permissions are passed in by the
sam deploycommand above. Set Value to 'Y' - Save arguments to samconfig.toml: If set to yes, your choices will be saved to a configuration file inside the project, so that in the future you can just re-run
sam deploywithout parameters to deploy changes to your application.
Once you have set all of these options, SAM CLI will create a changeset and will display a list of all actions that will be performed as part of the changeset. If you have set "confirm changes before deploy" to "y", you will then be asked whether or nor to deploy this changeset. Choose "y" to complete the installation.
Once the FormKiQ Core stack has been deployed, you will be able to find your API Gateway Endpoint URL in the output values displayed after deployment.
Due to restrictions related to AWS GovCloud (US) and the lack of CloudFront availability, the FormKiQ Document Console is not installed as part of the deployment. Instead, you can deploy a docker image into GovCloud for internal or external access. More information can be found here.
To try out the API, try our API Walkthrough. You can also check out the FormKiQ API Reference for more endpoints you can try out.