Application Build

Run this page on the build machine, using Java 17, Maven 3.9.x, and Node.js 22.x from environment setup. Build and runtime hosts can be separate. If you already have matching JAR and frontend artifacts, proceed to qOntology service deployment.

1. Obtain source code from the same release

# Clone the source and enter the project directory
git clone https://gitee.com/qiantongtech/qOntology.git
cd qOntology

# Select the actual release and record the build commit
git checkout '<RELEASE_TAG_OR_COMMIT>'
git rev-parse HEAD

Replace <RELEASE_TAG_OR_COMMIT> with the actual release. Record the commit, and obtain the initialization SQL, external configuration reference, backend, and frontend from that version. If the source directory already exists, enter it and verify the version instead of cloning again.

# Select Java 17 and build tool paths for this terminal
export JAVA_HOME=/usr/lib/jvm/java-17-openjdk-amd64
export PATH="$JAVA_HOME/bin:/opt/maven/bin:/opt/node22/bin:$PATH"

# Check Java, Maven, Node.js, and npm versions
java -version
mvn -version
node -v
npm -v

Expect Java 17, Maven 3.9.x, and Node.js 22.x. Frontend dependencies require access to the npm registry; backend dependencies require access to the Maven repositories defined in the POM.

2. Build the backend

2.1. Package the application

Run from the qOntology source root containing the top-level pom.xml:

# Build the backend and dependencies, skipping Docker command printing, image build, and push
mvn clean package -pl qontology-server -am \
  -Ddocker.print.skip=true \
  -Ddocker.build.skip=true \
  -Ddocker.push.skip=true

-am also builds required modules. The POM includes Docker-related tasks, so native deployment explicitly skips command printing, image builds, and pushes. Docker installation or login is not required.

If the release process explicitly permits skipping test execution, use the following command. A successful result means packaging succeeded, not that tests passed:

# Use only when skipping test execution is permitted; still skip all Docker tasks
mvn clean package -pl qontology-server -am -DskipTests \
  -Ddocker.print.skip=true \
  -Ddocker.build.skip=true \
  -Ddocker.push.skip=true

For dependency download or compilation errors, check the error logs and release version first. Do not bypass the problem by arbitrarily changing dependency versions.

2.2. Check the backend artifact

# Check that the JAR is nonempty and contains Spring Boot application content
test -s qontology-server/target/qontology-server.jar
jar tf qontology-server/target/qontology-server.jar | grep -E 'BOOT-INF/(classes|lib)' | head

The deployment artifact is qontology-server/target/qontology-server.jar. Do not select .original, a source archive, or an ordinary JAR from a business module. The next page explicitly overrides startup settings and port 8097, without relying on the source's development port.

3. Build the frontend

3.1. Check production configuration

Enter qontology-ui and edit .env.production.local. This file overrides settings for this production build, without changing shared environment files:

cd qontology-ui

Write the following, replacing the server IP before saving:

VITE_APP_BASE_API=/prod-api/
VITE_APP_FILE_VIEW=/kkfileview
VITE_APP_AUTH_TYPE=local
VITE_APP_THIS_APP_URL=http://<SERVER_IP>:8897

This series uses local login. The current frontend uses single sign-on only when VITE_APP_AUTH_TYPE=sso. VITE_APP_SERVER_URL and VITE_APP_CLIENTID are SSO settings; do not treat the example authentication server as the API address. Configure a real authentication service and callback URL separately if SSO is needed.

VITE_APP_FILE_VIEW=/kkfileview uses the current site's same-origin preview proxy. Frontend environment variables are embedded at build time; rebuild after changing the server address or authentication mode. Never store server-side secrets in VITE_* variables.

3.2. Install dependencies and build

The inspected source has no frontend lockfile. Use:

# Install project dependencies and build the production frontend
npm install
npm run build:prod

# Check the generated frontend entry file
test -s dist/index.html

Keep the generated lockfile and build records for reproducibility. If a later release includes a valid package-lock.json, use npm ci according to that release's process. Do not run npm ci without a lockfile; a global Vite installation is also unnecessary.

Deliver the entire qontology-ui/dist/ output. Production servers serve these static files through Nginx; do not use npm run dev or Vite preview as the production entry point.

4. Prepare deployment files

Source file or directory	Server location	Notes
qontology-server/target/qontology-server.jar	/opt/qontology/server/qontology-server.jar	Executable backend JAR
All files inside qontology-ui/dist/	/opt/qontology/web/	index.html sits directly under web
Initialization SQL from the same release	Staging directory for first-time initialization	Keep outside the Web root
deploy.yml written on the next page	/opt/qontology/config/deploy.yml	Overrides for native deployment

Upload the JAR to ~/qontology-release/qontology-server.jar on the server, and the contents of dist to ~/qontology-release/web/. The next page installs from this staging directory.

Record the release commit, build tool versions, whether tests were run, and checksums. From the source root, calculate checksums for the backend and frontend entry point:

sha256sum qontology-server/target/qontology-server.jar qontology-ui/dist/index.html

Do not replace this workflow with the repository's one-click release scripts; they may build or push images.

Next: qOntology service deployment.