Resolving pgAdmin Reverse Proxy Issues in GitHub Codespaces

If you are using pgAdmin in GitHub Codespaces and facing issues accessing it, the problem is likely due to the reverse proxy setup. GitHub Codespaces runs services behind a reverse proxy by default, requiring additional configuration for pgAdmin to function properly.

The Problem

When running pgAdmin inside GitHub Codespaces, you may encounter issues such as:

• The application failing to load

• Broken redirects

• Authentication problems

These issues occur because pgAdmin does not automatically detect the reverse proxy in Codespaces. The proxy setup requires explicit configuration to pass request headers correctly.

The Solution

To fix this, you need to set two additional environment variables for pgAdmin:

PGADMIN_CONFIG_PROXY_X_HOST_COUNT: 1
PGADMIN_CONFIG_PROXY_X_PREFIX_COUNT: 1

These variables configure pgAdmin to handle the reverse proxy properly:

PGADMIN_CONFIG_PROXY_X_HOST_COUNT=1 ensures that pgAdmin correctly recognises the number of X-Forwarded-Host headers.

PGADMIN_CONFIG_PROXY_X_PREFIX_COUNT=1 allows pgAdmin to work with the forwarded URL prefixes set by GitHub Codespaces.

How to Apply the Fix

You can add these environment variables in multiple ways, depending on how you're running pgAdmin.

1. Using Docker Compose

If you're running pgAdmin as a service in Docker Compose, update your docker-compose.yml file like this:

version: "3.8"

services:
  pgadmin:
    image: dpage/pgadmin4
    container_name: pgadmin
    restart: always
    environment:
      PGADMIN_DEFAULT_EMAIL: "[email protected]"
      PGADMIN_DEFAULT_PASSWORD: "yourpassword"
      PGADMIN_CONFIG_PROXY_X_HOST_COUNT: 1
      PGADMIN_CONFIG_PROXY_X_PREFIX_COUNT: 1
    ports:
      - "5050:80"

2. Using a Dockerfile

If you're building a custom pgAdmin image, add the environment variables in your Dockerfile:

FROM dpage/pgadmin4

ENV PGADMIN_CONFIG_PROXY_X_HOST_COUNT=1
ENV PGADMIN_CONFIG_PROXY_X_PREFIX_COUNT=1

3. Setting Environment Variables in Your Shell

If you prefer not to modify your Docker files, you can set the environment variables before running the container:

export PGADMIN_CONFIG_PROXY_X_HOST_COUNT=1
export PGADMIN_CONFIG_PROXY_X_PREFIX_COUNT=1

docker run --name pgadmin \
-e PGADMIN_DEFAULT_EMAIL=[email protected] \
-e PGADMIN_DEFAULT_PASSWORD=yourpassword \
-e PGADMIN_CONFIG_PROXY_X_HOST_COUNT=1 \
-e PGADMIN_CONFIG_PROXY_X_PREFIX_COUNT=1 \
-p 5050:80 dpage/pgadmin4

Why This Works

GitHub Codespaces uses a reverse proxy to expose services running inside the container to the internet. Without proper configuration, pgAdmin cannot handle proxy headers correctly, leading to broken requests and authentication failures.

By adding these environment variables, we instruct pgAdmin to recognise the forwarded headers, enabling it to work correctly inside Codespaces.

Conclusion

If you’re using pgAdmin inside GitHub Codespaces and experiencing issues, adding these two environment variables will ensure it works properly with the built-in reverse proxy. Whether you're using Docker Compose, a Dockerfile, or a direct docker run command, setting these variables will resolve common accessibility and authentication issues.