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. # https://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. # https://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. # https://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 # https://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=https://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 https://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.