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:
Type | AOP Minimum | AOP Recommended | AOP Heavy Use |
---|---|---|---|
CPU | 2 cores | 4 cores | 8 cores |
RAM | 6GB | 20GB | 40GB |
Harddisk | 2GB | 2GB | 2GB |
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
Please check the hash of the downloaded zips to ensure the integrity of the files.
If you work with sensitive data, we recommend running the AOP server in a private network without external internet access. For activation, you can provide --generate_lrf
to generate a license request file. After logging in, you can upload this license request file to our www.apexofficeprint.com portal.
For detailed information on the file generation process, refer to the Report Generation Process section.
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
create symbolic link for latest directory (see further for more explanation)
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.
install supporting packages
yum install wget
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.gzmake sure no old versions exist
yum remove openoffice* libreoffice*
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- extract tar
Install Java dependency (not necessary if you already have Java)
yum -y install java-1.8.0-openjdk.x86_64
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
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
Please check the hash of the downloaded zips to ensure the integrity of the files.
If you work with sensitive data, we recommend running the AOP server in a private network without external internet access. For activation, you can provide --generate_lrf
to generate a license request file. After logging in, you can upload this license request file to our www.apexofficeprint.com portal.
For detailed information on the file generation process, refer to the Report Generation Process section.
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:
- Download the installer from: https://www.libreoffice.org/download/download/
- Run the installer (full details: https://www.libreoffice.org/get-help/install-howto/windows/)
- Add the program folder from the installation folder into the system PATH variable.
Installation steps for Java:
- Download Oracle JDK or JRE (8 or higher) from: https://www.oracle.com/java/technologies/javase-jre8-downloads.html
- Run the installer (full details: https://java.com/en/download/help/windows_manual_download.html)
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
From Run (Windows + R), type dcomcnfg
Navigate to Component Services > Computers > My Computer > DCOM Config
Locate "Microsoft Excel Application" and right click properties of it
Navigate to Security Tab and Customize the Launch and Activation Permissions and Edit
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.
Add the current user (type the current user, click check names, and click ok) and grant permission for Local Launch and Local Activation
Go to Identity Tab and change the radio button to "The User"
Do the same for "Microsoft PowerPoint Slide".
Do the same for "Microsoft Word 97-2003 Document".
Setting directory permissions
Navigate to: "C:\Windows\System32\config\systemprofile\AppData\Roaming\Microsoft".
Right click and go to Properties
Under Security Tab add the current user and grant the Modify, Read & Execute, List Folder Content, Read, and Write permissions.
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
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)
Navigate to Component Services > Computers > My Computer > DCOM Config
Locate "Microsoft Excel Application" and right click properties of it
Navigate to Security Tab and Customize the Launch and Activation Permissions and Edit
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.
Add the current user (type the current user, click check names, and click ok) and grant permission for Local Launch and Local Activation
Go to Identity Tab and change the radio button to "The Interactive User" or "The Launching User" (automatic start)
Do the same for "Microsoft PowerPoint Slide".
Do the same for "Microsoft 97-2003 Document".
Setting directory permissions
Navigate to:
"C:\Windows\System32\config\systemprofile\AppData\Roaming\Microsoft".
Right click and go to Properties
Under Security Tab add the current user and grant the Modify, Read & Execute, List Folder Content, Read, and Write permissions.
Do the same for:
"C:\Windows\System32\config\systemprofile\AppData\Local\Microsoft"
Do the same for "C:\Windows\Temp\".
Running as Service in Windows
Navigate to WindowsService folder situated in the APEXOfficePrint folder.
Edit
Note that you can also add additional parameters for example for the port it should run on and the starting directory.1_SetupAsService.bat
to include the full path to the executable APEXOfficePrintWin64.exenssm.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.
- 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:
create the aop user
sudo useradd aop
sudo groupadd aop
sudo usermod -a -G aop aopgive the aop user the privileges to the /opt/aop directory
chown aop:aop /opt/aop -R
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.