Manual Deployment
This series describes a native installation of qOntology on Ubuntu 22.04 x86_64, with services managed by systemd. It is intended for operators who can use Linux commands, edit configuration files, and investigate service logs.
Deployment workflow
This section contains 1 index page and 5 content pages. For a first installation, follow this sequence:
| Step | Page | Result |
|---|---|---|
| 1 | Environment setup | Java runtimes, plus Maven and Node.js build tools where needed |
| 2 | Database and middleware deployment | Accessible MySQL, Redis, Neo4j, and file preview services |
| 3 | Data initialization | Initialized business database, application account, and graph connection |
| 4 | Application build | Backend JAR and frontend dist directory |
| 5 | qOntology service deployment | Backend service, Nginx entry point, and end-to-end access checks |
You may skip step 4 when using prebuilt artifacts from the same release. Maven and Node.js are needed only on build machines; building kkFileView from source also requires Java 17 on the build machine. The qOntology API, Neo4j, and kkFileView runtime servers also use JDK 17.
Services and baseline
| Service | Example used here | Responsibility |
|---|---|---|
| Nginx | Ubuntu repository version, entry port 8897 | Static frontend resources and API/file preview proxying |
| qOntology API | Java 17, port 8097 | Business APIs, permissions, and ontology processing |
| MySQL | 5.7.44, port 3306 | Relational business data |
| Redis | 6.x, port 6379 | Caches and session-related data |
| Neo4j Community | 4.4.40, Java 17, ports 7474/7687 | Graph storage and queries |
| kkFileView | 4.4.0, Java 17, port 8012 | File conversion and previews |
This series follows the project's MySQL 5.7 and Neo4j 4.4 configuration baseline. kkFileView is pinned to 4.4.0 so native installation steps can be checked; latest in the project's Compose configuration does not identify this version. These are tutorial examples, not certification of complete-system compatibility or capacity. Evaluate support lifecycles and upgrade compatibility of older components separately when selecting production versions.
AI models and persistent vector services are optional integrations outside these six services. The default example uses temporary in-memory vector storage. Configure a persistent vector service separately if vector data must survive restarts.
Directories and access conventions
/opt/qontology/
├── server/ # qontology-server.jar
├── config/ # External overrides in deploy.yml
└── web/ # Files from the frontend dist directory
/var/lib/qontology/
└── upload/ # Uploaded files
/var/log/qontology/ # Backend logsDatabases and the preview service use separate data directories. Browsers access http://<SERVER_IP>:8897. In this single-server example, the database, cache, graph database, and API listen only on loopback addresses. When moving to multiple hosts, update listening addresses, connection addresses, and network access rules together.
Replace <SERVER_IP>, <RELEASE_TAG_OR_COMMIT>, and <..._PASSWORD> with real values. Run commands from the directory specified before each code block. Use sudoedit to edit files; configuration snippets are file contents, not Shell commands.
First installation only
This series targets new environments. Initialization SQL contains DROP TABLE statements and must not be replayed directly against an existing business database. The application, initialization files, and configuration must come from the same release. For upgrades, back up first and use the corresponding upgrade scripts.
This is a single-server deployment without multi-replica high availability or automatic scaling. See server resource specifications for capacity planning and deployment architecture for component relationships; that diagram shows the Docker Compose deployment boundary. For containers, follow Docker Compose deployment.
The page organization follows the qData manual deployment tutorial; components, commands, and paths are adapted to qOntology.