Wup

What Wup Actually Does (and Why I Started Using It)

Wup is a command-line deployment and task management toolkit for PHP projects. It was built to solve the same problem Fabric solved for Python and Capistrano solved for Ruby — automating the "get code from git to live server" steps without writing a custom shell script for every deployment. In practice, Wup sits between your local machine and your remote servers, runs tasks defined in a simple YAML config, and handles the boring parts: locking, logging, releases, rollback, and post-deploy hooks. I started using it about two years ago after spending way too much time maintaining ad-hoc rsync scripts across a dozen PHP services. The first thing I noticed was how consistent the workflow became. Instead of copy-pasting ssh commands into a terminal, every team member ran the same commands. The same release directory structure. The same rollback procedure. The same log output. That consistency is worth more than any single feature.

Installation and Basic Setup

Installing Wup is straightforward if you already have PHP 8.1 or later and Composer available on your machine. You install it globally or per-project depending on your preference: composer require wup/wup Then run the init command to scaffold the configuration file:

wup init This creates a wup.yaml file in your project root. The default config looks something like this:

servers:
  production:
    host: 192.0.2.45
    user: deploy
    branch: main
    path: /var/www/myapp
    releases_path: releases
    shared:
      - config/.env
      - storage/logs

tasks:
  deploy:
    - git:checkout
    - composer:install --no-dev --optimize-autoloader
    - php:artisan migrate --force
    - php:artisan config:cache
    - deploy:symlink
    - deploy:cleanup
  rollback:
    - deploy:rollback
    - php:artisan down
    - php:artisan up

The first time I configured this, I forgot the shared section and tried to deploy a .env file into the releases directory. Every new release overwrote the previous environment variables. Wup's symlink-based release structure only makes sense when you understand that each release is a snapshot in time, and shared files live outside that cycle. Once I added the shared configuration, deployments became predictable again. Understanding the release directory structure is the single most important thing to know about Wup. When you trigger a deployment, Wup creates a new timestamped release directory inside your releases/ folder, checks out the code into it, runs your tasks against it, and then atomically symlinks the current pointer to the new release. The old release stays on disk until you run cleanup. This means rollbacks are just a symlink change — typically under 200 milliseconds regardless of application size. The atomic symlink approach is why Wup deployments never leave your application in a half-installed state. Either the old release is live, or the new one is. There's no window where Composer is running and requests are coming in simultaneously, because all work happens in the new release directory before the symlink switches.

Here's what a typical deployment output looks like:

$ wup run deploy --server production

[production] Starting deployment...
[production] Creating release 20240315142230
[production] Cloning repo (branch: main, revision: a3f8c2d)
[production] Running task: composer:install
  Installing dependencies from lock file
  - Installing symfony/console (v6.4.1)
  ... 147 packages installed
[production] Running task: php:artisan migrate --force
  Migrating tables...done
[production] Running task: deploy:symlink
  Switching current  releases/20240315142230
[production] Running task: deploy:cleanup
  Removed releases/20240315130001, 20240315120000
[production] Deployment complete (14.2s)

The timing matters. A typical Laravel app with moderate dependencies deploys in about 12 to 20 seconds over a fast connection. The bottleneck is almost always Composer, not Wup itself. I've seen deployments take 45 seconds on slow staging servers where Composer was downloading packages instead of using a shared cache. There are a few places where Wup quietly does something that trips people up. I'll list the ones that caused the most headaches for me. Parallel task execution is not automatic. If you define multiple tasks in a single job, they run sequentially. Wup respects the order you write them in. I once tried to run a database backup and a cache clear simultaneously, expecting parallel execution, and wasted an hour wondering why the backup was reading a partially-cleared cache. The fix was simple: split them into separate job definitions or add explicit ordering constraints.

Lock files are per-server, not per-project. When you run a deployment, Wup writes a lock file to the server's shared directory. If you run two deployments simultaneously — say, one from CI/CD and one from your local machine — both processes try to acquire the lock. One succeeds and runs. The other waits, then fails with a timeout after the default 30 seconds. I had this happen during a release when the CI pipeline and a manual deployment collided. The solution was to disable manual deployments during CI runs by checking an environment variable in the Wup config, or to increase the lock timeout to 120 seconds if your deployments routinely take longer than 30 seconds. SSH key requirements are strict. Wup expects passwordless SSH access or agent-forwarded keys. If your server requires a passphrase-protected key and you're not running the SSH agent, authentication fails silently in the early connection phase. The error message is unhelpful — it just says "connection failed" without mentioning the key. I learned to run ssh-add -l before every deployment to verify the agent had the right keys loaded. Windows support exists but has quirks. Wup runs on Windows, but the path handling differs from Unix systems. If you develop on Windows and deploy to a Linux server, the path separators in your wup.yaml config don't matter for remote operations, but local tasks that reference paths will break. Keep local-only tasks out of shared configs, or wrap them in conditional logic that checks the operating system.

Advanced Patterns I Use Regularly

Once you get past basic deployments, Wup supports patterns that make it genuinely powerful. Pre-deploy hooks for health checks. Before switching the symlink, you can run a quick smoke test against the new release without making it live. I use this to verify that the application boots and the database migration succeeded:

tasks:
  deploy:
    - git:checkout
    - composer:install --no-dev --optimize-autoloader
    - php:artisan migrate --force
    - deploy:test
    - deploy:symlink
    - deploy:cleanup

deploy:test:
  run: |
    cd {{release_path}}
    php -r "require 'vendor/autoload.php'; echo 'Bootstrap OK';"
    php artisan route:list > /dev/null

This task runs against the new release directory but doesn't affect the live site. If it fails, Wup aborts the deployment and rolls back to the previous release automatically. I've caught three bad migrations this way that would have taken down production. Database migration safety nets. Wup passes migration errors through to the console, but it doesn't auto-rollback failed migrations. If a migration throws an exception mid-execution, you need to handle it manually. I wrote a small helper script that runs migrations in a transaction where possible, and logs the last successful migration ID so I can resume from the right point:

php:artisan migrate --force
php:artisan db:transaction-migrate

The second command isn't built into Wup — it's a custom artisan command I wrote that wraps the migration in a transaction and catches failures. Worth noting that not all database engines support transactional migrations. MySQL InnoDB does, but MyISAM tables silently ignore the transaction wrapper. If you're on MySQL and have any MyISAM tables in your schema, test your migrations on a staging database first. Environment-specific configurations. Wup lets you override server settings per environment using separate config files or environment variables. I keep a wup.production.yaml and wup.staging.yaml and select between them with the --env flag. This keeps sensitive production paths and credentials out of the shared repository config.

Performance Characteristics of Wup in Production

I deployed Wup across five PHP services averaging 120 Composer dependencies each. The median deployment time was 16 seconds on a 1 Gbps connection between the CI server and the production host. The P99 deployment time was 34 seconds, and the outlier at P99.9 was 89 seconds — that one was a network blip, not a Wup problem. Memory usage during deployment peaks at roughly 256 MB for a typical Laravel application, mostly consumed by Composer's autoloader generation. Wup itself uses about 12 MB of PHP memory during task execution. The memory spike happens during composer:install, not during the symlink switch, which completes in under 10 milliseconds. If you're deploying to servers with less than 512 MB of RAM, you may need to set memory_limit = 512M in your PHP configuration before running deployments. Wup won't complain if PHP runs out of memory mid-task, but Composer will exit with a cryptic fatal error and the deployment will fail at the worst possible moment.

Limitations and When to Look Elsewhere

Wup is excellent for what it does, but it's not a universal solution. Here are the scenarios where I recommend considering alternatives. Non-PHP projects. Wup is PHP-centric. It has decent generic SSH task support, but it lacks built-in integration with Node.js, Ruby, or Go ecosystems. If your deployment pipeline includes non-PHP services, you'll find yourself writing shell scripts inside Wup tasks anyway, which defeats part of the purpose. In that case, a tool like Ansible or GitHub Actions might serve you better. Multi-region deployments. Wup can deploy to multiple servers, but it doesn't coordinate zero-downtime rolling updates across regions. You can define multiple servers in your config and deploy to all of them, but there's no built-in traffic shifting or gradual rollout. For blue-green or canary deployments, I pair Wup with a load balancer configuration script or use it alongside a proper orchestration platform.

Database-heavy migrations. If your application has migrations that take several minutes to run, Wup's default timeout settings will cause failures. The lock timeout, the SSH timeout, and the overall deployment timeout all need adjustment. I've seen teams hit the 30-second SSH timeout on migrations that legitimately need 90 seconds. Increase the timeouts in your config and you'll be fine, but it's easy to miss if you're just copying the default configuration. Team onboarding friction. The first time I introduced Wup to a team of four developers, two of them struggled with SSH key setup on their machines. The tool assumes a baseline familiarity with SSH agents and key management. If your team includes people who rarely work at the command line, the learning curve is steeper than it should be. I recommend pairing Wup documentation with a one-time SSH setup workshop before rolling it out.

Where Wup Fits in a Typical Workflow

Here's how I actually use Wup day to day. The CI/CD pipeline triggers a deployment on merge to main. The pipeline runs wup run deploy --server production --env production. If the deployment succeeds, the pipeline logs the release number and marks the build as green. If it fails, the pipeline notifies the team via Slack and leaves the server in the previous release state. Manual deployments happen when something needs immediate attention outside the normal release cycle. I run the same command from my laptop, and the output goes to the terminal. I keep the --verbose flag enabled locally so I can see exactly which task is running and how long each step takes. The verbose output is slightly more than I need in most cases, but it's invaluable when a deployment fails and I need to know whether it was the migration, the cache clear, or the symlink step that caused the issue. Rollbacks are the fastest part of the workflow. A typical rollback takes about 300 milliseconds because it's just a symlink change. I've never had to wait more than a second for a rollback to complete, even on heavily loaded servers. That speed is one of the main reasons I switched from the rsync-based approach I was using before.

Final Thoughts

Wup is not the only tool in this space. Deployer, Capistrano, and Fabric all solve overlapping problems. I chose Wup because its configuration felt the least intrusive to an existing Laravel project, and because the symlink-based release model matched the way I already thought about deployments. Whether that's the right choice for you depends on your stack, your team's comfort level with CLI tools, and how much you value having a rollback button that actually works in under a second. The biggest investment with Wup isn't learning the syntax — it's getting your SSH infrastructure right. Once that's sorted, the rest is mostly copy-pasting configuration from one project to the next. That's a good problem to have.