Skip to content

Cấu hình (Configuration)

Govard sử dụng cấu hình phân tầng cho dự án kết hợp với các framework blueprint.


Thứ tự ưu tiên của các lớp cấu hình

Govard tải cấu hình theo thứ tự sau (lớp sau sẽ ghi đè lên lớp trước):

Ưu tiênFileMô tả
1.govard.ymlCấu hình cơ bản của team — file chính được phép ghi
2.govard.<profile>.ymlGhi đè profile dùng chung cho team
3.govard.local.ymlGhi đè cấu hình local của developer (cũ)
4.govard/.govard.local.ymlGhi đè cấu hình local của developer (Khuyên dùng)
5.govard.<env>.ymlGhi đè cấu hình môi trường (cũ)
6.govard/.govard.<env>.ymlGhi đè cấu hình môi trường (Khuyên dùng)

Model sở hữu (Ownership Model)

  • .govard.yml — cấu hình cơ sở thuộc sở hữu của team; là mục tiêu cho mọi lệnh ghi govard config set.
  • Ghi đè Profile/local/env — là read-only dưới góc nhìn của CLI; không bao giờ bị Govard tự động ghi đè.

Profiles

Sử dụng profiles khi team cần nhiều mô hình runtime khác nhau cho cùng một dự án.

bash
govard config profile switch upgrade   # Chuyển sang profile nâng cấp
govard env up --profile upgrade       # Hoặc dùng trực tiếp cờ --profile
govard db dump --profile perf
govard config profile clear            # Reset về mặc định (không dùng profile)

Govard tải .govard.<profile>.yml và tạo một file compose cô lập + các volume dữ liệu riêng biệt, vì vậy việc chuyển đổi profile không làm ảnh hưởng đến dữ liệu hiện tại của nhau.

Các lệnh profile:

  • govard config profile - Hiển thị profile được khuyên dùng cho framework được nhận diện
  • govard config profile switch <name> - Chuyển sang một profile cụ thể (lưu trên từng dự án)
  • govard config profile clear - Reset về profile mặc định

Ghi đè môi trường (Environment Override)

bash
export GOVARD_ENV=staging
govard env up

Khi có GOVARD_ENV=staging, Govard sẽ tải thêm:

  • .govard.staging.yml
  • .govard/.govard.staging.yml

Các biến môi trường toàn cục (Global Environment Variables)

BiếnTác dụng
GOVARD_ENVKích hoạt layer cấu hình theo môi trường (.govard.<env>.yml + .govard/.govard.<env>.yml được load cuối cùng)
GOVARD_HOME_DIRGhi đè thư mục ~/.govard — toàn bộ state, file compose, cert, và cache
GOVARD_BLUEPRINTS_DIRGhi đè vị trí tìm kiếm blueprint (merged blueprints.FS)
GOVARD_IMAGE_REPOSITORYGhi đè tiền tố repository image được quản lý (vd. ghcr.io/my-org/govard-)
GOVARD_DOCKER_DIRGhi đè local Docker build context cho các build fallback

GOVARD_ENV là biến duy nhất ảnh hưởng tới thứ tự layer cấu hình; các biến còn lại ảnh hưởng tới filesystem/image. Các test nội bộ còn dùng GOVARD_GLOBAL_COMMANDS_DIR, GOVARD_OPERATIONS_LOG_PATH, GOVARD_PROJECT_REGISTRY_PATH để cô lập state — không cần cho sử dụng thông thường.


Ví dụ về file .govard.yml

yaml
project_name: "my_project"
framework: "magento2"
framework_version: "2.4.7"
domain: "myproject.test"
table_prefix: "demo_"
lock:
  strict: false
blueprint_registry:
  provider: "http"
  url: "https://example.com/govard-blueprints.tar.gz"
  checksum: "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
  trusted: false
stack:
  php_version: "8.4"
  node_version: "24"
  db_version: "11.4"
  web_root: "/public"
  cache_version: "7.4"
  search_version: "3.4.0"
  queue_version: "3.13.7"
  xdebug_session: "PHPSTORM"
  xdebug_version: "3.4.5"
  composer_version: "latest"
  services:
    web_server: "nginx"
    db: "mariadb"
    search: "opensearch"
    cache: "redis"
    queue: "none"
  features:
    xdebug: true
    varnish: false
    isolated: false
    mftf: false
    frontend_sync: false
linked_projects:
    - "other-project"
    - "external-host.com:127.0.0.1"

Các trường cấu hình chính

Định danh dự án (Project Identity)

TrườngMô tả
project_nameTên dự án độc nhất (không được trùng lặp với bất kỳ dự án nào khác)
frameworkFramework được tự động nhận diện hoặc ép buộc
framework_versionPhiên bản framework (dùng cho các version-aware profile)
domainDomain chính của dự án (ví dụ: myproject.test)
extra_domainsCác hostname bổ sung được định tuyến qua local proxy
store_domainsMagento multi-store hostname → ánh xạ mã scope
table_prefixTiền tố bảng database cho Magento 2, Mage-OS, Magento 1, OpenMage hoặc PrestaShop; bỏ qua hoặc để trống nếu không dùng
linked_projectsDanh sách các dependency (tên dự án hoặc IP:domain) để kết nối liên dự án

::: important QUAN TRỌNG project_namedomain phải là độc nhất trên tất cả các dự án Govard đang được theo dõi. Govard sẽ chặn lệnh initenv up nếu có dự án khác đã sử dụng trùng tên/domain. :::

store_domains — Dạng đơn giản (Legacy)

yaml
store_domains:
  brand-b.test: brand_b
  brand-c.test: brand_c

store_domains — Dạng Object (Định tuyến rõ ràng)

yaml
store_domains:
  brand-b.test:
    code: base
    type: website
  brand-c.test:
    code: brand_c
    type: store

Dạng Object hướng dẫn Govard tự động cấu hình các mapping host MAGE_RUN_CODE / MAGE_RUN_TYPE một cách tự động.

Tiền tố bảng table_prefix — Magento Schemas

Sử dụng table_prefix khi các bảng cơ sở dữ liệu Magento có tiền tố, ví dụ demo_core_config_data:

yaml
table_prefix: "demo_"

Govard sử dụng giá trị này cho Magento 2/Mage-OS env.php, Magento 1/OpenMage local.xml, PrestaShop parameters.php, SQL của lệnh config auto, các bộ lọc dữ liệu khi sync DB và quá trình migrate từ Warden. Giá trị này chỉ được chứa chữ cái, chữ số và dấu gạch dưới.


Runtime Stack

TrườngTùy chọnMô tả
stack.services.web_servernginx, apache, hybridWeb server
stack.services.dbmariadb, mysql, noneDịch vụ database
stack.services.searchopensearch, elasticsearch, noneCông cụ tìm kiếm
stack.services.cacheredis, valkey, noneDịch vụ cache
stack.services.queuerabbitmq, noneDịch vụ queue (hàng đợi)
stack.php_versionví dụ: 8.4, nonePhiên bản PHP (none = không có PHP container)
stack.node_versionví dụ: 24Phiên bản Node.js
stack.python_versionví dụ: 3.12Phiên bản Python (chỉ Django, Dagster; mặc định 3.12)
stack.db_versionví dụ: 11.4Phiên bản database
stack.web_rootví dụ: /pub, /publicThư mục web root
stack.composer_version1, 2, 2.2, latest, hoặc bất kỳ phiên bản nàoPhiên bản Composer
stack.xdebug_sessionví dụ: PHPSTORMTên session Xdebug
stack.xdebug_versionví dụ: 3.4.5Ghi đè phiên bản PECL Xdebug được cài trong container php-debug (mặc định: phiên bản Govard khuyến nghị theo PHP version — hiện là 3.4.5 cho PHP 8.1-8.4, 3.5.3 cho PHP 8.5 vì phiên bản này không có lựa chọn 3.4.x). Việc này sẽ buộc build image cục bộ vì phiên bản cụ thể được đóng gói sẵn trong image.
stack.features.frontend_synctrue, falseBật đồng bộ frontend tích hợp, chỉ dành cho Magento 2 và Mage-OS
stack.features.varnishtrue, falseBật dịch vụ cache Varnish
stack.features.xdebugtrue, falseBật Xdebug và dịch vụ php-debug
stack.features.isolatedtrue, falseCách ly network không cho truy cập từ bên ngoài
stack.features.mftftrue, falseBật Magento Functional Testing Framework

Đồng bộ Frontend

Chỉ đặt stack.features.frontend_sync: true cho dự án Magento 2 hoặc Mage-OS. Tùy chọn này bật phát hiện runtime frontend theo yêu cầu; govard env up không khởi động, chờ, hoặc proxy các dịch vụ frontend development.

Truy cập Elasticsearch/OpenSearch từ Host

Khi stack.services.searchelasticsearch hoặc opensearch, Govard tự động mở REST API của search engine cho host tại:

http://<your-domain>:9200

Ví dụ, nếu domain của dự án là myshop.test, chạy:

bash
curl http://myshop.test:9200/_cluster/health

Cách này hoạt động đồng thời cho mọi dự án — proxy dùng chung của Govard route cổng 9200 theo hostname, giống hệt cách nó đã route cổng 443. Nếu dự án của bạn được tạo trước khi tính năng này ra đời, hãy chạy govard env up một lần để render lại file compose và tạo lại container elasticsearch/opensearch trên network govard-proxy trước khi cổng :9200 truy cập được. Cổng này không có authentication hay TLS (khớp với cấu hình local-dev của chính engine), nên hãy coi nó chỉ dành cho phát triển cục bộ và không expose ra ngoài máy của bạn.

Truy cập RabbitMQ Management UI từ Host

Khi stack.services.queuerabbitmq, Govard tự động mở management UI cho host tại:

http://<your-domain>:15672

Ví dụ, nếu domain của dự án là myshop.test, mở http://myshop.test:15672 trên trình duyệt và đăng nhập bằng guest / guest. Cách route giống hệt truy cập :9200 của search engine ở trên — proxy dùng chung route cổng 15672 theo hostname, nên mọi dự án đều giữ UI riêng của mình cùng lúc. Cổng này không có TLS; hãy coi nó chỉ dành cho phát triển cục bộ và không expose ra ngoài máy của bạn. Nếu dự án của bạn được tạo trước khi tính năng này ra đời, hãy chạy govard env up một lần để render lại file compose và tạo lại container rabbitmq trên network govard-proxy trước khi cổng :15672 truy cập được.

Đối với các framework ưu tiên Node, hệ thống tự động nhận diện package manager từ package.json, pnpm-workspace.yaml hoặc các file lock.

Tối ưu hóa phiên bản Composer

Govard cung cấp hỗ trợ trực tiếp cho các phiên bản Composer phổ biến nhằm đảm bảo môi trường khởi động ngay lập tức:

  • Tích hợp sẵn (Tốc độ tức thì): 1, 2, 2.2, latest. Các phiên bản này được đóng gói sẵn trong PHP image và không cần tải về khi chạy.
  • Động (Tự động tải về): Có thể cấu hình bất kỳ phiên bản chi tiết nào (ví dụ: 2.7.2). Govard sẽ tự động tải về và xác minh binary vào lần chạy env up đầu tiên.

An toàn và Tính tái lặp (Safety and Reproducibility)

TrườngMô tả
lock.strictDừng chạy env up khi trạng thái lock file bị thiếu hoặc không khớp
lock.ignore_fieldsCác trường cần bỏ qua khi kiểm tra tính tuân thủ (ví dụ: host.docker_version)
blueprint_registry.*Đăng ký nguồn blueprint remote tùy chọn với yêu cầu về checksum + độ tin cậy

Remotes

Các cấu hình remote nằm dưới khóa remotes.<name>. Tên có thể là bất kỳ định danh hợp lệ nào — Govard chấp nhận các tên tiêu chuẩn (dev, staging, prod) cũng như bất kỳ tên tùy chỉnh nào sử dụng chữ thường, chữ số, dấu gạch ngang hoặc gạch dưới (ví dụ: qa, preprod, demo, client-uat).

yaml
remotes:
  staging:
    host: staging.example.com
    user: deploy
    path: /var/www/app
    port: 22
    capabilities:
      files: true
      media: true
      db: true
    protected: false
    auth:
      method: ssh-agent

  qa:
    host: qa.example.com
    user: deploy
    path: /var/www/app
    auth:
      method: keychain

  preprod:
    host: preprod.example.com
    user: deploy
    path: /var/www/app
    protected: true   # bật tính năng chống ghi đè cho môi trường tùy chỉnh
    auth:
      method: ssh-agent

LƯU Ý

Chỉ các remote có tên chuẩn hóa thành prod (prod, production, live) là tự động được bảo vệ chống ghi đè (write-protected). Tất cả các remote khác — bao gồm cả tên tùy chỉnh — mặc định không được bảo vệ. Sử dụng cấu hình protected: true để kích hoạt thủ công.

Các trường con chính:

TrườngMô tả
capabilitiesCác cờ phạm vi: files, media, db, deploy
protectedBảo vệ chống ghi đè cho remote này
auth.methodkeychain, ssh-agent, hoặc keyfile
auth.key_pathĐường dẫn tới key SSH (cho phương thức keyfile)
auth.strict_host_keyBật xác thực host-key nghiêm ngặt
auth.known_hosts_fileĐường dẫn file known_hosts tùy chỉnh

Các trường thông tin remote hỗ trợ các tham chiếu op://... được giải quyết thông qua 1Password CLI.

→ Hướng dẫn đầy đủ: Remote & Đồng bộ


Deploy

Block deploy: cấu hình cách một revision git trở thành một release trên target. Mỗi remote có thể ghi đè bất kỳ key nào của nó qua remotes.<name>.deploy.<key> (và các field topology branch, repository, deploy_path, publish, local ngay trên remote); flag dòng lệnh thắng cả hai.

yaml
deploy:
  keep_releases: 5
  command_timeout: 90m            # mọi bước ngoài maintenance window
  maintenance_timeout: 15m        # một bước bên trong window
  lock_stale_after: 2h            # lock cũ bao lâu thì `unlock` được lấy
  db_backup: true
  artifact_dir: artifacts         # chỉ cần nó tồn tại là chọn artifact mode
  verify:
    url: https://shop.example.com/
    timeout: 30s
  settings:                       # đối chiếu với recipe; key lạ thì exit 4
    php_bin: php8.3
    php_version: "8.3"
    mage_mode: production
  hooks:
    - { name: varnish-purge, on: "publish:activate", position: after, order: 10, run: "varnishadm ban req.url ~ /" }
TrườngMặc địnhMô tả
keep_releases5số release mà deploy:cleanup giữ lại, cùng dump database của chúng
command_timeout30mchặn mọi bước ngoài maintenance window
maintenance_timeout15mchặn một bước bên trong window
lock_stale_after2htuổi mà govard deploy unlock nhả lock không cần --force
db_backupfalsedump database trước task đầu tiên thay đổi dữ liệu (--db-backup theo từng lần chạy)
artifact_dirthư mục artifact; chỉ cần nó tồn tại là --build=auto resolve thành artifact
verify.urlrequest HTTP mà deploy:verify chạy sau publish
verify.timeout30srequest đó được phép mất bao lâu
settingsmặc định của recipesetting của framework và engine, được đối chiếu với recipe
hookscác bước neo vào task id, alias stage (stage:build) hoặc một hook khác

Bốn setting của engine quyết định govard sandbox phải cung cấp gì ngoài profile. Chúng được đọc ở tầng project (override theo remote không được xét: remote sandbox là synthetic và không bao giờ nằm trong cấu hình), và mỗi key thay thế danh sách của recipe chứ không nối thêm:

SettingMặc địnhTác dụng
sandbox_packagestheo recipeapt package bổ sung mà image sandbox cài
sandbox_extensionstheo recipePHP extension, cài dưới dạng php<series>-<name>
sandbox_servicestheo recipeinit service được start trong container trước sshd
sandbox_toolstheo recipebinary cài từ danh sách đóng của engine (wp-cli)
yaml
deploy:
  settings:
    sandbox_packages: [postgresql]
    sandbox_extensions: [intl, pgsql, mbstring, xml, curl, zip]
    sandbox_services: [postgresql, redis-server]

Một tên service thuộc bảng của engine mang theo cả package cung cấp nó, nên chỉ cần khai postgresql là đủ để cài và start. Service mà image không start được sẽ được nêu tên lúc container khởi động, thay vì bị bỏ qua im lặng.

Các field ở tầng remote mà engine deploy đọc:

TrườngMô tả
pathdocroot đang được phục vụ; việc nó không tồn tại, là symlink hay là thư mục thật sẽ quyết định chiến lược publish
deploy_pathlayout root chứa releases/, shared/.dep/; được dò từ target khi bỏ trống
deploy.publishauto (mặc định), symlink hoặc in_place
deploy.branch / deploy.repositoryghi đè giá trị ở tầng dự án
deploy.localchạy pipeline ngay trên máy này thay vì qua SSH

deploy.settings được đối chiếu với recipe của framework trước khi chạy bất cứ thứ gì: key lạ hoặc giá trị sai dạng sẽ thoát với mã 4 kèm tên key. Setting dạng chuỗi phải được quote nếu trông giống số (php_version: "8.2").

→ Hướng dẫn đầy đủ: Triển khaiCase study triển khai


Tiện ích mở rộng dự án (Project Extensions)

Đường dẫnMục đích
.govard/docker-compose.override.ymlGhi đè Compose được merge sau khi include framework
.govard/commands/*Các lệnh tùy chỉnh được hiển thị qua govard custom
.govard/hooks/*Các script được tham chiếu bởi hooks.*.run
.govard/nginx/custom/*.confDirective nginx bổ sung, được include vào bên trong server {} đã render (chỉ áp dụng cho nginx)
.govard/apache/custom/*.confDirective Apache bổ sung, được include vào bên trong <VirtualHost> đã render (chỉ áp dụng cho Apache)

Các sự kiện lifecycle hook:

  • pre-up / post-up
  • pre-down / post-down
  • pre-deploy / post-deploy
  • pre-delete / post-delete

GỢI Ý

Govard tạo mã hash vân tay cho .govard/docker-compose.override.yml, .govard/nginx/custom/, và .govard/apache/custom/. Nếu bất kỳ thứ nào trong số này thay đổi, lệnh env up tiếp theo sẽ tự động re-render cấu trúc compose.

Khi ghi đè dịch vụ, nên ưu tiên các bổ sung nhỏ (thêm biến môi trường, label, port). Việc thay thế hoàn toàn danh sách như services.web.volumes có thể làm mất các mount quan trọng do Govard quản lý. .govard/nginx/custom/.govard/apache/custom/ tồn tại chính xác để bạn không cần thay thế toàn bộ cấu hình web server chỉ để thêm một directive.

Framework khai báo runtime audit profiler khiến govard env up chuẩn bị và mount thư mục custom đang active ngay cả khi project không có snippet nào do người dùng viết. govard audit run --checks profiler dùng include lồng nhau .govard/nginx/custom/audit-profiler/ bên trong PHP FastCGI location của Magento cho nginx, hoặc include vhost tạm thời trong .govard/apache/custom/ cho Apache và hybrid. File được đặt tên duy nhất theo từng audit run và bị xóa trong quá trình cleanup có lease bảo vệ; không có thiết lập profiler nào được ghi vào .govard.yml hay app/etc/env.php của Magento.

Audit Lint Providers

audit.lint cấu hình backend mà govard audit dùng cho check lint. Cả hai key đều không bắt buộc; nếu không set gì, audit sẽ chạy backend native do Govard sở hữu.

yaml
audit:
  lint:
    # Provider mặc định cho dự án này. Khi bỏ trống, mặc định là "govard"
    # (backend native). Mọi giá trị khác phải trùng tên một key bên dưới.
    provider: govard

    # Các lint container bên thứ ba được khai báo tường minh. Không có gì được
    # tự phát hiện, và không cái nào là fallback cho backend native.
    external_providers:
      house-standard:
        type: docker            # bắt buộc; chỉ hỗ trợ "docker"
        image: example.invalid/lint@sha256:...  # bắt buộc
        command: ["lint", "--report", "/output/report.json"]  # bắt buộc, không rỗng
KeyBắt buộcMục đích
audit.lint.providerKhôngProvider mặc định của dự án. Phải là govard hoặc một key trong external_providers. Chỉ chữ thường, số, gạch ngang và gạch dưới.
audit.lint.external_providers.<name>.typeLoại provider. Chỉ hỗ trợ docker.
audit.lint.external_providers.<name>.imageImage container sẽ chạy. Nên ghim theo digest để evidence chỉ đúng một runtime bất biến.
audit.lint.external_providers.<name>.commandMảng tham số cho container. Mọi phần tử phải khác rỗng; không có shell.

Thứ tự ưu tiên là tường minh: flag --lint-provider luôn thắng, sau đó audit.lint.provider, cuối cùng là mặc định govard. Credential có chủ đích không phải là trường cấu hình — Composer auth được đọc từ ~/.composer/auth.json, còn forward SSH agent là opt-in theo từng run qua --allow-lint-ssh-agent.

CẢNH BÁO

External provider phải tạo ra report theo đúng schema lint của Govard và echo lại chính xác identity của run đó, nếu không report sẽ bị quarantine thay vì được nhận làm evidence. Gọi một provider chưa được cấu hình là lỗi, không bao giờ âm thầm quay về govard. Target standalone module không có cấu hình dự án nào, nên ở đó chỉ dùng được govard.


Lệnh cấu hình

bash
govard config get stack.php_version
govard config set stack.php_version 8.4
govard config profile --json
govard config profile apply --framework laravel --framework-version 11

govard config set chỉ ghi trực tiếp vào .govard.yml (cấu hình cơ sở).


Blueprint Registry

Nếu blueprint_registry được kích hoạt:

  • provider phải là git hoặc http
  • url là bắt buộc
  • checksum phải là mã SHA-256 hex dài 64 ký tự
  • trusted phải là true
  • Các package remote được cache tại ~/.govard/blueprint-registry/

Govard sẽ thất bại ngay lập tức nếu checksum không khớp.


Kết nối liên dự án (Inter-Project Connectivity)

Mặc định, các dự án Govard được cô lập. Để cho phép một dự án giao tiếp với một dự án Govard khác qua tên miền .test của nó, hãy sử dụng trường linked_projects.

Các hành vi chính

  • Hiển thị theo dạng Opt-in: Các hostname của dự án khác chỉ được inject vào /etc/hosts nếu dự án đó được khai báo rõ ràng trong linked_projects.
  • Tự động phân giải Domain: Khai báo tên dự án sẽ tự động map domain chính và tất cả các domain phụ của nó về IP của proxy dùng chung.
  • Khởi động lại Container có chọn lọc: Khi bạn khởi động một dự án, Govard sẽ xác định các dự án đang chạy nào phụ thuộc vào nó và chỉ khởi động lại các dự án cụ thể đó để cập nhật mapping host.
  • Mapping thủ công: Bạn cũng có thể cung cấp các cấu hình mapping thủ công theo định dạng hostname:ip.
yaml
linked_projects:
  - "my-api-project"             # Tên dự án
  - "custom.site:192.168.1.10"   # Ánh xạ thủ công

Ví dụ: một pipeline đồng bộ Dagster gọi tới một cửa hàng Magento 2

yaml
# Trong file .govard.yml của dự án Dagster
linked_projects:
  - "shop"   # tên của dự án Magento 2

Blueprint compose của framework Dagster đã mount và tin cậy (trust) sẵn Root CA nội bộ của Govard trong container, vì vậy khi linked_projects phân giải được domain của shop, code trong pipeline gọi tới https://shop.test (REST/GraphQL API của Magento 2) sẽ xác thực TLS đúng cách - không cần dùng verify=False/InsecureSkipVerify.


← Lệnh CLI | Frameworks →

Phát hành theo giấy phép MIT.