Mailcow logs viewer: A faster, cool way to monitor your emails

shlomi · 2025-12-25T18:47:39+00:00

Hi everyone, While mailcow is an amazing suite, I often found the built-in log viewing options a bit clunky when I needed to debug something quickly (its ev...

Kevo

timber

I’d be curious to see your proxy config. I just loaded this up today and Safari seems to find it confusing to have a secure site and an insecure site hosted on the same domain name. I think running it through nginx makes sense. Also I am wondering if it can be password protected through nginx as well. The login page seems to accept anything when using the basic auth setting.

I’ll have to do some more testing and look at it further when I have time so I can be sure I’m not doing something wrong somewhere.

timber

Kevo
root@mailcow:/opt/mailcow-dockerized/data/conf/nginx# cat 00-mailcow-logs-app.conf
resolver 127.0.0.11 valid=10s ipv6=off;

server {
listen 443 ssl;
listen [::]:443 ssl;
http2 on;
server_name maillogs.xyz.com;

ssl_certificate /etc/ssl/mail/cert.pem;
ssl_certificate_key /etc/ssl/mail/key.pem;

location / {
    set $upstream http://mailcow-logs-app:8080;
    proxy_pass $upstream;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;

    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
}

}

Kevo I run authentication with Mailcow being an OAUTH2 provider. In order to access Maillogs, I need to login in as a Mailcow user. Works well.

Kevo

Thanks. Got it setup and running. I have the log viewer app running out of it’s own direction and it didn’t seem to like connecting by name. It gave a bad gateway error when connecting. I ended up putting the server IP in directly for the proxy_pass line and that seems to work fine.

I’ll have to do some reading on the OAUTH2 option. I didn’t realize it was there.

timber

Kevo I see. The name refers to the Docker container. Just in case you want to run it in Docker, here’s the app part from the docker-compose.yml:

app:
    image: ghcr.io/shlomiporush/mailcow-logs-viewer:latest
    container_name: mailcow-logs-app
    restart: unless-stopped
    depends_on:
      db:
        condition: service_healthy
    expose:
      - "${APP_PORT:-8080}"
    volumes:
      - ./data:/app/data
    networks:
      - mailcow-logs-network
      - mailcow-net
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8080/api/health"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 40s
    env_file:
      - .env

networks:
  mailcow-logs-network:
    driver: bridge
  mailcow-net:
    external: true
    name: mailcowdockerized_mailcow-network

Oauth2 can be configured in the .env file. Samples are already there.

Kevo

I updated the compose yaml file to add the external network and now the named upstream is working. I attempted to get Oauth working, but it doesn’t seem to redirect properly.

After getting the authorize external app button in mailcow it goes back to the login page in mail log viewer and asks to login with mailcow again. I just end up looping there.

The only thing unexpected during setup was that automatic endpoint discovery didn’t work. I had to use the manual endpoint discovery, which did seem to work until I get to actually logging in. That just loops back to the login page.

I’m not really sure how to troubleshoot at this point or if there is something else I missed somewhere.

CK_beats

Thank you @shlomi for the new update!
I switched to version 2.3.0!
It’s great that you can now make the settings via the web interface! I wanted to suggest that before.
But I rejected it because I didn’t want to be rude and demanding.
Really excellent that you have now integrated it. Makes the configuration a lot easier.

I just have a small note:
My .env file is now basically “empty”. But with all settings I get the message that I should remove the .env variable.

This value differs from ENV. Remove the ENV variable to use the DB value.

But this no longer exists. I only have one Backup.env file left.

shlomi

CK_beats My .env file is now basically “empty”. But with all settings I get the message that I should remove the .env variable.

fixed in v2.3.1

maybl8

I still have this issue that I havnen’t figured out yet.
container.log
Log file not found or hasn’t been created yet.

Kevo

I updated to 2.3.0 as well. Not sure why OAuth2 isn’t working for me. I double checked the settings and looked at the guide in the docs on github, but nothing stands out.

In case anyone might recognize the problem, the error message in the log is…

OAuth2 callback error: UserInfo request failed: 404

Also, the basic auth still seems to let any credentials log in.

I think for now I am going to remove it until the authentication gets sorted out or I have time to investigate further.

Looks quite nice though. Congrats to @shlomi on the results so far.

timber

Kevo This works for me:


> 
> # =============================================================================
> # OAuth2/OIDC Authentication (Alternative to Basic Auth)
> # =============================================================================
> 
> # Enable OAuth2/OIDC authentication
> # Works with any standard OAuth2/OIDC provider (Mailcow, Keycloak, Auth0, Google, etc.)
> # Default: false
> OAUTH2_ENABLED=true
> 
> # Display name for the OAuth2 provider (shown on login button)
> # Examples: "Mailcow", "Keycloak", "Google", "Microsoft"
> OAUTH2_PROVIDER_NAME=Mailcow
> 
> # Option 1: OIDC Discovery (Recommended - auto-discovers endpoints)
> # Set the issuer URL and the client will automatically discover endpoints
> # Mailcow example: https://mail.example.com
> # Keycloak example: https://keycloak.example.com/realms/myrealm
> #OAUTH2_ISSUER_URL=https://mail.xyz.com
> 
> # Option 2: Manual Endpoint Configuration (if discovery not supported)
> # Uncomment and set these if OIDC discovery is not available
> OAUTH2_AUTHORIZATION_URL=https://mail.xyz.com/oauth/authorize
> OAUTH2_TOKEN_URL=https://mail.xyz.com/oauth/token
> OAUTH2_USERINFO_URL=https://mail.xyz.com/oauth/profile
> 
> # OAuth2 Client ID from your provider
> OAUTH2_CLIENT_ID=1234567
> 
> # OAuth2 Client Secret from your provider
> OAUTH2_CLIENT_SECRET=abcdef
> 
> # OAuth2 Redirect URI (callback URL)
> # Must match the redirect URI configured in your OAuth2 provider
> # Example: https://your-logs-viewer.example.com/api/auth/callback
> OAUTH2_REDIRECT_URI=https://maillogs.xyz.com/api/auth/callback
> 
> # OAuth2 Scopes to request
> # Default: openid profile email
> OAUTH2_SCOPES=profile
> 
> # Enable OIDC discovery (uses .well-known/openid-configuration)
> # Default: true (if OAUTH2_ISSUER_URL is set)
> OAUTH2_USE_OIDC_DISCOVERY=false
> 
> # Session secret key for signing session cookies
> # REQUIRED if OAUTH2_ENABLED=true
> # Generate a random secret: openssl rand -hex 32
> # WARNING: Use a strong random secret in production
> SESSION_SECRET_KEY=123456789
> # Session expiration time in hours
> # Default: 24 hours
> SESSION_EXPIRY_HOURS=168

diko

Kevo

Regarding OAuth: I had the same error, turned out that one of the OAuth variables in the .env file had a wrong name or value in my case (don’t remember which one exactly, I believe it was OAUTH2_USERINFO_URL, ). Double check and compare with the examples in the documentation

Regarding the basic authentication issue: verify that you have AUTH_ENABLED=true. Setting only BASIC_AUTH_ENABLED=true will not help.

shlomi

diko
just fixed it. AUTH_ENABLED is deprecated and BASIC_AUTH_ENABLED should be used.
Releasing hotfix update shortly

CK_beats

shlomi
Just executed the pull. Super!
Error message no longer exists!

What a great monitoring tool! 😊😊👍👍👌👌

Kevo

I reloaded the current version and it seems to be working fine. I enabled the basic auth in the settings and when I saved I got an error about SMTP which I had not touched yet. Closed the browser window and logged in with the password I just set up and everything seems good. I’ll play around with some of the other functions as needed. Right now it’s enough to just be able to take a glance at things occasionally. My server is small and mostly for personal use.

I did setup mine using the edits to the compose file from @timber which were posted above along with the conf for nginx to proxy locally. I then added an additional SAN for maillogs.mydomain.com in the mailcow conf so it would get added to my acme cert as well. It now integrates very nicely.

I appreciate the quick fixes too. Excellent work. :-)

accolon

Just a quick note regarding authentication and the new Web UI settings:

Since the UI settings override ENV variables, it’s easy to lock oneself out. I made a copy/paste mistake in my OIDC configuration and couldn’t sign in again to fix it. I guess this problem also affects basic auth (e.g. password typos). Fixing my mistake by directly changing the database solved it for me, though.

Perhaps an authentication override via an ENV variable could be a solution.

diko

accolon
It already should work that way:
Priority: Default → ENV → DB

accolon

diko

Are you sure? The release notes say “Settings stored in database override ENV variables”, so a mistake made in the UI, in my case a wrong OIDC configuration, currently cannot be fixed via an ENV variable.

diko

accolon
Sorry, you’re right. I read it in the wrong order. DB is the highest prio.

shlomi

Um, I honestly didn’t think about it. Does anyone have an idea?

DocFraggle

shlomi Can’t you just turn it around and make ENV settings override the DB settings? Or maybe use an extra “.env.override” file to override specific settings?

shlomi

DocFraggle
done. i need some more tests, change the image to shlomip/mailcow-logs-app:dev

« Previous Page Next Page »