====== Orbit 3DM Publisher on Ubuntu ======

This page documents only additional remarks to install Orbit on Ubuntu. \\
Guidelines to install the Publisher are available here: [[227:technology:platforms:install_server|]].

<note tip>
Going for Linux requires the system administrator to have good knowledge of using and managing the OS.
</note> 


===== Requirements and Precautions =====

**Java 11** \\ 
Java 11  is available for Ubuntu LTS 18.03 or later.

**Dedicated Service Account** \\ 
We advise creating a dedicated "orbit" user account to install and start the Orbit EOS service.  This user will also need sudo rights in order to install or manage the service. \\ 
It is possible to run the Orbit EOS Service as root user, but this might conflict with your security policy. \\
Complete all actions with one and the same user to avoid file access permission issues. If needed, check and change ownership and permissions on all files.

**Installation directory** \\ 
We advise to install the Publisher in ''/opt/orbit_3dm_publisher''. \\
Make sure this location is accessible by the service account and has at least 1Gb of free disk space.

**Editing configuration files** \\
We advise to use a Linux text editor e.g. vi, nano, gedit, ... to edit the configuration files. Dos (Windows), manipulated text files can contain extra characters, which may lead to the malfunctioning of the Orbit EOS Service. 

**Installation files** \\
The Linux Publisher installation files are provided as zip-package. Contact the Support Team for the most recent version.

===== Install Java =====

Install Java 11 using APT package manager:

<code bash>
$ sudo apt install openjdk-11-jre-headless
</code>

Configure Java 11 as default java version:

<code bash>
$ sudo update-alternatives --config java
There are 2 choices for the alternative java (providing /usr/bin/java).

  Selection    Path                                            Priority   Status
------------------------------------------------------------
  0            /usr/lib/jvm/java-11-openjdk-amd64/bin/java      1111      auto mode
* 1            /usr/lib/jvm/java-11-openjdk-amd64/bin/java      1111      manual mode
  2            /usr/lib/jvm/java-8-openjdk-amd64/jre/bin/java   1081      manual mode

Press <enter> to keep the current choice[*], or type selection number: 1
</code>

Verify Java 11 is set as default java version: 

<code bash>
$ java -version
openjdk version "11.0.7" 2020-04-14
OpenJDK Runtime Environment (build 11.0.7+10-post-Ubuntu-2ubuntu218.04)
OpenJDK 64-Bit Server VM (build 11.0.7+10-post-Ubuntu-2ubuntu218.04, mixed mode, sharing)
</code> 

===== Unpack Orbit installation files =====

Install the ''unzip'' utility:
<code bash>
$ sudo apt update
$ sudo apt install unzip
</code>

Copy and unpack archive to ''/opt/orbit_3dm_publisher'': 

<code bash>
$ cd /opt/orbit_3dm_publisher
$ unzip publisher.zip
</code>

Make all files in ''/opt/orbit_3dm_publisher/bin/'' executable: 
<code bash>
$ cd /opt/orbit_3dm_publisher/bin
$ chmod 774 *
</code>

===== Configure Orbit EOS Service Account =====

Enter Service Account in ''/opt/orbit_3dm_publisher/bin/eos'' file: 

<code bash>
RUN_AS_USER=XXX
</code>

===== Install, Start, Stop or Remove Orbit EOS Service =====

Install Orbit EOS Service: 

<code bash>
$ cd /opt/orbit_3dm_publisher/bin
$ sudo ./serviceinstall
</code>

Start Orbit EOS Service: 

<code bash>
$ cd /opt/orbit_3dm_publisher/bin
$ sudo ./servicestart
</code>

Stop Orbit EOS Service: 

<code bash>
$ cd /opt/orbit_3dm_publisher/bin
$ sudo ./servicestop
</code>

Remove Orbit EOS Service: 

<code bash>
$ cd /opt/orbit_3dm_publisher/bin
$ sudo ./serviceremove
</code>

===== Unprivileged ports =====

On Linux, only services started by the 'root' user can use privileged ports (ports < 1024). \\
If the Orbit EOS Service is required to run on a privileged port, we can advise two options: 

a) Setup 'root' as the service user (not recommended). \\
b) Patch Java using setcap, and Stop automatic Java updates, as the patch gets invalidated after an update.

Get the location of the java binary: 

<code bash>
$ update-alternatives --display java
java - manual mode
  link best version is /usr/lib/jvm/java-11-openjdk-amd64/bin/java
  link currently points to /usr/lib/jvm/java-11-openjdk-amd64/bin/java
  link java is /usr/bin/java
...
</code>

Patch the java binary (use the path after "link currently points to"): 

<code bash>
$ sudo /sbin/setcap 'cap_net_bind_service=ep' /usr/lib/jvm/java-11-openjdk-amd64/bin/java
</code>

The java binary now has the extra capability of using a privileged port.\\ 
To update the port used by Orbit 3DM Publisher, see [[227:server/eos/service]].

Disable java updates for a package (use the package name used to install java): 

<code bash>
$ sudo apt-mark hold openjdk-11-jre-headless
</code>