Run Locally from Source

This page explains running qOntology locally from source for integration testing and daily development. Prepare the environment, start middleware, configure the backend, and start the frontend in order, then access the system in a browser.

Startup approach used here

MySQL, Redis, Neo4j, and kkFileView run in Docker. The qOntology backend runs in IntelliJ IDEA, and the frontend uses Vite's development server. All services run on one development machine; containerized API and Nginx are not needed.

To deploy the complete system directly, see Docker Compose deployment. For a native server installation, see manual deployment.

1. Prerequisites

1.1. Prepare the development environment

Install Git, IntelliJ IDEA, and the tools in the version table below. Reserve memory and disk space for containers, IDEA, Java, and frontend builds. Docker Desktop's resource allocation must also cover middleware needs. See server resource specifications for server capacity planning.

OS	Docker environment and commands
Linux	Install Docker Engine and the Compose plugin; ensure the current user can connect to the engine
macOS	Install Docker Desktop for Intel or Apple Silicon and wait for the engine to become ready
Windows	Install and start Docker Desktop using Linux containers; execute commands in PowerShell

On ARM devices such as Apple Silicon, confirm that every image supports the architecture, especially the repository's MySQL 5.7 image. If architectures do not match, use a compatible x86_64 development environment or validate adapted images first. Do not simply replace the database's major version.

1.2. Check Docker

docker version
docker compose version
docker info

Confirm both Docker Client and Server are reachable and Compose is 2.23.2 or later. This page uses the spaced docker compose command. The stack uses include, so legacy docker-compose usage cannot be copied directly.

2. Version requirements

The following tool versions are used here. Java matches the source root's pom.xml; Maven and Node.js follow the recommended versions in the application build guide.

Component	Version or requirement
JDK	17
Maven	3.9.x recommended
Node.js	22.x recommended
npm	Version bundled with Node.js
Git	Can clone the project repository
Docker	Can run the Linux images required by the repository
Docker Compose	2.23.2 or later

Check in a terminal:

java -version
mvn -version
node -v
npm -v
git --version

Both java -version and mvn -version must report Java 17. Select JDK 17 for IDEA's Project SDK, Maven import, and backend runtime so the terminal, IDEA, Maven, and backend all use JDK 17.

3. Clone qOntology

git clone https://gitee.com/qiantongtech/qOntology.git
cd qOntology
git rev-parse HEAD

If source code already exists, enter its root and record the current commit. For a specific version, switch to its release tag or commit first. Use the same version for backend, frontend, configuration, and initialization SQL.

Relevant directories:

qOntology/
├── pom.xml
├── docker/
│   ├── .env
│   ├── docker-compose.yml
│   ├── docker-compose-base.yml
│   ├── docker-compose-qontology.yml
│   └── qOntology/mysql/init/
│       ├── init-system.sql
│       └── init-show.sql
├── qontology-server/          # Backend entry module
├── qontology-framework/       # AI, file storage, graph database configuration, etc.
└── qontology-ui/              # Frontend project

“Source root” below means qOntology/ containing the top-level pom.xml, not the documentation site or qontology-server/.

4. Start middleware with Docker Compose

4.1. Check connection details

Middleware uses the repository's docker/ Compose files. Check .env and docker-compose-base.yml. Backend connections use host ports:

Middleware	Host address	Purpose
MySQL 5.7	127.0.0.1:33067	qontology database
Redis 6	127.0.0.1:63897	Cache; the backend uses logical database 3
Neo4j 4.4.40	bolt://127.0.0.1:17687	Graph database connection
Neo4j Browser	http://localhost:17474	Graph administration UI
kkFileView	http://localhost:8017/kkfileview/	File preview

Read the MySQL password from mysql57.environment.MYSQL_ROOT_PASSWORD in docker-compose-base.yml; Redis from REDIS_PASSWORD in .env; and Neo4j credentials from neo4j.environment.NEO4J_AUTH in username/password format. Fill the YAML placeholders below with actual local values before startup.

If passwords change, update service authentication and health checks together. Existing database passwords do not change automatically with initialization environment variables. If ports change, update backend connections or frontend proxies accordingly.

4.2. Start and check

From the source root, enter docker/ and run:

cd docker
docker compose -p qontology --profile base config -q
docker compose -p qontology --profile base up -d mysql57 redis neo4j kkfileview
docker compose -p qontology --profile base ps -a

This workflow explicitly selects four services. Do not omit their names and start the entire base profile: it also includes the containerized API and Nginx. The full deployment's all profile is not needed either.

The first run pulls images and initializes services. Wait until all four report healthy. Inspect logs if necessary:

docker compose -p qontology --profile base logs -f --tail=100 mysql57 redis neo4j kkfileview

Press Ctrl+C to leave log viewing without stopping containers. Resolve image-pull failures, repeated restarts, or failed health checks before starting the backend.

4.3. Confirm initial database setup

MySQL runs the mounted init-system.sql and init-show.sql automatically on its first startup with an empty data directory, creating system and business tables. Do not manually import another set of initialization scripts.

Open the database client from docker/ and enter the MySQL password when prompted:

docker compose -p qontology --profile base exec mysql57 mysql -uroot -p qontology

Inside MySQL, check:

SHOW TABLES;
SELECT COUNT(*) AS system_users FROM system_user;
EXIT;

Do not reinitialize an existing environment

Initialization SQL deletes and recreates tables. Existing data directories are not initialized again automatically. Do not fix routine connection errors by reimporting SQL, running reset scripts, or deleting volumes. Do not additionally import historical initialization files or all upgrade scripts.

Neo4j starts with the existing mounted directory. This workflow does not automatically restore demo graphs. An empty new graph is not a startup failure.

5. Configure and start the backend

5.1. Open the project in IDEA

Open the source root in IntelliJ IDEA, import the Maven project from the top-level pom.xml, and wait for dependency downloads. Confirm JDK 17 for both the project SDK and Maven.

The default backend HTTP port is 8099. Its main configuration is qontology-server/src/main/resources/application.yml, which imports server, AI, file storage, system, and graph settings for the active profile. Use dev locally.

5.2. Configure MySQL and Redis

Edit the existing corresponding nodes in qontology-server/src/main/resources/application-dev.yml, keeping other pool settings. Do not append a second spring: or mysql: node.

datasource:
  type: mysql

mysql:
  driver-class-name: com.mysql.cj.jdbc.Driver
  url: 'jdbc:mysql://127.0.0.1:33067/qontology?useUnicode=true&characterEncoding=utf8&useSSL=false&serverTimezone=Asia/Shanghai'
  username: root
  password: '<MYSQL_PASSWORD>'

spring:
  data:
    redis:
      host: 127.0.0.1
      port: 63897
      database: 3
      password: '<REDIS_PASSWORD>'

The existing spring.datasource.dynamic.datasource.master references the database configuration via datasource.type; retain those references. root here matches the repository's default local-development initialization. If an application account exists, use its credentials and verify access to qontology.

5.3. Configure Neo4j

Edit the existing nodes in qontology-framework/qontology-graphis/qontology-graphis-starter/src/main/resources/application-graphis-dev.yml:

graphis:
  type: neo4j

neo4j:
  uri: bolt://127.0.0.1:17687
  user: neo4j
  password: '<NEO4J_PASSWORD>'

This project uses top-level neo4j.* settings. Java runs on the host, so connect to mapped port 17687, not container port 7687.

5.4. Configure local file storage

Confirm the upload directory in application.yml:

qontology:
  profile: ${user.dir}/upload/

Check and edit the corresponding nodes in qontology-framework/qontology-file/src/main/resources/application-file-dev.yml:

dromara:
  x-file-storage:
    default-platform: local
    local-plus:
      - platform: local
        enable-storage: true
        enable-access: false
        domain: ''
        path-patterns: /**
        base-path: /
        storage-path: ${user.dir}/upload/

Set enable-storage to false in the existing aliyun-oss configuration to avoid loading unconfigured example OSS storage. ${user.dir} is the Java process working directory. Both upload paths must match, and the current user must have write permission.

5.5. Configure AI development mode

Edit existing nodes in qontology-framework/qontology-ai/src/main/resources/application-ai-dev.yml, retaining timeouts and other settings:

qontology:
  ai:
    enabled: true
    vector-store: memory

Start with in-memory vector storage locally; no extra Weaviate installation is needed. Vectors are lost when the backend restarts. For persistence, configure accessible Weaviate and authentication later. AI extraction and question answering also need real models, endpoints, and credentials in the application. Successful login alone does not prove AI works.

5.6. Build and start

Run from the source root; if still in docker/, run cd .. first. Keep this command on one line for Linux, macOS, and PowerShell:

mvn clean install -pl qontology-server -am -Ddocker.print.skip=true -Ddocker.build.skip=true -Ddocker.push.skip=true

-am builds required modules, and install installs artifacts in the local Maven repository. The three docker.*.skip flags skip Docker command printing, image builds, and pushes. For local integration work where test skipping is allowed, add -DskipTests; packaging success does not imply passing tests.

Create or check the IDEA run configuration:

Setting	Value
Module	qontology-server
Main class	tech.qiantong.qontology.server.QOntologyApplication
JRE	JDK 17
Working directory	Absolute path of the qOntology source root
Program arguments	--spring.profiles.active=dev --server.port=8099 --user.password.universalPassword=

The final argument clears the built-in universal login password; local login uses actual user passwords. The main-class file is qontology-server/src/main/java/tech/qiantong/qontology/server/QOntologyApplication.java.

After starting, confirm dev is active, port 8099 is listening, and there are no persistent database, Redis, or graph connection errors. Check the CAPTCHA endpoint:

curl -fsS http://127.0.0.1:8099/captchaImage

Use curl.exe in Windows PowerShell. The endpoint should return application JSON, not a connection failure or HTML error page.

6. Configure and start the frontend

6.1. Configure local environment variables

From the source root, enter the frontend project:

cd qontology-ui

Create .env.development.local with the following overrides for the repository's development examples:

VITE_APP_BASE_API=/dev-api
VITE_APP_AUTH_TYPE=client
VITE_APP_THIS_APP_URL=http://localhost:5173
VITE_APP_WEBSOCKET_API=ws://127.0.0.1:8099
VITE_APP_FILE_VIEW=/kkfileview
VITE_APP_MODE=development

client uses local login without the example centralized identity service. development avoids the repository's demo page mode. Do not store server-side secrets in VITE_* variables. Restart the frontend development server after changing environment variables.

6.2. Check development proxies

Edit server.proxy in qontology-ui/vite.config.js and check these three existing proxies. Preserve plugins, build settings, and other configuration; change only the corresponding proxy entries:

proxy: {
  '/dev-api': {
    target: 'http://127.0.0.1:8099',
    changeOrigin: true,
    rewrite: (p) => p.replace(/^\/dev-api/, '')
  },
  '/v3/api-docs': {
    target: 'http://127.0.0.1:8099',
    changeOrigin: true
  },
  '/kkfileview': {
    target: 'http://127.0.0.1:8017',
    changeOrigin: true
  }
}

The repository's preview proxy may still point to 28012; change it to the actual Compose mapping, 8017. kkFileView already uses context /kkfileview, so retain that prefix. /dev-api must remove its prefix before forwarding to the backend.

6.3. Install dependencies and start

Run in qontology-ui/:

npm install
npm run dev -- --port 5173 --strictPort

The current source has no frontend lockfile, so use npm install initially. If a later release supplies a valid package-lock.json, follow its process and use npm ci.

The command explicitly selects 5173, overriding the source default of port 80 and avoiding the local documentation server on 8080. --strictPort fails if occupied, preventing automatic port changes from making addresses inconsistent. Keep the terminal running and restart the server after proxy changes.

7. Access and verify qOntology

7.1. Log in and check basic functions

Open http://localhost:5173 in a browser.

Use credentials from initialization instructions or delivery records for the same release. Public demo-site credentials do not establish the local initial password. For forgotten passwords, follow the version's recovery procedure; do not execute another product's password-reset SQL.

You can also check the frontend proxy:

curl -fsS http://localhost:5173/dev-api/captchaImage

On Windows, use curl.exe. Expect the same type of application JSON as the backend CAPTCHA endpoint.

Check	Pass criteria
Login page	Page, styles, and CAPTCHA load correctly
Login and menus	Valid credentials load authorized menus and pages
Projects and ontologies	Create and query test projects and ontology data according to permissions
Graph database	Test graph reads/writes with your own data, without connection/authentication errors
WebSocket	Actual page requests to /websocket/ connect to 8099 and complete the handshake
Upload and download	A small upload returns an accessible file URL and downloads successfully
File preview	PDF and Office previews work after the network checks below
AI (optional)	Validate extraction, question answering, etc. after configuring real models and credentials

7.2. Check preview network access

The browser opens previews through Vite's /kkfileview proxy, but the kkFileView container downloads the original file. If the upload returns http://127.0.0.1:8099/profile/..., 127.0.0.1 refers to the container itself. Preview then fails even if the browser can download the file.

For preview integration testing:

1. Find the development machine's LAN IP and confirm both browser and Docker containers can reach port 8099 there. The backend must not listen only on loopback; allow only required development networks through the firewall.
2. Change Vite's /dev-api target to http://<DEV_LAN_IP>:8099, retaining changeOrigin: true. Upload logic derives file URLs from the request address, so new frontend uploads then use that host address.
3. Restart the frontend, upload a new test file, and check its URL contains the reachable host IP, port 8099, and /profile/. Previously stored loopback URLs do not update automatically.
4. Run the command below in the source's docker/ directory, replacing placeholders with the complete URL of the new file. Confirm a successful HTTP status before opening its preview.

docker compose -p qontology --profile base exec kkfileview curl -fI 'http://<DEV_LAN_IP>:8099/profile/<ACTUAL_FILE_PATH>'

Docker Desktop and containers configured with host-gateway in this repository can also reach the host via host.docker.internal for container-side diagnosis. Browser-facing file URLs must still resolve and be reachable from both browser and container. If the file endpoint needs authentication, handle authorization according to the preview mechanism; browser login alone does not establish container access.

8. Stop services and troubleshoot

Press Ctrl+C in the frontend terminal and stop the backend in IDEA. From docker/, stop and resume middleware with these commands, keeping containers and data:

docker compose -p qontology --profile base stop mysql57 redis neo4j kkfileview
docker compose -p qontology --profile base start mysql57 redis neo4j kkfileview

When resuming, confirm middleware health before starting backend and frontend. Do not use down -v or volume removal for routine shutdown.

Symptom	First checks
Compose does not support include	Check docker compose version and upgrade to the required version
Image pull or architecture errors	Network, registry permissions, CPU architecture, and supported platforms for images such as MySQL 5.7
Ports such as 33067/63897 occupied	Identify existing services; if remapping, update backend settings without changing container ports
MySQL connection fails or tables missing	mysql57 logs, database name, actual password, and initial execution of both SQL files
Redis authentication fails	Password in .env, backend password, logical database 3
Neo4j connection fails	neo4j.*, host Bolt port 17687, actual credentials
Java compile/startup fails	JDK 17 in terminal, IDEA, and Maven; the first compiler/startup exception
YAML changes not applied	Active dev, actual imported module file, rebuild and backend restart
Weaviate connection requested	vector-store set to memory in application-ai-dev.yml
Frontend port 5173 occupied	Stop only a confirmed unneeded process, or update startup port, application URL, and access URL together
CAPTCHA/API fails	Test port 8099 directly, then /dev-api target and prefix removal
WebSocket connects to 8080	WebSocket address in .env.development.local; restart Vite
Preview page fails or assets return 404	Proxy port 8017, /kkfileview prefix, container health
Download works but preview fails	Check the actual file URL from the container per 7.2; exclude loopback, authentication, and firewall issues
Upload fails or file missing	IDEA working directory, matching upload paths, write permissions

After confirming the basic development environment, connect real models, persistent vector storage, and other business services as needed. For artifacts to run on a server, continue with application build.