atannex / desk-deploy
Universal Laravel deployment engine: atomic releases on VPS servers, in-place deployments to shared hosting over SFTP/FTPS, Git deployments, local and CI builds, artifacts, rollbacks and health checks.
Requires
- php: ^8.3
- ext-curl: *
- ext-json: *
- ext-zip: *
- guzzlehttp/guzzle: ^7.8.2|^8.0
- illuminate/console: ^12.0|^13.0
- illuminate/contracts: ^12.0|^13.0
- illuminate/events: ^12.0|^13.0
- illuminate/filesystem: ^12.0|^13.0
- illuminate/http: ^12.0|^13.0
- illuminate/support: ^12.0|^13.0
- phpseclib/phpseclib: ^3.0.43
- spatie/laravel-package-tools: ^1.92
- symfony/process: ^7.2|^8.0
- symfony/yaml: ^7.2|^8.0
- vlucas/phpdotenv: ^5.6
Requires (Dev)
- larastan/larastan: ^3.0
- laravel/pint: ^1.18
- orchestra/testbench: ^10.0|^11.0
- phpunit/phpunit: ^11.5|^12.0
Suggests
None
Provides
None
Conflicts
None
Replaces
None
README
One Laravel deployment interface. Multiple drivers. Multiple strategies. One consistent lifecycle.
Desk Deploy (atannex/desk-deploy) deploys Laravel applications to VPS and dedicated servers, CloudPanel,
cPanel and shared hosting over SSH, SFTP, FTPS or FTP, without hand-written deployment scripts. It builds
your application locally, in CI or on the server, transfers it safely, runs migrations and optimisation
where the server allows it, verifies the result with health checks, and tells you exactly what it could
not do on hosts with restricted capabilities.
DESK DEPLOY
────────────────────────────────────────────────────
Environment: production
Driver: SSH
Strategy: Atomic
Build: Local
[1/16] Validating configuration ................... PASSED 3ms
[2/16] Connecting to server ....................... PASSED 412ms
[3/16] Running preflight checks ................... PASSED 1.2s
[4/16] Acquiring deployment lock .................. PASSED 95ms
[5/16] Building application ....................... PASSED 48.3s
[6/16] Preparing release .......................... PASSED 120ms
[7/16] Uploading files ............................ PASSED 6.1s
[8/16] Linking shared files ....................... PASSED 210ms
[9/16] Installing dependencies .................... SKIPPED 1ms
[10/16] Enabling maintenance mode ................. SKIPPED 1ms
[11/16] Running migrations ........................ PASSED 2.4s
[12/16] Optimizing Laravel ........................ PASSED 1.9s
[13/16] Linking public storage .................... PASSED 88ms
[14/16] Activating release ........................ PASSED 140ms
[15/16] Running health checks ..................... PASSED 640ms
[16/16] Finalizing deployment ..................... PASSED 310ms
DEPLOYMENT SUCCESSFUL
Release: 20261121180000
Previous release: 20261121173000
Commit: 3f9c2d81a0b4
Duration: 1m 02s
Contents
- Features
- Supported environments
- Requirements
- Installation
- Quick start
- Configuration
- VPS deployment (atomic)
- Shared hosting deployment (in-place)
- Git deployments
- Builds: local, CI, remote and artifacts
- GitHub Actions
- Commands
- Rollback
- Server diagnosis
- Hooks, events and notifications
- Security
- Troubleshooting
- Limitations
- Testing and contributing
Features
- Drivers:
local,ssh,sftp(pure PHP via phpseclib: nossh,scporrsyncbinaries needed),ftpsandftp(libcurl, with TLS certificate verification for FTPS). - Strategies:
atomiczero-downtime releases with acurrentsymlink,in_placesynchronisation for shared hosting, andgitfetch-and-checkout on the server. - Builds: isolated local builds (Composer + npm, pnpm, yarn or bun), CI builds, remote builds and prebuilt, SHA-256 verified artifacts.
- Capability detection: remote execution, symlinks, PHP CLI, Composer, Git, Node and unzip are probed on each target. Nothing is assumed from the driver name.
- Honest reporting: operations that cannot run on a target (for example migrations without shell access) are reported as not executed, together with the manual action required, and the deployment is marked completed with warnings, never plain success.
- Safety: SSH host key verification by default, credential redaction everywhere, path traversal guards,
argv-only command execution, local and remote deployment locks, protected
.envand storage, and deletion limited to files Desk Deploy itself deployed. - Lifecycle: preflight checks, hooks at 14 points, migrations, maintenance mode, optimisation, storage link, health checks (files, Artisan, HTTP), automatic rollback for atomic releases, release retention, JSON history, Laravel events and webhook notifications.
- Developer experience:
deploy:initwizard,deploy:doctordiagnostics, dry runs with a transfer plan, GitHub Actions workflow generation.
Supported environments
| Environment | Driver | Strategy | Support |
|---|---|---|---|
| Ubuntu/Debian VPS, dedicated servers, Hostinger VPS | ssh |
atomic (or git) |
Full |
| CloudPanel | ssh |
atomic |
Full (point the site root at current/public) |
| cPanel with SSH (Terminal enabled) | ssh / sftp |
atomic or in_place |
Full where symlinks are allowed |
| Shared hosting with SFTP only | sftp |
in_place |
Files, .env, public directory, storage link (if symlinks allowed); migrations/optimisation reported as manual actions |
| Shared hosting with FTPS/FTP only | ftps / ftp |
in_place |
Files, .env, public directory; no symlinks and no commands (reported) |
| Local rehearsal / same-machine deploys | local |
any | Full |
| GitHub Actions | any | any | Workflow generation for SSH, SFTP/FTPS and artifact pipelines |
Requirements
- PHP 8.3+ with
zip,curl,jsonandopenssl - Laravel 12 or 13 (verified with both)
- Composer 2
- On the deploying machine, only what your build needs: Composer for local builds, and Node with your package manager if you build frontend assets. Git is needed only for building from a Git ref.
- Nothing is required on the server beyond file access. SSH, Composer, Git, Node, unzip and symlinks are used when they are available.
Installation
composer require atannex/desk-deploy php artisan deploy:install
The service provider is registered through package discovery. deploy:install publishes
config/desk-deploy.php, creates the git-ignored local storage directory (storage/desk-deploy) and
offers to start the interactive setup. To publish the configuration manually:
php artisan vendor:publish --tag=desk-deploy-config
Install Desk Deploy as a regular dependency (not
--dev) if you deploy from CI withcomposer install --no-dev, because the deploy command must be available in that checkout.
Quick start
php artisan deploy:init # answer a few questions; writes config + non-secret .env values php artisan deploy:trust production # SSH/SFTP only: verify and trust the server host key php artisan deploy:doctor production # check your machine, the configuration and the server php artisan deploy production --dry-run php artisan deploy production
Configuration
Everything lives in config/desk-deploy.php. Each entry of environments is a deployment target. The
global build, transfer and lock sections are inherited by every environment and can be overridden per
environment (associative arrays merge key by key, lists such as exclude replace the global list).
'environments' => [ 'production' => [ 'driver' => 'ssh', 'strategy' => 'atomic', 'confirm' => true, 'connection' => [ 'host' => env('DESK_DEPLOY_HOST'), 'port' => (int) (env('DESK_DEPLOY_PORT') ?: 22), 'username' => env('DESK_DEPLOY_USERNAME'), 'private_key' => env('DESK_DEPLOY_PRIVATE_KEY'), // path, or the key itself (CI secrets) 'passphrase' => env('DESK_DEPLOY_PASSPHRASE'), 'host_key' => env('DESK_DEPLOY_HOST_KEY'), // "SHA256:..." (or use deploy:trust) ], 'path' => '/var/www/example.com', 'url' => 'https://example.com', 'releases' => ['keep' => 5], 'shared' => ['files' => ['.env'], 'directories' => ['storage'], 'env_file' => null], 'migrations' => ['enabled' => true, 'command' => 'migrate --force'], 'optimize' => ['enabled' => true, 'commands' => ['optimize']], 'health_check' => ['url' => '/up', 'expected_status' => 200, 'retries' => 3], 'rollback' => ['automatic' => true], 'hooks' => [ 'after_activate' => ['php artisan queue:restart'], ], ], ],
Credentials always come from environment variables (or CI secrets). deploy:init never writes passwords
or passphrases to any file. php artisan deploy:validate checks a configuration without connecting.
The complete reference, including every key and default, is in docs/configuration.md.
VPS deployment (atomic)
Atomic deployments create a fresh release directory for every deployment and switch a symlink only when the release is complete, migrated and optimised:
/var/www/example.com
├── current -> releases/20261121180000
├── releases/
│ ├── 20261121173000/
│ └── 20261121180000/
├── shared/
│ ├── .env
│ └── storage/
└── .desk-deploy/ (release metadata, lock, upload staging)
- Point the web server document root at
/var/www/example.com/current/public. - Put the production
.envatshared/.envon the server, or setshared.env_fileto a local file (for example.env.production, kept out of version control) to upload it on every deployment. - Trust the host key once:
php artisan deploy:trust production. - Deploy:
php artisan deploy production.
If unzip is available on the server, the release is uploaded as a single verified archive and extracted
remotely; otherwise files are uploaded individually. When anything fails after activation (a health check,
an aborting after_activate/after_deploy hook), the previous release is restored automatically
(configurable). The active release is never deleted, and old
releases are pruned according to releases.keep.
Shared hosting deployment (in-place)
Shared hosting is a primary target. The recommended flow builds everything on your machine (or in CI) and transfers only the result:
Developer machine / CI ── composer --no-dev, frontend build, exclusions ──▶ SFTP / FTPS / FTP ──▶ host
'shared-host' => [ 'driver' => 'sftp', // or 'ftps' / 'ftp' 'strategy' => 'in_place', 'connection' => [ 'host' => env('DESK_DEPLOY_SHARED_HOST'), 'port' => 22, 'username' => env('DESK_DEPLOY_SHARED_USERNAME'), 'password' => env('DESK_DEPLOY_SHARED_PASSWORD'), ], 'path' => '/home/account/laravel', // the application, outside the web root 'public_path' => '/home/account/public_html', // receives public/, with a rewritten index.php 'url' => 'https://example.com', 'shared' => ['env_file' => '.env.production'], 'health_check' => ['url' => '/up'], ],
- Only new and changed files are uploaded, based on a manifest Desk Deploy keeps on the server. Each file is uploaded under a temporary name and renamed into place.
.env,storage/and Desk Deploy's metadata are protected and never overwritten.- Files are deleted only when
transfer.delete_removed_filesis enabled, and only if a previous Desk Deploy deployment uploaded them. Files you created on the server are never deleted. - With
public_path, the contents ofpublic/are published to the web root andindex.phpis rewritten to load the application frompath.
When the host cannot run commands, the deployment completes with warnings and tells you exactly what to do:
DEPLOYMENT COMPLETED WITH WARNINGS
Not executed:
- Database migrations (remote execution is unavailable)
- Laravel cache optimization (remote execution is unavailable)
- Storage symlink creation (symbolic links are not supported on this target)
Required manual actions:
- Run "php artisan migrate --force" using your hosting terminal.
- Run "php artisan optimize:clear" and then "php artisan optimize" on the server so stale cached configuration is not used.
- Create the public/storage link from your hosting control panel, or serve uploaded files through a route.
In-place deployments cannot be rolled back automatically, because files are overwritten. See docs/shared-hosting.md.
Git deployments
The git strategy fetches and checks out a commit inside path on the server, then runs Composer there
(and the frontend build if Node is installed). It needs SSH access with Git and Composer on the server.
'staging' => [ 'driver' => 'ssh', 'strategy' => 'git', 'build' => ['mode' => 'remote'], 'git' => ['repository' => 'git@github.com:acme/app.git', 'branch' => 'main'], // ... ],
php artisan deploy staging --branch=release/2.4 php artisan deploy staging --commit=3f9c2d81
Uncommitted changes to tracked files on the server abort the deployment unless
git.discard_local_changes is true. A server checkout of a different repository is refused.
Builds: local, CI, remote and artifacts
| Mode | What happens |
|---|---|
local |
Sources are copied to an isolated workspace in storage/desk-deploy/builds (or exported from a Git ref with --branch/--commit or build.source = git). composer install --no-dev and the frontend build run there. Your project directory is never modified. |
ci |
The current checkout is deployed as it is; CI has already run Composer and the frontend build. |
remote |
Sources are uploaded and dependencies are installed on the server (requires Composer there). |
artifact |
A prebuilt zip is deployed after its SHA-256 checksum and contents have been verified. |
The frontend package manager (npm, pnpm, yarn, bun) is detected from packageManager and the lock files,
and can be overridden. Vite reads VITE_* variables from .env; set build.env_file to make a file
available as .env during the build only.
php artisan deploy:build production --output=build/app.zip # creates app.zip and app.zip.sha256
php artisan deploy production --build=artifact --artifact=build/app.zip
Artifacts never contain .env files, .git, node_modules, tests or local storage contents.
Exclusions use .gitignore syntax and are configurable (transfer.exclude and transfer.include).
GitHub Actions
php artisan deploy:init production --github
This generates .github/workflows/deploy.yml (SSH, SFTP/FTPS or two-job artifact pipeline) that checks out
the code, sets up PHP, installs production dependencies, builds frontend assets when the project has a build
script, optionally runs your tests, and deploys with Desk Deploy on pushes to the chosen branch or on manual
dispatch. Git-strategy environments get a dedicated workflow that deploys the pushed commit. Credentials are
only written as ${{ secrets.* }} references; non-secret settings (driver, strategy, paths, URLs) are written
as plain values so CI deploys exactly the configured target. The command lists the secrets to create. The
generated YAML is parsed and validated before it is written. See docs/github-actions.md.
Commands
| Command | Purpose |
|---|---|
php artisan deploy:install |
Publish the configuration and prepare local storage |
php artisan deploy:init [env] [--github] |
Interactive setup of an environment (and workflow) |
php artisan deploy [env] |
Deploy |
php artisan deploy:build [env] [--mode=local|ci] [--output=] |
Build a checksummed artifact |
php artisan deploy:rollback [env] [--release=] [--database] |
Restore a previous release |
php artisan deploy:status [env] |
Active/previous release, recent releases, lock, capabilities |
php artisan deploy:history [env] [--id=] [--json] |
Deployment history recorded on this machine |
php artisan deploy:doctor [env] |
PASS/WARN/FAIL diagnostics of machine, configuration and server |
php artisan deploy:validate [env] [--all] |
Validate configuration without connecting |
php artisan deploy:servers |
List configured environments |
php artisan deploy:cleanup [env] [--hours=24] |
Prune old releases and temporary files |
php artisan deploy:trust [env] [--fingerprint=] |
Verify and trust an SSH host key |
Every command is also available with the desk-deploy: prefix (desk-deploy for deploy).
deploy options:
| Option | Effect |
|---|---|
--dry-run |
Validate, connect read-only, run preflight checks and print the transfer plan and operations. Nothing is changed. |
--force |
Skip the confirmation prompt (required in non-interactive sessions for environments with confirm) and allow breaking stale locks |
--build= |
Override the build mode (local, ci, remote, artifact) |
--artifact= |
Artifact for --build=artifact |
--strategy= |
Override the strategy |
--branch= / --commit= |
Git strategy target, or Git ref for local builds |
--skip-build |
Package sources without running Composer/Node |
--skip-migrations |
Do not run migrations (reported as a warning) |
--skip-health-check |
Do not verify the deployment (reported as a warning) |
-v, -vv |
Show stage details and command output |
Pressing Ctrl+C cancels the deployment after the current stage; the lock is released and an atomic release that was not activated is removed.
Rollback
php artisan deploy:rollback production # previous successful release
php artisan deploy:rollback production --release=20261121173000
- Atomic:
currentis pointed at the earlier release, then health checks run. - Git: the release's recorded commit is checked out and dependencies are reinstalled.
- In-place: not supported. Redeploy a known good commit instead (
--commit=withbuild.source = git).
The database is never rolled back implicitly. --database runs migrations.rollback_command from the
newer release, and only when migrations.rollback_database is explicitly enabled. See
docs/rollback.md.
Server diagnosis
php artisan deploy:doctor production checks the local PHP and Laravel versions, PHP extensions (local and
remote), build tools, connectivity and authentication, host key verification, capabilities, the destination
directory and layout, write permissions, disk space, the remote PHP version, the production .env, and the
Git checkout for Git deployments. Each check prints PASS, WARN or FAIL with a hint, followed by
the capability report. The command exits non-zero if any check fails.
Hooks, events and notifications
Hooks run at before_deploy, before_build, after_build, before_upload, after_upload,
before_migrate, after_migrate, before_activate, after_activate, after_health_check, after_deploy,
on_failure, before_rollback and after_rollback:
'hooks' => [ 'before_migrate' => ['php artisan backup:run --only-db'], 'after_activate' => [ 'php artisan queue:restart', ['run' => 'php artisan horizon:terminate', 'on_failure' => 'continue', 'timeout' => 60], ], 'after_build' => [['run' => ['npm', 'run', 'sentry:sourcemaps'], 'on' => 'local']], ],
Hooks are executed as argument arrays. Shell syntax (&&, |, >, $VAR) is rejected unless the hook sets
'shell' => true. Hooks run arbitrary commands with your server account's permissions: only configure
commands you trust. Every hook receives DESK_DEPLOY_ENVIRONMENT, DESK_DEPLOY_RELEASE,
DESK_DEPLOY_COMMIT and related variables.
Laravel events: DeploymentStarted, DeploymentStageStarted, DeploymentStageCompleted,
DeploymentCompleted, DeploymentFailed, RollbackStarted, DeploymentRolledBack and CleanupCompleted
(namespace Atannex\DeskDeploy\Events). Listen to them for Slack, email, monitoring or audit logs.
A JSON webhook compatible with Slack/Mattermost/Discord incoming webhooks is built in:
DESK_DEPLOY_WEBHOOK_URL=https://hooks.slack.com/services/...
Security
- Host keys are verified before credentials are sent. Unknown keys are rejected. Trust a server with
deploy:trust(fingerprint confirmation) or pinconnection.host_key. A changed key is always refused. - FTPS verifies certificates (
connection.ca_filefor private CAs). Plain FTP always warns. - Secrets (passwords, passphrases, private keys, tokens, URL credentials) are masked in logs, exceptions, terminal output, history and webhooks. Generated files only reference environment variables or GitHub secrets.
- Credential files are never shipped:
.envfiles (except.env.example),.git/,auth.json,.npmrc,.git-credentials,.netrcand the files named byshared.env_file,build.env_fileandconnection.private_keyare excluded from every build and artifact, whatevertransfer.excludesays. Child processes (Composer, npm, hooks) do not inheritDESK_DEPLOY_*credentials or the deploying application's.envvalues. Local builds and artifacts are private (0700/0600). - Commands run as argv arrays with timeouts and exit code checks. Remote arguments are quoted.
- Paths are normalised;
.., NUL bytes and escapes outside the deployment directory are rejected. Deletion is limited to release directories and to files Desk Deploy deployed. The active release is never removed. The local driver refuses destinations that overlap the running project. - Artifacts are SHA-256 verified locally and again on the server, and inspected for traversal, symlinks and environment files before extraction.
- Locks prevent concurrent deployments, both on the deploying machine and on the server.
See docs/security.md and SECURITY.md.
Troubleshooting
| Symptom | Fix |
|---|---|
The host key of ... is not trusted yet |
Run php artisan deploy:trust <env> and compare the fingerprint with your provider's |
HOST KEY MISMATCH |
The server key changed or the connection is intercepted. Verify with your provider before updating the trust |
[...]/current is a real directory |
The path already contains an application. Deploy atomic releases to an empty path |
Shared file [.../shared/.env] does not exist |
Upload the production .env there, or set shared.env_file |
already being deployed |
Another deployment holds the lock. Wait, or run with --force once the lock is stale |
| Migrations not executed on shared hosting | Expected without shell access. Run them from the hosting terminal (listed under Required manual actions) |
| FTPS certificate errors | Use the host's real hostname, or set connection.ca_file. Avoid disabling verify_peer |
More in docs/troubleshooting.md.
Limitations
- In-place deployments are not atomic per release and cannot be rolled back (files are synchronised individually and each file is replaced atomically).
- The remote lock uses write-then-verify, because SFTP/FTP offer no exclusive create. It prevents accidental concurrency but is not a distributed consensus lock.
- No built-in database backups: use a
before_migratehook (for example a backup package's command). - No remote HTTP deployment agent is included. It was deliberately left out, because it could not be offered with the required security guarantees.
- Artifacts are zip only. FTP permissions (
SITE CHMOD) are opt-in and server dependent. - Deployment history is stored on the machine that runs the deployment (release metadata, used for status and rollback, lives on the server).
- Windows servers are not supported as SSH targets (remote commands assume a POSIX shell).
Testing and contributing
composer test # PHPUnit: unit, feature and integration suites composer analyse # PHPStan (Larastan) level 6 composer format # Laravel Pint
The SSH/SFTP and FTP/FTPS integration tests run against real local servers when DESK_DEPLOY_TEST_PYTHON
points to a Python interpreter with asyncssh, pyftpdlib and pyopenssl. See
CONTRIBUTING.md.
License
MIT. See LICENSE.