Docker Compose Deployment

Qiantong Tech9/16/25About 4 minInstallation and DeploymentOne-click StartupQuick Start

Tutorial Video

qData open-source edition quick deployment tutorial (Docker Compose method)

Important

If you encounter environment configuration issues or task execution exceptions during deployment, we recommend watching the official qData Data Platform troubleshooting video collection.
This video series explains common troubleshooting methods and covers typical scenarios such as task failures, failure to add or run tasks, and no task instances, helping you quickly locate and resolve issues.

👉 Watch the troubleshooting video collection

Before You Start

Who should read this guide?

People trying qData for the first time who want to experience the features quickly
People who do not want to wrestle with complex environment configuration or frontend packaging
Users who want to experience the complete platform with a simple "one-click startup" flow

We have prepared a complete ready-to-use deployment package for you, including:

✅ Frontend static assets (the packaged dist folder)
✅ DolphinScheduler scheduler (no extra installation required)
✅ Complete Hadoop stack (HDFS + YARN)
✅ Spark 3.5.6 (already extracted)
✅ Preset .env environment variable file
✅ Complete directory structure and image package (no manual download required)

There is no need to manually install a pile of dependencies, build the frontend, or handle complex configuration. Just extract the package and run the scripts, and the whole big data platform plus qData can start running.
Even with zero prior experience, you can get started easily and experience qData in 10 minutes.

Step 1: Install Docker and Docker Compose

qData runs in Docker containers, so Docker and Docker Compose must be installed first.

Recommended versions:
- Docker: ≥ v19.03
- Docker Compose: ≥ v2.20.2

🖥️ Windows / macOS

Download and install Docker Desktop directly.
After installation, Docker Compose is included automatically and no extra installation is required.

🐧 Linux (Ubuntu 18.04+)

The deployment package already includes offline installation packages and an installation script, so you can run them directly:

# Enter the Docker installation package directory
cd ~/qData/docker-install

# Install Docker components
sudo dpkg -i containerd.io_1.6.9-1_amd64.deb docker-ce_24.0.7-1~ubuntu.20.04~focal_amd64.deb docker-ce-cli_24.0.7-1~ubuntu.20.04~focal_amd64.deb docker-compose-plugin_2.6.0~ubuntu-focal_amd64.deb

# Add the current user to the docker group (sudo-free usage is optional)
sudo usermod -aG docker $USER
newgrp docker

# Verify the installation
sudo docker -v
# Example output: Docker version 24.0.7, build afdd5

Install Docker Compose:

# Grant execute permission and move it to the system path
sudo chmod +x docker-compose
sudo mv docker-compose /usr/local/bin/docker-compose

# Verify the installation
sudo docker-compose -v
# Example output: Docker Compose version v2.20.2

Step 2: Deployment Package Download Address

🔗 Baidu Netdisk: https://pan.baidu.com/s/1sKgeBnMZmRnIr42_pVHmiw

🔑 Extraction code: Join the QQ discussion group and check the group files for the extraction code.👉 Click here to join the QQ discussion group

After downloading, extract the deployment package

Step 3: Start qData

There is a docker.zip archive inside the deployment package. Extract it first.
After extraction, enter the ~/qData/docker path, where you will see many .yml files.

3.1 Use MySQL as the Primary Database

⚠️ Tip: If you use Dameng Database (DM8), skip this step.

Step 1: Enter the installation directory

cd ~/(deployment-package-extraction-path)

Step 2: Edit the `.env` file

sudo vi .env

Find the following configuration and change dm8 to mysql:

# Database type. Available values: dm8 or mysql
DB_TYPE=mysql

3.2 Initialize the Database (required on first run)

sudo docker-compose --profile schema up -d

💡 If you use **MySQL** as the primary database, run:
sudo docker-compose -f docker-compose-mysql.yml --profile schema up -d

⚠️ Note: entrypoint.sh file permission issue
If the first run of sudo docker-compose --profile schema up -d reports permission or Windows line-ending issues, run the following commands in order:

# Grant script permissions and fix line endings
cd ~/qData(deployment-package-extraction-path)
sudo chmod -R 755 docker
sudo chown -R $USER:$USER ./docker

sed -i 's/\r$//' ./database/dm8/entrypoint.sh
sed -i 's/\r$//' ./database/dm8/entrypoint-arm64.sh

# Verify permissions
ls -l ./database/dm8/entrypoint.sh
# Expected: -rwxr-xr-x

# Run again
sudo docker-compose --profile schema up -d

💡 If you use **MySQL** as the primary database, run:
sudo docker-compose -f docker-compose-mysql.yml --profile schema up -d

3.3 Start qData

Choose lightweight mode or full mode according to your verification needs.

Lightweight Mode (light)

For quick deployment and feature verification, you can start qData without DolphinScheduler and Spark:

sudo docker-compose --profile light up -d

💡 If you use **MySQL** as the primary database, run:
sudo docker-compose -f docker-compose-mysql.yml --profile light up -d

Full Mode (all)

To use all dependency services, continue to use the all mode:

sudo docker-compose --profile all up -d

💡 If you use **MySQL** as the primary database, run:
sudo docker-compose -f docker-compose-mysql.yml --profile all up -d

3.4 Start Demo Data (Optional)

To verify qData with the built-in data source, start the demo mode separately. The demo mode is independent of all:

sudo docker-compose --profile demo up -d

💡 If you use **MySQL** as the primary database, run:
sudo docker-compose -f docker-compose-mysql.yml --profile demo up -d

3.5 Start Local Source-code Dependencies

# Steps 4.1 and 4.2 above do not need to be run
docker-compose --profile local up -d

💡 If you use **MySQL** as the primary database, run:
sudo docker-compose -f docker-compose-mysql.yml --profile all up -d (to be adapted)

⚠️ Note: port occupation issue
If sudo docker-compose --profile all up -d reports that a port is occupied:

Follow the error message and stop the process occupying the corresponding port on the server;
Or edit the *.yaml configuration files in the deployment package and comment out or delete port mappings other than port 80 (this does not affect container-internal operation).

5.5 Other Common Commands

⚠️ Tip:
The following commands use all as the example. If you started lightweight mode, replace all with light. Manage the demo mode separately.
If you use a custom docker-compose-xxx.yml file, every startup command must append
-f docker-compose-xxx.yml after docker-compose.
Example: sudo docker-compose -f docker-compose-mysql.yml --profile all up -d

View the running status of all services:

sudo docker-compose --profile all ps

Stop all qData services temporarily (data is retained):

sudo docker-compose --profile all stop

Restart all services:

sudo docker-compose --profile all restart

Completely stop services and delete data (restore the default environment):

sudo docker-compose --profile all down
sudo docker-compose --profile schema down

Middleware required for local source-code startup

docker-compose --profile local up -d

⚠️ down clears data. If you want to keep the data, use stop only.

Deployment Complete! 🎉

After deployment is complete, access the following addresses:

🌐 qData Data Platform
http://<server-IP>:80
Account: admin
Password: qData123
📅 Scheduler DolphinScheduler
http://<server-IP>:12345/dolphinscheduler/ui/home
Account: admin
Password: dolphinscheduler123
⚡ Spark Console
http://<server-IP>:8080/

⚠️ DolphinScheduler and Spark start only in all mode. Their URLs are expected to be unavailable in light mode.

🔑 Replace <server-IP> with your server's public or private IP.

💡 Important Reminder

After the first startup, we recommend waiting 1-2 minutes so all containers can finish initialization.
You can run docker ps to view container status.
If the service is inaccessible, check whether the server firewall has opened port 80.