FAQ
Common questions, issues, and solutions for Govard.
Try the --local flag to install without sudo:
curl -fsSL https://raw.githubusercontent.com/ddtcorex/govard/master/install.sh | bash -s -- --localThis installs to ~/.local/bin instead of /usr/local/bin.
You've mixed install channels. Pick one channel and clean up the other:
which govard # Find which one is active
ls /usr/bin/govard /usr/local/bin/govard # See both locationsRemove the one from the wrong channel manually. Do not use multiple channels on the same machine.
Govard needs write access to the installed binary path. If using system-wide paths:
sudo govard self-updateOr reinstall to a user-local path with --local.
If image pull fails, try the local fallback:
govard env up --fallback-local-buildThis builds missing Govard-managed images locally from embedded blueprints.
govard doctor # Checks for port conflicts
govard env ps # Check what containers are currently runningEnsure no other service is occupying ports 80, 443, or your project's mapped ports.
Another tracked project already uses the same project_name or domain.
govard project list # See all tracked projectsUpdate project_name or domain in .govard.yml to a unique value.
Run in this order:
govard svc up # Ensure global services are running
govard doctor trust # Re-import Root CAThen manually import ~/.govard/ssl/root.crt into your browser if auto-import fails.
Install certutil first:
# Ubuntu/Debian
sudo apt-get install libnss3-tools
# Then re-run:
govard doctor trustgovard env restart # Re-applies proxy routes and host entriesRun in this order:
govard doctor trust
govard env restartThis exports the Govard Root CA to ~/.govard/ssl/root.crt, then recreates the PHP runtime with that CA mounted and trusted inside the container.
- Ensure systemd-resolved is configured:
cat /etc/systemd/resolved.conf.d/govard-test.conf
- Verify dnsmasq service is running:
govard svc up
- Test DNS resolution:
resolvectl query myproject.test dig +short myproject.test
govard env ps # Check containers are actually running
govard env up # Restart if neededGovard re-renders the compose file on env up. Restart the environment:
govard env upIf you changed stack.php_version or other stack settings, containers need to be recreated.
govard config set only writes to .govard.yml (the base config). Profile and local override files are read-only from the CLI.
Modify stack.composer_version in .govard.yml. Govard optimizes for:
12-
2.2(LTS)
These versions are pre-baked in the image and switch instantly. Any other version (e.g. 2.7.2) will be downloaded automatically on the first env up.
This is correct behavior — skipping optional fixes is reported as INFO (Skipped) instead of ERROR. Your environment is healthy.
govard remote copy-id staging # Copy your SSH key to the remote
ssh-add ~/.ssh/id_rsa # Ensure key is loaded in SSH agent- Use
--no-compressif CPU is a bottleneck:govard sync -s staging --full --no-compress
- Check file exclusions —
--no-noisecan significantly reduce transfer size:govard sync -s staging --db --no-noise
Govard will suggest a permission fix for Magento 2 when this occurs. For manual fix:
govard remote exec staging -- chmod -R 755 /var/www/app/varQuote the path to prevent local expansion:
govard remote add staging --host host.example.com --user deploy --path '~/public_html'
# ^-- single quotesUse --drop to safely reset before import:
govard db import --file backup.sql --dropRun auto-config to inject the correct credentials:
govard config auto # Magento 2: rebuilds env.php with container DB settingsRun a full up to re-register the project:
govard env upThen visit govard open db.
- Check Xdebug is enabled:
govard debug status - Ensure the cookie
XDEBUG_SESSIONmatchesstack.xdebug_sessionin.govard.yml(default:PHPSTORM) - Check your IDE is listening on port 9003
Set a specific Xdebug session name and only trigger it via the cookie/browser extension. Xdebug routes to php-debug only when the session cookie is present.
This is a known AppArmor user namespace restriction issue. The installer handles this automatically, but you can apply manually:
sudo sysctl -w kernel.apparmor_restrict_unprivileged_userns=0You're viewing the frontend directly as a file (no backend active). Start the desktop properly:
govard desktop
# or for dev mode:
DISPLAY=:1 govard desktop --devThis is intentional — self-update detects non-interactive environments and skips heavy system checks to prevent CI timeouts.
The desktop binary is also updated by self-update. If the old version persists, restart the desktop app completely.
govard doctor # Full system diagnostics
govard doctor --json # Machine-readable output
govard doctor --pack # Bundle diagnostics for bug reportsgovard status # All running Govard environments
govard env ps # Current project containers
govard project list # All tracked projectsgovard env cleanup # Remove stale compose files
govard project list --orphans # Find orphaned Docker projects
govard project delete <name> # Remove a project completelygovard env down -v # Stop + remove volumes (databases)
govard env up # Fresh start
govard config auto # Re-inject app configuration (Magento 2)
