ddtcorex/maestro-skills/govard-toolbox

Govard Toolbox

Govard is a containerized development environment orchestrator. This skill provides high-level shortcuts and references. The CLI is the source of truth: govard <command> --help for flags and govard capabilities for what each command needs, so prefer them over any list below when they disagree.

Quick Reference

Environment Lifecycle

Common Commands

# Start environment
govard up
 
# Stop environment
govard down
 
# Stop with volumes (clean slate)
govard down -v
 
# Shell into PHP container
govard sh
 
# Run single command
govard sh -c "ls -la"
 
# View logs
govard logs -f
 
# Restart services
govard restart

Database Operations

# Connect to MySQL
govard db connect
 
# Run query -- table names may need a framework-specific prefix (e.g. Magento's
# db.table_prefix in app/etc/env.php, WordPress's $table_prefix) if one is configured
govard db query "SELECT * FROM admin_user LIMIT 1"
 
# Import dump
govard db import --file backup.sql --drop
 
# Export database
govard db dump --no-noise -e staging
 
# Direct sync from remote
govard db import --stream-db -e staging --drop

A remote path may point at the layout root: Govard probes <path>, <path>/public_html and <path>/current over SSH. "no database configuration at ..." lists every path tried, so check the remote path instead of retrying blindly. A failed dump is reported as a failure, never as an empty-file success; read the credential warning first.

Remote Sync

# Add remote
govard remote add staging ssh://user@staging.server/path
 
# Test connection
govard remote test staging
 
# Sync everything
govard sync --source staging --full
 
# Plan before sync (preview)
govard sync --source staging --full --plan
 
# Skip noise tables (cache, logs, sessions) and PII tables
govard sync --source staging --full --no-noise --no-pii

Bootstrap

# From staging (full setup)
govard bootstrap --clone -e staging --no-pii --no-noise --yes
 
# Preview plan
govard bootstrap --clone -e staging --plan

Deployment

Ships a git revision to a remote from .govard.yml. Read-only first, always:

govard deploy plan production          # every task with what it runs, or why this mode skips it (no ssh, no rsync, no Docker)
govard deploy plan production --json   # same plan machine-readable (carries schema_version, per-step skip_reason, run_on, needs_migration); timestamp-free, so two runs can be diffed in CI. `check` has no --json
govard deploy check production         # connectivity, permissions, layout, and the strategy that layout implies (ssh)
govard deploy releases production      # what the target has (a positional remote or --remote <name>)
govard deploy status production        # which revision the target serves (no remote: every configured remote)
govard deploy production --yes         # run it
govard deploy rollback production [--to <release>] [--with-db]   # default: the release before the live one; --with-db also restores its dump (destroys data)
govard deploy production --resume      # continue the newest unfinished release (or --from <task>)
govard deploy unlock production [--force]       # lock left by an interrupted run; a lock younger than lock_stale_after needs --force

Capabilities (confirm with govard capabilities): plan/build need nothing; check, releases, status and unlock need ssh; deploy/rollback also rsync; sandbox * needs Docker. A missing runtime is exit 3 CAPABILITY_MISSING, never a half-run. Recover a failed run with --resume (or --from <task>), never by unlocking and starting over. Resume adopts a recorded migrate verdict without re-probing; a recorded skip is discarded and re-probed; steps that already succeeded are not repeated.

Conditional migrate (Magento only). Before the downtime block the recipe probes cd {{release_path}} && {{php_bin}} bin/magento setup:db:status: exit 0 skips the whole downtime block (maintenance mode, worker pause, config import, db migrate, worker resume; reason db up-to-date (probe exit 0)); 1 or 2 runs it; any other exit fails the deploy. Compile, cache flush and the DB backup run regardless. Laravel, Symfony and WordPress have no probe, so their migrate steps always run. govard deploy plan shows which steps are gated (needs_migration).

Topology. Project-wide defaults live in a deploy: block (repository, branch, publish, deploy_path); per-remote overrides live ONLY under remotes.<name>.deploy:. Flat per-remote deploy keys are rejected by the loader (exit 4) with a message naming the key to move. Unset deploy_path probes the target and is adopted only when exactly one layout candidate matches.

What runs on the target comes from the framework recipe; --build=auto|server|artifact decides who builds, and govard deploy build --output <dir> makes the artifact. --db-backup defaults off; when on, the dump lands in shared/backups/deploy/<n>/ and rollback --with-db restores it. A framework whose recipe has no dump command refuses --db-backup up front (exit 4); see the framework skill.

# Rehearse the whole thing against a container playing the target
govard sandbox up --profile full --php 8.3 --docroot symlink   # profile, PHP series, target shape
govard deploy --remote sandbox --yes
govard sandbox down --purge          # also removes the image, key and mirror

Sandbox lists come from the recipe; deploy.settings.sandbox_{packages,extensions,services,tools} replace them. sandbox reset wipes the deploy directories (including shared/), so re-seed shared files. Details: SANDBOX.md.

Deploy preflight: govard deploy plan [remote] is read-only and never connects (--json for machine-readable output); govard deploy check [remote] connects over ssh and is meant to leave nothing behind on the target (its layout probe uses a scratch directory it removes again). Both accept --build, --artifact-dir, --branch, --revision and --tag; check prints human text only. plan reflects the configuration, not --publish, --keep or --verify, which only take effect on a real run. Run them on the host.

Per-framework detail (recipes, the conditional-migrate probe, and each framework's own step table): govard-magento, govard-laravel, govard-symfony, govard-wordpress. Full reference: <https://govard.ddtcorex.com/workflows/deployment>.

Host Without Docker

Govard works without a container runtime. Every command declares its runtime requirement, and the requirement-free set is derived from that manifest:

govard capabilities          # command, requirement, host status
govard capabilities --json   # machine-readable, schema_version 1

• CAPABILITY_MISSING / exit code 3 means a declared capability (docker, ssh,

rsync, cloudflared, net) is unavailable. The message names the capability, and govard env up --error-json prints it as a versioned JSON envelope. Do not hand-parse the text form.

• govard doctor exits 0 when only optional capabilities are missing and

reports required/severity/affects per check; govard doctor --strict treats optional warnings as failures (the hard gate for bootstrap scripts).

• Container-free analysis: govard audit run --checks integrity --format json

runs Go analyzers on the checkout with no Docker, no PHP and no toolchain. It is supported on Magento 2 only (composer manifest/lock problems plus module/DI wiring problems, govard-integrity findings); Laravel, Symfony and WordPress exit 1 with "does not support integrity audit". `--checks lint` still needs Docker and, without it, exits 3 pointing at --checks integrity. Xdebug is orthogonal to the container: on a host with stack.features.xdebug on, the audit refuses to start and asks for --allow-xdebug (govard verify has the same flag). Pass the flag or turn Xdebug off; this is not a capability failure and the exit code is not 3.

• Commands that forward their arguments (govard tool php ...,

govard redis cli ...) cannot parse --error-json; their exit codes are unchanged.

Tool Execution

# Run framework CLI
govard tool magento cache:flush
govard tool magerun cache:clear
govard tool artisan migrate
govard tool drush cr
 
# Node tools
govard tool npm install
govard tool composer install

Services

# Redis
govard redis flush
govard redis cli
 
# Varnish
govard varnish ban /.*   # purge URL pattern (no purge subcommand)
govard varnish ps        # container status (or `stats` for varnishstat)
 
# Open URLs
govard open admin    # Admin panel
govard open db       # PHPMyAdmin
govard open mail     # Mailpit
govard open shell    # shell access details (also: sftp, portainer, mftf, elasticsearch/opensearch, db --client)
 
# RabbitMQ management UI (when stack.services.queue is rabbitmq)
open http://<your-domain>:15672    # guest/guest, local-only, plain HTTP (never https)

Sandbox SSH gateway

Bastion govard-proxy-sshd at 127.0.0.1:2222: start it with govard svc up.

govard gateway allow-key "$(cat ~/.ssh/id_ed25519.pub)"   # one quoted key line; updates known fingerprints in place
ssh -p 2222 <project-slug>@127.0.0.1                       # stable address (vs the ephemeral sandbox port); sftp -P 2222 likewise
govard gateway status    # bastion running? plus target and allowlist counts (needs Docker); warns if port 2222 is held by another process
govard gateway revoke-key <exact-fingerprint-or-comment>   # exact match only, no substring; no match is an error

Prerequisites in order: govard svc up (bastion) → sandbox up (registers the slug; Foo_Bar logs in as foo-bar) → allow-key. Registration is best-effort and no deploy path goes through the gateway, so gateway breakage never blocks a real deploy.

Debugging

# Xdebug control
govard debug on
govard debug off
govard debug status
 
# Diagnostics
govard diag            # alias of `govard doctor`: human-readable health report
govard diag --json     # machine-readable verdict, one call answers "is this env healthy"
govard diag --fix      # apply safe automatic fixes (--dry-run previews them)

Agent guidance: before chaining govard ps / govard logs probes, run govard diag --json once and branch on its result; keep down && up escalation for diagnosed failures only.

Connecting an IDE

Xdebug listens on port 9003. govard debug on only enables the extension inside the container; the IDE side still needs to be configured to listen and map paths, or nothing will connect.

VSCode (.vscode/launch.json):

{
    "name": "Listen for Govard Xdebug",
    "type": "php",
    "request": "launch",
    "port": 9003,
    "pathMappings": { "/var/www/html": "${workspaceFolder}" }
}

PhpStorm: Settings → PHP → Debug → set debug port to 9003; Settings → PHP → Servers → add a server named <project_name>-docker (the PHP_IDE_CONFIG server name Govard exports), host <project-domain>, port 443, debugger Xdebug, path mapping /var/www/html → project directory.

If it still doesn't connect: check govard debug status, confirm the XDEBUG_SESSION cookie matches stack.xdebug_session in .govard.yml, and confirm the IDE is actually listening on 9003 before triggering a request. Disable Xdebug (govard debug off) when not actively debugging, because it slows down every request noticeably.

Configuration