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ên | File | Mô tả |
|---|---|---|
| 1 | .govard.yml | Cấu hình cơ bản của team — file chính được phép ghi |
| 2 | .govard.<profile>.yml | Ghi đè profile dùng chung cho team |
| 3 | .govard.local.yml | Ghi đè cấu hình local của developer (cũ) |
| 4 | .govard/.govard.local.yml | Ghi đè cấu hình local của developer (Khuyên dùng) |
| 5 | .govard.<env>.yml | Ghi đè cấu hình môi trường (cũ) |
| 6 | .govard/.govard.<env>.yml | Ghi đè 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 ghigovard 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.
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ệngovard 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)
export GOVARD_ENV=staging
govard env upKhi 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ến | Tác dụng |
|---|---|
GOVARD_ENV | Kí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_DIR | Ghi đè thư mục ~/.govard — toàn bộ state, file compose, cert, và cache |
GOVARD_BLUEPRINTS_DIR | Ghi đè vị trí tìm kiếm blueprint (merged blueprints.FS) |
GOVARD_IMAGE_REPOSITORY | Ghi đè tiền tố repository image được quản lý (vd. ghcr.io/my-org/govard-) |
GOVARD_DOCKER_DIR | Ghi đè 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
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ường | Mô tả |
|---|---|
project_name | Tên dự án độc nhất (không được trùng lặp với bất kỳ dự án nào khác) |
framework | Framework được tự động nhận diện hoặc ép buộc |
framework_version | Phiên bản framework (dùng cho các version-aware profile) |
domain | Domain chính của dự án (ví dụ: myproject.test) |
extra_domains | Các hostname bổ sung được định tuyến qua local proxy |
store_domains | Magento multi-store hostname → ánh xạ mã scope |
table_prefix | Tiề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_projects | Danh 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_name và domain 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 init và env up nếu có dự án khác đã sử dụng trùng tên/domain. :::
store_domains — Dạng đơn giản (Legacy)
store_domains:
brand-b.test: brand_b
brand-c.test: brand_cstore_domains — Dạng Object (Định tuyến rõ ràng)
store_domains:
brand-b.test:
code: base
type: website
brand-c.test:
code: brand_c
type: storeDạ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:
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ường | Tùy chọn | Mô tả |
|---|---|---|
stack.services.web_server | nginx, apache, hybrid | Web server |
stack.services.db | mariadb, mysql, none | Dịch vụ database |
stack.services.search | opensearch, elasticsearch, none | Công cụ tìm kiếm |
stack.services.cache | redis, valkey, none | Dịch vụ cache |
stack.services.queue | rabbitmq, none | Dịch vụ queue (hàng đợi) |
stack.php_version | ví dụ: 8.4, none | Phiên bản PHP (none = không có PHP container) |
stack.node_version | ví dụ: 24 | Phiên bản Node.js |
stack.python_version | ví dụ: 3.12 | Phiên bản Python (chỉ Django, Dagster; mặc định 3.12) |
stack.db_version | ví dụ: 11.4 | Phiên bản database |
stack.web_root | ví dụ: /pub, /public | Thư mục web root |
stack.composer_version | 1, 2, 2.2, latest, hoặc bất kỳ phiên bản nào | Phiên bản Composer |
stack.xdebug_session | ví dụ: PHPSTORM | Tên session Xdebug |
stack.xdebug_version | ví dụ: 3.4.5 | Ghi đè 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_sync | true, false | Bật đồng bộ frontend tích hợp, chỉ dành cho Magento 2 và Mage-OS |
stack.features.varnish | true, false | Bật dịch vụ cache Varnish |
stack.features.xdebug | true, false | Bật Xdebug và dịch vụ php-debug |
stack.features.isolated | true, false | Cách ly network không cho truy cập từ bên ngoài |
stack.features.mftf | true, false | Bậ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.search là elasticsearch hoặc opensearch, Govard tự động mở REST API của search engine cho host tại:
http://<your-domain>:9200Ví dụ, nếu domain của dự án là myshop.test, chạy:
curl http://myshop.test:9200/_cluster/healthCá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.queue là rabbitmq, Govard tự động mở management UI cho host tại:
http://<your-domain>:15672Ví 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ạyenv upđầu tiên.
An toàn và Tính tái lặp (Safety and Reproducibility)
| Trường | Mô tả |
|---|---|
lock.strict | Dừng chạy env up khi trạng thái lock file bị thiếu hoặc không khớp |
lock.ignore_fields | Cá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).
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-agentLƯ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ường | Mô tả |
|---|---|
capabilities | Các cờ phạm vi: files, media, db, deploy |
protected | Bảo vệ chống ghi đè cho remote này |
auth.method | keychain, ssh-agent, hoặc keyfile |
auth.key_path | Đường dẫn tới key SSH (cho phương thức keyfile) |
auth.strict_host_key | Bậ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.
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ường | Mặc định | Mô tả |
|---|---|---|
keep_releases | 5 | số release mà deploy:cleanup giữ lại, cùng dump database của chúng |
command_timeout | 30m | chặn mọi bước ngoài maintenance window |
maintenance_timeout | 15m | chặn một bước bên trong window |
lock_stale_after | 2h | tuổi mà govard deploy unlock nhả lock không cần --force |
db_backup | false | dump database trước task đầu tiên thay đổi dữ liệu (--db-backup theo từng lần chạy) |
artifact_dir | — | thư mục artifact; chỉ cần nó tồn tại là --build=auto resolve thành artifact |
verify.url | — | request HTTP mà deploy:verify chạy sau publish |
verify.timeout | 30s | request đó được phép mất bao lâu |
settings | mặc định của recipe | setting của framework và engine, được đối chiếu với recipe |
hooks | — | cá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:
| Setting | Mặc định | Tác dụng |
|---|---|---|
sandbox_packages | theo recipe | apt package bổ sung mà image sandbox cài |
sandbox_extensions | theo recipe | PHP extension, cài dưới dạng php<series>-<name> |
sandbox_services | theo recipe | init service được start trong container trước sshd |
sandbox_tools | theo recipe | binary cài từ danh sách đóng của engine (wp-cli) |
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ường | Mô tả |
|---|---|
path | docroot đ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_path | layout root chứa releases/, shared/ và .dep/; được dò từ target khi bỏ trống |
deploy.publish | auto (mặc định), symlink hoặc in_place |
deploy.branch / deploy.repository | ghi đè giá trị ở tầng dự án |
deploy.local | chạ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 khai và Case study triển khai
Tiện ích mở rộng dự án (Project Extensions)
| Đường dẫn | Mục đích |
|---|---|
.govard/docker-compose.override.yml | Ghi đè 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/*.conf | Directive nginx bổ sung, được include vào bên trong server {} đã render (chỉ áp dụng cho nginx) |
.govard/apache/custom/*.conf | Directive 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-uppre-down/post-downpre-deploy/post-deploypre-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/ và .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.
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| Key | Bắt buộc | Mục đích |
|---|---|---|
audit.lint.provider | Không | Provider 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>.type | Có | Loại provider. Chỉ hỗ trợ docker. |
audit.lint.external_providers.<name>.image | Có | Image container sẽ chạy. Nên ghim theo digest để evidence chỉ đúng một runtime bất biến. |
audit.lint.external_providers.<name>.command | Có | Mả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
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 11govard 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:
providerphải làgithoặchttpurllà bắt buộcchecksumphải là mã SHA-256 hex dài 64 ký tựtrustedphả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/hostsnếu dự án đó được khai báo rõ ràng tronglinked_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.
linked_projects:
- "my-api-project" # Tên dự án
- "custom.site:192.168.1.10" # Ánh xạ thủ côngVí dụ: một pipeline đồng bộ Dagster gọi tới một cửa hàng Magento 2
# Trong file .govard.yml của dự án Dagster
linked_projects:
- "shop" # tên của dự án Magento 2Blueprint 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.