Getting started with Kentico EMS using Docker
Tags: docker, cms
Published: 2019-11-26 22:36:08

>**Looking to get started with Kentico EMS, but not quite sure where to begin? Hesitant on installing another piece of software fortesting? Want to test the latest update? We've got you covered! Utilizing Docker, you can configure and run a complete Kentico EMS environment with a few commands.**

In this article, we'll walk through how you can try out Kentico utilizing Docker, alleviating the need to install it directly on your machine. We'll also look at how we can adjust the Docker environment to handle the different testing scenarios.

## Pre-requisites to getting started
- Download and install [Docker Desktop](https://docs.docker.com/get-started).
- Clone, or copy, the [Docker compose file](https://github.com/OnyxPrime/kentico-ems-docker-poc/blob/master/docker-compose.yml). We'll use it to create the Kentico EMS environment.

_At this time this can only be done on a Windows machine_

## Why Docker?
When .NET Core was released, I became a big fan immediately for one primary reason: I was able to run multiple versions side-by-side, which is something most applications we use today don't support. As a developer, I tend to push towards the leading edge of technology. This has it's benefits, you get to try the latest and greatest, and it's drawbacks, you tend to get cut. This is where Docker comes in to play.

Docker provides us a way to create an environment, isolated from the rest of our system, with all dependencies and libraries needed to run our applications. And when we're done with this environment, we can turn it off and reclaim any resources it was consuming. This also means we can run multiple versions of the same application side-by-side.

# Containerized Kentico EMS
If you've ever installed Kentico EMS, you know there is a bit of configuration around it. Kentico has several installation requirements, such as turning on IIS and setting up SQL Server Express, which might immediately dissuade some users from trying it. Containerizing Kentico EMS, along with all it's dependencies, has greatly reduced the amount of time it takes to get started using Kentico EMS.

## How to start up the Kentico EMS environment

Once the pre-requisites are completed, open your preferred command-line utility. Change to the directory where you cloned, or copied, the  Docker compose file listed in the pre-requisites. Starting up the environment is running a single command from a command-line.
```PowerShell
$ docker-compose -f .\docker-compose.yml up -d
```
We're using the following parameters with the `docker-compose` command:
- `-f .\docker-compose.yml` specifies the configuration for the Kentico environment
- `up` tells Docker compose to bring up the environment
- `-d` tells Docker compose to run in a detatched state 

![Running Docker Compose](https://thepracticaldev.s3.amazonaws.com/i/h6fisgxh3mxyze703a4o.png)

If you receive an error while running the Docker compose command, there a couple of possible reasons.

1. The host ports specified in the `docker-compose.yml` file are be used by another application or service.

2. There are old containers still using the network. Run `docker ps -a` to see if there are any containers remaining. If there are, run `docker-compose down` to remove the old Kentico containers.

Once the Kentico container environment is running, open a browser and navigate to `http://localhost:60051/Kentico12_Admin`

When you first navigate to the page, the license for Kentico EMS will be expired. ~~To renew the license, navigate to `https://www.kentico.com/download-demo/testversion/trial-extend` to request a new license.~~ To obtain a new trial license key, navigate to https://www.kentico.com/download-demo/trial-license-key and fill out the form. 

![Invalid License Key](https://thepracticaldev.s3.amazonaws.com/i/yq8v1wra9kr8gviv137h.png)

The current process can take up to 48-hours to get a new license, but we are currently working on a solution to reduce this time.

## Updating your license

Once you obtain an updated license, go to http://localhost:60051/Kentico12_Admin/Admin/cmsadministration.aspx and login to the administration portal. Enter _`Administrator`_ in the `User name` field. Leave the `Password` field blank and click the `Sign in` button.

![Administrator Login](https://thepracticaldev.s3.amazonaws.com/i/e5clc4uhgky19ocgls69.png)

You will be taken to the page where you can enter a new license. Click the `New license` button in the upper left part of the page, paste the license key in to the box and then click the `Save` button.

This will unlock the full features of the Kentico EMS solution.

# How the environment is constructed

Now that we have the Kentico EMS solution up and running, let's take a look at how the environment is constructed. Docker compose is a tool used to construct an environment using 1 to any number of docker images.

The first line of the file tells Docker compose what version, or format, the file follows.
```
version: '3.4'
```

Next, we define the various services, or container images, we want to instantiate.
```
services:
  web:
    image: kentico/ems:web-12.0-beta
    ports:
      - 60051:80
    links:
      - sql
    depends_on:
      - sql    

  sql:
    image: kentico/ems:db-12.0-beta
    ports:
      - 1435:1433
```

In the code above, we are creating 2 containers. 
### Web Container
The container called `web`, contains an instance of Internet Information Services (IIS) hosting Kentico 12 EMS. The `image` property defines the specific image in Docker Hub we are pulling down and instantiating with Docker Compose. The `ports` property defines the mapping of internal container ports to host ports. The IIS image we are using consumes port 80, but we are mapping it to a host port 60051. We are doing this to prevent conflicts from IIS potentially running on our local machine. 

To ensure the `web` container, and Kentico 12 EMS, is ready to use when an instance is created, the backing data store must be running. Using the `depends_on` property, we're telling Docker Compose to wait for the `sql` container to start before starting the `web` container.

### SQL Container

The  container called `sql`, contains an instance of Microsoft SQL Server Express and the Kentico 12 EMS database installed. We have mapped the normal SQL Server port 1433 to 1435, again, to prevent conflicts with any other installation of Microsoft SQL Server installed on the hosting machine.

## Adding additional instances
In the case where you'd want to run multiple instances of Kentico 12 EMS, such as setting up a web farm environment, you would copy the `web` section, paste it below, give it a new name and change the host port specified under ports. 

```
services:
  web:
    image: kentico/ems:web-12.0-beta
    ports:
      - 60051:80
    depends_on:
      - sql    

  web2:
    image: kentico/ems:web-12.0-beta
    ports:
      - 60052:80
    depends_on:
      - sql   

  sql:
    image: kentico/ems:db-12.0-beta
    ports:
      - 1435:1433
```

This configuration will instantiate two Kentico 12 EMS containers that depend on the same SQL Server container. 

## Summary

In this article, we have seen how we can create a "temporary", albeit full, environment to run an instance of Kentico 12 EMS using Docker. But this is just the tip of the iceberg! Using this type of configuration, you can:

* Reduce the time, and complexity, it takes to get a new developer setup and ready to go
* Test multiple versions/patches of Kentico 12 EMS against the same site using volume mapping (similar concept to volume mounting used with VMs)
* Create an environment in which to run tests (unit, integration, etc.)
* Testing an upgrade on an existing site
* and much more!

You can find the docker images used in this article on [Docker Hub](https://hub.docker.com/r/kentico/ems) and the Docker image definitions used to create those images on [GitHub](https://github.com/OnyxPrime/kentico-ems-docker-poc).

Try it out and if you've found this helpful, or not, let me know in the comments below, or DM me on [Twitter](https://twitter.com/ryano9791)!

>_Update 12/2/2019: Modified link for obtaining a trial license key to the new link getting a new trial license key immediately, instead of waiting 48 hours._