shopping2go/email-oauth2-proxy-docker repository overview

⁠📧 email-oauth2-proxy-docker

A Docker container running Email OAuth 2.0 Proxy⁠ in headless (--no-gui) mode on a Debian-based environment, with the configuration file exposed via a Docker volume.

⁠🚀 Quick start

⁠1. Prepare your configuration file

The image ships with a default emailproxy.config template. On the first start the container automatically copies this template to your mounted /config directory if no config file is found there yet. Edit the created file to add your email server and account details. See the upstream sample config⁠ for full documentation and provider-specific examples.

The config file must be named emailproxy.config and lives inside the directory mounted at /config.

⁠2. Build the image locally

docker build -t email-oauth2-proxy-docker .

⁠3. Run with Docker Compose

docker compose up -d

The default Compose file uses a named volume (emailproxy-config). Docker initialises a named volume only on first creation — it never overwrites existing data on subsequent docker compose down / up or docker compose up --build cycles. If you prefer to store the config in a specific host directory, switch to the bind-mount option in docker-compose.yml.

⁠4. Run with Docker

docker run -d \
    --name emailproxy \
    --restart unless-stopped \
    -e DEBUG=false \
    -e LOGFILE=true \
    -e CACHE_STORE=/config/credstore.config \
    -e LOCAL_SERVER_AUTH=false \
    -v emailproxy-config:/config \
    -p 1993:1993 \
    -p 1587:1587 \
    email-oauth2-proxy-docker

⁠📂 Configuration volume

Mount a volume at /config inside the container. This is required to persist your configuration (including OAuth tokens) across container restarts and upgrades.

On the first start the container seeds /config/emailproxy.config from the built-in default template if the file does not already exist. On every subsequent start the existing file is loaded as-is.

To reload the configuration file without restarting the container, send a SIGHUP signal:

docker kill --signal=SIGHUP emailproxy

Note that a SIGHUP reload only applies to settings the proxy supports reloading at runtime. Structural changes (servers, accounts) require a full restart.

⁠⚙️ Environment variables

⁠🔌 Exposed ports

Only expose the ports you actually need; remove unused entries from docker-compose.yml or the docker run command.

⁠🔑 First-time account authorisation

When running in --no-gui mode, accounts must be authorised before the proxy can function. Use one of the following approaches:

• LOCAL_SERVER_AUTH=true — The proxy starts a temporary web server to receive the OAuth redirect. Visit the authorisation URL printed in the logs, authenticate, and the proxy captures the token automatically. Map port 8080:8080 and ensure redirect_uri = http://localhost:8080 is set in your config (this is the default in the sample emailproxy.config).
• EXTERNAL_AUTH=true — The proxy prints an authorisation URL to the logs. Open it in a browser, authenticate, then copy the final redirect URL from the browser address bar and paste it back into the container standard input via docker attach emailproxy.
• Pre-authorised config — If the emailproxy.config file already contains cached tokens (from a previous GUI-mode authorisation), no interaction is needed.

⁠🔗 Upstream project

This container wraps simonrob/email-oauth2-proxy⁠. Refer to the upstream README for full details on OAuth 2.0 client credentials, provider-specific setup and advanced options.

⁠📄 License

This project is licensed under the Apache License 2.0⁠, matching the upstream email-oauth2-proxy⁠ license.

⁠⚠️ Disclaimer