This hands-on will go through the basics of XL-Deploy
and XL-Release
. XL-Deploy
is used for deploying applications and XL-Release
for orchestrating your release pipeline. We'll use PetClinic
as a "Hello World" appliction to demonstrate deployments and version differences. PetClinic
is deployed on a Tomcat server. XL-Deploy
, XL-Release
and Tomcat
are installed on a Alpine Linux VM using VirtualBox
.
- Oracle VM VirtualBox
- Internet Browser, like Chrome, Firefox or Edge
- Optional: If you want to check the VM, you can use a SSH terminal like putty to login to the VM(allows scaling of the command window and easy use of copy-paste)
Alpine Linux hosts all applications used in this session. Tomcat is installed on the VM, while XL-Deploy and XL-Release are available as docker containers with data persistence on the VM. The VM is available as an appliance you can import in your VirtualBox. The appliance also takes care of the port mapping, so you can access the applications using "localhost:<portNumber>"
Follow these instructions to import the VM as an appliance(*.ova). You'll only need the instructions under paragraph Importing an OVA
and keep the default settings of the appliance.
- VM
- User:
root
- Password:
devoteam2019
- User:
- XL-Deploy/XL-Release:
- User:
admin
- Password:
devoteam2019
- User:
- XL-Deploy: http://localhost:4516
- XL-Release: http://localhost:5516
- Tomcat: http://localhost:8080
- SSH VM:
localhost:22
- Docker Ip*:
172.17.0.1
*The "Docker Ip" is used to connect the containers and Tomcat over the network.
This hands-on will go through the following:
- Deploy for the first time with
XL-Deploy
- Create a simple release pipeline in
XL-Release
- How to use tags in
XL-Deploy
- .....
Start up the VM in VirtualBox
and all tools should be available in about two to three minutes.
We going to deploy for the first time. In the next few paragraphs we'll guide you through the following steps:
- Import version 1.0 of the
PetClinic
application for deployment - Define the
Tomcat
infrastructure - Define an environment we can deploy
PetClinic
to - Deploy version 1.0 of
PetClinic
- Import version 2.0 of the
PetClinic
application for deployment - Deploy and rollback version 2.0 of
PetClinic
The developers have build the first version of PetClinic
and it has to be deployed, so we need to make PetClinic
available in XL-Deploy
:
- Login to XL-Deploy
- Click on the
...
next toApplications
, then go toImport
>From XL Deploy Server
- Select
PetClinic-war/1.0
from thePackage
selection box and clickImport
- You should be able to see this:
Now you have an application you can't deploy to anything.
We need to define the Tomcat
infrastructure, so XL-Deploy
knows where to deploy PetClinic
. We'll start by defining the target host first:
- Click on the
...
next toInfrastructure
, then go toNew
>overthere
>SshHost
- Fill in the following:
- Name:
TomcatHost
- Operating system:
Unix
- Connection Type:
SCP
- Address:
172.17.0.1
- Port:
22
- Username:
root
- Password:
devoteam2019
- Name:
- Click on
Save and close
- Click on the
...
next toTomcatHost
, then go toCheck connection
- Click on
Execute
to verify the connection to theTomcat
host. If verification is successful, click onFinish
Now that we have a target host, we're going to tell XL-Deploy
where the Tomcat
instance is installed on that host:
- Click on the
...
next toTomcatHost
, then go toNew
>tomcat
>Server
- Fill in the following:
- Name:
TomcatInstance
- Home:
/usr/local/tomcat/apache-tomcat-9.0.17
- Start Command:
/usr/local/tomcat/apache-tomcat-9.0.17/bin/startup.sh
- Stop Command:
/usr/local/tomcat/apache-tomcat-9.0.17/bin/shutdown.sh
- Name:
- Click on
Save and close
Last step in the infrastructure is to define where PetClinic
needs to be deployed:
- Click on the
...
next toTomcatInstance
, then go toNew
>tomcat
>VirtualHost
- Fill in the following:
- Name:
TomcatPetClinic
- Name:
- Click on
Save and close
The end result should look like this:
We can't deploy on infrastructure in XL-Deploy
, we need an environment for that.
An environment is nothing more than a grouping of one or more infrastructure entries you can deploy to. In this case the environment will only contain TomcatPetClinic
.
- Click on the
...
next toEnvironments
, then go toNew
>Environment
- Fill in the following:
- Name:
Production
(because that's how we roll) - Containers:
Infrastructure/TomcatHost/TomcatInstance/TomcatPetClinic
- Name:
- Click on
Save and close
Finally we can deploy PetClinic
.
- First check if you get a
HTTP 404
error when opening PetClinic in your browser - In
XL-Deploy
click on the bigStart a deployment
button in the center:
- Drag and drop the following:
Applications/PetClinic-war/1.0
toDrag and drop package here
Environments/Production
toDrag and drop environment here
- Click on
Preview
to see what tasksXL-Deploy
will execute to deployPetClinic
- Click on
Close preview
to return to the previous view - Click on
Deploy
andPetClinic
should be deployed in seconds - Go to PetClinic and browse the application:
- Go back to
XL-Deploy
and click onFinish
. This will tellXL-Deploy
you accept this deployment.
PetClinic
1.0 is running all fine and dandy, but the developers have build a second version we need to deploy to production.
- Click on the
...
next toApplications
, then go toImport
>From XL Deploy Server
- Select
PetClinic-war/2.0
from thePackage
selection box and clickImport
- You should be able to see this:
Hhhmm, importing a new version takes time. Maybe something that the developers can automate? :)
Let's see what happens if we deploy version 2.0
- In
XL-Deploy
click on the bigStart a deployment
button in the center:
- Drag and drop the following:
Applications/PetClinic-war/2.0
toDrag and drop package here
Environments/Production
toDrag and drop environment here
- Click on
Preview
and you can see that a task calledDestroy petclinic on TomcatPetClinic
has been added. Depending on if it's a first deploy, update or undeploy,XL-Deploy
will change the tasks accordingly. - Click on
Close preview
to return to the previous view - Click on
Deploy
andPetClinic
should be deployed in seconds. - Go to PetClinic. You see that the image on the homepage has been changed (if not: refresh the page):
- Let's say we don't like the new image in version 2.0 and we want to rollback to version 1.0. Go back to
XL-Deploy
and click onRollback
, thenYes
. - Go back to PetClinic and refresh the page. The image should revert to this:
- Ah, much better. Go back to
XL-Deploy
and click onFinish
to accept the deployment. Should you want to rollback after accepting a deployment, you can always start a new deployment.
When you want to get your software to production, deploying is probably not the only thing you'll need to do. Most organisation have checks and quality gates in place software needs to comply to to be allowed to go to production. An option is to do those tasks separately, but a better option is to all the tasks together in a single overview, so everone can easily see what the progress is of your software. This is where XL-Release
comes in. XL-Release
not only shows the status of a release, but can also start tasks, so it can function as a orchestrator.
We're going to deploy a version of PetClinic
with XL-Release
.
- Login to XL-Release
- Before we can start creating releases, we need to register the
XL-Deploy
server: Click onSettings
>Shared configuration
- Scroll down to
XL Deploy Server
and click on the+
symbol next to it. - Fill in the following:
- Title:
XLDServer
- Url:
http://172.17.0.1:4516
- Authentication Method:
Basic
- Username:
admin
- Password:
devoteam2019
- Title:
- Click on
Test
to verify the connection toXL-Deploy
. You should get theXL Deploy Server is available.
message. - Click on
Save
- Now that we have a
XL-Deploy
server that can deployPetClinic
, we can create the first release: In the top menu click onReleases
, then in the new screenNew release
- Enter a name for the release and click on
Create
- Now we can add our deployment task in the release. Click on
Add task
. - Give the task a new and from the dropdown menu select:
XL-Deploy
>Deploy
and click onAdd
- Click on the task to open it. Fill in the following:
- Click outside of the task to close it, it saves your input automatically.
- Now that we have defined the release let's start it: Click on
Start Release
>Start
- The tasks should say
In Progress
and after the release is complete, check PetClinic to verify version 2.0 is deployed:
Adding a task for each release is doable, but usually a release pipeline has way more tasks than one. To save time, XL-Release
has templates you can create to start your releases from. That way you have a single point where you add, update or remove tasks you need for a release.
- Go to
Design
>Templates
>New template
- Enter
PetClinic Release Pipeline
forTemplate name
and click onCreate
- Add the
XL-Deploy
task like previously and fill in the following:- Name:
Deploy PetClinic to Production
- Task Type:
XL-Deploy
>Deploy
- Server:
XLDServer
- Package:
Applications/PetClinic-war
- Environment:
Environments/Production
(there's an auto-complete function when you start typing)
- Name:
- Hey, where's the version of
PetClinic
? Well, you don't want to start each release with the same version, do you? ;) Let's make the version variable, so each release can have a different version: On the top-left you'll see a dropdown menu calledShow
. In that menu selectVariables
. - Click on
New variable
and name itPetClinicVersion
- In the dropdown select
Release flow
to go back. - Open task
Deploy PetClinic to Production
and add the new variable in the Package field, like so:Applications/PetClinic-war/${PetClinicVersion}
- Now let's see if this works. Click on
New release
, give the release a name and enter1.0
for thePetClinicVersion
. Click onCreate
, thenStart release
>Start
- Wait for the release to finish and go to PetClinic to verify version 1.0 is running (refresh if necessary):
Like mentioned in the beginning, release pipelines consist of more tasks than just deploying. In many organisations there's an approval needed to be allowed to deploy to production. Here we're going to play a scenario with a Developer
and a Product Owner
. The Developer
keeps an eye on the pipeline and the Product Owner
is the only one who can give the approval.
First we're going to create the user accounts for the both of them.
- Go to
User management
>Users
- Click on
New user
and fill in the following:- Username:
dev
- Set password:
dev
- Confirm password:
dev
- Username:
- Click on
Save
- Repeat steps two and three for the
Product Owner
- Username:
po
- Set password:
po
- Confirm password:
po
- Username:
Change the permissions of the PetClinic Release Pipeline
template for the Developer
and Product Owner
- Go to the
PetClinic Release Pipeline
template and select from the dropdown menuTeams and permissions
. You'll see two parts: One where you can define teams and one where you can assign users or teams to the available permissions:
- We're going to create two teams. Click on
New team
and name itDevelopers
and click onCreate
. - Create another team called
Product Owner
- Add the
dev
user to teamDevelopers
and userpo
toProduct Owner
by clicking in theUsers
column of the team and start typing the user you want to add. There's an auto-complete, so when the user appears, click on it:
- Now we're going to give the teams some permissions. Add the
Developers
team to permissionsCreate release
,Start release
,View release
, andView template
. AddProduct Owner
toView release
,andView template
. - Be careful in this screen! Unlike in the
Release flow
screen changes aren't saved automatically: So click onSave
!
Let's add an approval to the template
- Select
Release flow
from the dropdown menu - Click on
Add phase
, name itPre-deployment check
and move it to the left by dragging and dropping it. Rename the old phaseProduction Deployment
and give the phase the colorRed
. - Click on
Add task
within thePre-deployment check
phase, name itApproval PO
and click onAdd
(the task type should already be set onManual
). - Open the
Approval PO
task. Edit the description toProduct Owner: Please give the approval for deployment of version ${PetClinicVersion} to production
and clickSave
. Assign teamProduct Owner
to the task:
- Close the task and result should look like this:
Now we're going to start a release with the dev
user and approve it with the po
user.
- Open a incognito window of your browser. Go to XL-Release and login with the
dev
user. - Create a release from the
PetClinic Release Pipeline
template calledProper Release
withPetClinicVersion
2.0. Now start the release. - Log out by clicking on the gears symbol on the top-right and clicking on
Log out
- Log in with the
po
user and click onMy tasks
- You should see the
Approval PO
assigned to theProduct Owner
forProper Release
:
If you login with another user, you won't see theApproval PO
task inMy tasks
- Open the
Approval PO
task and click onComplete
, then fill in the field and click onOK
- Once the release is done, check PetClinic to verify version 2.0 is deployed:
With tagging you can make sure that applications can only be deployed on certain servers. In this scenario we going to define a second Tomcat
server in the Production
environment and assign the PetClinic
tag to application and the first Tomcat
server, so it will only be deployed there.
- Login to XL-Deploy
- Follow the steps at Infrastructure, but change the name of each
Tomcat
infrastructure entry. Like so:
- Edit the
Production
environment and addInfrastructure/TomcatHost2/TomcatInstance2/TomcatApplication
toContainers
- Create (but don't start) a deployment to
Production
andPetClinic
version 1.0. You'll see thatPetClinic
is added to bothTomcatPetClinic
andTomcatPetApplication
. Open the preview to see what tasks are executed. Cancel the deployment.
- Now we're going to add the tag
PetClinic
to make sure its only deployed toTomcatPetClinic
. OpenInfrastructure/TomcatHost/TomcatInstance/TomcatPetClinic
and enterPetClinic
in theTags
field and click onAdd
, thenSave and close
. - Open
Applications/PetClinic-war/1.0/petclinic
and add the tagPetClinic
in theTags
field and click onAdd
, thenSave and close
. - Open
Applications/PetClinic-war/2.0/petclinic
and add the tagPetClinic
in theTags
field and click onAdd
, thenSave and close
. - Start a deployment of
PetClinic
version 1.0 toProduction
and you'll see that only serverTomcatPetClinic
is selected as target.
I got the Docker images from XebiaLabs themselves:
XL-Deploy
: https://hub.docker.com/r/xebialabs/xl-deploy/XL-Release
: https://hub.docker.com/r/xebialabs/xl-release/
The Docker containers in the VM use my trial license which will expire. You can get your own trial license here:
XL-Deploy
: https://xebialabs.com/products/xl-deploy/trial/XL-Release
: https://xebialabs.com/products/xl-release/trial/
I applied the licenses by adding them as an environment variable in the docker run command:
XL-Deploy
:docker run -d -p 4516:4516 \ -e "ADMIN_PASSWORD=<password>" \ -e "XL_LICENSE=<licenseString>" \ -v /home/xebialabs/xl-deploy-server/conf:/opt/xebialabs/xl-deploy-server/conf:rw \ -v /home/xebialabs/xl-deploy-server/repository:/opt/xebialabs/xl-deploy-server/repository:rw \ -v /home/xebialabs/xl-deploy-server/archive:/opt/xebialabs/xl-deploy-server/archive:rw \ --name xld xebialabs/xl-deploy:8.6.1
XL-Release
:If you're using the VM, you might need to delete thedocker run -d -p 5516:5516 \ -e "ADMIN_PASSWORD=<password>" \ -e "XL_LICENSE=<license>" \ -v /home/xebialabs/xl-release-docker/conf:/opt/xebialabs/xl-release-server/conf:rw \ -v /home/xebialabs/xl-release-docker/repository:/opt/xebialabs/xl-release-server/repository:rw \ -v /home/xebialabs/xl-release-docker/archive:/opt/xebialabs/xl-release-server/archive:rw \ --name xlr xebialabs/xl-release:8.6.1
*.lic
file in/home/xebialabs/xl-release-docker/conf
first before running the Docker image.
If you want to run the Docker images on your own host/VM, make sure the volume paths have full permissions, otherwise the default configuration from the container can't be copied and will cause the container to stop. This caused by the default configuration files having a different user as owner than root in the container. No idea why XebiaLabs did that.