Deploy openGauss in 5 Minutes with Docker Compose: Zero-Pitfall Guide

Environment Preparation Checklist

Operating System: CentOS 7.9 / Ubuntu 20.04 LTS

Docker: 26.1.4

Docker Compose: v2.34.0

openGauss: Official latest stable image; host port 8888 (customizable), container port 5432 (default); config file at /data/opengauss/data/postgresql.conf; persistent storage at /data/opengauss/data

Detailed Deployment Steps

1. Create Directories and Permissions

Create the persistent storage directory and set permissions for the container's default user omm (UID 1000):

# 1. Create persistent storage directory (data + config)
mkdir -p /data/opengauss/data

# 2. Set directory permissions (critical! avoids container read/write issues)
chown -R 1000:1000 /data/opengauss/data
chmod -R 755 /data/opengauss/data

# 3. Enter working directory (all subsequent commands run here)
cd /data/opengauss/

2. Write Docker Compose File

Generate docker-compose.yml with core configuration: image, port mapping, environment variables, persistent mounts.

# Create and edit docker-compose.yml
cat > docker-compose.yml << EOF
version: '3.8'
services:
  opengauss:
    image: opengauss/opengauss:latest
    container_name: opengauss
    # Privileged mode (solves container permission issues)
    privileged: true
    restart: always
    ports:
      - "8888:5432"
    # Environment variables (must change passwords!)
    environment:
      - GS_PASSWORD=OpenGauss@2025
      - GS_NODENAME=opengauss_node
      - GS_DB=mydb
      - GS_USERNAME=myuser
      - GS_USER_PASSWORD=MyPw@2025
    volumes:
      - ./data:/var/lib/opengauss
EOF

Key Note: GS_PASSWORD is the superuser omm password. It must meet the policy: 8+ characters, uppercase, lowercase, digit, special symbol (avoid # and $ to prevent conflicts). Otherwise the container fails to start.

3. Start openGauss Container

Launch the service in the background; Docker pulls the image and creates the container automatically.

# 1. Start service in background (-d = detached)
docker-compose up -d

# 2. Check container status ("Up" means success)
docker ps | grep opengauss

Successful startup example output:

[+] Running 2/2
 ✔ Network opengauss_default  Created
 ✔ Container opengauss         Started

If you see "port is already allocated", host port 8888 is in use. Return to step 2 and change the ports mapping to a free port (e.g., 5432:5432 ), then rerun the start command.

4. Service Verification

Container Internal Verification (Quick Service Confirmation)

# 1. Enter openGauss container
docker-compose exec opengauss bash

# 2. Switch to superuser omm (container default is root; must switch to connect)
su omm

# 3. Connect to database (using mydb created in step 2 and default port 5432)
gsql -d mydb -p 5432

# 4. Execute SQL tests (successful output confirms normal operation)
select version();  -- view database version
create table test(id int, name varchar(20));  -- create test table
insert into test values(1, 'openGauss');  -- insert data
select * from test;  -- query data

# 5. Exit connection (type \q + Enter)
\q

Key Configuration Notes

Persistent Storage

Host /data/opengauss/data maps to container /var/lib/opengauss, containing database data and config files (e.g., postgresql.conf). Data persists even if the container is removed.

To modify database settings (e.g., connection limits, port), edit the host file /data/opengauss/data/postgresql.conf and restart the container with docker-compose restart.

Port Usage

Container port 5432: openGauss default database port (cannot be changed inside the container; use GS_PORT env var if needed).

Host port 8888: external mapping port for application connections (customizable, ensure it is not occupied).

Environment Variables Core Functions GS_PASSWORD: Superuser omm password (highest privilege, keep secure). GS_DB: Database auto-created at startup (avoids manual creation). GS_USERNAME / GS_USER_PASSWORD: Business user and password (recommended for application connections instead of superuser omm).

Common Issues

Container Exits Immediately with "password does not meet the requirements"

Cause: GS_PASSWORD does not meet format requirements (8+ chars, upper/lower case, digit, special symbol).

Fix: Update GS_PASSWORD in docker-compose.yml (e.g., Gauss_2025), then run docker-compose down && docker-compose up -d to restart.

Host Connection Fails with "permission denied for directory /data/opengauss/data"

Cause: Incorrect directory permissions; container user omm cannot read/write the host directory.

Fix: Reset permissions: chown -R 1000:1000 /data/opengauss/data, then restart the container.

External Machines Cannot Connect (Host Can Connect)

Cause: Host firewall blocks the mapped port (e.g., 8888).

Fix: Open the port and reload firewall (CentOS example):

firewall-cmd --zone=public --add-port=8888/tcp --permanent
firewall-cmd --reload

Following this workflow achieves standardized /data directory management and one-click service control via Docker Compose, enabling beginners to deploy openGauss in 5 minutes. Future scaling or migration only requires copying the /data/opengauss/data directory.