How to install PgHero on Ubuntu 20.04
You’ll learn how to get PgHero up and running on a fresh Ubuntu 20.04 machine in under ten minutes, plus a few handy tweaks that keep it humming smoothly.
1. Update the system and grab the basics
sudo apt update && sudo apt upgrade -y sudo apt install -y curl gnupg2 build-essential libpq-dev git
libpq-dev is essential; without it PgHero’s Ruby bindings will refuse to compile, a pain I’ve seen many newcomers run into.
2. Install PostgreSQL (if you don’t already have one)
sudo apt install -y postgresql postgresql-contrib sudo systemctl enable --now postgresql
PgHero talks directly to the database, so make sure it can reach a running instance. On Ubuntu 20.04 the default config listens only on localhost, which is fine for development.
3. Create a dedicated user for PgHero
sudo -u postgres psql CREATE USER pghero WITH PASSWORD 'changeme'; GRANT CONNECT ON DATABASE postgres TO pghero; ALTER ROLE pghero SET client_encoding TO 'utf8'; \q
I’ve seen this step skipped, and the app crashes with “permission denied” when it can’t connect. Give it a proper role.
4. Install Ruby (via rbenv for version control)
sudo apt install -y git-core libssl-dev zlib1g-dev curl -fsSL https://github.com/rbenv/rbenv-installer/raw/main/bin/rbenv-installer | bash echo 'export PATH="$HOME/.rbenv/bin:$PATH"' >> ~/.bashrc echo 'eval "$(rbenv init -)"' >> ~/.bashrc source ~/.bashrc git clone https://github.com/rbenv/ruby-build.git "$HOME/.rbenv/plugins/ruby-build" cd $HOME/.rbenv/plugins/ruby-build && ./install.sh rbenv install 3.1.2 rbenv global 3.1.2 gem install bundler --no-document
PgHero works best on Ruby ≥ 2.5, but I prefer the stability of 3.1 on Ubuntu 20.04. The --no-document flag keeps your gem installation lean.
5. Pull PgHero’s source and install the gem
git clone https://github.com/ankane/pghero.git cd pghero bundle install --without development test
Bundler pulls in all runtime dependencies, so you won’t be surprised by missing gems later on.
6. Configure database access for PgHero
Create a .env file (or export env vars) with the connection string:
echo "PGHERO_DATABASE_URL=postgres://pghero:changeme@localhost/postgres" > .env
Replace changeme with your real password, and adjust the database name if you want to monitor a different one.
7. Start PgHero locally
bundle exec pghero -b localhost:3000 --port 8081
The -b flag binds to localhost only; that’s what most devs expect. The port can be anything free—8081 is my favorite because it doesn’t clash with other services.
You’ll see something like:
[INFO] PgHero listening on http://localhost:8081
Open that URL in your browser and you’re in. If you get a “404 Not Found” error, double‑check the .env file; a typo in the password or hostname will throw the whole thing off.
8. Common pitfalls (and how to avoid them)
- Missing libpq-dev – causes pg gem compilation errors. I hit this once after upgrading to Ubuntu 20.04 and forgetting the dev package.
- Wrong Ruby version – PgHero refuses to start if your Ruby is older than 2.5. Check with ruby -v.
- Port conflict – if something else already listens on 8081, pick another port in step 7.
- Database permissions – if PgHero can’t query the catalog tables you’ll see “permission denied” errors. The role created earlier solves this.
9. (Optional) Run PgHero as a background service
Create /etc/systemd/system/pghero.service:
[Unit] Description=PgHero monitoring [Service] User=yourusername WorkingDirectory=/home/yourusername/pghero ExecStart=/home/yourusername/.rbenv/shims/bundle exec pghero --port 8081 Restart=always EnvironmentFile=/home/yourusername/pghero/.env [Install] WantedBy=multi-user.target
Then:
sudo systemctl daemon-reload sudo systemctl enable --now pghero.service
Now PgHero will start on boot and you can check its status with systemctl status pghero.
