Wiki source code of Deployment Using CDK Code

Last modified by Sanchita Singh on 2021/09/08

version	line-number	content
4.2	1	{{box cssClass="floatinginfobox" title="Contents"}}
	2	{{toc start="1" depth="6" numbered="false" scope="page"/}}
	3	{{/box}}
	4
	5	{{warning}}
4.6	6	Installation on AWS is currently an XWiki Contrib project and not supported by the core XWiki Dev Team.
4.2	7	{{/warning}}
	8
4.6	9	= Overview =
	10
6.1	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 the cloudFormation template.
4.6	12
4.14	13	= Pre-Requisites =
1.1	14
4.15	15	* 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.
5.3	16	* 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.
4.13	17	* You must have [[NPM installed>>https://docs.npmjs.com/downloading-and-installing-node-js-and-npm]] or use a docker image.
1.1	18
6.1	19	= XWiki Installation =
4.2	20
4.8	21	== What You Will Build ==
4.2	22
4.5	23	Using this Clodformation template you'll be provisioning these resources in your AWS account.
4.2	24
2.1	25	* 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.
	26	* In the public subnets, managed network address translation (NAT) gateways to provide outbound internet connectivity for instances in the private subnets.
4.4	27	* 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.
4.6	28	* An AWS Loadbalancer, which you will connect to using the DNS provided at the end of the installation.
2.1	29	* An AWS Identity and Access Management (IAM) role to enable AWS resources created through the Template to access other AWS resources when required.
4.6	30
2.1	31	The production installation will create the following resources in your AWS account.
	32
4.8	33	== Configuration parts within CDK in more details ==
4.2	34
2.1	35	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
4.2	36
4.6	37	* 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.(((
4.16	38	{{code language="TypeScript"}}
	39	export const region = 'us-east-1'; // region in which you want to configure xwiki instance
	40	export const xwikiVersion = 'xwiki:mysql-tomcat' //or 'xwiki:mysql-stable-tomcat'
	41	{{/code}}
4.6	42	)))
	43	* 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.(((
4.16	44	{{code language="TypeScript"}}
	45	public readonly xwikivpc: Vpc;
2.1	46	constructor (scope: cdk.App, id: string, props?: cdk.StackProps) {
	47	super(scope, id, props)
	48	this.xwikivpc = new Vpc(this, 'xwiki-vpc', {
	49	cidr: '10.42.42.0/24',
	50	defaultInstanceTenancy: DefaultInstanceTenancy.DEFAULT,
	51	maxAzs: 2,
	52	natGatewayProvider: NatProvider.gateway(),
	53	natGateways: 1,
	54	subnetConfiguration: [
	55	{
	56	name: 'public',
	57	subnetType: SubnetType.PUBLIC,
	58	cidrMask: 27
	59	},
	60	{
	61	name: 'private-database',
	62	subnetType: SubnetType.PRIVATE,
	63	cidrMask: 26
	64	}
	65	]
	66	})
4.16	67	}
	68	{{/code}}
4.6	69	)))
	70	* 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.(((
4.16	71	{{code}}
	72	const xwikiEncryptionKey = new Key(this, 'XWikiEncryptionKey', { //encryption key to be used by the file system and rds
2.1	73	alias: `xwiki`,
	74	description: `Encryption Key for XWiki Storage Resources`,
	75	enableKeyRotation: true,
	76	enabled: true,
	77	trustAccountIdentities: true,
	78	});
	79	const xwikiSecretEncryptionKey = new Key(this, 'XWikiSecretEncryptionKey', { //used for fenerating password for rds
	80	alias: `xwiki-secret`,
	81	description: `Encryption Key for XWiki Secrets`,
	82	enableKeyRotation: true,
	83	enabled: true,
	84	trustAccountIdentities: true,
4.16	85	});
	86	{{/code}}
4.6	87	)))
	88	* 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(((
4.16	89	{{code}}
	90	const xwikiEfs = new FileSystem(this, 'XWikiFileSystem', { // File System that will conatin static xwiki files
2.1	91	vpc: props.vpc,
	92	enableAutomaticBackups: true,
	93	encrypted: true,
	94	kmsKey: xwikiEncryptionKey,
	95	performanceMode: PerformanceMode.GENERAL_PURPOSE,
	96	securityGroup: xwikiEfsSg,
	97	vpcSubnets: props.vpc.selectSubnets(
	98	{
	99	subnetType: SubnetType.PRIVATE
	100	}
	101	)
4.16	102	});
	103	{{/code}}
4.6	104	)))
	105
4.16	106	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]].
4.2	107
4.8	108	== Deploying Production XWiki ==
4.2	109
4.3	110	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.
4.2	111
5.6	112	* Clone the repo [[https:~~/~~/github.com/xwiki-contrib/aws>>https://github.com/xwiki-contrib/aws]](((
	113	{{code language="bash"}}
	114	git clone https://github.com/xwiki-contrib/aws.git
	115	{{/code}}
	116	)))
5.5	117
4.16	118	* Navigate into the clone Directory(((
	119	{{code language="bash"}}
	120	cd aws
	121	{{/code}}
4.6	122	)))
4.16	123	* Navigate into the Production Directory(((
	124	{{code language="bash"}}
	125	cd xwiki-production-cdk
	126	{{/code}}
4.6	127	)))
	128	* Install all needed packages locally(((
4.16	129	{{code language="bash"}}
	130	npm install
	131	{{/code}}
4.6	132	)))
	133	* Execute the deployment, and wait for the process to get complete.(((
4.16	134	{{code language="bash"}}
	135	cdk deploy --all
	136	{{/code}}
4.6	137	)))
5.4	138	* {{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}}
2.1	139
5.4	140	* {{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}}
2.1	141
	142	* 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.(((
	143	{{image reference="cdk-output-aws.png"/}}
	144	)))
4.2	145	* Connect to the LoadBalancer DNS shown in the output of the previous command to configure your newly hosted XWiki installation(((
2.1	146	{{image reference="xwiki-installed-output.png"/}}
	147	)))
	148
4.8	149	= Github Repository =
4.2	150
4.6	151	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,
2.1	152
4.2	153	= Troubleshooting =
	154
2.1	155	* 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/
	156	* 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.

Wiki source code of Deployment Using CDK Code

Quick Links

Navigation

About

About

Support

Platform

User Guide

Admin Guide

Developer Guide

Projects

XWiki

Extensions

Other

Contribute

Status

Practices

Under the Hood

Get Involved

Get Connected