Docker Compose Deployment

Qiantong Technology11/1/26About 4 minDeploymentDocker ComposeOpen source edition

Before you begin

Intended audience

For users familiar with basic Docker commands who need to deploy qOntology open source on one server for the first time, or look up startup, shutdown, and troubleshooting commands.

Confirm before deployment

The host must reach the image registry, Docker must run Linux containers, and Compose must be 2.23.2 or later.
Use images, frontend files, SQL, and configuration from the same release. Images must match the host architecture. Reserve memory and disk for your data volume and concurrency.
This guide covers first deployment. Back up environments with existing business data and follow an upgrade plan instead.

This guide uses a complete deployment package containing preset environment variables, Docker Compose files, initialization SQL, application configuration, and prebuilt frontend resources. The default stack is MySQL, Redis, Neo4j, kkFileView, qOntology API, and Nginx.

Working directory

Unless stated otherwise, run commands in the extracted package's docker/ directory, retaining -p qontology --profile all. Existing installations must keep their original project name. Replace placeholders such as <SERVER_IP> and /path/to/.

Deployment workflow

Complete step 1 for your operating system, then follow the shared steps 2–4: download and extract the package, start services, and access the application.

Step 1: Install Docker and Docker Compose

Linux

Install Engine and the Compose plugin using the Docker Engine instructions for your distribution. Run in the deployment server's terminal:

docker version
docker compose version
docker info

Pass criteria: both Client and Server are reachable, and Compose ≥ 2.23.2. Check host memory, available disk space, and image architecture.

macOS

Install Docker Desktop for Mac, choosing the package for Intel or Apple Silicon. Start Docker and wait for the engine; Desktop includes Compose. Run in Terminal:

docker version
docker compose version
docker info

Pass criteria: both Client and Server are reachable, and Compose ≥ 2.23.2. Also check Docker Desktop resource limits and disk space.

Windows

Install Docker Desktop for Windows, follow its system setup wizard, and use Linux containers. Start Docker and wait for the engine; Desktop includes Compose. Open PowerShell and run:

docker version
docker compose version
docker info

Pass criteria: both Client and Server are reachable, and Compose ≥ 2.23.2. Also check Docker Desktop resource limits and disk space.

Step 2: Download and extract the deployment package

🔗 Deployment package URL: https://pan.baidu.com/s/1Lw8a4GX2G0m2c7u9CfAC9g
🔑 Download access code: Join the QQ group and find the code in the group files.
💬 QQ group entry: Join the QQ group

Download and extract the complete package to obtain the docker/ folder. This step applies to Linux, macOS, and Windows. Preserve the hidden .env file and the directory structure.

The deployment directory should contain the following; frontend resources are included:

docker/                              # Working directory for subsequent Compose commands
├── .env                             # Preset images, passwords, and ports
├── docker-compose.yml               # Main entry
├── docker-compose-base.yml          # Middleware and Nginx
├── docker-compose-qontology.yml     # API
└── qOntology/
    ├── mysql/                       # conf.d/my.cnf, init/*.sql
    ├── nginx/                       # dist/index.html, nginx.conf, sites/
    └── server/                      # application.yml, application-prod.yml, upload/

Step 3: Start qOntology

3.1. Enter the deployment directory

Linux / macOS: enter the extracted docker/ directory in a terminal, replacing the example path:

cd "/path/to/docker"

Windows: open the extracted docker folder in File Explorer, type powershell in its address bar, and press Enter to open a terminal there.

Confirm .env and docker-compose.yml exist in the current directory. Run subsequent commands there.

3.2. Start with default settings

The complete package normally needs no configuration edits before starting. Run in a terminal or PowerShell:

docker compose -p qontology --profile all up -d
docker compose -p qontology --profile all ps -a

First startup pulls missing images, creates containers, and runs initialization SQL against an empty MySQL data directory. Wait for downloads and initialization to finish; duration depends on the network and host.

3.3. Confirm readiness

The list should include mysql57, redis, neo4j, kkfileview, qontology-api, and nginx. Wait for middleware health checks to report healthy and for API/Nginx to remain running before step 4.

To inspect startup progress:

docker compose -p qontology --profile all logs -f --tail=200 qontology-api nginx

API logs should indicate completed startup without persistent connection or authentication errors. Press Ctrl+C to leave log viewing; containers keep running. Up alone does not prove readiness. See troubleshooting if startup keeps failing.

Initialization is for new environments only

Existing data directories do not automatically rerun initialization SQL. Do not reimport initialization SQL into a business database or run reset.sh, which can reset business data.

Step 4: Access qOntology

Deployment complete: access the system

URL: http://<SERVER_IP>:8897
Initial account: qOntology
Initial password: qOntology123

On the deployment host itself, replace <SERVER_IP> with localhost. Credentials depend on the package's actual initialization version. Use your configured port if changed, and change the password after first login.

You can also check the home page and CAPTCHA endpoint from the server:

curl -I http://127.0.0.1:8897/
curl -fsS http://127.0.0.1:8897/prod-api/captchaImage

In Windows PowerShell, use curl.exe instead of curl. The home page should return normally, and the CAPTCHA endpoint should return application JSON.

After login, complete these checks:

Check	Pass criteria
Login and project management	Log in, open menus, and create/query test projects according to permissions
Upload, download, and preview	A small uploaded file can be found, downloaded, and previewed through `/kkfileview/`
Graphs (optional)	Verify reads/writes with your own test data; this workflow does not restore `neo4j-init` sample graphs automatically
AI (optional)	Calls succeed with valid models and credentials; verify vector storage/retrieval separately when enabled

Common operations commands

# Status and logs; replace service names with mysql57, redis, neo4j, etc. as needed
docker compose -p qontology --profile all ps -a
docker compose -p qontology --profile all logs --tail=200 qontology-api nginx
# Routine stop/start, retaining containers and data
docker compose -p qontology --profile all stop
docker compose -p qontology --profile all start

After changing .env or Compose environment variables, restart does not apply the new configuration. Recreate affected services. For an API-only change:

docker compose -p qontology --profile all up -d --no-deps --force-recreate qontology-api
docker compose -p qontology --profile all exec nginx nginx -t
docker compose -p qontology --profile all exec nginx nginx -s reload

Back up databases, graph data, uploaded files, and configuration before upgrades. Do not run down -v or remove volumes before confirming data mounts and backups. Use stop for routine shutdown.

Troubleshooting

Symptom	Checks
Compose missing or `include` unsupported	Check plugin installation/version; validate with `docker compose -p qontology --profile all config -q`
Image pull fails	Check registry permissions, name, tag, and architecture; do not substitute an unrelated version
Middleware `unhealthy`	Inspect its logs; after password changes, compare server authentication, API settings, and health checks
Blank page, 403, 502	Confirm `qOntology/nginx/dist/index.html` exists; check API logs per section 3.3 and Nginx with `docker compose -p qontology --profile all exec nginx nginx -t`
`host not found in upstream`	Confirm API and kkFileView readiness; if Nginx errors persist, run `docker compose -p qontology --profile all restart nginx` and retry
Accessible only from the server itself	Check the entry port, firewall, cloud security groups, and client network
Upload succeeds but preview fails	Check kkFileView health, frontend preview URL, and file URL reachability from containers; `127.0.0.1` inside a container refers to that container
AI/graph settings not applied	Verify actual loaded configuration paths and environment variables