0

Docker Compose cho máy dev: ba database một lệnh, và bốn cái bẫy

Mình làm một công cụ báo cáo đọc dữ liệu từ ba loại database: PostgreSQL, MySQL và SQL Server. Cài cả ba lên máy thì mất cả buổi chiều, và máy người mới vào team lại phải cài lại từ đầu. Docker Compose giải quyết đúng chuyện này: một file mô tả app cùng ba database, một lệnh docker compose up là có đủ.

Bản đầu tiên của file đó chạy lên được, container nào cũng "running". Rồi app báo không kết nối được database. Rồi bảng trong SQL Server trống trơn dù mình đã mount script tạo bảng. Bài này là bốn cái bẫy mình dính trong file compose đó, theo thứ tự gặp, và file compose cuối cùng mình dùng.

Nói nhanh cho ai mới: Compose là công cụ chạy nhiều container cùng lúc từ một file YAML. Mỗi mục trong services là một container, chúng nói chuyện với nhau qua tên service (app gọi postgres:5432 chứ không phải localhost:5432).

File ban đầu

version: '3.8'

services:
  app:
    build: .
    ports: ["3000:3000"]
    depends_on: [postgres, mysql, mssql]

  postgres:
    image: postgres:15-alpine
    environment:
      - POSTGRES_PASSWORD=testpass
    volumes:
      - postgres_data:/var/lib/postgresql/data
      - ./scripts/init-postgres.sql:/docker-entrypoint-initdb.d/init.sql

  mysql:
    image: mysql:8.0
    # ... tương tự, có init-mysql.sql

  mssql:
    image: mcr.microsoft.com/mssql/server:2022-latest
    environment:
      - ACCEPT_EULA=Y
      - SA_PASSWORD=TestPass123!
    volumes:
      - ./scripts/init-mssql.sql:/docker-entrypoint-initdb.d/init.sql

volumes:
  postgres_data:

Trông gọn gàng. Bốn cái bẫy nằm hết trong đây.

1. depends_on không chờ database sẵn sàng

depends_on: [postgres] chỉ có nghĩa là container postgres được khởi động trước container app. Nó không chờ PostgreSQL bên trong mở cổng nhận kết nối. Database cần vài giây (SQL Server cần lâu hơn hẳn) để khởi tạo, trong khi app đã chạy và thử kết nối ngay. Kết quả: app crash lần đầu, docker compose up lần hai thì lại chạy được. Kiểu lỗi "lúc được lúc không" tốn thời gian nhất.

Cách đúng là cho mỗi database một healthcheck, rồi bảo app chờ trạng thái healthy:

  postgres:
    image: postgres:15-alpine
    healthcheck:
      # pg_isready trả về 0 khi server đã nhận kết nối
      test: ["CMD-SHELL", "pg_isready -U $$POSTGRES_USER -d $$POSTGRES_DB"]
      interval: 5s
      timeout: 3s
      retries: 10

  app:
    depends_on:
      postgres:
        condition: service_healthy

$$ là để Compose không tự thay biến lúc đọc file, mà để nguyên $POSTGRES_USER cho shell trong container thay. Đây là cách Docker khuyên làm cho thứ tự khởi động.

Dù vậy, app vẫn nên tự thử kết nối lại vài lần. Trên server, database có thể khởi động lại giữa chừng, và lúc đó chẳng có depends_on nào giúp được.

2. docker-entrypoint-initdb.d không phải tính năng của Docker

Script init-postgres.sql và init-mysql.sql chạy, còn init-mssql.sql thì không. Lý do: thư mục /docker-entrypoint-initdb.d là quy ước riêng của image PostgreSQL và image MySQL, do script khởi động của chính các image đó đọc. Docker không biết gì về nó. Image SQL Server của Microsoft không có cơ chế này, nên file mount vào đó nằm im.

Cách mình làm cho SQL Server: một service chạy một lần, dùng chính sqlcmd có trong image, chạy sau khi database healthy:

  mssql:
    image: mcr.microsoft.com/mssql/server:2022-CU14-ubuntu-22.04
    environment:
      - ACCEPT_EULA=Y
      - MSSQL_SA_PASSWORD=${MSSQL_SA_PASSWORD}
    healthcheck:
      # -C: tin chứng chỉ tự ký của container (sqlcmd bản 18 bắt buộc mã hoá)
      test: ["CMD-SHELL", "/opt/mssql-tools18/bin/sqlcmd -S localhost -U sa -P \"$$MSSQL_SA_PASSWORD\" -C -Q 'SELECT 1' || exit 1"]
      interval: 10s
      retries: 12

  mssql-init:
    image: mcr.microsoft.com/mssql/server:2022-CU14-ubuntu-22.04
    depends_on:
      mssql:
        condition: service_healthy
    volumes:
      - ./scripts/init-mssql.sql:/init.sql:ro
    environment:
      - MSSQL_SA_PASSWORD=${MSSQL_SA_PASSWORD}
    entrypoint: ["/bin/sh", "-c", "/opt/mssql-tools18/bin/sqlcmd -S mssql -U sa -P \"$$MSSQL_SA_PASSWORD\" -C -i /init.sql"]
    restart: "no"

  app:
    depends_on:
      mssql-init:
        condition: service_completed_successfully

service_completed_successfully nghĩa là app chỉ khởi động khi script khởi tạo đã chạy xong và thoát với mã 0.

Thêm hai chi tiết: biến mật khẩu giờ tên là MSSQL_SA_PASSWORD (tên cũ SA_PASSWORD đã bị bỏ), và mật khẩu phải đủ mạnh theo chính sách của SQL Server, không thì container tự tắt ngay sau khi khởi động, chỉ để lại một dòng log.

Một bẫy con của bẫy này, áp dụng cả cho PostgreSQL và MySQL: script trong initdb.d chỉ chạy khi thư mục dữ liệu còn trống, tức lần đầu tạo volume. Sửa script rồi docker compose up lại thì không có gì xảy ra, vì volume cũ vẫn còn. Muốn chạy lại thì xoá volume: docker compose down -v (cẩn thận, mất hết dữ liệu trong đó).

3. latest làm máy hai người khác nhau

mssql/server:2022-latest hôm nay và tháng sau là hai image khác nhau. Người mới vào team pull về bản mới, người cũ giữ bản cũ trong cache, rồi một ngày hai máy chạy cùng một script mà ra hai kết quả. Trong một project khác mình còn để service log tập trung là datalust/seq:latest. Chưa gây chuyện gì, nhưng ngày nào đó pull về một bản đổi cấu hình thì sẽ không ai biết vì sao log ngừng chảy về.

Ghi rõ phiên bản cho mọi image. Muốn cập nhật thì đổi số trong file, commit, cả team cùng đổi.

4. Secret nằm thẳng trong file và dòng version thừa

File ban đầu có SA_PASSWORD=TestPass123! và JWT_SECRET=your-jwt-secret-here viết thẳng trong YAML, commit vào Git. Với database chỉ dùng trên máy dev thì chưa phải thảm hoạ, nhưng đây là thói quen sẽ đi theo bạn lên file compose của server.

Compose tự đọc file .env cùng thư mục để thay các biến ${...} trong file YAML:

# .env (không commit, đã có trong .gitignore)
MSSQL_SA_PASSWORD=Mot_Mat_Khau_Du_Manh_1
POSTGRES_PASSWORD=doi_cai_nay_di

Commit kèm một file .env.example có tên biến và giá trị giả, để người mới biết cần điền gì. Bài sau trong series nói kỹ hơn chuyện biến môi trường và secret trong container.

Còn dòng version: '3.8' ở đầu file: Compose bản mới (lệnh docker compose, có dấu cách) đã bỏ trường này và sẽ in cảnh báo "the attribute version is obsolete". Xoá đi là xong.

File cuối cùng

services:
  app:
    build: .
    ports: ["3000:3000"]
    env_file: .env
    depends_on:
      postgres: { condition: service_healthy }
      mysql: { condition: service_healthy }
      mssql-init: { condition: service_completed_successfully }

  postgres:
    image: postgres:15.8-alpine
    environment:
      - POSTGRES_DB=reportdb
      - POSTGRES_USER=report
      - POSTGRES_PASSWORD=${POSTGRES_PASSWORD}
    volumes:
      - postgres_data:/var/lib/postgresql/data
      - ./scripts/init-postgres.sql:/docker-entrypoint-initdb.d/init.sql:ro
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U $$POSTGRES_USER -d $$POSTGRES_DB"]
      interval: 5s
      retries: 10

  mysql:
    image: mysql:8.0.39
    environment:
      - MYSQL_DATABASE=reportdb
      - MYSQL_USER=report
      - MYSQL_PASSWORD=${MYSQL_PASSWORD}
      - MYSQL_ROOT_PASSWORD=${MYSQL_ROOT_PASSWORD}
    volumes:
      - mysql_data:/var/lib/mysql
      - ./scripts/init-mysql.sql:/docker-entrypoint-initdb.d/init.sql:ro
    healthcheck:
      test: ["CMD", "mysqladmin", "ping", "-h", "localhost"]
      interval: 5s
      retries: 20

  mssql:
    image: mcr.microsoft.com/mssql/server:2022-CU14-ubuntu-22.04
    environment:
      - ACCEPT_EULA=Y
      - MSSQL_SA_PASSWORD=${MSSQL_SA_PASSWORD}
    volumes:
      - mssql_data:/var/opt/mssql
    healthcheck:
      test: ["CMD-SHELL", "/opt/mssql-tools18/bin/sqlcmd -S localhost -U sa -P \"$$MSSQL_SA_PASSWORD\" -C -Q 'SELECT 1' || exit 1"]
      interval: 10s
      retries: 12

  mssql-init:
    image: mcr.microsoft.com/mssql/server:2022-CU14-ubuntu-22.04
    depends_on:
      mssql: { condition: service_healthy }
    environment:
      - MSSQL_SA_PASSWORD=${MSSQL_SA_PASSWORD}
    volumes:
      - ./scripts/init-mssql.sql:/init.sql:ro
    entrypoint: ["/bin/sh", "-c", "/opt/mssql-tools18/bin/sqlcmd -S mssql -U sa -P \"$$MSSQL_SA_PASSWORD\" -C -i /init.sql"]
    restart: "no"

volumes:
  postgres_data:
  mysql_data:
  mssql_data:

Tag phiên bản trong ví dụ là minh hoạ, lấy bản đang dùng trong team bạn. Script init-mssql.sql nên viết kiểu chạy lại được (IF NOT EXISTS ... CREATE TABLE), vì service mssql-init chạy mỗi lần up, không như initdb.d chỉ chạy một lần.

Bốn cái bẫy, tóm vào một bảng

Bẫy Dấu hiệu Sửa
depends_on không chờ DB App lỗi kết nối lần đầu, lần sau lại chạy healthcheck + condition: service_healthy
initdb.d với SQL Server Bảng không được tạo, không có lỗi gì Service chạy một lần bằng sqlcmd
initdb.d chỉ chạy lần đầu Sửa script mà DB không đổi docker compose down -v hoặc migration thật
Tag latest Hai máy hai kết quả Ghi rõ phiên bản

Thử ngay: chạy docker compose down && docker compose up hai lần liền trên project của bạn. Nếu lần nào đó app lỗi kết nối database rồi tự khỏi ở lần sau, đó là bẫy số 1.

Bài sau trong series: cấu hình và secret trong container, biến môi trường đi từ đâu tới đâu, và chuyện một cái entrypoint in khoá bí mật ra log. Bạn đã từng dính bẫy nào trong bốn cái trên? Comment kể mình nghe với.

P.S. Lỗi "lúc được lúc không" ở bẫy số 1 là loại mình hay đoán bừa nhất. Giờ mình gọi skill debug trong PrimeKit, bộ skill mình tự làm. Skill buộc tái hiện lỗi trước, đặt giả thuyết nguyên nhân rồi kiểm, sau đó mới sửa, thay vì thêm sleep 10 vào entrypoint cho qua. Cài bằng npx @lovehlmmm/primekit init, rồi gõ /pk:debug kèm triệu chứng. Đọc log container vẫn là việc bạn phải làm.

Tài liệu để đọc thêm


Series khác của mình


All Rights Reserved

Viblo
Let's register a Viblo Account to get more interesting posts.