Lab 1: Create custom docker container - Alfresco/alfresco-acs-workshops GitHub Wiki

Lab I

Lab Overview:

This lab describes:

  • A short Docker introduction. A number of howtos: building custom image, starting a Docker container, killing a Docker container, bashing into a container, running commands inside a container, outputting container logs, everything that is needed for customising and troubleshooting personalised Alfresco deployment.
  • Integration of maven fabric8 plugin into AMP maven projects and how to properly configure the plugin.
  • Deploying a custom Alfresco Repository Docker image using docker-compose.
Table of Contents:

Before we start

Creating Dockerfile

Building custom docker image

Deploy custom repository using docker-compose

Validate installed AMP

Add fabric8-maven-plugin

Troubleshooting

Before we start:

Prerequisites:

Nice to have:
  • IDE (Intellij/Eclipse/etc)
  • Favorite Text Editor (Sublime Text/Notepad++/etc)
You can validate the installed prerequisites by running the following the commands:

Git:

> git --version
git version 2.10.0.windows.1

Maven:

> mvn --version
Apache Maven 3.6.0
Maven home: C:\Program Files\apache-maven\bin\..
Java version: 11.0.1, vendor: Oracle Corporation,

OpenJDK:

> java -version
java version "1.8.0_191"
Java(TM) SE Runtime Environment (build 1.8.0_191-b12)
Java HotSpot(TM) 64-Bit Server VM (build 25.191-b12, mixed mode)

Docker:

> docker -v
Docker version 18.09.1, build 4c52b90

Docker-compose:

> docker-compose -v
docker-compose version 1.23.2, build 1110ad01
Clone hello-world-amp, this AMP is compatible with ACS 6.1 and it would be used to create a custom alfresco-content-repository-community docker image.

Creating Dockerfile:

  • Documentation on how to create a custom Docker image without a Dockerfile can be found here
  • Documentation on how to create a custom Docker image using only a Dockerfile can be found here
  1. Build hello-world-amp to generate AMP file extension. Navigate to hello-world-amp and run the following command:

$PATH\hello-world-amp > mvn clean install

  1. Navigate to $PATH\hello-world-amp\repo-amp\target and confirm that the amp file is created:
ls -l
total 16
drwxr-xr-x 1 P3700654 1049089     0 Jan 28 20:40 classes/
drwxr-xr-x 1 P3700654 1049089     0 Jan 28 20:40 generated-sources/
drwxr-xr-x 1 P3700654 1049089     0 Jan 28 20:40 generated-test-sources/
drwxr-xr-x 1 P3700654 1049089     0 Jan 28 20:40 hello-world-repo-amp-1.0-SNAPSHOT/
-rw-r--r-- 1 P3700654 1049089 14924 Jan 28 20:40 hello-world-repo-amp-1.0-SNAPSHOT.amp
drwxr-xr-x 1 P3700654 1049089     0 Jan 28 20:40 maven-archiver/
drwxr-xr-x 1 P3700654 1049089     0 Jan 28 20:40 maven-status/
drwxr-xr-x 1 P3700654 1049089     0 Jan 28 20:40 surefire-reports/
drwxr-xr-x 1 P3700654 1049089     0 Jan 28 20:40 test-classes/
  1. Create a new file named $PATH\hello-world-amp\repo-amp\Dockerfile and add the following content to it:
# Docker image to customise
FROM alfresco/alfresco-content-repository-community:6.1.2-ga

# Copy AMP file into tomcat/amps folder on the docker container
COPY target/hello-world-repo-amp-*.amp /usr/local/tomcat/amps/

# Install amps on alfresco repository
RUN java -jar /usr/local/tomcat/alfresco-mmt/alfresco-mmt*.jar install \
              /usr/local/tomcat/amps /usr/local/tomcat/webapps/alfresco -directory -nobackup -force
  1. Save the file with no extension.

Building custom docker image:

  1. Open a terminal tab and navigate to the Dockerfile location
  2. Run the following command to build the custom docker image:
> docker build . -t ace-hello-world
  1. List docker images to verify that the image has been created:
>docker images
REPOSITORY                                       TAG                 IMAGE ID            CREATED             SIZE
aepure/ace-hello-world                           latest              ed909c01c4a6        27 hours ago        2.07GB

Deploy custom repository using docker-compose:

  1. Copy/clone docker-compose.yml from acs-community-deployment
  2. Edit docker-compose.yml and change content repository image name and tag.
services:
    alfresco:
        image: ace-hello-world:latest
        mem_limit: 1500m
  1. Start up docker-compose
docker-compose up

Validate installed AMP:

  1. Navigate to http://localhost:8082/api-explorer/
  2. Select Discovery API tab from API Definition
  3. Try out the GET /discovery API
        {
          "id": "hello-world-repo-amp",
          "title": "Hello World Repository AMP Module",
          "description": "Repository Hello World V0 API",
          "version": "1.0-SNAPSHOT",
          "installDate": "2019-01-27T19:00:14.998+0000",
          "installState": "INSTALLED",
          "versionMin": "6.1",
          "versionMax": "999"
        },
  1. Verify that hello-world webscript is working by navigating to http://localhost:8082/alfresco/s/sample/helloworld 
Message: 'Hello from JS!' 'HelloFromJava'

Add fabric8-maven-plugin:

  1. Into hello-world-amp/repo-amp/pom.xml add following properties used by the fabric8 plugin
<properties>
    <image.repository>DockerhubId</image.repository>
    <image.name>ace-hello-world</image.name>
    <image.tag>latest</image.tag>
    <registry.username>DockerhubId</registry.username>
    <registry.password>DockerhubPassword</registry.password>
    <dependency.fabric8.version>3.5.37</dependency.fabric8.version>
</properties>
  1. Create a Dockerfile for the repo amp hello-world-amp/repo-amp/Dockerfile
  2. Add .maven-dockerignore file to repo-amp project
target/docker/
  1. Add maven-fabric8-plugin into repo-amp/pom.xml section 
            <plugin>
                <groupId>io.fabric8</groupId>
                <artifactId>fabric8-maven-plugin</artifactId>
                <version>${dependency.fabric8.version}</version>
                <configuration>
                    <images>
                        <image>
                            <name>${image.repository}/${image.name}:${image.tag}</name>
                            <build>
                                <dockerFileDir>${project.basedir}/</dockerFileDir>
                            </build>
                        </image>
                    </images>
                    <authConfig>
                        <username>${registry.username}</username>
                        <password>${registry.password}</password>
                    </authConfig>
                </configuration>
            </plugin>
  1. Add a profile for only building the image
        <profile>
            <id>buildImage</id>
            <build>
                <plugins>
                    <plugin>
                        <groupId>io.fabric8</groupId>
                        <artifactId>fabric8-maven-plugin</artifactId>
                        <version>${dependency.fabric8.version}</version>
                        <executions>
                            <execution>
                                <id>build-image</id>
                                <phase>install</phase>
                                <goals>
                                    <goal>build</goal>
                                </goals>
                            </execution>
                        </executions>
                    </plugin>
                </plugins>
            </build>
        </profile>
  1. Add a profile for building and pushing images
        <profile>
            <id>buildAndPushImage</id>
            <build>
                <plugins>
                    <plugin>
                        <groupId>io.fabric8</groupId>
                        <artifactId>fabric8-maven-plugin</artifactId>
                        <version>${dependency.fabric8.version}</version>
                        <executions>
                            <execution>
                                <id>build-image</id>
                                <phase>install</phase>
                                <goals>
                                    <goal>build</goal>
                                    <goal>push</goal>
                                </goals>
                            </execution>
                        </executions>
                    </plugin>
                </plugins>
            </build>
        </profile>
  1. Build docker image
mvn clean install -PbuildImage -Dimage.repository=DockerhubId
  1. Build docker image and push it to dockerhub
mvn clean install -PbuildAndPushImage -Dimage.repository=DockerhubId
Troubleshooting: Docker container suddenly dies:

This issue is common with MacOS and Windows, the problem is usually low RAM memory allocated to the Docker daemon, this value can be modified by executing the following steps:

  1. right click on the docker icon and go to "Setting" menu.

  1. select "Advanced" tab from the new windows

  2. Increase memory capacity to at least 4gb.

Executing docker container without sudo:

Please follow these steps from : Official Documentation

⚠️ **GitHub.com Fallback** ⚠️