Web interface to manage email aliases

[scheidti]

Hi community,

I’m excited to share an addon I’ve developed for DMS. It’s called Docker Mailserver Aliases, and it provides a simple web interface to manage email aliases! I developed it for my own DMS instance to easily create and delete email aliases.

For now this are the implemented features:

• List existing aliases: Easily view all email aliases and their forwarding addresses.
• Add new aliases: Create new email aliases.
• Delete aliases: Remove any unwanted or outdated aliases.

You can run it as a Docker container alongside Docker Mailserver.

Maybe someone will find it useful, and I’d love to get feedback!

[casperklein]

I couldn't get it to work. After startup, the mailserver-alias container immediately exits: mailserver-aliases-1 exited with code 0

Here is the demo setup I used:

compose.yaml

services:
  mailserver:
    hostname: mail.example.com
    image: ghcr.io/docker-mailserver/docker-mailserver:latest
    configs:
      - source: dms-account
        target: /tmp/docker-mailserver/postfix-accounts.cf

  mailserver-aliases:
    image: chscheid/docker-mailserver-aliases:1.0.1
    restart: unless-stopped
    environment:
      - GIN_ADDR=8080
    ports:
      - "8080:8080"
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock

# NOTE: This feature requires Docker Compose v2.23.1 (Nov 2023) or newer:
# https://github.com/compose-spec/compose-spec/pull/446
configs:
  # DMS requires an account to complete setup
  # password is `secret`
  dms-account:
    content: |
      [email protected]|{SHA512-CRYPT}$$6$$sbgFRCmQ.KWS5ryb$$EsWrlYosiadgdUOxCBHY0DQ3qFbeudDhNMqHs6jZt.8gmxUwiLVy738knqkHD4zj4amkb296HFqQ3yDq4UXt8.

---

Two thoughts:

1. Mounting /var/run/docker.sock gives the container full access to the docker daemon. This is bad from a security point of view (allowing the container to control every container, running additional containers etc.). Instead you could install a SSH daemon in the DMS container and issue the commands via ssh.
2. If I understand correctly, DMS is detected by the used image name. If DMS is run with a custom image build (with a different image name), it does not work? The container name could be configurable via an ENV.

[casperklein]

That said I actually don't see as much of a problem with the socket approach in your project specifically

I agree with @polarathene. Just for completeness and generally speaking: IMO mounting docker.sock into a container should be avoided whenever possible. It basically means giving the container full access to the host system. For example, running this inside a container (with docker.sock mounted) gives full rw access to the host: docker run -it -v /:/host/ debian chroot /host/ bash.

Edit: More information here.

For those that are still concerned there's always docker-socket-proxy to restrict permissions (nice guide here).

That makes things a lot safer 👍 At least, as long as docker-socket-proxy itself doesn't have any (security) bugs. Then you have just shifted the risk from one container to another.

---

If you/Georg agree, I could integrated a small HTTP server (disabled by default) based on the example above into DMS.

[scheidti]

Thank you, guys!

Based on your feedback, here are the next steps I will take in my project:

1. Clarify in the README what it means to mount the Docker daemon in my container so that users can make an informed decision about using my project. I will also mention docker-socket-proxy.
2. Make the image name configurable.
3. Attempt to implement an alternative method that doesn't involve mounting the Docker daemon.

[polarathene]

Then you have just shifted the risk from one container to another.

Yeah, I'm not exactly fond of it being tacked on to an alpine image with shell access, but it is just a reverse-proxy (HAProxy). I could put together the same with Caddy I think and create an image that is a bit more secure by throwing away everything else not needed in the image 😅

There's still a benefit from the indirection, which complicates the effort to attack and compromise the socket (notably when there's more than one container wanting socket access).

Unfortunately they don't offer a way to manage permissions for different scopes, so multiple proxy services need to be run if sharing the same permissions isn't appropriate.

---

EDIT: I looked through the docker-socket-proxy project and existing issues along with some past closed ones and merged PR history and wasn't too fond of what I was seeing. I think I'd rather just build the equivalent with Caddy tbh.

[polarathene]

If you/Georg agree, I could integrated a small HTTP server (disabled by default) based on the example above into DMS.

I am reluctant, we have a separate API repo that was meant to build towards that but stalled. If someone wants to run a service like you've proposed in DMS they should build the executable and add the supervisord config themselves rather than us maintaining an official one that starts getting depended on by other projects if we're not able to commit the time to approach it properly 😓

While not as small, similar could be done and maybe a bit more accessible with Caddy and the caddy-exec plugin (though there is a bug that'd need to be addressed, not quite sure how well maintained the plugin is tbh). The token may help but not so much when it's going over HTTP instead of HTTPS, with Caddy the user has a bit more options including self-signed certs (or using the same certs that DMS has been provisioned with), you could also leverage forward auth or mTLS, along with trust by IP, etc.

So while less convenient, I'd suggest docs + feature request issue as usual so we know of explicit demand/interest instead of implicit. Personally I'd rather see the setup CLI (or at least portions of it like user management) ported away from shell scripts to Go or Rust which could then offer CLI + API options along with JSON responses which would be a bit more friendly to projects like @scheidti has made. This would better match the intended use-case too, and while unfortunately is much more effort it wouldn't add friction to maintaining DMS if it was later pursued when other users become dependent upon the stop gap solution from running any commands via HTTP.

[polarathene]

2. Make the image name configurable.

Rather than searching containers by filtering on the image name alone, you could use other heuristics like labels (on DMS for your image to identify) or even the DMS container name? (as an input configured to your image)

You could technically use this label too I think:

docker-mailserver/Dockerfile

Lines 332 to 333 in cace9c5

	# Add metadata to image:
	LABEL org.opencontainers.image.title="docker-mailserver"

Assuming that persists across custom builds that extend DMS 🤔

[leoborlot]

I´ve build this interface, with access control, password recover and manager each email from each domain.

still working in progress and in pt-br language.
Any one intersted?

[polarathene]

A web interface should be separate from the main DMS image, similar to the k8s helm chart.

Does your project also rely on leveraging the docker socket? Or are you running it within the same DMS container?

---

For now it's probably best to follow our current feature policy and contribute to our docs if you'd like to spread awareness of your web UI for DMS. A feature request issue can be opened to get user interest / feedback, and if the community prefers your solution it could probably be brought into the docker-mailserver organization?

I'm leaning towards a separate image and repo as I'm not sure if the existing maintainers can support reviewing PRs for a web interface. It's very nice looking btw, great work!

[leoborlot]

Im running on this structure:
[ DMS container ] -- [ Python/Flask DMS API ] -- [ This Frontend consuming API ]

I did it to solve our client demmand, there some thing to improuve, but, for now, solve the main crude features:

• create, update or remove mailboxes.
• change password or create a link for final user change self password.
• switch and list mailbox from each domain in user acounte.
• limit and count the quota do number of mailbox or disk size on avaliable.

need to apply another features as:

• alias controle
• mailbox metrics
• quality check (based in bounces or spam issues)

some features with privacy issues

• monitoring features (check content of mailboxes out and income) because the focused on the business market
• alert about prohibited content
• IA check the email content and account summary

plus:
I´ve Created a drive to Roundcube, then the final user could change password direct from interface, dont need call to Ops.

[polarathene]

Awesome thanks for sharing.

So we have this admin API repo that didn't quite take off. The goal was to plan out an OpenAPI config and look into offering an API or Web UI example from there that extends the DMS image. The contributor was using Python too IIRC.

My stance was that DMS could include an API service to make integration easier, but as security and other requirements could be implemented in various ways, that'd be delegated to another layer outside of DMS (such as a reverse proxy with forward auth, rate limiting, etc), allowing anyone to add their own Web UI tailored to their requirements, but share a common DMS API.

Maintainers for DMS are prefer to not use Python, but it does seem to be what contributors are preferring to use. It could probably be ported to Rust without too much trouble.

With the features you describe, some of those would probably be out of scope for the existing maintainers to accept, in which case you'd need to still carry your own API, which may be of less interest to you? Metrics for example may need a DB, and I think we'd like to leverage Vector in future for logs where metrics could be extracted and forwarded elsewhere for collection, which is where your metrics and potentially monitoring may be better suited.

Your other needs may be better suited by ensuring that DMS can easily be extended with your own feature additions (you could try upstream them into DMS officially but this is a slow process with limited maintainer time). Or the other alternatives to DMS like stalwart, mailcow, mailu, etc might better suit you?

---

I know there's demand for easier API access and web UI for common functionality like mailbox and alias management, especially for changing passwords. I have considered replacing our shell scripts for the related CLI support to be rewritten in Rust along which could add on API support easily enough, but I don't know when I'll ever have time for that myself.

---

Anyway, way forward for now is likely:

• If open-source, you can contribute a link your repo on our docs, along with a feature request issue to link to.
• As you refine your API, once you're quite happy with it and are able to derive the OpenAPI schema, you could consider contributing that to the admin API repo I linked.

[leoborlot]

By the way, English is not my first language, so I might make some mistakes.

---

Good! This project is almost like a side project for me; I went up to the first checkpoint for the client and left new features to be developed when I have the time.

I completely understand and agree with you. The current format of DMS is very concise and is working well. Running everything locally in a file-based setup has made the project quite solid.

There are some exceptions when we need to interact with the data, but that’s expected when dealing with shell and file-based operations. Nothing that the project’s evolution won’t eventually resolve.

I personally don't see a strong need to open an API within DMS, as it serves a wide range of users, including those who prefer it to remain standalone and isolated.

The API I developed interacts with the container through the Docker Socket and Python's Docker library. It makes requests directly on the DMS container's shell, handling stdout and stderr to return JSON to the consumer (some times using regex to strutcture the json). Realy, at this api level, we need a database to manage access permissions, keys, and temporary data (such as password reset tokens, for example). Currently, I use MySQL, but considering portability, we could think about using SQLite, given the low database requirements. This way, we continue with the DMS project's encapsulated aspect.

I haven’t implemented OpenAPI yet; I followed a modular architecture with JWT authentication. I’ll study OpenAPI to assess its impact on the current project and will report back to see if it can be adopted.

I chose to build the frontend with React as I find it easier than doing it directly with Python. For frontend work, even PHP is easier than Python. React has some great component features for listings and routing. This specific frontend I would rebuild entirely, as it's been a year since then, and I was still maturing my knowledge of React at the time. But since it's a single page, I believe I will revisit it when I get to adding the basic features.

I think the project could indeed become open-source, even as a reinforcement for the DMS project, which has already solved a number of issues by delivering most of the needed features. I will review everything we discussed here and organize things so that this can be done.

[polarathene]

By the way, English is not my first language, so I might make some mistakes.

Yes I understand, that's ok! No worries 😎

---

The API I developed interacts with the container through the Docker Socket and Python's Docker library. It makes requests directly on the DMS container's shell, handling stdout and stderr to return JSON to the consumer (some times using regex to strutcture the json).

Oh ok, this is the approach @scheidti also chose, but with Go instead of Python.

---

Really at this API level, we need a database to manage access permissions, keys, and temporary data (such as password reset tokens, for example).
Currently, I use MySQL, but considering portability, we could think about using SQLite, given the low database requirements. This way, we continue with the DMS project's encapsulated aspect.

For permissions, this is not something DMS is suitable to handle. LDAP and OAuth2 are better at conveying that information and both are external.

As you are managing only for ACCOUNT_PROVISIONER=FILE support (?), you might want to handle permissions on your end with something like Permify. That is a language agnostic service suited for the task.

Password reset tokens is identity related, you can implement this functionality yourself, or use a service like Authelia (I think they have password reset support) which provides OAuth2 and can integrate with LDAP and file based configs of their own for accounts. Services like Authelia with OAuth2 / OIDC allows a user to share the same account login with DMS and your web UI with common metadata that could help with permissions.

That said OAuth2/OIDC support is limited in DMS, we still need to manage postfix-accounts.cf or LDAP. Services like Authelia would need to implement SCIM support, and DMS would also need this to have postfix-accounts.cf managed by the identity service instead. For now you would still need to manage postfix-accounts.cf or setup email ....

Currently, I use MySQL, but considering portability, we could think about using SQLite, given the low database requirements. This way, we continue with the DMS project's encapsulated aspect.

Database for accounts is a feature DMS has tried to avoid, but we may be able to add support in future. At least for now if you'd like to contribute docs for what changes are required and a feature request issue for users to express interest, that would help towards landing that integration.

I have basic example for Postgres with a compose.yaml that extends the DMS official image with needed package and config change for relay config: #4145 (comment) (it should be similar for other supported databases)

Your other needs for a database would probably need to be a separate database (or use the services I mentioned that have their own sqlite support for their needs).

---

I haven’t implemented OpenAPI yet; I followed a modular architecture with JWT authentication. I’ll study OpenAPI to assess its impact on the current project and will report back to see if it can be adopted.

That's ok, it is just a good practice as it is language agnostic and can generate some nice docs. It is also helpful for testing APIs with.

Many frameworks will have support to export OpenAPI schema. For example here is one for Flask that uses decorators in Python, and it's API docs generator support.

Since only your frontend will use your API for now, this is not too important, but it helps when the API is a separate service/container for others to also use. The OpenAPI schema can also be used to generate initial client code in different languages for easier adoption of your API.

---

I chose to build the frontend with React as I find it easier than doing it directly with Python. For frontend work, even PHP is easier than Python. React has some great component features for listings and routing.

React is a fine choice and I would endorse that, it is my preferred choice for building web UIs with.

I think the project could indeed become open-source, even as a reinforcement for the DMS project, which has already solved a number of issues by delivering most of the needed features. I will review everything we discussed here and organize things so that this can be done.

Great to hear!

If you're new to maintaining open-source projects, it can sometimes have some downsides vs private development. I would suggest starting with your own separate repo when you're ready, no rush to move it into the DMS organization 👍

Do update us with a link here should you publish to Github. If you have any queries for advice on how we do anything with CI or project maintenance with DMS that would interest you let me know.