Starting Out With Alfresco Process Services—Getting a Docker Container up and Running

By Jeff Rosler

Recently, I started a project where I needed to do development work on a new Alfresco Process Services (APS) application and wanted to bring up an environment quickly on my Mac. My first thought was just to use Docker to spin up an environment. I knew that a Docker image was available (see the Alfresco docs), so it seemed like the quickest way forward.

I really like using Docker as opposed to VirtualBox, VMWare, etc. to quickly spin up Linux environments. It’s lightweight and you can emulate more complex environments with high availability, clustering, and disaster recovery that you might see in production. Whether you’re on macOS, Microsoft Windows, or Linux, you can download Docker and run containers in your local environment. I’ll leave how to download Docker and Docker Compose for your environment as an exercise for you and continue on about how to install and configure your APS environment using Docker once you’ve got it installed.

Download Your Licenses

After installing Docker, the first step is to get a license for APS. I already had a license, but you can get a 30-day trial license by filling out a simple form and downloading from the email you receive. If you do this, follow the steps below:

  • Step 1: Select Option 2 and the “Deployable main webapp (activiti-app.war)” from the “Start Your Alfresco Trial Now” email you received.
  • Step 2: Download the”30-Day Trial License” under Step 2

The reason you need to download the activti-app-1.8.1.zip is that there is another license in the zip file for the OEMd Aspose library which is used to perform Microsoft Office document transforms and manipulation. If, like me, you already own a license but don’t have it, you can download it from the Alfresco Support site. Don’t forget to get the activiti-app-1.8.1.zip file as well.

Create a folder on a local machine where you’ll run your Docker APS environment and copy your APS license file (activiti.lic) and the Aspose license file (transform.lic from the activiti-app-1.8.1.zip).

Create Your Docker Compose File

We’ll use docker-compose to run our Docker containers so you’ll want to create a yaml file named docker-compose.yml for that. The yaml file specifies images, containers, and container parameters. Copy the contents below and paste them in your new docker-compose.yml file. I copied the original docker-compose.yml file from the Alfresco aps-docker-library github repository and modified it for my local environment.

The first thing I did was to change the version of the process-services image to the latest which is 1.8.1. I could also just have specified “latest” (without the quotes) instead of a specific version. You can see all of the tags in the Alfresco Process Services Docker page.

The second change I made was to setup my volumes. I needed to map my license files into the APS container and I also wanted to specify local host folders for the APS content store and the database. Additionally, I set up a volume mapping for overriding the activiti-app.properties file, so that I can specify email integration.

Finally, I changed the port number I’m using to expose APS and made it 8081 as I frequently run Alfresco Content Services locally on port 8080 and didn’t want the port conflict.

version: "3.1"
services:
  process:
    image: alfresco/process-services:1.8.1
    environment:
      ACTIVITI_DATASOURCE_USERNAME: alfresco
      ACTIVITI_DATASOURCE_PASSWORD: alfresco
      ACTIVITI_DATASOURCE_DRIVER: org.postgresql.Driver
      ACTIVITI_HIBERNATE_DIALECT: org.hibernate.dialect.PostgreSQLDialect
      ACTIVITI_DATASOURCE_URL: 'jdbc:postgresql://postgres:5432/activiti?characterEncoding=UTF-8'
      ACTIVITI_CSRF_DISABLED: 'true'
      ACTIVITI_CORS_ENABLED: 'true'
      ACTIVITI_ES_SERVER_TYPE: client
      ACTIVITI_ES_DISCOVERY_HOSTS: elasticsearch:9300
      ACTIVITI_ES_CLUSTER_NAME: elasticsearch
    volumes:
      - "~/.activiti/enterprise-license:/root/.activiti/enterprise-license/:ro"
      - ./activiti-app.properties:/usr/share/tomcat/lib/activiti-app.properties
      - ./transform.lic:/usr/share/tomcat/lib/transform.lic
      - ./psdata:/usr/local/data/
    ports:
      - 8081:8080
    links:
      - elasticsearch:elasticsearch
      - postgres:postgres
    depends_on:
      - elasticsearch
      - postgres

  elasticsearch:
    image: elasticsearch:1.7.3

  postgres:
    image: postgres:9.6.2
    environment:
      POSTGRES_DB: activiti
      POSTGRES_USER: alfresco
      POSTGRES_PASSWORD: alfresco
    volumes:
      - ./pgdata:/var/lib/postgresql/data

Setting up Email

Since email notifications are an important part of my APS application, I also wanted to make sure that I configured my APS environment to send emails. For my purposes, I’ll use Gmail. I copied the activiti-app.properties file from the Activiti container the first time I ran it and added email information at the end. I then specified in my docker-compose.yml file that my activiti-app.properties should override the one in the running container. That’s done through the “- ./activiti-app.properties:/usr/share/tomcat/lib/activiti-app.properties” line in under “volumes:” as can be seen in the docker-compose.yml file.

Create your activiti-app.properties file in the Docker folder that contains the docker-compose.yml and license files and copy the contents below into it. After copying the contents, you’ll need to update the values for yourgmailtestaccount and yourgmailtestaccountpassword everywhere you see them to the Gmail account information that you’re going to use.

You also need to set your yourgmailtestaccount to let less secure apps access it (see https://support.google.com/accounts/answer/6010255?hl=en), so you might want to use something other than your primary Gmail account for this.

# Activiti General server settings.
# http://docs.alfresco.com/activiti/docs/admin-guide/1.5.0/#_general_server_settings for reference
server.onpremise=true
server.stencil.custom.allowed=true
server.contextroot=/activiti-app

# Datasource Information.
# http://docs.alfresco.com/activiti/docs/admin-guide/1.5.0/#databaseConfiguration for reference.

license.multi-tenant=false
# Database username and password
datasource.username=alfresco
datasource.password=alfresco

# Driver to be used
datasource.driver=org.postgresql.Driver

# Database url. H2 by default, for standalone runs
# THis should point to your database ( external possibly )
datasource.url=jdbc:postgresql://postgres:5432/activiti?characterEncoding=UTF-8

# Hibernate dialect of choice
hibernate.dialect=org.hibernate.dialect.PostgreSQLDialect

# ElasticSearch configuration.
# http://docs.alfresco.com/activiti/docs/admin-guide/1.5.0/#elasticSearchConfig for reference


elastic-search.server.type=client
elastic-search.discovery.type=unicast
elastic-search.cluster.name=elasticsearch
elastic-search.discovery.hosts=elasticsearch:9300
elastic-search.data.path=/usr/local/elasticsearch/data

event.generation.enabled=true
event.processing.enabled=true


# Admin user informations
#  user: admin@app.activiti.com , password: admin.
admin.email=admin@app.activiti.com
admin.passwordHash=25a463679c56c474f20d8f592e899ef4cb3f79177c19e3782ed827b5c0135c466256f1e7b60e576e
admin.lastname=Administrator
admin.group=Administrators

# ContentStorage
# http://docs.alfresco.com/activiti/docs/admin-guide/1.5.0/#contentStorageConfig for reference
contentstorage.fs.rootFolder=/usr/local/data/
contentstorage.fs.createRoot=true
contentstorage.fs.depth=4
contentstorage.fs.blockSize=1024

# Security settings
security.csrf.disabled=true

#password min length
security.password.constraints.min-length=8
security.password.constraints.reg-exp=^(?=.*[a-z])(?=.*[A-Z]).+$

# USER TOKEN TTL
# after how long the cookie should expire
security.cookie.max-age=1800
# how often the cookie get controlled
security.cookie.database-removal.cronExpression=0 0/10 * * * ?

# SIGN UP TO THE APP
security.signup.disabled=true

# DISABLE SCRIPTING
validator.editor.bpmn.disable.scripttask=true
validator.editor.bpmn.disable.scripttask.groovy=true

# Beans whitelisting
beans.whitelisting.enabled=true

# EL whitelisting
el.whitelisting.enabled=true

# CORS settings
cors.enabled=true
cors.allowed.origins=*
cors.allowed.methods=GET,POST,HEAD,OPTIONS,PUT,DELETE
cors.allowed.headers=Authorization,Content-Type,Cache-Control,X-Requested-With,accept,Origin,Access-Control-Request-Method,Access-Control-Request-Headers,X-CSRF-Token
cors.exposed.headers=Access-Control-Allow-Origin,Access-Control-Allow-Credentials
cors.support.credentials=true
cors.preflight.maxage=10

# Email template settings
spring.freemarker.template-loader-path=classpath:/email-templates

email.enabled=true
email.host=smtp.gmail.com
email.port=587
email.useCredentials=true
email.username=yourgmailtestaccount@gmail.com
email.password=yourgmailtestaccountpassword
email.tls=true
email.from.default= yourgmailtestaccount@gmail.com
email.from.default.name=Workflow Notification
email.feedback.default= yourgmailtestaccount@gmail.com
email.base.url=http://localhost:8081/activiti-app

Start Alfresco Process Services

Now you’re ready to start your APS Docker containers. Bring up a command prompt/terminal window and change directory to the folder you created. Run “docker-compose up” without the quotes and it’ll start. The first time it starts, it’ll need to download images and build and may take awhile. Depending on your machine and internet connection, after a few minutes you should see a line in your output that says something like this:

process_1        | 31-May-2018 17:47:53.127 INFO [main] org.apache.catalina.startup.Catalina.start Server startup in 45051 ms

You can now launch a browser and go to http://localhost:8081/activiti-app. Log on with with username admin@app.activiti.com and password admin.

Stopping Alfresco Process Services

You can break from within your command prompt or just bring up another command prompt/terminal window and change directory to the folder you created and run “docker-compose down” without the quotes and it’ll gracefully stop APS. The next time you start, it’ll use the data that’s stored in the psdata and pgdata folders. If you wanted to start it “clean” without saving any of this previous data, you can always rename or delete these folders.

Next Steps

You can take a look at the getting starting section in the online APS docs and the Alfresco Community also provides great support.

If you’d like to learn more or discuss with our team, contact us here.

Pin It on Pinterest

Sharing is caring

Share this post with your friends!