Environment Setup

This is step 1 of manual deployment, using Ubuntu 22.04 x86_64. These operations require sudo privileges and network access to official software repositories. Package names cannot be applied directly to other distributions or ARM hosts.

Version requirements

Component	Example version	Purpose and installation host
OpenJDK	17	qOntology API, Neo4j, and kkFileView servers; backend and kkFileView build machines
Maven	3.9.x	Required to build the backend or kkFileView
Node.js	22.x	Frontend build machine only
npm	Bundled with Node.js	Install frontend dependencies and run builds

This tutorial uses JDK 17 for the qOntology API, Neo4j, and kkFileView, as well as backend and kkFileView source builds. The backend POM specifies Java 17. Explicitly set the Java 17 path when starting services rather than relying on the global default. The frontend uses Vite 5, and this tutorial standardizes on Node.js 22. Vite 5 requirements

1. System preparation

1.1. Check the system and resources

Run on the deployment host:

# Check the operating system and CPU architecture
cat /etc/os-release
uname -m

# Check available memory, disk space, and listening ports
free -h
df -h / /opt /var
sudo ss -lntp

Confirm Ubuntu 22.04 and an architecture output of x86_64. Reserve disk and memory according to the resource specifications. Check that ports 8897, 8097, 3306, 6379, 7474, 7687, and 8012 are not used by other instances.

1.2. Install basic tools

# Update package metadata and install download, archive, and certificate tools
sudo apt update
sudo apt install -y ca-certificates curl wget git tar unzip xz-utils fontconfig

# Create and enter the download directory for this deployment
mkdir -p "$HOME/qontology-packages"
cd "$HOME/qontology-packages"

Save subsequent downloads here. After downloading official archives, verify SHA256 or SHA512 against the checksum file on the download page. Do not use packages for another architecture.

2. JDK 17

2.1. Install

# Install Java 17 and verify runtime/compiler versions using absolute paths
sudo apt install -y openjdk-17-jdk
/usr/lib/jvm/java-17-openjdk-amd64/bin/java -version
/usr/lib/jvm/java-17-openjdk-amd64/bin/javac -version

2.2. Configure the current user's build environment

Add the following once to the build user's ~/.profile:

export JAVA_HOME=/usr/lib/jvm/java-17-openjdk-amd64
export PATH="$JAVA_HOME/bin:$PATH"

Apply it to the current Bash session and check:

source "$HOME/.profile"
java -version
javac -version

Both commands should report major version 17. Java 17 does not require JDK 8's JRE_HOME or a manually configured CLASSPATH. systemd does not read the user's ~/.profile; later service files explicitly specify the Java executable.

3. Maven

Run this section only on the build machine. On the Apache Maven download page, choose the 3.9.x binary tar.gz and its checksum file, not Maven 4 or a source archive.

3.1. Download and extract

Place the download in ~/qontology-packages and replace the filename below with the actual 3.9.x version. The variable refers only to this downloaded archive:

# Select the actual Maven archive and check that it exists
cd "$HOME/qontology-packages"
MAVEN_ARCHIVE='apache-maven-3.9.x-bin.tar.gz'
test -f "$MAVEN_ARCHIVE"

# Extract into the installation directory, removing the outermost archive directory
sudo install -d /opt/maven
sudo tar -xzf "$MAVEN_ARCHIVE" -C /opt/maven --strip-components=1

These paths are for a first installation. If /opt/maven already exists, check its version first; do not mix new files with an old installation.

3.2. Configure and verify

Add once to ~/.profile:

export MAVEN_HOME=/opt/maven
export PATH="$MAVEN_HOME/bin:$PATH"

source "$HOME/.profile"
mvn -version

Confirm Maven 3.9.x, Java 17, and a Java home pointing to the Java 17 installation. See the official Maven installation guide.

4. Node.js and npm

Run this section only on the frontend build machine. On the official Node.js download page, choose the 22.x Linux x64 tar.xz binary archive and its matching SHASUMS256.txt. Do not use another major version just because it is displayed by default.

4.1. Extract

Place the archive and checksum file in ~/qontology-packages, and substitute the actual filename:

# Select the actual Node.js archive and verify its SHA256 checksum
cd "$HOME/qontology-packages"
NODE_ARCHIVE='node-v22.x.y-linux-x64.tar.xz'
grep " $NODE_ARCHIVE\$" SHASUMS256.txt | sha256sum -c -

# After verification, extract into the installation directory without the outermost directory
sudo install -d /opt/node22
sudo tar -xJf "$NODE_ARCHIVE" -C /opt/node22 --strip-components=1

If the checksum fails or no matching entry is found, stop and check the files before extracting. /opt/node22 should also be an empty directory for this first installation.

4.2. Environment variables and verification

Add once to ~/.profile:

export PATH="/opt/node22/bin:$PATH"

source "$HOME/.profile"
node -v
npm -v

Node.js should report v22.*, and npm should print a version number. There is no need to install npm, Vue CLI, or Vite globally. Project dependencies are installed in the application build step.

5. Environment checklist

Check	Expected result
Run java -version using the absolute Java 17 path	Version 17, for the qOntology API, Neo4j, and kkFileView
Run mvn -version on the build machine	Maven 3.9.x, Java 17
Run node -v and npm -v on the frontend build machine	Node.js 22.x and a working npm
Disk and listening ports	Sufficient space and no conflicts on planned ports

This completes basic environment preparation; it does not mean that the databases or application are running. Next: database and middleware deployment.