Deployment Using CDK Code

Version 2.1 by Sanchita Singh on 2021/08/10

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 Cloudformation template given above. 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 much easier way as compared to cloudformation template.

Deployment Steps Using CDK Code

Deployment Options

Here, we provide two different types of installation one demo/test installation and another one the production installation. Demo installation Provides a built-in XWiki, with a portable database (HSQLDB) and a lightweight Java container (Jetty). This standalone distribution is not recommended in a production environment. If you need to use it on a production basis, you may look at the other option. With that there is an obvious choice of version of XWiki, we recommend these two options though you can install a specific version of your choice.

  • Long-term support: This version is the latest stable version from the last XWiki cycle. This is the most stable version and is recommended to use in production.
  • Stable: This version is the latest stable version from the current XWiki cycle. This is the version recommended if you wish to try out the new features from the cycle.

Prerequisite: You should have AWS Command Line Interface (CLI) installed and configured. you can refer to this, in case you don't have CLI installed

Prerequisite: you should be using root account or atleast IAM user with root privelages. Otherwise you might get error regarding permissions to create resources.

Demo Installation

What You Will Build

Here, you will have an EC2 instance and inside it a built-in XWiki, with a portable database (HSQLDB) and a lightweight Java container (Jetty). You need to simply SSH into the EC2 instance and start XWiki. Follow the step-by-step instruction to do so.
This installation is not to used in production. This is for only for Demo puposes 

Deploying Demo XWiki

  • First step would be to make a key in AWS console with name test. to do so, follow this guide. make sure to keep the name of your key-pair "test".
  • Clone the repo https://github.com/xwiki-contrib/aws
    git clone https://github.com/xwiki-contrib/aws.git
  • Navigate into the clone Diretory
    cd aws
  • Navigate into the Demo Diretory
    cd xwiki-demo-cdk
  • Install all needed packages locally
    npm install
  • Execute the deployment, and wait for the process to get complete.
    cdk deploy
  • You have an EC2 instance with XWiki demo installed. Now to start the server, SSH into the newly created instance
    and start xwiki.
  • For starting XWiki, go into the folder
    cd xwikihome && cd xwiki-platform-distribution-flavor-jetty-hsqldb-13.1 
  • run start_xwiki.sh
    chmod +x ./start_xwiki.sh && ./start_xwiki.sh
  • Now, to connect to XWiki you need to go to port 8080 of public Ip address. 

Production Installation

What You Will Build

Using this Clodformation template you'll be provisioning these resources in your AWS account. for more details on sytem Design check Design Page

  • 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 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. You can check this link 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 idea about code style an how to modify it according to your needs. You can get whole code in the github repository.

Deploying Production Xwiki

After installing and configuring AWS Command Line interface (CLI) with 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.

  • Clone the repo https://github.com/xwiki-contrib/aws
    git clone https://github.com/xwiki-contrib/aws.git
  • Navigate into the clone Diretory
    cd aws
  • Navigate into the Demo Diretory
    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 our 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.
Tags:
   

Get Connected