Skip to main content

Installation

This documentation will guide you how to run APEX Office Print on the following platforms:

Hardware requirements​

Following table gives an overview of the minimum requirements to run the AOP Server:

TypeAOP MinimumAOP RecommendedAOP Heavy Use
CPU2 cores4 cores8 cores
RAM6GB20GB40GB
Harddisk2GB2GB2GB

We recommend a CPU with at least 4 cores. For memory, AOP initially consumes about 1GB RAM, but depending the prints it can consumes more. We recommend 2GB of harddisk space; the executable and supporting files are about 1GB and we might create some temporary files and a log and error file. When you print many PDF documents at the same time, it's interesting to run two (or more) AOP Servers and put a load-balancer in front of it.

A question we often get is; does AOP have to go on its own server, the database server or the application (ORDS) server?

You can choose. Having AOP on the same server as the database machine is most performant and easiest as you don’t have network connections to other servers. If you install AOP on its own server you can size and monitor that server better. AOP on the Application server is another option, as long as the database can connect to the AOP server component, the AOP server doesn't need to be accessible from the outside (clients). So it’s whatever you are most comfortable with.

Installation on Linux​

Download and unzip file​

Log in on apexofficeprint.com and download the Linux version of AOP. Copy the zip you downloaded to the server where you want to run the AOP Server. Unzip the file in a directory of choice e.g. /opt/aop

create AOP directory​

mkdir /opt/aop

unzip​

unzip aop_linux_v24.1.zip -d /opt/aop
ln -s /opt/aop/v24.1 /opt/aop/latest

give permissions to executable​

chmod 755 /opt/aop/latest/server/APEXOfficePrintLinux64_4096/APEXOfficePrintLinux64

In order for AOP to convert PDFs it relies on LibreOffice (6 or higher) and Java, so both of those should be available on the server. You will find step-by-step instructions on how to verify if the pre-requisites are met and how to install those below.

Install LibreOffice​

Verify if LibreOffice is already installed on your system:

Check for installation of soffice/ LibreOffice​

soffice --version

Create default profile for soffice/ LibreOffice​

Create the default profile for soffice by running it once and exit by entering CTRL + C.

soffice

Expected output format​

LibreOffice 7.2.6.2 0c292870b25a325b5ed35f6b45599d2ea4458e77

Check for installation of Java​

java -version

Expected Output format:​

openjdk version "1.8.0_282"
OpenJDK Runtime Environment (build 1.8.0_282-b08)
OpenJDK 64-Bit Server VM (build 25.282-b08, mixed mode)

In case you need to install LibreOffice and Java you can follow the next steps.​

  1. install supporting packages

    yum install wget

  2. download LibreOffice for the PDF converter (or copy to the server) note that sometimes you have to retry in order for it to download

    cd /tmp
    wget https://download.documentfoundation.org/libreoffice/stable/7.2.6/rpm/x86_64/LibreOffice_7.2.6_Linux_x86-64_rpm.tar.gz

  3. make sure no old versions exist

    yum remove openoffice* libreoffice*

  4. install LibreOffice

    • extract tar
      tar -xvf LibreOffice_7.2.6_Linux_x86-64_rpm.tar.gz
    • install via yum
      cd /tmp/LibreOffice_7.2.6.2_Linux_x86-64_rpm/RPMS/
      yum -y localinstall *.rpm

    alternative to above you can do: rpm -ivh *.rpm --nodigest --nofiledigest

    info
    • optional: install some missing dependencies (depending your linux version this is not necessary)
    • Note if the below fails; you can add the Oracle repo:
    • cd /etc/yum.repos.d/
    • wget http://yum.oracle.com/public-yum-ol7.repo
    yum -y install libXineram
    yum -y install cairo.x86_64
    yum -y install cups.x86_64 --skip-broken
    yum -y install mesa-libGL.x86_64

  5. Install Java dependency (not necessary if you already have Java)

    yum -y install java-1.8.0-openjdk.x86_64

  6. make soffice available to your user

    • option 1 (recommended): create symbolic link

      ln -s /opt/libreoffice7.2/program/soffice /usr/sbin/soffice

    • run LibreOffice for the first time, this will create the default home directory of LibreOffice

      soffice

      CTRL-C to exit

    The following steps are OPTIONAL

    • option 2 (alternative): add LibreOffice to the profile for your user (as it needs to be able to find soffice)
    • if you did option 1, this is not necessary
      vi /etc/profile
      export PATH=$PATH:/opt/libreoffice7.2/program
      source /etc/profile

  7. check the version of LibreOffice and try to run a conversion

    soffice --version
    soffice --headless --invisible --convert-to pdf --outdir /tmp /tmp/LibreOffice_7.2.6.2_Linux_x86-64_rpm/readmes/README_en-US

if you get: Fontconfig warning: ignoring UTF-8: not a valid region tag

echo "$LC_CTYPE"

you probably have UTF-8 defined; unset it

export LC_CTYPE=""

optional: cleanup LibreOffice install

rm -rf LibreOffice_7.2.6.2_Linux_x86-64_rpm/
rm -f LibreOffice_7.2.6_Linux_x86-64_rpm.tar.gz

Installation on Windows​

Download and unzip file​

Log in on apexofficeprint.com and download the Windows version of AOP. Copy the zip you downloaded to the server where you want to run the AOP Server. Unzip the file in a directory of choice e.g. D:\aop

If you're on Windows, you can choose for LibreOffice or MS Office. We recommend LibreOffice, but in case you want to use MS Office, make sure you have MS Office 2007 or higher installed and also install OfficetoPDF (direct download), which allows to run conversions from the command line.

Note: Place the OfficetoPDF executable location in the system PATH variable.

Install LibreOffice​

In order for AOP to convert PDFs it relies on LibreOffice (6 or higher) and Java (optional but necessary for PDF manipulations is wished), so both of those should be available on the server. You will find below step-by-step instructions how to verify if the pre-requisites are met and how to install those.

Verify if LibreOffice is already installed on your system:

Open command Prompt and

  • check for soffice 

    soffice --version

    Expected output format

    LibreOffice 7.2.6.2 64390860c6cd0aca4beafafcfd84613dd9dfb63a

  • Check for Java Version.

    java -version

    Expected output format

    openjdk version "1.8.0_282"
    OpenJDK Runtime Environment (build 1.8.0_282-b08)
    OpenJDK 64-Bit Server VM (build 25.282-b08, mixed mode)

Installation steps for Libreoffice:

Installation steps for Java:

Activate and manual start APEX Office Print​

APEX Office Print needs a valid license file. If AOP doesn't find a license, it will run in Trial mode and print a trial watermark on every document.

In order to activate AOP:

  • Open Windows Powershell or Command Prompt
  • Navigate to the location where the APEX Office Print server is located and run:
    APEXOfficePrintWin64 -a
  • AOP will prompt for an email. Provide the email that was registered and where a valid license has been bought.
  • AOP will try to generate the license key. License key will be generated if there is an open connection to the internet. If there’s no internet connection, or something goes wrong with the activation, AOP will generate a license request file. You can upload this license request file on the dashboard at https://www.apexofficeprint.com/ after logging in. The received license file should be placed on the same location where the AOP executable is located. If the license file is located somewhere else, please modify the aop_config.jsonc file to point to it.
  • Once the license file is generated, restart of AOP is necessary. AOP will log the license information in the next run.

To start APEX Office Print:

  • go to the server directory and run APEXOfficePrintWin64.exe file.

On the first run of APEXOfficePrint a configuration file, aop_config.jsonc, is created. Customize the aop_config.jsonc file to your needs. For example to change the port to a different port than the default 8010. See the Configure APEX Office Print section for more info.

Using Microsoft Office as PDF converter and AOP as a service​

If you wish to use Microsoft office as PDF converter for your documents, some tweaks are necessary before APEX Office Print can be used or started as service.

32-Bit Windows​

Directory Creation​

Create a directory "Desktop" if it does not already exist under \

"C:\\Windows\\system32\\config\\systemprofile\\Desktop"
DCOM config​

  1. From Run (Windows + R), type dcomcnfg

  2. Navigate to Component Services > Computers > My Computer > DCOM Config

  3. Locate "Microsoft Excel Application" and right click properties of it

  4. Navigate to Security Tab and Customize the Launch and Activation Permissions and Edit

  5. Check that no instances of excel.exe are running before changing the properties, either close the applications that are running the Excel or go to task manager and kill the excel.exe processes.

  6. Add the current user (type the current user, click check names, and click ok) and grant permission for Local Launch and Local Activation

  7. Go to Identity Tab and change the radio button to "The User"

  8. Do the same for "Microsoft PowerPoint Slide".

  9. Do the same for "Microsoft Word 97-2003 Document".

Setting directory permissions​

  1. Navigate to: "C:\Windows\System32\config\systemprofile\AppData\Roaming\Microsoft".

  2. Right click and go to Properties

  3. Under Security Tab add the current user and grant the Modify, Read & Execute, List Folder Content, Read, and Write permissions.

  4. Do the same for "C:\Windows\Temp\".

64-Bit Windows​

Directory Creation​

Create a directory "Desktop" if it does not already exist under:

"C:\Windows\system32\config\systemprofile\Desktop" and "C:\Windows\SysWOW64\config\systemprofile\Desktop"

DCOM config​

  1. From Run (Windows + R), type dcomcnfg (if your Microsoft Office is 32 bit then open command line and change directory to "C:\Windows\SysWOW64" and run "mmc comexp.msc /32" command)

  2. Navigate to Component Services > Computers > My Computer > DCOM Config

  3. Locate "Microsoft Excel Application" and right click properties of it

  4. Navigate to Security Tab and Customize the Launch and Activation Permissions and Edit

  5. Check that no instances of excel.exe are running before changing the properties, either close the applications that are running the Excel or go to task manager and kill the excel.exe processes.

  6. Add the current user (type the current user, click check names, and click ok) and grant permission for Local Launch and Local Activation

  7. Go to Identity Tab and change the radio button to "The Interactive User" or "The Launching User" (automatic start)

  8. Do the same for "Microsoft PowerPoint Slide".

  9. Do the same for "Microsoft 97-2003 Document".

Setting directory permissions​

Navigate to:

  1. "C:\Windows\System32\config\systemprofile\AppData\Roaming\Microsoft".

  2. Right click and go to Properties

  3. Under Security Tab add the current user and grant the Modify, Read & Execute, List Folder Content, Read, and Write permissions.

    Do the same for:

  4. "C:\Windows\System32\config\systemprofile\AppData\Local\Microsoft"

  5. Do the same for "C:\Windows\Temp\".

Running as Service in Windows​

  • Navigate to WindowsService folder situated in the APEXOfficePrint folder.

  • Edit 1_SetupAsService.bat to include the full path to the executable APEXOfficePrintWin64.exe

    Note that you can also add additional parameters for example for the port it should run on and the starting directory.
    nssm.exe install APEXOfficePrint %0\..\..\APEXOfficePrintWin64.exe --port 8090 -s D:\apexofficeprint

  • Run 1_SetupAsService.bat.

  • The service should be installed and can be seen in Services (Control Panel > Administrative Tools > Services).

  • To change how the APEXOfficePrint service starts you can change it from Services or start it manually via 2_StartService.bat (should be run as Administrator).

  • To check if the service has started, navigate to http://localhost:8010/

  • To stop the service run 3_StopService.bat as Administrator or stop it from Services.

  • To remove APEXOfficePrint as service run 4_RemoveService.bat.

  • The APEXOfficePrint service should now be removed from Services. If it says Disabled then it will be removed after the service has been stopped.

Make sure you restart APEX Office Print after installing LibreOffice.

info
  • We sometimes see LibreOffice doesn't generate the same PDF as MS Office is generating, but we found LibreOffice is becoming more and more inline, so we recommend using the latest version of LibreOffice.
  • Depending on the version of LibreOffice converting to HTML from docx, xlsx, pptx might include the images as base64 or include a link.

Installation on Docker​

Pre-requisites​

Define a Docker network, if you don't have one yet

docker network create my_network

Make sure your Oracle database container is in this network

docker network connect my_network oracle

Start your ORDS container on this network

docker run -t -i \
--name ords \
--network=my_network \
-e DATABASE_HOSTNAME="oracle" \
-e DATABASE_PORT="1521" \
-e DATABASE_SERVICENAME="ORCLPDB1" \
-e DATABASE_PUBLIC_USER_PASS=oracle \
-e APEX_LISTENER_PASS=oracle \
-e APEX_REST_PASS=oracle \
-e ORDS_PASS=oracle \
--volume /docker/apex/images:/usr/local/tomcat/webapps/i \
-p 8181:8080
ords/ords_apex:3.0.9

Download the AOP docker image​

docker pull apexrnd/apexofficeprint

Activating APEX Office Print the first time. This step is only needed once.

docker run -it \
--name apexofficeprint \
--network=my_network \
-p 8010:8010 \
-v /docker/apexofficeprint/:/apexofficeprintstartup/ \
apexrnd/apexofficeprint \
-s /apexofficeprintstartup/
-a

You can also build your own docker image. The dockerfile content are as follows:


FROM ubuntu:18.04
ARG email

EXPOSE 8010
RUN apt-get update && \
    apt-get install -y libreoffice && \
    apt-get install net-tools && \
    mkdir /APEXOfficePrint/ && \
    cd /APEXOfficePrint/ && \
    apt-get install -y wget && \
    apt-get install -y unzip && \
    wget https://s3-eu-west-1.amazonaws.com/apexofficeprint/linux/aop_linux_latest.zip && \
    unzip aop_linux_latest.zip && \
    rm aop_linux_latest.zip && \
    version=$(ls -d */|head -n 1) && \
    mv $version/server/* ./ && \
    rm -r $version/ && \
    chmod u+x APEXOfficePrintLinux64 && \
    wget https://download.documentfoundation.org/libreoffice/stable/7.2.6/deb/x86_64/LibreOffice_7.2.6_Linux_x86-64_deb.tar.gz && \
    tar -xvf LibreOffice_7.2.6_Linux_x86-64_deb.tar.gz && \
    rm LibreOffice_7.2.6_Linux_x86-64_deb.tar.gz && \
    dpkg -i LibreOffice_7.2.6.2_Linux_x86-64_deb/DEBS/*.deb && \
    rm -r LibreOffice_7.2.6.2_Linux_x86-64_deb && \
    rm /usr/bin/soffice  && \
    ln -s /opt/libreoffice7.2/program/soffice /usr/bin/soffice  && \
    ./APEXOfficePrintLinux64 -a $email
ENTRYPOINT ["/APEXOfficePrint/APEXOfficePrintLinux64"]

In case you have an Enterprise License, add the aop.license file in the directory you specified, in below example it's /docker/apexofficeprint/

Start an AOP container on the network of your Oracle database container​

docker run -d \
--name apexofficeprint \
--network=my_network \
-p 8010:8010 \
-v /docker/apexofficeprint/:/apexofficeprintstartup/ \
apexrnd/apexofficeprint \
-s /apexofficeprintstartup/

You should now be able to connect to APEX Office Print server by going to http://apexofficeprint:8010/. You can view this video to see the above in action.

Adding fonts to the container​

You can add fonts into the container in two ways. You can run a shell into the running container and install the fonts like you do in Linux systems. 

docker exec -it <<container_id>> /bin/bash
#getting the font
apt install wget
wget https://github.com/jenskutilek/free-fonts/raw/master/Roboto/Roboto%20Sans/TTF/Roboto-Black.ttf
#installting the font
mv Roboto-Black.ttf /usr/share/fonts/
#updating the cache
fc-cache -fv
exit
docker restart <<container_id>>

The other way would be to for example include a volume that maps the fonts folder into the fonts folder of the container: 

docker run -d -p 9930:8010 -v /usr/share/fonts:/usr/share/fonts/custom apexrnd/apexofficeprint:latest

Activate and manual start APEX Office Print​

APEX Office Print needs a valid license file. If AOP doesn't find a license, it will run in Trial mode. You have all features when running in Trial mode, but AOP will print a trial watermark on top of the document.

In order to activate AOP, so there's no trial watermark:

  • Go to the folder containing executable for APEXOfficePrint and run: 
    ./APEXOfficePrintLinux64 -a
  • AOP will prompt you for the email.
  • Enter the email you registered with and where a license has been bought.
  • AOP will try to generate the license key. License key will be generated if there is an open connection to the internet. If there’s no internet connection, or something goes wrong with the activation, AOP will generate a license request file. You can upload this license request file on the dashboard at https://www.apexofficeprint.com/ after logging in. The received license file should be placed on the same location where the AOP executable is located. If the license file is located somewhere else, please modify the aop_config.jsonc file to point to it.
  • Once the license file is generated, restart of AOP is necessary. AOP will log the license information in the next run.

To start APEX Office Print:

  • go to the server directory and run 

    ./APEXOfficePrintLinux64 &

On the first run of APEXOfficePrint a configuration file, aop_config.jsonc, is created. Customize the aop_config.jsonc file to your needs. For example to change the port to a different port than the default 8010. See the Configure APEX Office Print section for more info.

If you encounter this error:

-------------------------------------------------
Error on Thu Feb 04 2016 19:33:35 GMT-0800 (PST)
-------------------------------------------------
listen EADDRINUSE

It means the port is already being used.

Start/Stop APEX Office Print as a service​

On Linux you can use systemd (systemctl) to start and stop services. For Red Hat and Oracle Enterprise Linux you can follow the below instructions.

As user root or sudo privileged user:

  1. create the aop user

    sudo useradd aop
    sudo groupadd aop
    sudo usermod -a -G aop aop

  2. give the aop user the privileges to the /opt/aop directory

    chown aop:aop /opt/aop -R

  3. create aop.service

    cd /etc/systemd/system
    vi aop.service

Paste the following in and adjust for your installation as required. In this script, AOP is installed in /opt/aop, run with the aop user which has as home directory /home/aop.

[Unit]
Description=APEX Office Print
After=network.target

[Service]
Type=simple
User=aop
Group=aop

Environment=AOP_HOME=/opt/aop/latest/server/APEXOfficePrintLinux64_4096
Environment=AOP_PROCESS_NAME=APEXOfficePrint
Environment=AOP_EXECUTABLE_NAME=APEXOfficePrintLinux64

Environment=PATH=/usr/local/bin:/usr/bin:/usr/local/sbin:/usr/sbin:/bin/
Environment=HOME=/home/aop
SyslogIdentifier=apexofficeprint
Restart=always
RestartSec=30
TimeoutStartSec=30
TimeoutStopSec=30

ExecStart=/usr/bin/env ${AOP_HOME}/${AOP_EXECUTABLE_NAME} -s ${AOP_HOME}

ExecStop=/usr/bin/env pkill ${AOP_PROCESS_NAME}

[Install]
WantedBy=multi-user.target

Reload the daemon

systemctl daemon-reload

A simple setup is needed to install the version of aop in /opt/aop. When you install a new version just unzip in this directory. You will end up for example with the following directories v18.2, v19.3 and v21.2. Create in the directory /opt/aop a symbolic link to point to the latest version.

ln -s /opt/aop/v24.1 /opt/aop/latest

Suppose something is not working properly and you need to revert back to your previous version, all you need to do is to change the symbolic link to point to a previous version. For example

unlink latest
ln -s /opt/aop/v24.1 /opt/aop/latest

As root

start aop               : systemctl start aop
stop aop                : systemctl stop aop
status aop              : systemctl status aop
autostart at boot       : systemctl enable aop
remove autostart at boot: systemctl disable aop

Example output of systemctl status aop

[root@s2s-proddb-03 system]# systemctl status aop.service
● aop.service - APEX Office Print
   Loaded: loaded (/usr/lib/systemd/system/aop.service; disabled; vendor preset: disabled)
   Active: active (running) since Sat 2018-03-10 20:39:47 AEDT; 6s ago
Main PID: 28273 (APEXOfficePrint)
   CGroup: /system.slice/aop.service
           ├─28273 /opt/aop/latest/server/APEXOfficePrintLinux64 -p 8010 -s /opt/oracle/aop/latest/server
           ├─28283 /opt/aop/v3.4/server/APEXOfficePrintLinux64 --pkg-fallback --max_old_space_size=4096 /snapshot/apexofficeprint/aop_server/node_modules/apexrnd-startup-utils/sequentialConverter.js -d 0 --idleT...
           └─28288 /opt/aop/v3.4/server/APEXOfficePrintLinux64 --pkg-fallback --max_old_space_size=4096 /snapshot/apexofficeprint/aop_server/apexofficeprint.js -p 8010 -s /opt/oracle/aop/latest/server
Mar 10 20:39:47 http://proddb-032.acme.com systemd[1]: Started APEX Office Print.
Mar 10 20:39:47 http://proddb-032.acme.com systemd[1]: Starting APEX Office Print...
Mar 10 20:39:48 http://proddb-032.acme.com apexofficeprint[28273]: Current license is activated to: xxxx@thiscompany.com
Mar 10 20:39:48 http://proddb-032.acme.com apexofficeprint[28273]: The products activated are:
Mar 10 20:39:48 http://proddb-032.acme.com apexofficeprint[28273]: Word
Mar 10 20:39:49 http://proddb-032.acme.com apexofficeprint[28273]: Listening on port 8010
Mar 10 20:39:49 http://proddb-032.acme.com apexofficeprint[28273]: AOP 1 running

To view detailed logs of the service do:

journalctl -u aop.service

FAQ On Installation​

What kind information is sent while activation?

When you try to activate the product, AOP will ask for the registered email. Afterwards it looks at the UUID/GUID of the machine, this is:

For Windows:

MachineGuid key in registry HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Cryptography

For Linux:

/var/lib/dbus/machine-id

The machine id is then hashed using sha-256.

The following content after encryption is sent to the AOP license server:

{
"email": "provided-registered-email",
"mid": "sha-256 hashed machine-id",
"version": "AOP version getting activated"
}

Since SHA-256 is a one way function, it is impossible to derive the actual machine id from the given hash. No actual IP address, hostname, serial number, MAC address or any other hardware information are exposed.

Does AOP on-prem version require internet access to activate/run?

During the activation, AOP will try to connect to our license server. If this fails, AOP will generate a license request file that can be uploaded to our website in order to get back the license file. This license file should be placed in the same folder as the AOP executable.

In short, AOP does not require internet access to be activated and to run.

Installation of Fonts​

To install the most used Microsoft fonts, execute following commands:

rpm -i https://yum.oracle.com/repo/OracleLinux/OL7/developer_EPEL/x86_64/getPackage/cabextract-1.9-7.el7.x86_64.rpm
yum -y install rpm-build cabextract ttmkfdir fontconfig
rpm -i https://downloads.sourceforge.net/project/mscorefonts2/rpms/msttcore-fonts-installer-2.6-1.noarch.rpm
fc-cache -fv

If you need special characters or language support, make sure the necessary fonts and languages are on your system. For example to add Chinese or Japanese support do:

yum install "@Chinese Support"
yum groupinstall Fonts

Further more if you want to install additional fonts here's a good link. AOP Cloud API has Google Noto fonts installed.

Installing a font is nothing more than installing the font on your system. For example on (RedHat) Linux, we copy the *.ttf files (or directory) to /usr/share/fonts/ and run "fc-cache -f -v"

For barcodes, you could also choose to install a barcode font, for example Free 3of9 or http://www.dafont.com/3of9-barcode.font. Barcode fonts are more performant than images.

If you are using font awesome and using html tag or interactive reports/grid in Word, you will have to install the font-awesome desktop fonts in order to render the PDFs properly.