Global pgAdmin with Docker Compose

This repository provides a Docker Compose configuration to run a global instance of pgAdmin4. The goal is to make database management easier by hosting a single pgAdmin client that can connect to any PostgreSQL service, as long as both are attached to the same global Docker network.

By the end you will have a global pgAdmin4 instance running in Docker, connected to any PostgreSQL service running in the same network.

✨ Features

• Centralized pgAdmin: One pgAdmin instance accessible to all developers or services.
• Global network support: Any PostgreSQL container added to the shared network can be managed directly from pgAdmin.
• Flexible connections: No need to run multiple pgAdmin containers — just connect new DB services to the network.
• Portable setup: Defined entirely in Docker Compose for easy deployment and reuse.

🛠 How it works

• The Compose file spins up a pgAdmin container.
• pgAdmin is attached to a global Docker network.
• Any PostgreSQL service that joins this network becomes accessible from pgAdmin by simply adding its connection details in the pgAdmin UI.
• You can nowconnect pgAdmin to any Postgres service in the global network.
  See instructions below

⚙️ Setup Instructions

1. Clone this repository
2. Copy the .env.example into .env and fill in your credentials as environment variables
3. pgadmin will be accessed at http://localhost:8085 change the port number to your convinence at line 15 of the docker-compose file provided
4. Run the command docker compose up -d making sure you are in the parent directory of the docker-compose.yml file.
5. Access pgAdmin4 at http://localhost:8085 using the credentials you set in the .env file.

Here’s a minimal Postgres service snippet you can drop into another docker-compose.yml so it attaches to the same global network as our pgAdmin instance:

services:
  postgres:
    image: postgres:16
    container_name: my_postgres
    restart: always
    environment:
      POSTGRES_USER: myuser
      POSTGRES_PASSWORD: mypassword
      POSTGRES_DB: mydb
    # ports:
    #   - "5432:5432"
    volumes:
      - postgres-data:/var/lib/postgresql/data
    networks:
      - global_pgadmin-network

networks:
  global_pgadmin-network:
    external: true   # important: reuse the already-created network

volumes:
  postgres-data:

• Take note that the service is attacheed to the global_pgadmin-network making it accessible to our pgadmin4 instance we just set up

🌍 Environment Variables (TODO)

Accessing a Postgres DB with this Container

(Upcoming — I might be lazy sometimes I KNOW)

Maybe listen to some music ?

🛠️ Troubleshooting

🔑 Common Issues

• pgAdmin login fails

  • Make sure you set PGADMIN_DEFAULT_EMAIL and PGADMIN_DEFAULT_PASSWORD correctly in your .env file.
  • Restart the container after updating environment variables.

• Cannot connect to Postgres

  • Verify that your Postgres service is attached to the same global_pgadmin-network.
  • Use the service name (e.g., postgres) as the host in pgAdmin, not localhost.
  • Ensure the Postgres container is running and listening on port 5432.

• Network not found

  • If you see errors about global_pgadmin-network, check that it was created by Compose.
  • For other Compose files, mark the network as external: true to reuse it.