Skip to content
Klutch.sh Docs

Deploying a Pgweb App

Pgweb is a web-based database browser for PostgreSQL, written in Go. It provides a simple, user-friendly interface for managing and visualizing PostgreSQL databases, making it easy to run queries, view tables, and explore your data from any browser.

This guide explains how to deploy a Pgweb application to Klutch.sh, both with and without a Dockerfile. It also covers installation and provides sample code to get started.

Prerequisites

  • Go 1.20+ (if building from source)
  • Git and GitHub account
  • Klutch.sh account

Getting Started: Install Pgweb

  1. Download the latest Pgweb binary from Pgweb Releases or build from source:
    Terminal window
    go install github.com/sosedoff/pgweb@latest
  2. Run Pgweb locally:
    Terminal window
    pgweb --bind=0.0.0.0 --port=8081 --url=postgres://user:pass@host:port/dbname
    Visit http://localhost:8081 to see Pgweb running.

Sample Command

Terminal window
pgweb --bind=0.0.0.0 --port=$PORT --url=postgres://user:pass@host:port/dbname

Deploying Without a Dockerfile

  1. Push your Pgweb config or wrapper script to a GitHub repository.
  2. Log in to Klutch.sh.
  3. Create a new project and give it a name.
  4. Create a new app:
    • Select your Pgweb GitHub repository and branch
    • Set the port to route traffic (usually 8081 for Pgweb)
    • Choose region, compute, number of instances, and add any environment variables
  5. Add a start command in your app settings:
    Terminal window
    pgweb --bind=0.0.0.0 --port=$PORT --url=postgres://user:pass@host:port/dbname
    (Klutch.sh will provide the PORT environment variable.)
  6. Click “Create” to deploy. Klutch.sh will build and deploy your app automatically.

Deploying With a Dockerfile

  1. Add a Dockerfile to your project root. Example: 
    # Use official Pgweb image
    FROM sosedoff/pgweb:latest
    

    # Expose port (match your Pgweb app)
    EXPOSE 8081
    

    # Start the app
    CMD ["pgweb", "--bind=0.0.0.0", "--port=$PORT", "--url=postgres://user:pass@host:port/dbname"]
  2. Push your code (with Dockerfile) to GitHub.
  3. In Klutch.sh, follow the same steps to create a project and app, but select the Dockerfile option when prompted.
  4. Set the service details and environment variables as needed.
  5. Click “Create” to deploy. Klutch.sh will build your Docker image and deploy your app.

Note: Your Pgweb app should always listen on the PORT environment variable as shown above.

Resources

Deploying to Klutch.sh is simple and flexible. Choose the method that best fits your workflow and project requirements.