The Ruby Princess Runs Away

Setting Up The Ruby Princess Runs Away Properly

The Ruby Princess Runs Away is a Ruby-based automation script that handles file synchronization and directory monitoring across distributed environments. It's not particularly flashy, but it does what it needs to do if you configure it right. Most people get tripped up on the initial dependency setup and skip ahead to problems that could have been avoided with a couple extra minutes upfront. At its core, the tool watches specified directories and mirrors changes to a remote endpoint using SSH tunneling by default. It handles file conflicts by naming them with timestamps rather than overwriting, which saves you from losing work when two people push to the same path at the same time. That's actually one of the better design choices in the codebase, though it does create a lot of orphaned files over time if you run it long enough. I spent about three days debugging why certain files weren't syncing across a staging environment, only to realize I had the recursive flag set wrong in the config. The default behavior doesn't follow symbolic links unless you explicitly tell it to. Once I added --follow-symlinks to the watch command, everything started flowing correctly. The documentation mentions this in a footnote on page fourteen, which is not where anyone would look first.

Installation Without Breaking Your Environment

Start by installing Ruby 3.1 or later. The script breaks on older versions because of pattern matching syntax that was added in 3.0. You can check your version with ruby -v before doing anything else. If you're on macOS, the system Ruby is almost certainly too old, so use Homebrew or rbenv to get a current version. Once Ruby is sorted, grab the gem with gem install ruby_princess_runs_away or clone the repository directly from GitHub if you need the development branch. The released version on the gem server tends to lag by a few weeks behind the main branch. If you're running this in production, staying a few weeks behind is usually fine. If you need a recent patch, clone the repo.

Basic Configuration

Create a princess_config.yml file in your project root. Here's what a working minimal config looks like: watch_paths: - /var/www/myapp/public/assets

- /var/www/myapp/uploads remote_host: backup-server.internal remote_path: /mnt/sync/myapp

exclude_patterns: - "*.log" - "tmp/*"

- ".DS_Store" sync_interval: 30 SSH keys need to be set up before you run the first sync. The tool expects key-based authentication, not password login. Generate a key pair with ssh-keygen -t ed25519, copy the public key to the remote server's authorized_keys file, and verify connectivity with ssh backup-server.internal before launching the daemon.

Running It as a Daemon

You can run it in the foreground with princess watch, but that's not useful for anything beyond testing. For production, set it up as a systemd service. Create a file at /etc/systemd/system/princess.service with the standard service unit configuration. Set the user to whichever account owns the watched directories, point the ExecStart to the gem binary, and enable it with systemctl enable princess. I found that running the process under the root user caused permission issues on the remote side. Files were being created with root ownership and then the application couldn't write to them. Running it under the web server user fixed that completely. Check the ownership on your remote target path and match the user accordingly.

Common Problems and Fixes

Sync Delays After Large Uploads

One thing that trips people up is the throttling behavior. When you upload a large batch of files, The Ruby Princess Runs Away will naturally slow down after about fifty concurrent transfers. This is by design to avoid saturating your network link, but it can look like the tool has hung if you're not expecting it. The throttle kicks in at a configurable threshold. Add max_concurrent_transfers: 20 to your config if you're on a high-bandwidth connection and need faster bulk syncs. I set mine to 50 on a dedicated fiber link without issues. The timestamp-based conflict naming can create confusion during audits. You'll see files like style.css.20240315-142203 sitting next to the original. They pile up. I wrote a simple cleanup script that runs weekly to remove conflict files older than seven days, but you can also disable conflict naming entirely and let the tool overwrite older files. That's faster but riskier. Choose based on how often your team pushes simultaneous changes. The tool uses inotify on Linux for file change detection, which is efficient. You won't notice a CPU impact watching thousands of files. Memory usage sits around 40 megabytes for a typical mid-size deployment. The main bottleneck is usually SSH latency, not the script itself. If your remote server is across an ocean, expect sync delays proportional to round-trip time. Running a local mirror and pushing in batches can reduce that overhead significantly.

There's also no built-in encryption beyond what SSH provides, so don't expect the tool to handle sensitive data without additional measures. I wrap the entire sync pipeline in GPG encryption for a client project before it leaves the local machine. It adds about two seconds per transfer but keeps things compliant.

When It Doesn't Work

The Ruby Princess Runs Away simply won't work on Windows without WSL, and even then I've seen inconsistent behavior with the inotify layer. macOS users can run it, but the file system events are less reliable than on Linux due to how FSEvents works compared to inotify. If you're on macOS and need production-grade reliability, consider running the daemon on a Linux box and syncing from there instead. Network interruptions aren't handled gracefully either. If the SSH connection drops mid-transfer, the tool will attempt to reconnect every ten seconds by default. That's fine for a brief outage, but if the remote server is down for hours, you'll accumulate error logs and the sync queue can back up. I've seen cases where the queue grew to over ten thousand pending files after an extended downtime, and the startup time to drain that queue was substantial. Setting queue_depth_limit: 5000 prevents unbounded growth, and anything beyond that gets logged and dropped with a warning. Overall, The Ruby Princess Runs Away is a solid tool for its niche. It's not a replacement for something like rsync over SSH in a cron job if your needs are simple, but when you need persistent, real-time synchronization with conflict handling, it does the job without drama. Just read the config file twice before running it for the first time. I wish I'd done that myself.