Troubleshooting

Common issues and how to fix them. If you're stuck, start here.

Connection Issues

"Permission denied (publickey)"

This means SSH can't authenticate with your server. Here's how to fix it:

1. Verify your public key is on the server

   SSH into your server manually and check:

   cat ~/.ssh/authorized_keys

   Your public key should be listed there.

2. Verify your private key in Ship It Squirrel

   Make sure you pasted the entire private key, including the -----BEGIN and -----END lines.

3. Check the SSH user

   For new DigitalOcean droplets, the user is root. After provisioning, Ship It Squirrel creates a deploy user.

"Connection refused" or "Connection timed out"

The server isn't accepting connections. Check:

• Is the server running? Check your DigitalOcean dashboard
• Is the IP address correct? Typos happen!
• Is SSH running? If you can access the DigitalOcean console, run: systemctl status ssh
• Is the firewall blocking port 22? Run: ufw status to check

"Host key verification failed"

This usually happens if you've reinstalled the server. The SSH fingerprint changed and your computer is being cautious.

Remove the old key from your known_hosts:

Provisioning Issues

Provisioning seems stuck

Provisioning installs a lot of software and can take 5-10 minutes. If it's been longer:

1. Check the server status in your dashboard
2. Try SSHing into the server manually to see if it's responsive
3. Check the Rails logs for any error messages

"E: Unable to locate package"

The package manager's cache is out of date. SSH into your server and run:

Then try provisioning again.

Ruby installation failed

This is usually a memory issue on smaller droplets. Make sure you have at least 2GB of RAM. If you're on a 1GB droplet, you can add swap space:

fallocate -l 2G /swapfile
chmod 600 /swapfile
mkswap /swapfile
swapon /swapfile
echo '/swapfile none swap sw 0 0' >> /etc/fstab

Deployment Issues

"bundle install" failed

Common causes:

• Missing native dependencies - Some gems need system libraries. Check the error message for which library is missing.
• Out of memory - Try adding swap space (see above)
• Bundler version mismatch - SSH in and run: gem install bundler

"rails assets:precompile" failed

Asset compilation can fail for several reasons:

• Node.js/Yarn issues - Make sure yarn install completed successfully
• Missing environment variables - Some assets need RAILS_ENV=production and a valid SECRET_KEY_BASE
• Out of memory - Asset compilation is memory-intensive. Consider a larger droplet or add swap.

"rails db:migrate" failed

Database migration issues:

• Database doesn't exist - Run rails db:create first
• Permission denied - Check your DATABASE_URL has the right credentials
• Migration error - Check the specific error message. You may need to fix the migration and redeploy.

App deployed but shows "502 Bad Gateway"

This means Caddy is running but can't reach your Rails app. Check if Puma is running:

If it's not running, check the logs:

App shows old version after deploy

The current symlink might not have updated. Check it:

If it points to an old release, you can manually update it:

cd /var/www/yourapp
ln -sfn releases/LATEST_RELEASE_FOLDER current
systemctl restart yourapp-puma

Rails Credentials Issues

"ActiveSupport::MessageEncryptor::InvalidMessage"

Your Rails master key doesn't match your credentials file. Make sure:

1. You're using the production key, not the development one
2. The key in Ship It Squirrel matches config/credentials/production.key
3. Your config/credentials/production.yml.enc file exists and is committed to git

To check your key:

"Missing encryption key"

Rails can't find your master key. Either:

1. Add the key to Ship It Squirrel (App settings > Rails Master Key)
2. Or set the RAILS_MASTER_KEY environment variable

SSL/HTTPS Issues

"Your connection is not private"

Caddy should automatically get SSL certificates, but it needs:

• A real domain - Not an IP address
• DNS pointing to your server - The domain must resolve to your server's IP
• Ports 80 and 443 open - Check your firewall: ufw status

Check Caddy's logs:

Still Stuck?

Getting more information

SSH into your server and check these logs:

# Rails app logs
journalctl -u yourapp-puma -f

# Caddy (web server) logs
journalctl -u caddy -f

# PostgreSQL logs
journalctl -u postgresql -f

# System logs
journalctl -f

Common debugging commands

# Check disk space
df -h

# Check memory
free -m

# Check running processes
htop

# Check what's listening on ports
ss -tlnp

# Check systemd services
systemctl list-units --type=service --state=running