Semaphore Studio with Docker

To build a docker image and containers for Studio:

1. Create a folder for your Studio docker project. Store all the files in this folder.

2. Download all the necessary RPM files to install Studio. You will need:

   • Java 11 x64: A supported JDK. In this example, we will be using Amazon Corretto JDK 11 RPM for Linux x64.

   • Semaphore Studio RPM installation file

3. Create a file named start-studio.sh containing the following:

   Copy

   #!/bin/bash
   
   function shutdown { 
   cd /opt/semaphore/kmm
   export CATALINA_BASE=/opt/semaphore/kmm
   /opt/semaphore/tomcat/bin/shutdown.sh
   sleep 100 
   pkill java 
   sleep 10 
   exit }
   
   echo
   echo "Starting Semaphore Studio" echo trap shutdown SIGHUP SIGINT
   SIGTERM
   
   # Unpack the tarball under /var/opt/semaphore if studio folder does not exist (for bind mounts).
   [ ! -d "/var/opt/semaphore/studio/" ] && tar xvzf /sem_var_opt_sem.tgz # Unpack the tarball under /etc/opt/semaphore if studio folder does not exist (for bind mounts).
   [ ! -d "/etc/opt/semaphore/studio/" ] && tar xvzf /sem_etc_opt_sem.tgz
   
   # Start services cd /opt/semaphore/da JAVA_HOME=/usr/lib/jvm/java-11-amazon-corretto/opt/semaphore/da/bin/start.sh &
   
   cd /opt/semaphore/rm JAVA_HOME=/usr/lib/jvm/java-11-amazon-corretto
   /opt/semaphore/rm/bin/start.sh &
   
   cd /opt/semaphore/sm
   JAVA_HOME=/usr/lib/jvm/java-11-amazon-corretto/opt/semaphore/sm/bin/start.sh &
   export CATALINA_HOME=/opt/semaphore/tomcat export
   JAVA_HOME=/usr/lib/jvm/java-11-amazon-corretto
   
   cd /opt/semaphore/kmm
   SEMAPHORE_WORKBENCH_HOME=/var/opt/semaphore/kmm/data JAVA_HOME=/usr/lib/jvm/java-11-amazon-corretto CATALINA_BASE=/opt/semaphore/kmm
   /opt/semaphore/tomcat/bin/startup.sh
   
   cd /opt/semaphore/studio JAVA_HOME=/usr/lib/jvm/java-11-amazon-corretto
   /opt/semaphore/studio/bin/start.sh & cd /opt/semaphore
   
   if [ ! -f ".env_configured" ]; then
   sleep 30
   # configure SES, CS and publishing permission defaults on first startup.
   /opt/semaphore/upload-license.sh &> upload-license.log
   /opt/semaphore/create-ses-service.sh &> create-ses-service.log
   /opt/semaphore/create-cs-service.sh &> create-cs-service.log
   /opt/semaphore/add-superadmin-publish-permission.sh &> add-superadmin-publish-permission.log
   touch ".env_configured" 
   fi
   
   while true 
   do sleep 
   1 done
   

   You will use this script to launch containers. This script launches Studio, KMM, RM, SM and DA as background processes, and then sleeps periodically until the container stops. The trap command maps various process signals to our custom shutdown function which exits the script. The tar operations for /var/opt/semaphore and /etc/opt/semaphore are used to pre-populate filesystem, if using bind mounts rather than docker volumes. Note that this script starts three background processes: KMM as a Tomcat service, and the remaining as Quarkus service applications.

   The SEMAPHORE_WORKBENCH_HOME environment variable is very important as it puts the database for KMM on the /var/opt/semaphore external volume. After building the container, you should confirm that the /var/opt/semaphore/kmm/data folder has a workspace folder:

   Copy

   docker exec -it studio563-1 bash
   
   cd /var/opt/semaphore/kmm/data/ 
   ls -l
   

4. Add a default user to studio-authentication.properties for Studio. This will allow you to log in after creating the container.

   Copy

   # Authentication mechanisms: FORM, LDAP, OIDC, NO_AUTH
   studio.auth.mechanism=FORM ## User & Roles
   
   ### If the properties are stored in plain text. If this is true (the default) then it is expected that the passwords are of the form HEX( MD5
   #quarkus.security.users.embedded.plain-text=true
   #quarkus.security.users.embedded.algorithm=digest-md5
   ### The user to password mappings are specified by properties keys of the form quarkus.security.users.embedded.users.<user>=<password>. quarkus.security.users.embedded.users.SuperAdministrator=admin quarkus.security.users.embedded.users.Administrator=admin
   quarkus.security.users.embedded.users.user=User
   ### The user to role mappings are specified by properties keys of the
   form
   quarkus.security.users.embedded.roles.<user>=role1[,role2[,role3[,
   quarkus.security.users.embedded.roles.SuperAdministrator=SemaphoreSuperAdministrators,SemaphoreAdministrators,SemaphoreRoots
   quarkus.security.users.embedded.roles.Administrator=SemaphoreAdministrators
   quarkus.security.users.embedded.roles.User=SemaphoreUsers
   

5. Once all the prerequisites are copied to your project folder, build the Dockerfile.

   We start the Dockerfile using the Oracle Enterprise Linux version 8 image. We then install all the RPMs, configure some environment variables, copy files and scripts onto the local image, and define the exposed ports and /var/opt/semaphore as our external volume.

   The following is an example DockerFile:

   Copy

   FROM oraclelinux:8
   
   LABEL maintainer="Progress Semaphore Semaphore Ltd"
   LABEL sem5-version="5.6.3"
   
   # Copy local RPMs and licence file to image
   
   RUN mkdir /local-rpms/
   COPY *.rpm /local-rpms/
   
   # Get CentOS updates and install rpms, and clean up.
   
   RUN yum -y --setopt=tsflags=nodocs update && \ yum install -y
   --setopt=tsflags=nodocs patch && \
   
   yum install -y util-linux-user && \
   yum install -y jq && \ yum install -y less && \
   yum install -y --setopt=tsflags=nodocs
   /local-rpms/java-11-amazon-corretto-devel-11.*.*.rpm && \
   yum install -y /local-rpms/Semaphore-Studio-5.6.3-1.noarch.rpm && \
   yum install -y tar && \ yum clean all
   
   # Default authentication file with SuperAdministrator, Administrator and User accounts
   COPY studio-authentication.properties /opt/semaphore/studio/conf/studio-authentication.properties
   
   #Copy in the daemon creation script and start script
   COPY start-studio.sh /opt/semaphore
   
   #Copy the configure-studio.sh and licence file to image
   COPY create-ses-service.sh /opt/semaphore
   COPY create-cs-service.sh /opt/semaphore
   COPY add-superadmin-publish-permission.sh /opt/semaphore
   COPY upload-license.sh /opt/semaphore
   COPY licence /opt/semaphore
   
   # make scripts executable
   
   RUN chmod 777 /opt/semaphore/start-studio.sh
   RUN chmod 777 /opt/semaphore/create-ses-service.sh
   RUN chmod 777 /opt/semaphore/create-cs-service.sh
   RUN chmod 777 /opt/semaphore/upload-license.sh
   RUN chmod 777 /opt/semaphore/add-superadmin-publish-permission.sh
   
   # TAR the directories and files under /var/opt/semaphore and /etc/opt/semaphore # so we can initialize bind mounts if necessary. Still works with docker volumes.
   
   RUN cd / && tar cvzf sem_var_opt_sem.tgz /var/opt/semaphore/ && tar cvzf
   sem_etc_opt_sem.tgz /etc/opt/semaphore/
   
   # set path environment variable
   ENV PATH /usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin:/opt/semaphore
   
   # external volumes off union filesystem
   VOLUME ["/var/opt/semaphore"]
   VOLUME ["/etc/opt/semaphore"]
   
   # Export Studio port 5080
   EXPOSE 5080
   
   CMD ["/opt/semaphore/start-studio.sh"]
   

   The filesystem locations /var/opt/semaphore and /etc/opt/semaphore are declared external volumes with the VOLUME keyword. They contain state that changes when the application runs. Use a named docker volume if possible when starting the container. If you must use bind mounts rather than docker volumes, we've provided a simple technique using tar.gz files in the image to pre-populate the filesystem when the application starts.

6. Create the scripts that build the Classification Server, Semantic Enhancement Service services in Studio, and assign publisher permissions for SuperAdministrator account.

   See the docker-examples in github for example scripts that use cURL to configure studio after startup. These scripts include:

   • Uploading a license file (upload-license.sh)

   • Defining an SES service (create-ses-service.sh) Defining CLS Service (create-cs-service.sh)

   • Setting Publishing Permissions for the SuperAdministrator account (add-superadmin-publish-permissions.sh)

7. Build the image using the following command:

   Copy

   docker build -t studio563
   

8. Once the image is successfully built, run to build a container instance using the following command:

   Copy

   docker run -d --name studio563-1 -p 5080:5080 \
   --mount src=sem5_studio_var_volume,target=/var/opt/semaphore,type=volume \
   --mount src=sem5_studio_etc_volume,target=/etc/opt/semaphore,type=volume \
   studio563
   

   Note the use of the --mount flag. It is very important to use a named volume for the external volume indicated at /var/opt/semaphore and /etc/opt/semaphore.

   If you use bind mounts, run as follows:

   Copy

   docker run -d --name studio563-1 -p 5080:5080 \
   
   --mount src=/path/to/local/var/folder,target=/var/opt/semaphore,type=bind \
   --mount src=/path/to/local/etc/folder,target=/etc/opt/semaphore,type=bind \
   studio563
   

9. Use the docker ps command to verify that the container is running. I successful, you should see the following container running:

   Copy

   CONTAINER ID    IMAGE       COMMAND                      CREATED          STATUS        PORTS 
   c06a135be25b    studio563   \"/opt/semaphore/star...\"   15 minutes ago   Up 15 minutes 0.0.0.0:5080->5080/tcp 
   

Open your browser and go to the http://localhost:5080 to confirm that Studio is up and running.