Installation guide for Neptune DXP - Open Edition

This installation guide describes how you install, upgrade, and start Neptune DXP - Open Edition. This guide is for Neptune DXP - Open Edition server, release 2.x.

Neptune DXP - Open Edition, release 2.x, does not support filesystems. An upgrade from the filesystem is not possible. We recommend that you install Neptune DXP - Open Edition in a different location and move artifacts from Neptune DXP - Open Edition 1.x to Neptune DXP - Open Edition 2.x. The replacement for the filesystem is SQLite DB.

Neptune DXP - Open Edition is delivered as an executable file, including all resources such as node.js.

Installation package

The installation package contains the following files:

  • Neptune DXP - Open Edition executable file (for example, openedition-linux)

  • SQLite Node binding file: node_sqlite3.node. It contains a dependency for Neptune DXP - Open Edition executable. The NodeJS is binding for SQLite for the target platform. It is mandatory that this file is in the same directory as Neptune DXP - Open Edition executable.

  • LICENSES file. It consists of plain text and contains all licenses of the NPM modules that Neptune DXP - Open Edition internally uses.

Folder structure

The installation of Neptune DXP - Open Edition creates the following folders on your system:

  • Configuration directory: Configuration file(s) that are created to configure Neptune DXP - Open Edition. Do not edit these files.

  • Log directory: All logs generated by Neptune DXP - Open Edition are logged here. This is useful to diagnose issues.

  • package*.json file(s): If the custom NPM module directory is configured in Neptune DXP - Open Edition directory, a package.json and package-lock.json file is created.

  • Database directory and *.sql files: This is where the local SQLite database is located. It is only present if an SQLite database has been used or is used.

Start Neptune DXP - Open Edition server

Enter the following parameters when you start Neptune DXP - Open Edition for the first time, as normal startup or as upgrade of an existing version.

Table 1. Parameters for first start
Operating system First time startup Normal startup

Windows

planet9-win –upgrade

planet9-win

Linux

planet9-linux –upgrade

planet9-linux

iOS

planet9-macos –upgrade

planet9-macos

Special aspects of installing Neptune DXP - Open Edition on macOS

There are some known issues with Safari. The browser adds ".dms" to the filename. Perform the following steps when installing Neptune DXP - Open Edition on macOS:

  1. After the download is finished, open the download folder and check the filename.

  2. Rename the file and delete the extension ".dms".

  3. Open a console and go to the folder where the file is located.

  4. Type the following command: chmod +x ./planet9-macos

The file is not executable (macOS or Linux)

If the file is not executable, perform the following steps:

  1. Open a console.

  2. Enter cd <path to planet9>.

  3. Enter chmod+x ./planet9-macos.

Post-upgrade activities

After you have upgraded Neptune DXP - Open Edition, perform the following tasks:

Launchpad

Check for Launchpad updates in the store [Link to Neptune store] and download the new version if available.

New features

Navigate to Cockpit > Security > Role and check ACL for new functions delivered in the new version.

Node and npm

This version runs on an upgraded version of node: v12.13.1. It is important that you upgrade your custom node modules accordingly:

  1. Upgrade your own node version to 12.13.1

  2. Open a console.

  3. Run npm rebuild in the directory where the node modules are installed.

Run Neptune DXP - Open Edition

After Neptune DXP - Open Edition is started, open a browser and navigate to the URL corresponding to your server:

The default username is “admin/admin”.

Run Neptune DXP - Open Edition server in production

When you deploy a Neptune DXP - Open Edition instance on a remote system, do not run the Neptune DXP - Open Edition instance as an “admin”, “root”, or any other super admin-type privileged user. Depending on the system, this results in Neptune DXP - Open Edition probably (depending on OS) not being able to bind by default to port 80 (HTTP) or 443 (HTTPS). To bind Neptune DXP - Open Edition to these default ports, we advise to use a web server like NGINX. This web server can bind to the ports 80 and 443 and forwards requests to the Neptune DXP - Open Edition instance.

Use NGINX

You can use NGINX to cache any media request. By this, less data traffic is put on Neptune DXP - Open Edition instance for serving static assets, for example, images. NGINX has a free open source version available for commercial use and can be downloaded at NGINX.

Store custom npm modules

We recommend that you create a folder where all custom npm modules are installed. You can configure Neptune DXP - Open Edition instance to use this folder in Settings > Customizing > General.

Run Neptune DXP - Open Edition server on a remote system

To run Neptune DXP - Open Edition server on a remote system, you need to be able to disconnect from the system without detaching the process. There are two options to do this:

Option 1: Forking

Fork the system so that it can run as a background process or as a service. The benefit of running as a service is that Neptune DXP - Open Edition instance can restart in the event of a Neptune DXP - Open Edition application crash and auto-start after booting. IMPORTANT: Make sure that the user running Neptune DXP - Open Edition service has the following properties and permissions:

  • The user can access the custom npm folder.

  • The user set the path to npm.

  • The user has the permissions for Neptune DXP - Open Edition executable (see installation step).

A configuration for a Linux service would look as follows:

[Unit]

Description=Neptune DXP - Open Edition

[Service] ExecStart=/var/planet9/planet9-linux
Restart=always
User=MyUser
Group=nobody
# Notice the NPM path
Environment=PATH=/home/MyUser/.nvm/versions/node/v10.16.3/bin:/usr/
bin:/usr/local/bin
Environment=NODE_ENV=production
WorkingDirectory=/var/planet9

[Install] WantedBy=multi-user.target

Option 2: Use a terminal multiplexer

You can use a terminal multiplex, for example, screen or tmux. To install tmux on Linux, type the following:

sudo yum install tmux

How to use tmux on Linux:

  1. Start tmux on your computer.

  2. Start Neptune DXP - Open Edition. From this point on, even if you are disconnected from the server, Neptune DXP - Open Edition continues to run.

  3. After you started Neptune DXP - Open Edition, disconnect from tmux: Type c-b d (or c- space d). 'd' stands for disconnect.

  4. The next time you connect to Neptune DXP - Open Edition and want to continue where you left, start the server and type tmux ls. You see the running tmux sessions and type tmux attach to it.

You can run Neptune DXP - Open Edition without performing above steps. As soon as you lose the connection to the remote system, the parent process stops and only the forked system processes continue running. This means that you cannot see the system processes running inside Neptune DXP - Open Edition.