Wiki source code of Deployment Using CDK Code
Version 5.9 by Vincent Massol on 2021/08/30
Show last authors
| author | version | line-number | content |
|---|---|---|---|
| 1 | {{box cssClass="floatinginfobox" title="**Contents**"}} | ||
| 2 | {{toc start="1" depth="6" numbered="false" scope="page"/}} | ||
| 3 | {{/box}} | ||
| 4 | |||
| 5 | {{warning}} | ||
| 6 | Installation on AWS is currently an XWiki Contrib project and not supported by the core XWiki Dev Team. | ||
| 7 | {{/warning}} | ||
| 8 | |||
| 9 | = Overview = | ||
| 10 | |||
| 11 | 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>>Documentation.AdminGuide.Installation.XWiki Installation on AWS.Deployment Using Cloudformation Template.WebHome]]. 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 cloudFormation template. | ||
| 12 | |||
| 13 | = Deployment Options = | ||
| 14 | |||
| 15 | Here, we provide two different types of installation: one demo/test installation and another one for a 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. | ||
| 16 | |||
| 17 | * 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. | ||
| 18 | * 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. | ||
| 19 | |||
| 20 | = Pre-Requisites = | ||
| 21 | |||
| 22 | * You must have the [[AWS CDK Command Line Interface (CLI) installed and configured>>https://docs.aws.amazon.com/de_de/cdk/latest/guide/getting_started.html]] or use a docker image. | ||
| 23 | * You should be using a root account or at least an IAM user with all the permission required mentioned [[here>>doc:Documentation.AdminGuide.Installation.XWiki Installation on AWS.WebHome]]. Otherwise, you might get errors regarding permissions to create resources. | ||
| 24 | * You must have [[NPM installed>>https://docs.npmjs.com/downloading-and-installing-node-js-and-npm]] or use a docker image. | ||
| 25 | |||
| 26 | = Demo Installation = | ||
| 27 | |||
| 28 | == What You Will Build == | ||
| 29 | |||
| 30 | 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. | ||
| 31 | |||
| 32 | {{warning}} | ||
| 33 | This installation is not to use in production. This is only for Demo purposes. | ||
| 34 | {{/warning}} | ||
| 35 | |||
| 36 | == Changing the version == | ||
| 37 | |||
| 38 | To change the version, go to config.ts file in lib/stacks file. You can change the variable {{code}}xwikidownload{{/code}} to the download link of the XWiki version of your choice from the [[download XWiki>>doc:Download.WebHome]] (click on the Download button for the version and then get the download link for the Standard Flavor Pre-installed package). Change the {{code}}region{{/code}} variable according to what region you want the EC2 instance to be created. | ||
| 39 | |||
| 40 | == Deploying Demo XWiki == | ||
| 41 | |||
| 42 | * First step would be to [[make a key in AWS console with name ##xwiki-demo-key##>>https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-key-pairs.html#having-ec2-create-your-key-pair]]. Make sure to keep the name of your key-pair ##xwiki-demo-key##. | ||
| 43 | * Clone the repo https://github.com/xwiki-contrib/aws ((( | ||
| 44 | {{code language="bash"}}git clone https://github.com/xwiki-contrib/aws.git{{/code}} | ||
| 45 | ))) | ||
| 46 | * Navigate into the cloned directory((( | ||
| 47 | {{code language="bash"}} | ||
| 48 | cd aws | ||
| 49 | {{/code}} | ||
| 50 | ))) | ||
| 51 | * Navigate into the Demo directory((( | ||
| 52 | {{code language="bash"}} | ||
| 53 | cd xwiki-demo-cdk | ||
| 54 | {{/code}} | ||
| 55 | ))) | ||
| 56 | * Install all needed packages locally((( | ||
| 57 | {{code language="bash"}} | ||
| 58 | npm install | ||
| 59 | {{/code}} | ||
| 60 | |||
| 61 | or with docker: | ||
| 62 | |||
| 63 | {{code language="bash"}} | ||
| 64 | docker run -v "$PWD":/usr/src/app -w /usr/src/app node npm install | ||
| 65 | {{/code}} | ||
| 66 | ))) | ||
| 67 | * Execute the deployment, and wait for the process to get complete.((( | ||
| 68 | {{code language="bash"}} | ||
| 69 | cdk deploy | ||
| 70 | {{/code}} | ||
| 71 | ))) | ||
| 72 | * You have an EC2 instance with an XWiki demo installed. Now to start the server, SSH into the newly created instance | ||
| 73 | and start XWiki. To SSH into the server follow the below steps. | ||
| 74 | ** Open an SSH client. | ||
| 75 | ** Locate your private key file. The key you downloaded in the previous step | ||
| 76 | ** {{code language="bash"}} ssh -i /path/xwiki-demo-key.pem my-instance-user-name@my-instance-public-dns-name {{/code}} | ||
| 77 | ** Here, /path/xwiki-demo-key.pem is the path of the key you downloaded while creating the key earlier and 'my-instance-user-name@my-instance-public-dns-name' is the name of your EC2 instance and its public DNS. To get these go EC2 in the AWS console and select your newly created instance. go to the "connect" tab and select "SSH client" | ||
| 78 | * For starting XWiki, go into the folder. Change the name of the folder will be according to the version you downloaded. ((( | ||
| 79 | {{code language="bash"}} | ||
| 80 | cd xwikihome && cd xwiki-platform-distribution-flavor-jetty-hsqldb-13.1 | ||
| 81 | {{/code}} | ||
| 82 | ))) | ||
| 83 | * run ##start_xwiki.sh##((( | ||
| 84 | {{code language="bash"}} | ||
| 85 | chmod +x ./start_xwiki.sh && ./start_xwiki.sh | ||
| 86 | {{/code}} | ||
| 87 | ))) | ||
| 88 | * Now, to connect to XWiki you need to go to port 8080 of public IP address. | ||
| 89 | |||
| 90 | = Production Installation = | ||
| 91 | |||
| 92 | == What You Will Build == | ||
| 93 | |||
| 94 | Using this Clodformation template you'll be provisioning these resources in your AWS account. | ||
| 95 | |||
| 96 | * 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. | ||
| 97 | * In the public subnets, managed network address translation (NAT) gateways to provide outbound internet connectivity for instances in the private subnets. | ||
| 98 | * 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. | ||
| 99 | * An AWS Loadbalancer, which you will connect to using the DNS provided at the end of the installation. | ||
| 100 | * An AWS Identity and Access Management (IAM) role to enable AWS resources created through the Template to access other AWS resources when required. | ||
| 101 | |||
| 102 | The production installation will create the following resources in your AWS account. | ||
| 103 | |||
| 104 | == Configuration parts within CDK in more details == | ||
| 105 | |||
| 106 | 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 | ||
| 107 | |||
| 108 | * 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>>https://hub.docker.com/_/xwikitab=tags&page=1&ordering=last_updated&name=mysql-tomcat]] for the tag to be used for your preferred version.((( | ||
| 109 | {{code language="TypeScript"}} | ||
| 110 | export const region = 'us-east-1'; // region in which you want to configure xwiki instance | ||
| 111 | export const xwikiVersion = 'xwiki:mysql-tomcat' //or 'xwiki:mysql-stable-tomcat' | ||
| 112 | {{/code}} | ||
| 113 | ))) | ||
| 114 | * 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.((( | ||
| 115 | {{code language="TypeScript"}} | ||
| 116 | public readonly xwikivpc: Vpc; | ||
| 117 | constructor (scope: cdk.App, id: string, props?: cdk.StackProps) { | ||
| 118 | super(scope, id, props) | ||
| 119 | this.xwikivpc = new Vpc(this, 'xwiki-vpc', { | ||
| 120 | cidr: '10.42.42.0/24', | ||
| 121 | defaultInstanceTenancy: DefaultInstanceTenancy.DEFAULT, | ||
| 122 | maxAzs: 2, | ||
| 123 | natGatewayProvider: NatProvider.gateway(), | ||
| 124 | natGateways: 1, | ||
| 125 | subnetConfiguration: [ | ||
| 126 | { | ||
| 127 | name: 'public', | ||
| 128 | subnetType: SubnetType.PUBLIC, | ||
| 129 | cidrMask: 27 | ||
| 130 | }, | ||
| 131 | { | ||
| 132 | name: 'private-database', | ||
| 133 | subnetType: SubnetType.PRIVATE, | ||
| 134 | cidrMask: 26 | ||
| 135 | } | ||
| 136 | ] | ||
| 137 | }) | ||
| 138 | } | ||
| 139 | {{/code}} | ||
| 140 | ))) | ||
| 141 | * 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.((( | ||
| 142 | {{code}} | ||
| 143 | const xwikiEncryptionKey = new Key(this, 'XWikiEncryptionKey', { //encryption key to be used by the file system and rds | ||
| 144 | alias: `xwiki`, | ||
| 145 | description: `Encryption Key for XWiki Storage Resources`, | ||
| 146 | enableKeyRotation: true, | ||
| 147 | enabled: true, | ||
| 148 | trustAccountIdentities: true, | ||
| 149 | }); | ||
| 150 | const xwikiSecretEncryptionKey = new Key(this, 'XWikiSecretEncryptionKey', { //used for fenerating password for rds | ||
| 151 | alias: `xwiki-secret`, | ||
| 152 | description: `Encryption Key for XWiki Secrets`, | ||
| 153 | enableKeyRotation: true, | ||
| 154 | enabled: true, | ||
| 155 | trustAccountIdentities: true, | ||
| 156 | }); | ||
| 157 | {{/code}} | ||
| 158 | ))) | ||
| 159 | * 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((( | ||
| 160 | {{code}} | ||
| 161 | const xwikiEfs = new FileSystem(this, 'XWikiFileSystem', { // File System that will conatin static xwiki files | ||
| 162 | vpc: props.vpc, | ||
| 163 | enableAutomaticBackups: true, | ||
| 164 | encrypted: true, | ||
| 165 | kmsKey: xwikiEncryptionKey, | ||
| 166 | performanceMode: PerformanceMode.GENERAL_PURPOSE, | ||
| 167 | securityGroup: xwikiEfsSg, | ||
| 168 | vpcSubnets: props.vpc.selectSubnets( | ||
| 169 | { | ||
| 170 | subnetType: SubnetType.PRIVATE | ||
| 171 | } | ||
| 172 | ) | ||
| 173 | }); | ||
| 174 | {{/code}} | ||
| 175 | ))) | ||
| 176 | |||
| 177 | 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>>https://github.com/xwiki-contrib/aws]]. | ||
| 178 | |||
| 179 | == Deploying Production XWiki == | ||
| 180 | |||
| 181 | 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. | ||
| 182 | |||
| 183 | * Clone the repo [[https:~~/~~/github.com/xwiki-contrib/aws>>https://github.com/xwiki-contrib/aws]]((( | ||
| 184 | {{code language="bash"}} | ||
| 185 | git clone https://github.com/xwiki-contrib/aws.git | ||
| 186 | {{/code}} | ||
| 187 | ))) | ||
| 188 | |||
| 189 | * Navigate into the clone Directory((( | ||
| 190 | {{code language="bash"}} | ||
| 191 | cd aws | ||
| 192 | {{/code}} | ||
| 193 | ))) | ||
| 194 | * Navigate into the Production Directory((( | ||
| 195 | {{code language="bash"}} | ||
| 196 | cd xwiki-production-cdk | ||
| 197 | {{/code}} | ||
| 198 | ))) | ||
| 199 | * Install all needed packages locally((( | ||
| 200 | {{code language="bash"}} | ||
| 201 | npm install | ||
| 202 | {{/code}} | ||
| 203 | ))) | ||
| 204 | * Execute the deployment, and wait for the process to get complete.((( | ||
| 205 | {{code language="bash"}} | ||
| 206 | cdk deploy --all | ||
| 207 | {{/code}} | ||
| 208 | ))) | ||
| 209 | * {{warning}}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##.{{/warning}} | ||
| 210 | |||
| 211 | * {{info}}**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.{{/info}} | ||
| 212 | |||
| 213 | * 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.((( | ||
| 214 | {{image reference="cdk-output-aws.png"/}} | ||
| 215 | ))) | ||
| 216 | * Connect to the LoadBalancer DNS shown in the output of the previous command to configure your newly hosted XWiki installation((( | ||
| 217 | {{image reference="xwiki-installed-output.png"/}} | ||
| 218 | ))) | ||
| 219 | |||
| 220 | = Github Repository = | ||
| 221 | |||
| 222 | You can visit the [[GitHub repository>>https://github.com/xwiki-contrib/aws]] to download the CDK code for this deployment to modify it for your needs and to post your comments, | ||
| 223 | |||
| 224 | = Troubleshooting = | ||
| 225 | |||
| 226 | * 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/ | ||
| 227 | * 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. |
