Published on Alfresco Documentation (https://docs.alfresco.com)

Home > Alfresco Content Services 6.0.1 > Deploying > Understanding containerized deployment

Understanding containerized deployment

Use the following links to help you understand what containerized deployment is, and the deployment options available for Alfresco Content Services.

  • Deployment concepts [1]Alfresco Content Services deployment introduces a number of concepts.
  • Public Alfresco Docker images [2] The public Alfresco Docker images are available in the Docker Hub registry.
  • Deployment prerequisites [3] There are a number of software requirements for installing (or deploying) Alfresco Content Services using the new deployment mechanism.
  • Deploying using Docker Compose [4] Use this information to quickly start up Alfresco Content Services using Docker Compose. Due to the limited capabilities of Docker Compose, this deployment method is recommended for development and test environments only.
Parent topic: Deploying [5]

Deployment concepts

Alfresco Content Services deployment introduces a number of concepts.

The way you deploy and run Alfresco Content Services has changed significantly since version 6.0. Traditionally, you'd download an installer that installed Java, Tomcat, Database, WARs, tools, etc. and everything was configured to work together out-of-the-box. Then you'd use a script to start things off. That's no longer the case and there are no installers available. We'll be working with Docker containers instead.

You can start Alfresco Content Services from a number of Docker images. These images are available in the https://hub.docker.com [6] repository. However, starting individual Docker containers based on these images, and configuring them to work together might not be the most productive way to get up and running. To make things easier, and achieve a single-step deploy and run solution, a Docker Compose file is available to quickly start Alfresco Content Services when you need to test something or work on a proof-of-concept (PoC).

There are also Helm Charts available to deploy Alfresco Content Services in a Kubernetes cluster, for example, on Amazon Web Services (AWS). These charts are a deployment template which can be used as the basis for your specific deployment needs. The Helm charts are undergoing continual development and improvement and should not be used "as-is" for a production deployment, but should help you save time and effort deploying Alfresco Content Services for your organisation.

The following is a list of concepts and technologies that you'll need to understand as part of deploying and using Alfresco Content Services version 6.0.1. If you know all about Docker, then you can skip this part.

Virtual Machine Monitor (Hypervisor)

A Hypervisor is used to run other OS instances on your local host machine. Typically it's used to run a different OS on your machine, such as Windows on a Mac. When you run another OS on your host it is called a guest OS, and it runs in a Virtual Machine (VM).

Image

An image is a number of layers that can be used to instantiate a container. This could be, for example, Java and Apache Tomcat. You can find all kinds of Docker images on the public repository Docker Hub [7]. There are also private image repositories (for things like commercial enterprise images), such as the one Alfresco uses called Quay [8].

Container

An instance of an image is called a container. If you start this image, you have a running container of this image. You can have many running containers of the same image.

Docker

Docker is one of the most popular container platforms. Docker [9] provides functionality for deploying and running applications in containers based on images.

Docker Compose

When you have many containers making up your solution, such as with Alfresco Content Services, and you need to configure each individual container so that they all work well together, then you need a tool for this. Docker Compose is such a tool for defining and running multi-container Docker applications locally. With Compose, you use a YAML [10] file to configure your application's services. Then, with a single command, you create and start all the services from your configuration.

Dockerfile

A Dockerfile is a script containing a successive series of instructions, directions, and commands which are run to form a new Docker image. Each command translates to a new layer in the image, forming the end product. The Dockerfile replaces the process of doing everything manually and repeatedly. When a Dockerfile finishes building, the end result is a new image, which you can use to start a new Docker container.

Difference between containers and virtual machines

It's important to understand the difference between using containers and using VMs. Here's a picture from What is a Container | Docker [11]:

The main difference is that when you run a container, you are not starting a complete new OS instance. This makes containers much more lightweight and quicker to start. A container also takes up much less space on your hard-disk as it doesn't have to ship the whole OS.

Parent topic: Understanding containerized deployment [12]

Public Alfresco Docker images

The public Alfresco Docker images are available in the Docker Hub registry.

Go to Docker Hub https://hub.docker.com/u/alfresco/ [13] to see a list of images belonging to the alfresco user. Alternatively, access Docker Hub [6] and search for alfresco (note that not all images are visible):

There are a number of Docker images that relate to Alfresco Content Services:

  • alfresco/alfresco-share - the Share web interface (i.e. share.war) running on Apache Tomcat
  • alfresco/alfresco-search-services - the Solr 6 based search service running on Jetty
  • alfresco/alfresco-content-repository - the Repository app (i.e. alfresco.war) running on Apache Tomcat

There are also other supporting features available, such as Docker images for image and document transformation:

  • alfresco/alfresco-imagemagick
  • alfresco/alfresco-libreoffice
  • alfresco/alfresco-pdf-renderer

To build the alfresco/alfresco-content-repository image, Alfresco uses the Alfresco/acs-packaging [14] GitHub project. This project doesn't include any deployment templates. The Alfresco/acs-deployment [15] GitHub project contains deployment templates and instructions. It includes a Docker Compose script that's used to launch a demo, test, or PoC of Alfresco Content Services. You can customize this script, if you like, in order to run with different versions than those set by default (which are usually the latest versions).

When you deploy Alfresco Content Services, the following containers are started:

  • Alfresco Repository with:
    • Alfresco Share Services AMP
    • Alfresco Office Services (AOS) AMP
    • Alfresco vti-bin war - that helps with AOS integration
    • Alfresco Google Docs Integration Repo AMP
  • Alfresco Share with:
    • Alfresco Google Docs Integration Share AMP
  • Alfresco Search Services (Solr 6)
  • A Postgres Database

GitHub projects

Deployment project

The deployment project contains the Docker Compose file to start up an Alfresco Content Services environment locally. You'll find the relevant files in the docker-compose folder. To look at the project in more detail, just browse to:

If you're interested in the Helm charts to deploy Alfresco Content Services with Kubernetes, you'll find the relevant files in the helm/alfresco-content-services folder.

Packaging project

The packaging project is used to build the repository artifacts, such as the Docker image for the repository. To look at the project in more detail, just browse to:

Other projects

Note that the Docker files for Alfresco Share and Alfresco Search Services are in their own projects:

Parent topic: Understanding containerized deployment [12]

Deployment prerequisites

There are a number of software requirements for installing (or deploying) Alfresco Content Services using the new deployment mechanism.

You'll find a list of prerequisites in the GitHub project documentation.

Note that the VERSIONS.md [18] file in GitHub lists the supported versions.

Here, you can review the requirements for your chosen deployment method.

Requirements for using Helm charts

To deploy Alfresco Content Services using Helm charts, you need to install the following software:

  • AWS CLI [19] - the command line interface for Amazon Web Services.
  • Kubectl [20] - the command line tool for Kubernetes.
  • Helm [21] - the tool for installing and managing Kubernetes applications.
    • There are Helm charts that allow you to deploy Alfresco Content Services in a Kubernetes cluster, for example, on AWS.

See Deploying Alfresco Content Services Helm charts to AWS EKS [22] for more.

Requirements for a manual install using a distribution zip containing WAR files

To install Alfresco Content Services using the distribution zip, make sure that the required software is available on your system:

  • Java
  • Application server: Apache Tomcat
  • Database: PostgreSQL or MySQL
  • LibreOffice
  • ImageMagick

For a list of supported components and versions, refer to the VERSIONS.md file in the distribution zip.

See Installing using distribution zip [23] for more.

Java requirements

Java 8 is recommended.

Requirements for using docker-compose (recommended for evaluations only)
  • Docker [24] (latest stable version)
    • This allows you to run Docker images and docker-compose on a single computer.
  • Docker Compose [25]
    • Docker Compose is included as part of some Docker installers. If it's not part of your installation, then install it separately after you've installed Docker.

See Deploying using Docker Compose [4] for more.

Parent topic: Understanding containerized deployment [12]

Deploying using Docker Compose

Use this information to quickly start up Alfresco Content Services using Docker Compose. Due to the limited capabilities of Docker Compose, this deployment method is recommended for development and test environments only.

To deploy Alfresco Content Services using docker-compose, download and install Docker [24], then follow the steps below.

  1. Clone the repository [15] locally or download [26] one of the docker-compose.yml files (e.g. 6.0.N-docker-compose.yml), and then change directory to the project folder: 

    git clone https://github.com/Alfresco/acs-deployment.git
cd acs-deployment
    Note: Make sure that the following ports are free on your computer: 5432, 8080, 8082, 8083. These ports are set in the docker-compose.yml file - refer to the host:container port definitions.

    See the Alfresco/acs-deployment project README [15] for more.

  2. Change directory to the docker-compose folder: 

    cd docker-compose
  3. Deploy Alfresco Content Services, including the repository, Share, Postgres database, and Search Services:

    For example:

    docker-compose -f 6.0.N-docker-compose.yml up

    This downloads the images, fetches all the dependencies, creates each container, and then starts the system: 

    Creating network "docker-compose_default" with the default driver
...
Creating docker-compose_alfresco-pdf-renderer_1 ... done
Creating docker-compose_solr6_1                 ... done
Creating docker-compose_postgres_1              ... done
Creating docker-compose_imagemagick_1           ... done
Creating docker-compose_libreoffice_1           ... done
Creating docker-compose_share_1                 ... done
Creating docker-compose_alfresco_1              ... done
Attaching to docker-compose_postgres_1, docker-compose_solr6_1, docker-compose_alfresco-pdf-renderer_1, docker-compose_imagemagick_1, docker-compose_alfresco_1, docker-compose_libreoffice_1, docker-compose_share_1
...

    As an alternative, you can also start the containers in the background by running docker-compose up -d.

  4. Wait for the logs to complete, showing messages: 

    ...
alfresco_1 | 2018-08-28 08:40:30,386  INFO  [management.subsystems.ChildApplicationContextFactory] [http-nio-8080-exec-10] Starting 'Transformers' subsystem, ID: [Transformers, default]
alfresco_1 | 2018-08-28 08:40:30,661  INFO  [management.subsystems.ChildApplicationContextFactory] [http-nio-8080-exec-10] Startup of 'Transformers' subsystem, ID: [Transformers, default] complete

    If you encounter errors whilst the system is starting up:

    • Stop the session by using CONTROL+C.
    • Remove the containers (using the --rmi all option): 
      docker-compose down --rmi all
    • Try allocating more memory resources, as advised in docker-compose.yml. For example, in Docker, change the memory setting in Preferences (or Settings) > Advanced > Memory, to at least 8 GB. Make sure you restart Docker and wait for the process to finish before continuing.
    • Go back to step 3 [27] (above) to start the deployment again.
    Note: Keep in mind that 8 GB is much lower than the required minimum, and may need to be adapted for your environment. You'll need a machine with at least 13GB of memory to distribute among the Docker containers.
  5. Open your browser and check everything starts up correctly:

    • Share: http://localhost:8080/share
    • REST APIs and administration: http://localhost:8082/alfresco
    • Search administration: http://localhost:8083/solr
  6. Log in as the admin user. Enter the default administrator password admin.

You can use a number of commands to check that the system started correctly. See Checking system start up [28] for more.

See the Alfresco/acs-deployment [15] GitHub project documentation for the prerequisites and detailed setup: Docker Compose deployment [29]

In this project, you can use the docker-compose.yml file following the documentation for standard installations.

To modify your development environment, for example to change or mount files in the existing images, you'll have to create new custom Docker images (recommended approach). The same approach applies if you want to install AMP files into the repository and Share images. See the Customization Guidelines [30] for more.

  • Checking system start up [31] Use this information to verify that the system started correctly, and to clean up the deployment.
Parent topic: Understanding containerized deployment [12]

Checking system start up

Use this information to verify that the system started correctly, and to clean up the deployment.

Before continuing, make sure that you've completed the steps in Deploying using Docker Compose [32].

  1. Open a new terminal window.
  2. Change directory to the docker-compose folder that you created in the deployment steps.
  3. Verify that all the services started correctly.
    1. List the images and additional details: 

      docker-compose images

      You should see a list of the services defined in your docker-compose.yaml file: 

              Container                           Repository                           ...     Size 
-----------------------------------------------------------------------------------------------
docker-compose_alfresco-pdf-renderer_1   alfresco/alfresco-pdf-renderer         ...   560 MB
docker-compose_alfresco_1                alfresco/alfresco-content-repository   ...   1.01 GB
docker-compose_imagemagick_1             alfresco/alfresco-imagemagick          ...   633 MB
docker-compose_libreoffice_1             alfresco/alfresco-libreoffice          ...   1.39 GB
docker-compose_postgres_1                postgres                               ...   274 MB
docker-compose_share_1                   alfresco/alfresco-share                ...   714 MB
docker-compose_solr6_1                   alfresco/alfresco-search-services      ...   849 MB
    2. List the running containers: 

      docker-compose ps

      You should see a list of the services defined in the docker-compose.yaml file.

    3. View the log files for each service <service-name>, or container <container-name>: 

      docker-compose logs <service-name>
docker container logs <container-name>

      For example, to check the logs for Share, run any of the following commands: 

      docker-compose logs share
docker container logs docker-compose_share_1

      You can add an optional parameter --tail=25 before <container-name> to display the last 25 lines of the logs for the selected container. 

      docker-compose logs --tail=25 share
docker container logs --tail=25 docker-compose_share_1

      Check for a success message: 

      Successfully retrieved license information from Alfresco.

    Once you've tested the services, you can clean up the deployment by stopping the running services.

  4. Stop the session by using CONTROL+C in the same window as the running services: 

    ^CGracefully stopping... (press Ctrl+C again to force)
Stopping docker-compose_libreoffice_1           ... done
Stopping docker-compose_solr6_1                 ... done
Stopping docker-compose_postgres_1              ... done
Stopping docker-compose_alfresco_1              ... done
Stopping docker-compose_share_1                 ... done
Stopping docker-compose_imagemagick_1           ... done
Stopping docker-compose_alfresco-pdf-renderer_1 ... done
  5. Alternatively, you can open a new terminal window, change directory to the docker-compose folder, and run: 

    docker-compose down

    This stops the running services, as shown in the previous example, and removes them from memory: 

    Stopping docker-compose_postgres_1              ... done
Stopping docker-compose_share_1                 ... done
... 
Removing docker-compose_postgres_1              ... done
Removing docker-compose_share_1                 ... done
Removing docker-compose_libreoffice_1           ... done
Removing docker-compose_imagemagick_1           ... done
Removing docker-compose_solr6_1                 ... done
Removing docker-compose_alfresco-pdf-renderer_1 ... done
Removing docker-compose_alfresco_1              ... done
Removing network docker-compose_default
  6. You can use a few more commands to explore the services when they're running. Change directory to docker-compose before running these:
    1. Stop all the running containers: 

      docker-compose stop
    2. Restart the containers (after using the stop command): 

      docker-compose restart
    3. Starts the containers that were started with docker-compose up: 

      docker-compose start
    4. Stop all running containers, and remove them and the network: 

      docker-compose down [--rmi all]

      The --rmi all option also removes the images created by docker-compose up, and the images used by any service. You can use this, for example, if any containers fail and you need to remove them:

      Stopping docker-compose_libreoffice_1           ... done
... 
Removing docker-compose_libreoffice_1           ... done
... 
Removing network docker-compose_default
Removing image alfresco/alfresco-content-repository:6.0.x
Removing image ...

See the Docker documentation [33] for more on getting started with Docker and using Docker.

Parent topic: Deploying using Docker Compose [4]
Source URL: https://docs.alfresco.com/6.0/concepts/deploy-overview.html

Links:
[1] https://docs.alfresco.com/../concepts/deploy-concepts.html
[2] https://docs.alfresco.com/../concepts/public-docker-images.html
[3] https://docs.alfresco.com/../concepts/deploy-prereqs.html
[4] https://docs.alfresco.com/../tasks/deploy-docker-compose.html
[5] https://docs.alfresco.com/../concepts/master-deploy.html
[6] https://hub.docker.com
[7] https://hub.docker.com/
[8] https://quay.io/
[9] https://www.docker.com/
[10] https://en.wikipedia.org/wiki/YAML
[11] https://www.docker.com/what-container
[12] https://docs.alfresco.com/../concepts/deploy-overview.html
[13] https://hub.docker.com/u/alfresco/
[14] https://github.com/Alfresco/acs-packaging
[15] https://github.com/Alfresco/acs-deployment
[16] https://github.com/Alfresco/share/tree/6.0
[17] https://github.com/Alfresco/SearchServices
[18] https://github.com/Alfresco/acs-packaging/blob/master/distribution/src/main/resources/VERSIONS.md
[19] https://github.com/aws/aws-cli#installation
[20] https://kubernetes.io/docs/tasks/tools/install-kubectl/
[21] https://github.com/kubernetes/helm#install
[22] https://docs.alfresco.com/../tasks/deploy-helm-aws.html
[23] https://docs.alfresco.com/ch-install.html
[24] https://docs.docker.com/install/
[25] https://docs.docker.com/compose/install/
[26] https://github.com/Alfresco/acs-deployment/tree/master/docker-compose
[27] https://docs.alfresco.com/deploy-docker-compose.html%23deploy-docker-compose__up
[28] https://docs.alfresco.com/docker-system-startup.html
[29] https://github.com/Alfresco/acs-deployment/tree/master/docs/docker-compose
[30] https://github.com/Alfresco/acs-deployment/blob/master/docs/docker-compose/examples/customisation-guidelines.md
[31] https://docs.alfresco.com/../tasks/docker-system-startup.html
[32] https://docs.alfresco.com/deploy-docker-compose.html
[33] https://docs.docker.com/