Quick Start Guide (Docker Compose One-Click Deployment, Detailed Beginner Version)

Qiantong Tech6/11/26About 4 minInstallation and DeploymentOne-Click StartupQuick Start

Tutorial Video

qData Open-Source Edition Quick Deployment Tutorial (Docker Compose)

Important

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

Click to watch the Troubleshooting Videos collection

Before You Start

Who is this guide for?

Users who are new to qData and want to quickly experience its functions.
Users who do not want to deal with complex environment configuration and frontend packaging.
Users who want to use "one-click startup" to experience the complete platform with less effort.

We have prepared a complete out-of-the-box deployment package for you, including:

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

You do not need to manually install many dependencies, build the frontend, or perform complex configuration. Just extract the package and run the script, and the whole big data platform and qData can start running.
Even with zero foundation, you can set it up easily. Experience qData in 10 minutes.

Step 1: Install Docker and Docker Compose

qData runs through 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 is complete, Docker Compose is already included automatically and does not need to be installed separately.

🐧 Linux(Ubuntu 18.04+)

The deployment package already includes offline installation packages and installation scripts. 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 user group (optional for avoiding sudo)
sudo usermod -aG docker $USER
newgrp docker

# Verify 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 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 community group and view 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, open 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: Open the Installation Directory

cd ~/(deployment package extraction location)

Step 2: Edit the `.env` File

sudo vi .env

Find the following configuration and change dm8 to mysql:

# Database type, optional 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
When running sudo docker-compose --profile schema up -d for the first time, if a permission error occurs or there is a Windows line ending issue, run the following commands in order:

# Add script permissions and fix line endings
cd ~/qData(deployment package extraction location)
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 from Local Source Code

Start only the middleware required for local source-code development:

# DM8
docker-compose --profile local up -d

# MySQL
docker-compose -f docker-compose-mysql.yml --profile local up -d

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

Close the process occupying the corresponding port on the server according to the error message.
Or edit the *.yaml configuration in the deployment package and comment out or delete port mappings other than port 80 (this does not affect internal container 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, all startup commands need to 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 will not be lost):

sudo docker-compose --profile all stop

Restart all services:

sudo docker-compose --profile all restart

Completely shut down and delete data (restore the default environment):

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

Middleware required for local source startup:

docker-compose --profile local up -d

⚠️ down will clear data. If you want to keep data, use only stop.

Deployment Complete! 🎉

After deployment is complete, you can 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 Backend
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 public or intranet IP.

💡 Important Reminder

We recommend waiting 1-2 minutes after the first startup so all containers can finish initialization.
You can use docker ps to view container status.
If you cannot access the service, check whether the server firewall has opened port 80.