Deployment Using CDK Code

Last modified by Sanchita Singh on 2021/09/08

Installation on AWS is currently an XWiki Contrib project and not supported by the core XWiki Dev Team.

Overview

Another method you can use to deploy XWiki in your AWS account is by using the CDK code. AWS CDK or Cloud Development Kit is used in order to provision resources inside an AWS Account without the hassle of creating them manually and helps to lock down on configurations required for provisioning those resources so as to maintain consistency across various stages and installs. With CDK we can write infrastructure as code in languages like typescript, python, java, .NET. If you prefer to install your XWiki instance in a couple of clicks from the console we recommend you to use the Cloudformation Template. But if you are a fan of AWS CLI and/or want to tweak the configuration according to your needs you can use the CDK code. You'll need basic programming knowledge if you want to tweak configuration according to you. But you can do it in CDK code in a much easier way as compared to the cloudFormation template.

Pre-Requisites

XWiki Installation

What You Will Build

Using this Clodformation template you'll be provisioning these resources in your AWS account.

  • A virtual private cloud (VPC) that is configured across two Availability Zones. For each Availability Zone, this template provisions one public subnet and one private subnet, according to AWS best practices.
  • In the public subnets, managed network address translation (NAT) gateways to provide outbound internet connectivity for instances in the private subnets.
  • In the private subnets, Amazon Elastic File System(EFS), which provides simple, scalable file storage for XWiki files, Amazon Aurora database instances running MySQL and Elastic Container Service(ECS) fargate service.
  • An AWS Loadbalancer, which you will connect to using the DNS provided at the end of the installation.
  • An AWS Identity and Access Management (IAM) role to enable AWS resources created through the Template to access other AWS resources when required.

The production installation will create the following resources in your AWS account.

Configuration parts within CDK in more details

Here we will have a look at some parts of the code and how you can configure it if you want according to your needs

  • Inside the lib folder, we have the config.ts file. There you will have two basic required configurations. First, one being the region you want to deploy your resources into and the second is the version of XWiki you want to choose. You can edit this file according to your needs. We recommend you to use xwiki:stable-mysql-tomcat or xwiki:lts-mysql-tomcat to set for xwikiversion. Though you can choose any other mysql-tomcat version from Docker Hub for the tag to be used for your preferred version.
    export const region = 'us-east-1'; // region in which you want to configure xwiki instance
    export const xwikiVersion = 'xwiki:mysql-tomcat' //or 'xwiki:mysql-stable-tomcat'
  • Inside the lib/stacksvpc.ts you have the IAAC that will provision a new VPC in your account. Here we used cidr: 10.42.42.0/24 which is small but sufficient for this installation. You can increase this if you wish to deploy other services inside this network in future.
     public readonly xwikivpc: Vpc;
       constructor (scope: cdk.App, id: string, props?: cdk.StackProps) {
         super(scope, id, props)
           this.xwikivpc = new Vpc(this, 'xwiki-vpc', {
            cidr: '10.42.42.0/24',
            defaultInstanceTenancy: DefaultInstanceTenancy.DEFAULT,
            maxAzs: 2,
            natGatewayProvider: NatProvider.gateway(),
            natGateways: 1,
            subnetConfiguration: [
              {
                name: 'public',
                subnetType: SubnetType.PUBLIC,
                cidrMask: 27
              },
              {
                name: 'private-database',
                subnetType: SubnetType.PRIVATE,
                cidrMask: 26
              }
            ]
          })
        }
  • We have configured two encryption keys to be used for storing resources passwords etc. We have enabled rotation by default, as suggested to be the best practice according to AWS documentation.  AWS KMS rotates the key automatically every year. You don't need to remember or schedule the update.
    const xwikiEncryptionKey = new Key(this, 'XWikiEncryptionKey', { //encryption key to be used by the file system and rds
           alias: `xwiki`,
           description: `Encryption Key for XWiki Storage Resources`,
           enableKeyRotation: true,
           enabled: true,
           trustAccountIdentities: true,
          });
    const xwikiSecretEncryptionKey = new Key(this, 'XWikiSecretEncryptionKey', { //used for fenerating password for rds
           alias: `xwiki-secret`,
           description: `Encryption Key for XWiki Secrets`,
           enableKeyRotation: true,
           enabled: true,
           trustAccountIdentities: true,
          });
  • We have configured two encrytion keys to be used for storing resources passowrd etc. We have enabled rotation by default and uses the key that we configured earlier
      const xwikiEfs = new FileSystem(this, 'XWikiFileSystem', { // File System that will conatin static xwiki files
            vpc: props.vpc,
            enableAutomaticBackups: true,
           encrypted: true,
            kmsKey: xwikiEncryptionKey,
            performanceMode: PerformanceMode.GENERAL_PURPOSE,
            securityGroup: xwikiEfsSg,
            vpcSubnets: props.vpc.selectSubnets(
             {
                subnetType: SubnetType.PRIVATE
             }
            )
         });

This is not the whole configuration but only a part to give you an idea about code style and how to modify it according to your needs. You can get the whole code in the Github repository.

Deploying Production XWiki

After installing and configuring the AWS Command Line Interface (CLI) with an access key and secret access key belonging to your root account or IAM user with root privileges, follow these steps to get your XWiki deployed.

  • Navigate into the clone Directory
    cd aws
  • Navigate into the Production Directory
    cd xwiki-production-cdk
  • Install all needed packages locally
    npm install
  • Execute the deployment, and wait for the process to get complete.
    cdk deploy --all
  • The stacks will be deployed in the region set in the config.ts file in lib folder. The default set region is us-east-1.
  • TIP: Consider choosing a region closest to your data center or corporate network to reduce network latency between systems running on AWS and the systems and users on your corporate network.
  • Monitor the status of creation of stacks in your command line and answer yes to the prompt questions asking permission to deploy. You will see this at the end of deployment of stacks.

    cdk-output-aws.png

  • Connect to the LoadBalancer DNS shown in the output of the previous command to configure your newly hosted XWiki installation

    xwiki-installed-output.png

Github Repository

You can visit the GitHub repository to download the CDK code for this deployment to modify it for your needs and to post your comments,

Troubleshooting

  • You might get an ‘ResourceLimitExceeded’ error while deploying the stack. You get this error when ther resource you are trying to create already reached it quota limit. But you can request to increase quota in your AWS account. It can take a few days for the new service quota to become effective. For more details on how to request quota increase, refer to, https://aws.amazon.com/premiumsupport/knowledge-center/resourcelimitexceeded-sagemaker/
  • If you get an “Unrecognised Resources” error you are creating the stack in a region where not all the resources needed are available. To solve this change the region to some other nearest region to your center.

Get Connected