Search by

atannex / desk-deploy

Atanga1920

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.

Package info

github.com/atannex/desk-deploy

pkg:composer/atannex/desk-deploy

Statistics

Installs: 39

Dependents: 0

Suggesters: 0

Stars: 0

Open Issues: 0

v1.0.1 2026-11-22 00:39 UTC

This package is auto-updated.

Last update: 2026-11-22 00:40:20 UTC


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

  1. Features
  2. Supported environments
  3. Requirements
  4. Installation
  5. Quick start
  6. Configuration
  7. VPS deployment (atomic)
  8. Shared hosting deployment (in-place)
  9. Git deployments
  10. Builds: local, CI, remote and artifacts
  11. GitHub Actions
  12. Commands
  13. Rollback
  14. Server diagnosis
  15. Hooks, events and notifications
  16. Security
  17. Troubleshooting
  18. Limitations
  19. Testing and contributing

Features

  • Drivers: local, ssh, sftp (pure PHP via phpseclib: no ssh, scp or rsync binaries needed), ftps and ftp (libcurl, with TLS certificate verification for FTPS).
  • Strategies: atomic zero-downtime releases with a current symlink, in_place synchronisation for shared hosting, and git fetch-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 .env and 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:init wizard, deploy:doctor diagnostics, 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, json and openssl
  • 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 with composer 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)
  1. Point the web server document root at /var/www/example.com/current/public.
  2. Put the production .env at shared/.env on the server, or set shared.env_file to a local file (for example .env.production, kept out of version control) to upload it on every deployment.
  3. Trust the host key once: php artisan deploy:trust production.
  4. 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.

See docs/vps-deployment.md.

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_files is 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 of public/ are published to the web root and index.php is rewritten to load the application from path.

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: current is 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= with build.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 pin connection.host_key. A changed key is always refused.
  • FTPS verifies certificates (connection.ca_file for 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: .env files (except .env.example), .git/, auth.json, .npmrc, .git-credentials, .netrc and the files named by shared.env_file, build.env_file and connection.private_key are excluded from every build and artifact, whatever transfer.exclude says. Child processes (Composer, npm, hooks) do not inherit DESK_DEPLOY_* credentials or the deploying application's .env values. 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_migrate hook (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.