ThisCalculator

Everyday

Deploy Fizzy with Kamal on Your Own VPS

Updated · Standard formula, shown below

Deploy Fizzy with Kamal on Your Own VPS

This guide walks you through deploying Fizzy, a self-hosted feed reader, on your own VPS using Kamal, a deployment tool that uses Docker and runs on a single server. By the end, you’ll have a live, HTTPS-secured instance accessible from your domain, with automatic restarts and simple rollbacks.

What You’ll Need

  • A VPS (any provider) with at least 1 GB RAM, running Ubuntu 22.04 or 24.04 (or another Debian-based distro).
  • A domain name pointing to your VPS’s public IP (A record).
  • SSH access to the VPS (root or a user with sudo).
  • Docker and Docker Compose installed on the VPS (Kamal can install them automatically, but pre-installing is faster).
  • Ruby 3.0+ and Bundler installed on your local machine (to run Kamal).
  • Git to clone the Fizzy repository.

Step-by-Step

  1. Clone Fizzy – On your local machine, run git clone https://github.com/mccxiv/fizzy.git and cd fizzy.
  2. Install Kamal – Add gem "kamal" to your Gemfile, then run bundle install. Alternatively, install globally with gem install kamal.
  3. Initialize Kamal – Run kamal init in the Fizzy directory. This creates a config/deploy.yml file.
  4. Edit deploy.yml – Open config/deploy.yml and set:
    • service: fizzy
    • image: your-dockerhub-username/fizzy (or use a private registry)
    • servers: – list your VPS IP under web.
    • proxy: – set host: yourdomain.com and ssl: true (Kamal uses Let’s Encrypt automatically).
    • env: – add SECRET_KEY_BASE (generate with rails secret or openssl rand -hex 64) and any database credentials.
  5. Configure the database – Fizzy uses PostgreSQL. In deploy.yml, add a db service using the postgres:16 image, with a volume for persistence. Set environment variables like DATABASE_URL to point to the db service.
  6. Build and push the image – Run kamal build to build the Docker image locally, then kamal push to push it to your registry.
  7. Install Docker on the VPS (if needed) – Kamal can do this automatically, but you can pre-install by SSHing into the server and running the official Docker install script.
  8. Deploy – Run kamal setup – this installs Docker, creates the necessary directories, and starts the app. Then run kamal deploy to deploy the current version.
  9. Run migrations – After the first deploy, run kamal app exec --reuse "rails db:create db:migrate" to set up the database schema.
  10. Verify – Visit https://yourdomain.com. You should see the Fizzy login page. Create an account and start adding feeds.

Common Mistakes

  • Forgetting to set the domain – If you don’t set the proxy host, Kamal will use the server IP, and SSL won’t work.
  • Not configuring the database URL – Fizzy needs a valid DATABASE_URL. A common mistake is using localhost instead of the service name (e.g., db).
  • Incorrect volume permissions – The PostgreSQL container may fail to start if the volume directory has wrong ownership. Use a named volume (e.g., fizzy-db-data) instead of a bind mount.
  • Missing SECRET_KEY_BASE – Without it, Rails won’t start. Always set it in the environment.
  • Pushing to a private registry without logging in – Kamal needs credentials to push/pull. Use kamal registry login first.

Tips

  • Use a non-root deploy user on the VPS for better security. Kamal supports ssh_user in deploy.yml.
  • Set up a swap file if your VPS has less than 2 GB RAM – Rails and Postgres can be memory-hungry.
  • Use kamal rollback to revert to a previous version if something breaks.
  • Keep your deploy.yml in version control – it’s your deployment recipe.
  • For production, set RAILS_ENV=production in the environment variables.

Troubleshooting

  • SSL certificate fails – Ensure your domain’s A record points to the VPS IP and that port 80 is open. Kamal uses Let’s Encrypt via Traefik; if the cert doesn’t appear, check the Traefik logs with docker logs traefik.
  • Container restarting in a loop – Check logs with kamal app logs. Common causes: missing env vars, database connection refused, or migrations not run.
  • Database connection refused – Verify the DATABASE_URL includes the correct host (service name) and port (5432). Also check that the db container is running with docker ps.
  • Port 80/443 already in use – Stop any existing web server (Apache, Nginx) or change the proxy port in deploy.yml.
  • Build fails on local machine – Ensure Docker is running locally and that you have the latest version. Try kamal build --push to see the full error.
  • Cannot SSH to VPS – Check your SSH key is added to the agent (ssh-add -l) and that the user has sudo privileges.

Frequently Asked Questions

Can I use a different database?

Fizzy is built with Rails and expects PostgreSQL. Using MySQL or SQLite would require code changes, so stick with Postgres.

How do I update Fizzy to a new version?

Pull the latest changes from the repository, run kamal build and kamal deploy. If there are new migrations, run kamal app exec --reuse "rails db:migrate".

Is Kamal free?

Yes, Kamal is open-source and free to use. You only pay for your VPS and domain.

Can I deploy to multiple servers?

Yes, Kamal supports multiple servers, but Fizzy is designed for a single instance. For multi-server, you’d need to configure a shared database and Redis.

How do I back up my data?

Back up the PostgreSQL volume. You can use docker exec to run pg_dump and save the output to a file.

What if I don’t have a domain?

You can use the IP address, but SSL won’t work. For testing, you can set proxy.ssl: false and access via http://IP.

Related

Method: the standard formula for this calculation, rounded as each result states. See how the calculators work or report an error.