/ Management  

How to deploy an AppWorks package

Hi there AppWorks fans,

Welcome to a new installment of AppWorks tips.

Finally,…the moment where we’ve all been waiting for: “The deployment of our first (runtime) package!”. No other words required…

Let get right into it…

And the first thing we need to do is make a ‘clean’ environment available!

Damn…but that is a lot of work?…Yes but do it again and again and again will improve your skills too.

But lucky for me (and maybe also for you) is that we made a ‘snapshot’ of our VM image, so we can easily jump back in time with a clean steady image.

Start you Oracle VirtualBox and go to your image that might look like this:


You can make 2 choices here

  • ‘Clone’ the image, but that also clones the snapshots you have
  • ‘Restore’ to the state where is was all ‘running fine’ in my case

We choose the second option and with that option we make a new snapshot of the current state with a description like this ‘State when first package was created’.


After the restore start your ‘clean’ image and check out the result…

  • You can’t login anymore with the ‘awdev’ user account
  • And our ‘AppWorksTips’ organization is gone

With this information we can continue to…

The deployment of a package

You have it ready right?…The .CAP file (e.g. AppWorksTips AppWorks 1.0.0.cap)

Now open your ‘Explorer’ in the ‘/home/system’ organization with the ‘sysadmin’ account that has the role ‘setupUser’ applied by default.

This is always your start point for deployment!

Open the ‘Application Deployer’ artifact from the main screen.


Click that ‘Browse’ button to select your downloaded .CAP file and hit the ‘Upload’ button for the magic!

And there it is…shining like a star.


Now the big moment of truth…The deployment itself…just hit it like a pro and see what happens


We get to the first step of package deployment.


We just nicely click ‘Next >’ for step 2…You feel the excitement?


Hmmmm…that’s too bad…We have an ‘unsigned’ package!


Ok…let’s sign the bastard!

Sign a package with the ‘Package Signer’ tool

Open your MobaXTerm to the CentOS VM we’re using and go to the ‘original’ location where your AppWorks installation journey started with the extracted installation directory!

In my case the ‘home’ folder for the ‘otadmin’ installation account cd /home/otadmin/opentext-appworks-suite-16.7-linux/OpenTextAppWorksPlatform/packagesigner

First make the ‘packageigner.sh’ executable chmod +x packagesigner.sh

And do a fix command as this file contains windows-formatted <Enter> keys that the bash command does not like: sed -i -e 's/\r$//' packagesigner.sh

Now you can do ./packagesigner.sh or sh packagesigner.sh to get some result back!


We can extend the command now with the correct parameters like this example:

./packagesigner.sh -keystore /opt/SignApplication/keystore.pfx -storepass admin -packagepath /opt/SignApplication/packages/AppWorksTips\ AppWorks\ 1.0.0.cap -alias AppWorksTips

But to make this work we need to create some locations and files!

First for the locations:

  • sudo mkdir /opt/SignApplication and sudo chown otadmin:otadmin /opt/SignApplication

  • sudo mkdir /opt/SignApplication/packages and sudo chown otadmin:otadmin /opt/SignApplication/packages

Then for the certification and key files:

  • openssl genrsa -des3 -out /opt/SignApplication/server.key 2048

    • Use ‘admin’ as pass phrase (with a verify)
  • openssl req -new -key /opt/SignApplication/server.key -out /opt/SignApplication/server.csr

    • Use ‘admin’ as pass phrase
    • Fill in like this and leave ‘challenge password’ and ‘optional company name’ empty.
    Country Name (2 letter code) [XX]:NL
    State or Province Name (full name) []:BRABANT
    Locality Name (eg, city) [Default City]:EINDHOVEN
    Organization Name (eg, company) [Default Company Ltd]:APPWORKS-TIPS
    Organizational Unit Name (eg, section) []:DEVELOPMENT
    Common Name (eg, your name or your server's hostname) []:WIN-5SKKMBURVO7
    Email Address []:contact@appworks-tips.com

    Please enter the following 'extra' attributes
    to be sent with your certificate request
    A challenge password []:
    An optional company name []:
  • openssl x509 -req -days 365 -in /opt/SignApplication/server.csr -signkey /opt/SignApplication/server.key -out /opt/SignApplication/server.crt

    • Use ‘admin’ as pass phrase
  • cat /opt/SignApplication/server.key > /opt/SignApplication/server.pem

  • cat /opt/SignApplication/server.crt >> /opt/SignApplication/server.pem

  • openssl pkcs12 -export -in /opt/SignApplication/server.pem -out /opt/SignApplication/keystore.pfx -name AppWorksTips

    • Use ‘admin’ as pass phrase
    • Use ‘admin’ as export passcode (with a verify)
  • Now you should be able to sign the .cap package with ‘packagesigner.sh’, but…read the comment!

Maybe it’s my image, but I was not able to execute the .sh file properly with the correct parameters so I executed it manually with the content from that file!

export CLASSPATH=jars/packagesigner.jar:$CLASSPATH
export PATH=$JAVA_HOME/bin:$PATH
java com.cordys.tools.signpackages.ArchiveSigner -keystore /opt/SignApplication/keystore.pfx -storepass admin -packagepath /opt/SignApplication/packages/AppWorksTips\ AppWorks\ 1.0.0.cap -alias AppWorksTips

The result must be a finally ‘relieved’ message


Second try for our deployment (with signed package this time)

Go back to the ‘Application Deployer’ artifact in the system space with the ‘sysadmin’ account.

Now upload the brand-new signed .CAP package to the list. You get a notification, but nothing (at first sight) changes, but believe me…it’s uploaded!

Now right-click again on the package and hit ‘Deploy’ so the wizard is started again.

You can scroll to the top if you like and get back here till you see this screen, but hmmmm…we’re ‘Untrusted’!


Bloody hell….now what?

Let’s dive into the application security settings as the message is telling me!

Application security settings

Let’s start the artifact with the (logically called) name ‘Security Administration’!…Yes, in the ‘System’ space with the ‘sysadmin’ account.

It looks we can do 2 options here

  1. Upload our self-signed certificate and make it ‘trustworthy’ in the shared space!
  2. Make sure a self-signed certificate is accepted as ‘trusted’

We go for option 2 in the second tab ‘Code Signing’ where we change the 2 required options!


Save the settings and go for the (three times is right!) deployment option again.

Third try for our deployment

No need to restart anything and no upload is needed as all is fine…Just right-click the package again from the ‘Package Deployer’ artifact and go…

Hooray…we get a next screen…finally!

Actually, the certificate validation is skipped, and we have only 5 steps in the wizard left…For a ‘Development’ environment this is also fine for now.


Let’s go for the next step by clicking ‘Next >’


And there we go…Time for coffee?


There it is…Our shining ‘Finish’ button…hit it!

And check the detail for our deployed package


Now what?…Can we just open our front-end (/home/appworks_tips/app/start) now like we did before?

For sure not, as that organization space is not available (yet)…Remember that restore we did?…Follow the 3 quick steps below!

Quick steps for organization management:
  • Open the ‘Manage Organizations’ artifact
  • Add a new organization with for example:
    • Name: appworks_tips
    • Full Name: AppWorks Tips
  • Add the ‘sysadmin’ account as the ‘Administrator’ role

Now the space /home/appworks_tips/ is available

Quick steps for user managements
  • Go the new organization space URL
  • Open the ‘User Manager’ artifact
  • Add a new user
    • Type: Platform
    • User Name: awuser
    • User Full Name: awuser
    • User ID: awuser
    • Default organization: AppWorks Tips (greyed out)
    • Password: admin
  • Apply the new user with the role ‘Entity Runtime User’
Quick steps for making the solution available
  • Open the admin console /home/appworks_tips/app/admin
  • Show the ‘Shared’ solutions and make the solution available for the ‘Entity Runtime User’


The moment of truth…

Open the end-user interface on /home/appworks_tips/app/start and login with the new ‘awuser’ account!

There we go…Our solution is ready for usage!


Deploy a package sssssssssht (silently)

That’s a good one to do…right!?

And it was possible, but when you look in the administration documentation we’ll find this very clear note.


🆕 !!UPDATE!!
As we are now in release 20.2 CE we see this ‘deprecated’ section being removed from the administration documentation!
That’s a ‘hooray’ for us…it’s placed on the backlog for future investigation.

Wow…does this give us a big ‘DONE’ on the package deployment…What a journey, but now we all know what to expect and that’s great. Too bad the silent deployment is deprecated, and you need to struggle yourself through the deployment wizard, but it works smooth (when you know how it work). Good to see that the silent installation is still a possible option to do…We’ll see in the future!

As always…I see you in the next post about a new AppWorks installment.

Don’t forget to subscribe to get updates on the activities happening on this site. Have you noticed the quiz where you find out if you are also “The AppWorks guy”?