Deployer Tasks for Lameco

A collection of common tasks for Deployer to streamline deployment workflows.

Requirements

• PHP 8.4 or higher
• Deployer 7.0 or higher
• MariaDB client tools (mariadb and mariadb-dump) on every host that runs the database tasks (lameco:db_download, lameco:db_upload, lameco:sync, lameco:deactivate) — both locally and on each remote host. The legacy mysql / mysqldump binaries are no longer invoked; see Upgrading from 1.x.

Installation

composer require lameco/deployer-tasks --dev

Or to migrate Capistrano to Deployer

php <(curl -s https://gist.githubusercontent.com/development-lameco/02e829e96ec8e7dd99657c5d65c2a09c/raw) .

Available Tasks

lameco:load

Loads project configuration for use in custom tasks.

• Detects project type (symfony, kunstmaan, craftcms, laravel) by checking for key files and composer packages.
• Sets lameco_project_type, lameco_dump_dir, and lameco_public_dir accordingly.
• These variables are used in default directory settings and can be overridden in your deploy.php.

---

lameco:verify_deploy_branch

Ensures the local branch matches the deployment branch.

• Compares the current local git branch with the branch configured on the host (or --branch when provided).
• Stops the deployment if the branches do not match, preventing asset builds from mismatching the deployed code.
• If deploying to a staging* host without a branch configured, and origin has release/* branches, deployment is halted until a release branch is selected.

---

lameco:db_download

Downloads the remote database and imports it locally.

• Reads the remote .env file to extract DB credentials (supports Symfony, Craft CMS, Laravel formats, and DATABASE_URL).
• Creates a compressed database dump on the remote server.
• Downloads the dump to a local directory (as determined by lameco_dump_dir).
• Reads the local .env for local DB credentials.
• Drops and recreates the local database, then imports the dump.
• Cleans up dump files both remotely and locally.

---

lameco:db_credentials

Displays remote database credentials.

• Reads the remote .env file.
• Extracts and prints the remote DB username and password.

---

lameco:db_open

Opens the remote database of the selected host in Sequel Ace, tunneled over SSH with your local SSH key.

• Reads the remote .env file and extracts DB user, password, name, host and port (supports Symfony DATABASE_URL, Craft CRAFT_DB_* and Laravel DB_*).
• Reads SSH host, port and user from the Deployer host config.
• Resolves the SSH key: uses the host's identity_file if set, otherwise falls back to the first existing of ~/.ssh/id_ed25519, ~/.ssh/id_rsa.
• Builds a mysql:// URL with Sequel Ace's ssh_* query parameters and launches it via open. Sequel Ace then establishes the tunnel itself.
• macOS only. Errors out clearly on other platforms or when credentials/SSH key cannot be resolved.

Example:

dep lameco:db_open staging
dep lameco:db_open production

Notes:

• Sequel Ace must have sandbox access to the SSH key file — grant it in Settings → Files.
• Sequel Ace uses its own strict ssh_known_hosts file (under ~/Library/Containers/com.sequel-ace.sequel-ace/Data/.keys/). On the first connection to a new host, the host key needs to be added — e.g. ssh-keyscan -p 22 host.example.com >> ~/Library/Containers/com.sequel-ace.sequel-ace/Data/.keys/ssh_known_hosts_strict.

---

lameco:db_upload

Uploads a local database dump to a remote host and imports it.

• Looks for the dump file set in dump_file (automatically set by lameco:db_download).
• If dump_file is not set, auto-detects the most recently modified current_*.sql.gz in lameco_dump_dir.
• Uploads the dump to {{deploy_path}}/shared on the remote server.
• Reads the remote .env file to extract DB credentials.
• Drops and recreates the remote database, then imports the dump.
• Cleans up dump files both remotely and locally.

---

lameco:download

Downloads directories from remote to local.

• Downloads each directory in lameco_download_dirs from {{deploy_path}}/shared on the remote to the same path locally.
• By default, downloads ['{{lameco_public_dir}}/uploads'].
• For Craft CMS projects, also downloads the translations directory by default.

---

lameco:upload

Uploads directories from local to remote.

• Uploads each directory in lameco_upload_dirs from local to {{deploy_path}}/shared on the remote.
• By default, uploads ['{{lameco_public_dir}}/uploads'].
• For Craft CMS projects, also uploads the translations directory by default.

---

lameco:sync

Syncs the database and/or uploaded files between two endpoints via SSH streaming.

• Prompts to select a sync scope: Database and files, Database only, or Files only.
• Interactively prompts for a source (data is copied from) and a destination (data is written to). Each can be any configured host or local (your own machine), in either direction — so you can pull a remote down to local, push local up to a remote, or sync one remote to another.
• The endpoint list is grouped for clarity: local first, then staging host(s), then production and any other host(s) — each group keeping its deploy.php declaration order.
• For safety the prompts default to the typical production → staging flow: the source defaults to the first non-staging (production-like) host and the destination defaults to the first staging host (detected via the stage label or staging in the host alias/hostname), even when multiple production hosts are configured.
• Requires confirmation before overwriting data on the destination.
• Database sync: streams the database directly between endpoints by piping mariadb-dump | gzip from the source to gunzip | mariadb on the destination — no temporary files are written to disk. Remote endpoints are reached over SSH; the local endpoint reads credentials from the project-root .env and runs directly.
• File sync: streams directories between endpoints by piping tar — no temporary files are written to disk. Local files live at the project root; remote files live under {{deploy_path}}/shared.
• Restarts PHP-FPM and Supervisor on the destination after the sync completes — skipped when the destination is local.
• Typical usage: sync production data to staging, or pull production data down to your local machine.

Example:

dep lameco:sync

The task will prompt to select the sync scope, source, and destination from local plus the configured hosts.

---

lameco:build_assets

Builds local assets.

• Loads Node.js version from .nvmrc.
• Installs the correct Node.js version using nvm if not already installed.
• Loads nvm in a non-interactive bash shell and runs each command with nvm use, so manual nvm use is not required.
• Enables Corepack if supported by Node.js version (Node 14.19+, 16.9+, or >16).
• Installs dependencies with yarn.
• Builds assets with yarn.
• Appends any flags set in lameco_assets_build_flags to the yarn build command.

---

lameco:upload_assets

Uploads built assets to remote.

• Uploads each directory in lameco_assets_dirs from local to {{release_path}} on the remote.
• Uploads each file in lameco_assets_files from local to {{release_path}} on the remote.
• Default: uploads ['{{lameco_public_dir}}/dist'] for directories, empty array for files.

---

lameco:restart_php

Restarts php-fpm service.

• Restarts the service specified by lameco_php_config (default: php-fpm-{{http_user}}.service) on the remote server.
• Skips if lameco_restart_php is false.

---

lameco:restart_supervisor

Restarts supervisor.

• Restarts each supervisor config in lameco_supervisor_configs using supervisorctl.
• Skips if lameco_restart_supervisor is false.

---

crontab:sync

Synchronizes crontab jobs for the project.

• Automatically sets up crontab jobs based on project type and detected plugins (e.g., Craft CMS with Blitz or Formie).
• Jobs are defined in the crontab:jobs configuration, which is dynamically generated for Craft CMS projects.

---

lameco:update_htpasswd

Updates .htpasswd file for staging environments.

• Automatically checks if the current hostname contains "staging".
• If it's a staging environment, creates or updates the .htpasswd file at /projects/{{http_user}}/.local/nginx/.htpasswd.
• Sets the username to lameco and uses the http_user value as the password, hashed with bcrypt.
• Uses mkpasswd -m bcrypt to generate the password hash as recommended by Rootnet.
• Skips the update if the .htpasswd file is already up-to-date.

---

Parameters

• lameco_project_type: Project type (auto-detected: symfony, kunstmaan, craftcms, laravel)
• lameco_dump_dir: Directory for database dumps (auto-set by project type)
• lameco_public_dir: Public directory (auto-set by project type)
• lameco_download_dirs: Directories to download from remote (default: ['{{lameco_public_dir}}/uploads'], plus translations for Craft CMS)
• lameco_upload_dirs: Directories to upload to remote (default: ['{{lameco_public_dir}}/uploads'], plus translations for Craft CMS)
• lameco_assets_dirs: Asset directories to upload (default: ['{{lameco_public_dir}}/dist'])
• lameco_assets_files: Asset files to upload (default: [])
• lameco_assets_build_flags: Extra flags to append to the yarn build command (default: [])
• lameco_restart_php: Enable/disable PHP-FPM restart (default: true)
• lameco_php_config: PHP-FPM systemd service name (default: php-fpm-{{http_user}}.service)
• lameco_restart_supervisor: Enable/disable supervisor restart (default: true)
• lameco_supervisor_configs: Supervisor config files (default: [get('http_user') . '.conf'])
• http_user: User running PHP-FPM or supervisor

Task Dependencies

• lameco:load runs before deploy
• lameco:verify_deploy_branch runs before deploy
• lameco:db_download, lameco:db_credentials, lameco:download, and lameco:upload depend on lameco:load
• lameco:build_assets runs before deploy:symlink
• lameco:upload_assets runs after lameco:build_assets
• lameco:restart_php and lameco:restart_supervisor run after deploy:cleanup
• crontab:sync and lameco:update_htpasswd run after deploy:success

Usage

Include the tasks in your deploy.php file:

require 'vendor/lameco/deployer-tasks/src/tasks.php';

// Override or extend parameters if needed
set('lameco_assets_dirs', ['public/build']);
add('lameco_supervisor_configs', ['app.conf', 'queue.conf']);
set('lameco_php_config', 'php-fpm-customuser.service');

Notes

• Project type detection is automatic and supports Symfony, Kunstmaan, Craft CMS, and Laravel.
• Database credential extraction supports .env formats for Symfony (DATABASE_URL), Craft CMS (CRAFT_DB_*), and Laravel (DB_*).
• Asset build and upload tasks expect a working Node.js/yarn setup and .nvmrc file.
• lameco:build_assets expects nvm in $NVM_DIR (or ~/.nvm) and uses bash -lc to load it.
• Supervisor and PHP-FPM restarts are configurable and can be disabled per project.
• For staging hosts, configure a deployment branch (or pass --branch) if release/* branches exist to avoid ambiguous deployments.

Upgrading from 1.x

Version 2.0 switches all database CLI invocations from mysql / mysqldump to mariadb / mariadb-dump. This is a breaking change: the affected tasks (lameco:db_download, lameco:db_upload, lameco:sync, lameco:deactivate) will fail with command not found on any host where only the legacy MySQL client is installed.

To upgrade:

1. Install the MariaDB client package locally and on every remote host that runs the database tasks.
   • On Debian/Ubuntu: apt install mariadb-client.
   • On macOS via Homebrew: brew install mariadb.
2. If you cannot install the MariaDB client on a given host, create symlinks as a stopgap:

   ln -s "$(command -v mysql)"     /usr/local/bin/mariadb
   ln -s "$(command -v mysqldump)" /usr/local/bin/mariadb-dump

3. The MYSQL_PWD environment variable is still used for password handling — the MariaDB client honors it for backward compatibility, so no credential changes are required.
4. The lameco:db_open task still builds a mysql:// URL for Sequel Ace; that is a Sequel Ace URL scheme and is unaffected.

Contributing

Commit messages

This repository uses Conventional Commits. Release tags, GitHub Releases and CHANGELOG.md are produced automatically by release-please based on commit prefixes:

Prefix	Effect on next release
feat:	Minor bump (e.g. 1.4.0 → 1.5.0), listed under Features in the changelog
fix:	Patch bump (e.g. 1.4.0 → 1.4.1), listed under Bug Fixes
feat!: or any commit with a BREAKING CHANGE: footer	Major bump (e.g. 1.4.0 → 2.0.0)
docs:, chore:, refactor:, style:, test:, ci:, build:	No version bump, no changelog entry

Example: feat: add lameco:db_open task to open remote DB in Sequel Ace via SSH tunnel

When release-please detects a releasable commit on main, it opens (or updates) a "chore: release X.Y.Z" PR. Merging that PR creates the git tag and a GitHub Release; Packagist auto-discovers the tag.

License

This package is open-sourced software licensed under the MIT license.