Quickstart
What is FormKiQ?
FormKiQ is an API-first document management platform that can run in any Amazon Web Services (AWS) account.
Document management is at the core of most organizations, with numerous documents that need to be stored, tracked, managed and organized. FormKiQ strives to be the most flexible, customizable and cost-effective document management system available.
FormKiQ’s flexibility and customizability comes from its API-first design. All document management functionality (CRUD) is exposed through a robust set of APIs. This allows anyone to quickly and easily to add document management functionality to any application and cut months off of development time, while the FormKiQ Console enables organizations to have a full-featured document management system with as little or as much customization as they need.
FormKiQ was built to run in any AWS account. This ensures that you maintain full control of your documents 100% of the time.
Prerequisites
For this quickstart you will need access to an AWS account, preferably with administrator access. The FormKiQ installation will create a number of AWS services and using an account with administrator access will ensure you have the correct permissions.
If you do not have a AWS account, you can sign up for one at https://aws.amazon.com.
Before installation verify that the AWSServiceRoleForECS has been enabled on your AWS Account. The easiest fix is to open up AWS CLI and run the following against your account once.
aws iam create-service-linked-role --aws-service-name ecs.amazonaws.comInstall FormKiQ
The FormKiQ installation process uses AWS CloudFormation. AWS CloudFormation is a service that automates the process of creating and managing cloud resources. It allows you to easily install and update FormKiQ using a single url.
To install FormKiQ, select the installation link for the AWS region you want to install FormKiQ to below.
AWS Region |
Install Link |
us-east-1 |
|
us-east-2 |
|
us-west-2 |
|
ca-central-1 |
|
eu-central-1 |
|
ap-south-1 |
|
ap-southeast-2 |
|
ap-northeast-2 |
|
sa-east-1 |
If the region you want to use is not listed, follow the SAM CLI Installation
| For FormKiQ Pro and Enterprise users, you’ll find a similar single click installation url in your custom GitHub repository you were provided. |
Clicking the installation link will bring you to the AWS Console Login if you are not already logged in. Once you are logged in, you will be taken to the CloudFormation Create Stack page. As you can see the Amazon S3 URL is automatically populated with the FormKiQ installation url. This url tells CloudFormation where it can find the CloudFormation yaml files that describes all the FormKiQ resources to create.
Clicking the Next button will take you to the stack details page. On this page we can configure FormKiQ.
The first thing you will need to set is the CloudFormation Stack Name. The Stack name can include letters (A-Z and a-z), numbers (0-9), and dashes (-). We recommended to use the naming convention formkiq-core-<app_environment>, ie: formkiq-core-prod, formkiq-core-dev, etc. The <app_environment> allows you to differentiate between multiple installations of FormKiQ. This will give context to each FormKiQ installation and prevent accidentally deleting the wrong FormKiQ installation stack.
| For production installations, we recommend using AWS Organizations to create a separate account to run your production version of FormKiQ. AWS makes it easy to switch between accounts within an organization, and best practice is to keep your production environment in a separate account from any non-production resources. This not only helps with security, but also to help organize your costs. Ideally, you would have a new AWS account within your AWS organization for each environment (e.g., dev, test/qa, staging/pre-prod, and production). |
Set the admin email address. During the FormKiQ installation, this email address will be automatically set up with administrator access. An email will be sent to the address that provides a link to where the administrator password can be set.
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.
FormKiQ uses AWS Fargate service to run certain services. AWS Fargate supports using either FARGATE or FARGATE_SPOT capacity provider. While FARGATE_SPOT is much cheaper, we recommend that it be used only for development environments, with FARGATE being used for production environments.
Whether to enable "/public" endpoints, defaults to false. Public endpoints allow external users to submit documents, such as through a web form. As with any publicly-available functionality, there is a risk of abuse if enabled.
| You can always enable/disable your public endpoints at any time by updating your FormKiQ CloudFormation Stack and changing the value you’ve set. |
FormKiQ uses Amazon Cognito as the identity store for all users. Cognito support number of different password policies that you can configure.
Optional: API Key to access the Typesense server. Typesense is used to provide full text search support for document metadata. The API Key can be any random string of characters. To enable Typesense, the VpcStackName also needs to be set (see VPC CloudFormation).
| Typesense is optional, since it requires a VPC to be created, which can add to your AWS usage costs. Without Typesense, you will only be able to search documents using tags and the document’s created date. |
Optional: The name of the FormKiQ VPC CloudFormation stack (currently used for both Typesense and OpenSearch). You will need to deploy the VPC CloudFormation in order to have a VPC Stack Name to provide here. We recommend that you create this main FormKiQ stack first, and then run the VPC stack, before finally updating the main stack with the VPC Stack Name.
Keep selecting Next until you get to the last Submit Create Stack page. Once you’ve checked the checkboxes, you can click Submit to being the stack creation.
The operation to create your new FormKiQ stack should take between fifteen and thirty minutes.
Welcome to FormKiQ Email
Once the FormKiQ CloudFormation installation has completed, an email will be sent to the email specified as the AdminEmail. This email will contain a link that will confirm the email address and allow the recipient to set a password for the administrator account.
Clicking the Verify Email link will allow you to set your administrator password.
Once your password is set you can now login to the FormKiQ Console.
Once in the FormKiQ Console, you can start working with FormKiQ.
| Additional FormKiQ users can be created using Amazon Cognito. See Authentication / Authorization for more information. |
VPC CloudFormation
Certain FormKiQ features (currently Typesense and the OpenSearch add-on for FormKiQ Enterprise) require a VPC to be configured, and then the FormKiQ stack needs to be updated to use that VPC.
Below you’ll find single-click installs links for creating a FormKiQ VPC.
Select the link below that is in the same region as your FormKiQ installation.
AWS Region |
Install Link |
us-east-1 |
|
us-east-2 |
|
us-west-2 |
|
ca-central-1 |
|
eu-central-1 |
|
ap-south-1 |
|
ap-southeast-2 |
|
ap-northeast-2 |
|
sa-east-1 |
Create stack
After clicking one of the one-click VPC installation links and logging into your AWS account, you’ll be brought to the CloudFormation Create Stack console. The Amazon S3 URL is populated with the FormKiQ VPC installation URL.
Click Next to continue to the configuration page.
Set Parameters
Stack Name will be needed for when you update the main FormKiQ stack.
EnableEnterpriseFeatures is for FormKiQ Enterprise; it must be set to true in order for FormKiQ Enterprise to be configured correctly for any add-ons or customizations. It is not required for FormKiQ Core or Pro.
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.
| 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 VPC is also configured with 3 public and 3 private subnets.
VpcLabel: you should also provide a label for the VPC. This will be visible in the AWS Management Console when viewing your VPCs, and will help identify this VPC in future.
Update FormKiQ Stack
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 current template.
For the VpcStackName parameter, set the value to the same value you used for the VPC stack you created above.
Keep selecting Next until you get to the last Submit Create Stack page. Once you’ve checked the checkboxes, you can click Submit to being the stack creation.