Database and Middleware Deployment

After environment setup, follow this page on the Ubuntu 22.04 x86_64 deployment host. This page only installs services; qOntology business data is imported on the next page. Replace every <..._PASSWORD> and <SERVER_IP> placeholder.

This single-server example exposes Nginx on port 8897 as the entry point; middleware listens on 127.0.0.1. Users, installation paths, and data directories below assume a new environment. If a service or data already exists, check the instance before proceeding; do not reinitialize it.

1. MySQL 5.7.44

1.1. Obtain the package and dependencies

From the official MySQL archives, select 5.7.44, Linux Generic, x86_64, glibc 2.12 binaries, and upload to ~/qontology-packages. The example filename is mysql-5.7.44-linux-glibc2.12-x86_64.tar.gz. If yours differs, adjust the name and runtime libraries to match. Do not substitute Ubuntu's default apt install mysql-server.

# Update package metadata and install the MySQL binary's runtime libraries
sudo apt update
sudo apt install -y libaio1 libnuma1 libncurses5 libtinfo5

# Create the service user and installation directory, then extract the package
sudo useradd --system --user-group --home-dir /var/lib/mysql57 --shell /usr/sbin/nologin mysql57
sudo install -d /opt/mysql57
cd "$HOME/qontology-packages"
sudo tar -xzf mysql-5.7.44-linux-glibc2.12-x86_64.tar.gz -C /opt/mysql57 --strip-components=1

# Create writable data and log directories for the database service user
sudo install -d -o mysql57 -g mysql57 -m 750 /var/lib/mysql57 /var/log/mysql57

# Check the MySQL version and shared libraries for missing dependencies
/opt/mysql57/bin/mysqld --version
ldd /opt/mysql57/bin/mysqld

Expect version 5.7.44 and no not found entries from ldd. Install the actual missing compatible libraries; do not force symlinks between libraries with different ABIs. Reference: MySQL generic binary installation.

1.2. Configure and initialize for the first time

Run sudoedit /etc/mysql57.cnf and write:

[mysqld]
user=mysql57
basedir=/opt/mysql57
datadir=/var/lib/mysql57
port=3306
bind-address=127.0.0.1
socket=/var/lib/mysql57/mysql.sock
pid-file=/var/lib/mysql57/mysql.pid
log-error=/var/log/mysql57/error.log
character-set-server=utf8mb4
collation-server=utf8mb4_general_ci
explicit_defaults_for_timestamp=1

[client]
socket=/var/lib/mysql57/mysql.sock
default-character-set=utf8mb4

Run once, only when the data directory is empty:

sudo /opt/mysql57/bin/mysqld --defaults-file=/etc/mysql57.cnf --initialize --user=mysql57
sudo grep 'temporary password' /var/log/mysql57/error.log

Record the locally generated temporary root password and change it at the first login in the next step. Do not paste this log or password into public issue reports.

1.3. Configure systemd

Run sudoedit /etc/systemd/system/mysql57.service:

[Unit]
Description=MySQL 5.7 for qOntology
After=network.target

[Service]
Type=simple
User=mysql57
Group=mysql57
ExecStart=/opt/mysql57/bin/mysqld --defaults-file=/etc/mysql57.cnf
Restart=on-failure
TimeoutStopSec=300
LimitNOFILE=65535

[Install]
WantedBy=multi-user.target

# Load the service definition, start MySQL, and enable startup at boot
sudo systemctl daemon-reload
sudo systemctl enable --now mysql57

# Check service status, then log in with the temporary password to change it
sudo systemctl status mysql57 --no-pager
MYSQL_HISTFILE=/dev/null /opt/mysql57/bin/mysql --defaults-file=/etc/mysql57.cnf -uroot -p --connect-expired-password

After logging in with the temporary password, replace the new password below and execute. Escape single quotes according to SQL string rules if the password contains them:

ALTER USER 'root'@'localhost' IDENTIFIED BY '<MYSQL_ADMIN_PASSWORD>';
SELECT VERSION();
EXIT;

The application account is created during data initialization. The API does not connect as root.

2. Redis 6.x

2.1. Install and configure

# Install Redis and check its version
sudo apt install -y redis-server
redis-server --version

# Edit listening addresses, authentication, and persistence settings
sudoedit /etc/redis/redis.conf

Confirm version 6.x. Edit the existing settings in the file instead of appending duplicates:

bind 127.0.0.1 ::1
protected-mode yes
port 6379
requirepass <REDIS_PASSWORD>
dir /var/lib/redis
appendonly yes

For passwords containing spaces or special characters, use double quotes and escaping according to Redis configuration rules. Keep the package's systemd, logging, and process-management configuration. The Redis user owns the data directory. AOF provides persistence; backup storage still needs separate planning.

2.2. Start and verify

# Enable startup at boot and restart Redis to apply configuration
sudo systemctl enable redis-server
sudo systemctl restart redis-server

# Check service status and test the connection with password authentication
sudo systemctl status redis-server --no-pager
redis-cli -h 127.0.0.1 -p 6379 --askpass PING

Enter the password when prompted; expect PONG. qOntology uses Redis logical database 3; keep later settings consistent. On failure, check journalctl -u redis-server and /var/log/redis/redis-server.log.

3. Neo4j Community 4.4.40

3.1. Download and prepare directories

Select the Community 4.4.40 Linux tar archive from Neo4j releases, or use its official distribution URL:

# Enter the download directory and obtain the specified Neo4j release
cd "$HOME/qontology-packages"
curl -fLO https://dist.neo4j.org/neo4j-community-4.4.40-unix.tar.gz

# Create the service user and installation directory, then extract
sudo useradd --system --user-group --home-dir /var/lib/neo4j --shell /usr/sbin/nologin neo4j
sudo install -d /opt/neo4j
sudo tar -xzf neo4j-community-4.4.40-unix.tar.gz -C /opt/neo4j --strip-components=1

# Prepare data, log, and runtime directories writable by the service user
sudo install -d -o neo4j -g neo4j -m 750 /var/lib/neo4j /var/log/neo4j /opt/neo4j/run
sudo chown -R neo4j:neo4j /opt/neo4j/run

3.2. Configure Java, data paths, and connections

Run sudoedit /opt/neo4j/conf/neo4j.conf and update the existing settings:

dbms.directories.data=/var/lib/neo4j
dbms.directories.logs=/var/log/neo4j
dbms.directories.run=/opt/neo4j/run
dbms.default_listen_address=127.0.0.1
dbms.default_advertised_address=127.0.0.1
dbms.connector.bolt.enabled=true
dbms.connector.bolt.listen_address=:7687
dbms.connector.http.enabled=true
dbms.connector.http.listen_address=:7474
dbms.connector.https.enabled=false
dbms.memory.heap.initial_size=512m
dbms.memory.heap.max_size=2G
dbms.memory.pagecache.size=1G

Memory values are initial examples; adjust them to available host memory and graph size. Do not allocate all host memory to each service. Set the password before the first startup, using Bash:

# Read the initial password without echoing input
read -rsp 'Neo4j initial password: ' NEO4J_INITIAL_PASSWORD
printf '\n'

# Set the new database password using Java 17, then clear the temporary variable
sudo -u neo4j env JAVA_HOME=/usr/lib/jvm/java-17-openjdk-amd64 \
  /opt/neo4j/bin/neo4j-admin set-initial-password "$NEO4J_INITIAL_PASSWORD"
unset NEO4J_INITIAL_PASSWORD

This operation is for a new database, not for resetting an existing database password.

3.3. Service management and verification

Run sudoedit /etc/systemd/system/neo4j.service:

[Unit]
Description=Neo4j for qOntology
After=network.target

[Service]
Type=simple
User=neo4j
Group=neo4j
Environment=JAVA_HOME=/usr/lib/jvm/java-17-openjdk-amd64
WorkingDirectory=/opt/neo4j
ExecStart=/opt/neo4j/bin/neo4j console
Restart=on-failure
LimitNOFILE=60000
TimeoutStopSec=120

[Install]
WantedBy=multi-user.target

# Load the service definition, start Neo4j, and enable startup at boot
sudo systemctl daemon-reload
sudo systemctl enable --now neo4j

# Check service status and open the graph query terminal with Java 17
sudo systemctl status neo4j --no-pager
JAVA_HOME=/usr/lib/jvm/java-17-openjdk-amd64 \
  /opt/neo4j/bin/cypher-shell -a bolt://127.0.0.1:7687 -u neo4j

After entering the password, execute RETURN 1;; expect 1. Exit with :exit. To check HTTP, run curl -I http://127.0.0.1:7474/ on the server. Do not temporarily expose the graph database to the public Internet just for remote access.

4. kkFileView 4.4.0

4.1. Obtain a fixed-version artifact

Use a Linux distribution package from the official kkFileView 4.4.0 release. If no binary is directly available, build from source on a machine with Maven as shown below. The build requires access to the project's dependency repositories:

# Obtain kkFileView 4.4.0 source and enter the project directory
git clone --branch v4.4.0 --depth 1 https://github.com/kekingcn/kkFileView.git kkFileView-4.4.0
cd kkFileView-4.4.0

# Build with Java 17, skipping test execution
env JAVA_HOME=/usr/lib/jvm/java-17-openjdk-amd64 \
  PATH="/usr/lib/jvm/java-17-openjdk-amd64/bin:$PATH" \
  mvn clean package -DskipTests

# Check the artifact and configuration file from this version
test -f server/target/kkFileView-4.4.0.jar
test -f server/src/main/config/application.properties

-DskipTests skips test execution; a successful build does not mean tests passed. Upload this JAR and application.properties from the same tag to ~/qontology-packages/kkfileview/ on the server. With a distribution package, take the files from its extracted bin/ and config/ directories and place them in that staging directory. Do not mix in 5.x configuration.

4.2. Install Office and service files

# Install Office conversion components and CJK fonts, then check the Office version
sudo apt install -y libreoffice fonts-noto-cjk
libreoffice --version

# Create the service user and installation, data, and log directories
sudo useradd --system --user-group --home-dir /var/lib/kkfileview --shell /usr/sbin/nologin kkfileview
sudo install -d /opt/kkfileview/bin /opt/kkfileview/config
sudo install -d -o kkfileview -g kkfileview -m 750 /var/lib/kkfileview /var/lib/kkfileview/files /var/log/kkfileview

# Install the JAR and configuration, then edit preview settings
sudo install -m 644 "$HOME/qontology-packages/kkfileview/kkFileView-4.4.0.jar" /opt/kkfileview/bin/
sudo install -o root -g kkfileview -m 640 "$HOME/qontology-packages/kkfileview/application.properties" /opt/kkfileview/config/
sudoedit /opt/kkfileview/config/application.properties

Update the corresponding existing settings, retaining the rest of the 4.4.0 file:

server.port=8012
server.address=127.0.0.1
server.servlet.context-path=/kkfileview
office.home=/usr/lib/libreoffice
file.dir=/var/lib/kkfileview/files/
cache.type=jdk
base.url=http://<SERVER_IP>:8897/kkfileview/
trust.host=<SERVER_IP>
file.upload.disable=true

Set trust.host to the hostname or IP actually used in the browser, without protocol or port. Separate multiple domains with commas according to this version's rules. The restriction must match the file sources. This setup retains in-application previews and disables the standalone upload feature on the kkFileView home page. Restart after changing base.url or the context path. 4.4.0 configuration definitions

4.3. Configure systemd and start

Run sudoedit /etc/systemd/system/kkfileview.service:

[Unit]
Description=kkFileView for qOntology
After=network.target

[Service]
Type=simple
User=kkfileview
Group=kkfileview
Environment=JAVA_HOME=/usr/lib/jvm/java-17-openjdk-amd64
Environment=HOME=/var/lib/kkfileview
Environment=KKFILEVIEW_BIN_FOLDER=/opt/kkfileview/bin
WorkingDirectory=/opt/kkfileview/bin
ExecStart=/usr/lib/jvm/java-17-openjdk-amd64/bin/java -Xms512m -Xmx1024m -Dfile.encoding=UTF-8 -Dspring.config.location=/opt/kkfileview/config/application.properties -jar /opt/kkfileview/bin/kkFileView-4.4.0.jar
Restart=on-failure
TimeoutStopSec=120

[Install]
WantedBy=multi-user.target

# Load the service definition, start previews, and enable startup at boot
sudo systemctl daemon-reload
sudo systemctl enable --now kkfileview

# Check service status, initialization logs, and the HTTP response
sudo systemctl status kkfileview --no-pager
sudo journalctl -u kkfileview -n 100 --no-pager
curl -I http://127.0.0.1:8012/kkfileview/

Office may take longer on its first startup. At this stage, check only service responses and conversion-process initialization. Verify complete Office/PDF previews after deploying Nginx and the application. The Java heap limit excludes memory used by LibreOffice child processes.

5. Middleware checklist

Service	Check	Expected result
MySQL	Run SELECT VERSION(); after login	5.7.44, working administrator authentication
Redis	redis-cli --askpass PING	PONG
Neo4j	Run RETURN 1; in cypher-shell	Returns 1
kkFileView	Request /kkfileview/ and inspect journal	HTTP responds; Office initializes without errors

Use sudo ss -lntp to check listening addresses and ports. Stop with sudo systemctl stop <SERVICE_NAME> and restart with sudo systemctl restart <SERVICE_NAME>. MySQL error logs are in /var/log/mysql57/; Neo4j logs are in /var/log/neo4j/; journal collects kkFileView console output.

Next: data initialization.