This guide walks you through deploying a Ruby on Rails application to a Virtual Private Server (VPS) from scratch. You’ll end up with a production-ready app served by Puma and Nginx, with PostgreSQL as the database, running on Ubuntu. Before starting, you should have a Rails app that works locally, a VPS with Ubuntu 22.04 or 24.04, and SSH access to that server.
What You’ll Need
- A VPS with Ubuntu 22.04 or 24.04 (any provider works)
- SSH access to the server (root or a user with sudo privileges)
- A Rails application that runs locally (Ruby 3.x, Rails 7.x recommended)
- A domain name pointing to your server’s IP (optional but recommended for production)
- Git installed on your local machine
- Basic comfort with the command line
Step-by-Step
- Update the server and create a deploy user. SSH into your VPS as root, then run
apt update && apt upgrade -y. Create a new user withadduser deploy, add them to the sudo group withusermod -aG sudo deploy, and switch to them withsu - deploy. Using a non-root user is safer for production. - Install Ruby. Use a version manager like rbenv to install the Ruby version your app needs. As the deploy user, run
sudo apt install -y git curl libssl-dev libreadline-dev zlib1g-dev autoconf bison build-essential libyaml-dev libncurses5-dev libffi-dev libgdbm-dev, thencurl -fsSL https://github.com/rbenv/rbenv-installer/raw/HEAD/bin/rbenv-installer | bash. Add rbenv to your shell by runningecho 'export PATH="$HOME/.rbenv/bin:$PATH"' >> ~/.bashrcandecho 'eval "$(rbenv init -)"' >> ~/.bashrc, then reload withsource ~/.bashrc. Install Ruby withrbenv install 3.2.2(or your app’s version) and set it globally withrbenv global 3.2.2. - Install Node.js and Yarn. Rails needs a JavaScript runtime for the asset pipeline. Install Node.js 18.x with
curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash -thensudo apt install -y nodejs. Enable Yarn withsudo corepack enable. - Install PostgreSQL. Run
sudo apt install -y postgresql postgresql-contrib libpq-dev. Start the service withsudo systemctl start postgresql. Create a database user for your app:sudo -u postgres createuser --createdb deployand set a password withsudo -u postgres psql -c "ALTER USER deploy WITH PASSWORD 'your_strong_password';". Write down this password. - Install Nginx. Run
sudo apt install -y nginx. This will serve static files and proxy requests to Puma. - Clone your app to the server. From your local machine, push your Rails app to a Git repository (GitHub, GitLab, etc.). On the server, as the deploy user, run
git clone https://github.com/yourusername/yourapp.gitin your home directory. Thencd yourapp. - Install dependencies. Run
bundle install --without development testto install gems. Then runyarn installto install JavaScript packages. - Configure the database. Edit
config/database.ymlto use PostgreSQL in production. Set the username todeployand the password to the one you created. You can use environment variables for security:username: <%= ENV['DB_USERNAME'] %>. Create a.envfile in the app directory withDB_USERNAME=deployandDB_PASSWORD=yourpassword. Then runRAILS_ENV=production bundle exec rails db:create db:migrate. - Precompile assets and set the secret key. Run
RAILS_ENV=production bundle exec rails assets:precompile. Generate a secret key withRAILS_ENV=production bundle exec rails secretand add it to your.envfile asSECRET_KEY_BASE=your_generated_key. - Test Puma. Start Puma manually to verify it works:
RAILS_ENV=production bundle exec puma -C config/puma.rb. You should see it listening on port 3000. Press Ctrl+C to stop it. - Create a systemd service for Puma. Create a file
/etc/systemd/system/puma.servicewith sudo. Include the following (adjust paths to match your app):[Unit] Description=Puma HTTP Server After=network.target [Service] User=deploy WorkingDirectory=/home/deploy/yourapp Environment=RAILS_ENV=production EnvironmentFile=/home/deploy/yourapp/.env ExecStart=/home/deploy/.rbenv/shims/bundle exec puma -C config/puma.rb Restart=always [Install] WantedBy=multi-user.target
Then run
sudo systemctl daemon-reloadandsudo systemctl enable --now puma. - Configure Nginx. Create a new Nginx site with
sudo nano /etc/nginx/sites-available/yourapp. Add a server block that listens on port 80, sets the server name to your domain or IP, and proxies requests to Puma. A minimal config looks like:server { listen 80; server_name yourdomain.com; root /home/deploy/yourapp/public; location / { proxy_pass http://127.0.0.1:3000; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; } location ~ ^/assets/ { expires 1y; add_header Cache-Control public; } }Enable the site with
sudo ln -s /etc/nginx/sites-available/yourapp /etc/nginx/sites-enabled/, remove the default site withsudo rm /etc/nginx/sites-enabled/default, and test withsudo nginx -t. Then restart Nginx withsudo systemctl restart nginx. - Open the firewall. If you have UFW enabled, allow SSH and HTTP:
sudo ufw allow OpenSSHandsudo ufw allow 'Nginx Full'. Then enable withsudo ufw enable. - Verify the deployment. Visit your server’s IP or domain in a browser. You should see your Rails app. If not, check the logs with
sudo journalctl -u pumaandsudo tail -f /var/log/nginx/error.log.
Common Mistakes
- Forgetting to set the secret key base. Rails will refuse to start in production without it. Always generate and set it.
- Using the wrong Ruby version. If your app uses 3.2.0 but you installed 3.2.2, bundle may fail. Match exactly.
- Not precompiling assets. If you skip this, Nginx will serve raw Ruby files and your CSS/JS will be broken.
- Hardcoding database credentials. Putting passwords in
database.ymlis a security risk. Use environment variables. - Forgetting to run migrations. Your database tables won’t exist, causing errors at runtime.
Tips
- Use Capistrano or Kamal for future deployments. They automate the process and handle rollbacks gracefully.
- Set up SSL with Let’s Encrypt. Use
sudo apt install certbot python3-certbot-nginxthensudo certbot --nginxto get a free certificate. - Use a swap file if your VPS has little RAM. Rails can be memory-hungry. Create one with
sudo fallocate -l 2G /swapfileand enable it. - Backup your database regularly. Use
pg_dumpand store backups off-server.
Troubleshooting
- 502 Bad Gateway from Nginx. This usually means Puma isn’t running. Check
sudo systemctl status pumaand the logs. Ensure theEnvironmentFilepath is correct and the user has permission to read it. - Assets not loading. Run
RAILS_ENV=production bundle exec rails assets:precompileagain and restart Puma. Also check thatpublic/assetsexists. - Database connection refused. Check that PostgreSQL is running (
sudo systemctl status postgresql) and that the credentials in.envmatch what you set in PostgreSQL. - Puma starts then exits. Look at
sudo journalctl -u puma -n 50. Common causes: missing secret key, wrong database config, or missing gems. - Permission denied when writing to log or tmp. Ensure the deploy user owns the app directory:
sudo chown -R deploy:deploy /home/deploy/yourapp.
Frequently Asked Questions
Do I need to use PostgreSQL?
No, you can use MySQL or SQLite, but PostgreSQL is the most common choice for Rails production because of its reliability and features. Adjust the install steps accordingly.
Can I deploy without a domain name?
Yes, you can use your server’s IP address in the Nginx config. Just set server_name to the IP.
How do I update my app after making changes?
Pull the new code with git pull, run bundle install if dependencies changed, run migrations if needed, precompile assets, and restart Puma with sudo systemctl restart puma.
Is it safe to run Rails as root?
No, always use a non-root user like deploy. Running as root can lead to security vulnerabilities and permission issues.
What if my app uses background jobs like Sidekiq?
You’ll need to install Redis and create a separate systemd service for Sidekiq, similar to the Puma service but with ExecStart=/home/deploy/.rbenv/shims/bundle exec sidekiq.
How do I set up SSL?
Install Certbot with sudo apt install certbot python3-certbot-nginx, then run sudo certbot --nginx -d yourdomain.com. Certbot will automatically configure Nginx and renew the certificate.
Related
General steps for current mainstream versions; menus can differ by device and version. See the disclaimer or report an error.
More in this bed
- Spotify Jam Not Working on Mobile? Fixes That Work
- Windows 10 No Internet Secured WiFi Error Fix
- Multi-Cloud GPU Failover Design Guide
- Error Code Currant Destiny? Meaning & Fixes
- AirPlay with Roku Multi-Device Setup: A How-To
- How to Set a Timer on iPhone (iOS 18 & 17)