🚀 Host pgAdmin as a Website on Google Cloud Run with Cloud SQL

Easily deploy pgAdmin as a public website on Google Cloud Run, securely connect to Cloud SQL, and manage your PostgreSQL databases from anywhere.

---

Built for Mac users.

_{For Windows/Linux, adapt the commands or ask your favorite LLM for equivalents.}

---

📚 Table of Contents

• ✨ Overview
• 🛠️ Prerequisites
• ⚡ Step 1: Initialize gcloud and Docker
• 📁 Step 2: Project Setup
• 🐳 Step 3: Build the Docker Image
• ☁️ Step 4: Deploy to Cloud Run with Cloud SQL Proxy
• 🌐 Step 5: Connect Your Domain via Cloudflare
• 🩺 Troubleshooting
• 💡 Key Takeaways
• 🔗 Alternatives & Further Reading
• 🤝 Contributing

---

✨ Overview

• 🌍 Host pgAdmin (a PostgreSQL admin tool) as a website using Cloud Run.
• 🔒 Securely connect pgAdmin to your Google Cloud SQL database using the Cloud SQL Proxy.
• ⚡ Preload your database connection for easy access.

---

🛠️ Prerequisites

You’ll need:

• 🏦 Google Cloud account with billing enabled
• 🐘 Cloud SQL PostgreSQL instance (with credentials)
• 💻 Macbook

---

⚡ Step 1: Initialize gcloud and Docker

Expand for setup commands

# Install gcloud CLI (if not already installed)
# Visit: https://cloud.google.com/sdk/docs/install

# Authenticate with your Google Cloud account
gcloud auth login

# Update if needed
gcloud components update

# Find your Project ID and Project Number at: https://console.cloud.google.com/welcome

# Set your project ID
gcloud config set project $YOUR_PROJECT_ID

# Enable required APIs
gcloud services enable run.googleapis.com
gcloud services enable sqladmin.googleapis.com
gcloud services enable artifactregistry.googleapis.com

# Grant Cloud SQL Client permissions to Cloud Run service account
gcloud projects add-iam-policy-binding $YOUR_PROJECT_ID \
  --member="serviceAccount:$YOUR_PROJECT_NUMBER-compute@developer.gserviceaccount.com" \
  --role="roles/cloudsql.admin"

---

# Install Docker Desktop (if not already installed)
# Visit: https://www.docker.com/products/docker-desktop/

# Start Docker Desktop
# On macOS, launch Docker Desktop from Applications

# Verify Docker is running
docker --version
docker ps

---

# Create a repository for your Docker images
gcloud artifacts repositories create pgadmin-repo \
  --repository-format=docker \
  --location=us-central1 \
  --description="Repository for pgAdmin Docker images"

---

📁 Step 2: Project Setup

Expand for project structure & templates

mkdir pgadmin-cloudrun
cd pgadmin-cloudrun
touch Dockerfile servers.json

Open the project in your IDE:

code .

---

Dockerfile template:

FROM dpage/pgadmin4:latest
ENV PGADMIN_LISTEN_PORT=8080

COPY servers.json /pgadmin4/servers.json

Explanation:
This uses the official pgAdmin image and configures it to listen on port 8080, which Cloud Run requires. The COPY command will add the servers.json file to the container.

servers.json template:

{
  "Servers": {
    "1": {
      "Name": "YOUR_DATABASE_NAME",
      "Group": "Servers",
      "Host": "/cloudsql/YOUR_PROJECT_ID:YOUR_REGION:YOUR_INSTANCE_NAME",
      "Port": 5432,
      "MaintenanceDB": "postgres",
      "Username": "YOUR_DB_USERNAME",
      "SSLMode": "disable"
    }
  }
}

⚠️ Replace the ALL_CAPS values with your actual Cloud SQL details.

• Host uses the Cloud SQL Proxy format: /cloudsql/PROJECT_ID:REGION:INSTANCE_NAME

---

🐳 Step 3: Build the Docker Image

Expand for build & push commands

# Authenticate Docker with Google Artifact Registry
gcloud auth configure-docker us-central1-docker.pkg.dev

# Build and push the image for the correct architecture (Apple Silicon users: this is required!)
docker buildx build --platform linux/amd64 \
  -t us-central1-docker.pkg.dev/YOUR_PROJECT_ID/pgadmin-repo/pgadmin:latest \
  --push .

Explanation:
The --platform linux/amd64 flag ensures compatibility with Cloud Run, especially if you're on Apple Silicon.

---

☁️ Step 4: Deploy to Cloud Run with Cloud SQL Proxy

Expand for deploy command

gcloud run deploy pgadmin-service \
  --image=us-central1-docker.pkg.dev/YOUR_PROJECT_ID/pgadmin-repo/pgadmin:latest \
  --platform=managed \
  --region=us-central1 \
  --allow-unauthenticated \
  --set-env-vars=PGADMIN_DEFAULT_EMAIL=admin@example.com,PGADMIN_DEFAULT_PASSWORD=SecurePassword123,PGADMIN_CONFIG_SERVER_MODE=True,PGADMIN_CONFIG_SERVERS_JSON_PATH=/pgadmin4/servers.json \
  --add-cloudsql-instances=YOUR_PROJECT_ID:REGION:INSTANCE_NAME

Explanation:

• --add-cloudsql-instances enables the Cloud SQL Proxy integration, allowing secure database access.
• Environment variables configure pgAdmin and preload your database connection.

---

🌐 Step 5: Connect Your Domain via Cloudflare

1. Get your Cloud Run URL (e.g., https://pgadmin-service-xxxxxx-uc.a.run.app).
2. In Cloudflare DNS:
   • Add a CNAME record:
     • Name: pgadmin (for pgadmin.yourdomain.com)
     • Target: ghs.googlehosted.com
     • Proxy status: DNS only (gray cloud)
3. In Google Cloud Console:
   • Go to Cloud Run → Domain mappings
   • Map pgadmin.yourdomain.com to your service
   • Follow verification prompts (may require adding a TXT record in Cloudflare)
4. Wait for DNS propagation (usually a few minutes).
5. Access your pgAdmin website at your custom domain.

---

🩺 Troubleshooting

🐞 Problem	💡 Solution
Docker build fails	Ensure Dockerfile and config files are present and correct. Use --platform linux/amd64.
Cloud Run container fails to start	Ensure PGADMIN_LISTEN_PORT=8080 is set as an environment variable. Check logs in Cloud Console.
pgAdmin can't connect to Cloud SQL	Check servers.json host, deploy with --add-cloudsql-instances, ensure service account has Cloud SQL Client role.
Domain doesn't resolve	Double-check Cloudflare DNS and Google Cloud Run domain mapping. Use DNS only mode until SSL is provisioned.

---

💡 Key Takeaways

• 🚀 Cloud Run is the simplest and most secure way to host pgAdmin as a website on GCP.
• 🔗 Cloud SQL Proxy is the recommended method for connecting securely to Cloud SQL from any platform.
• 🏗️ Use Docker's --platform linux/amd64 when building images on Apple Silicon.
• ⚡ Preload your database connection in pgAdmin using servers.json for a seamless experience.
• 🆕 Modern alternatives to pgAdmin (like CloudBeaver or Pgweb) are available if you want a different web UI.

---

🔗 Alternatives & Further Reading

• pgAdmin Official Docs
• Google Cloud SQL Proxy
• Cloudflare DNS Docs
• CloudBeaver (web-based DBeaver)
• Pgweb (lightweight web-based PostgreSQL client)

---

🤝 Contributing

🙌 Found a bug or have an idea?
Open an issue or PR!
Your feedback makes this project better.

---