{"id":15064373,"url":"https://github.com/scheidti/docker-mailserver-aliases","last_synced_at":"2026-01-03T11:14:00.165Z","repository":{"id":255527182,"uuid":"850351119","full_name":"scheidti/docker-mailserver-aliases","owner":"scheidti","description":"This project is an addon for the Docker Mailserver (DMS) project. It provides a simple web interface to manage email aliases.","archived":false,"fork":false,"pushed_at":"2024-10-20T12:55:03.000Z","size":234,"stargazers_count":1,"open_issues_count":1,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-01-22T09:29:30.591Z","etag":null,"topics":["daisyui","docker","mailserver","svelte","tailwindcss"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/scheidti.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-08-31T14:30:50.000Z","updated_at":"2024-10-20T12:48:02.000Z","dependencies_parsed_at":"2024-09-05T23:37:48.661Z","dependency_job_id":"91f442b3-383a-4c93-906e-146d7f710733","html_url":"https://github.com/scheidti/docker-mailserver-aliases","commit_stats":null,"previous_names":["scheidti/docker-mailserver-aliases"],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/scheidti%2Fdocker-mailserver-aliases","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/scheidti%2Fdocker-mailserver-aliases/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/scheidti%2Fdocker-mailserver-aliases/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/scheidti%2Fdocker-mailserver-aliases/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/scheidti","download_url":"https://codeload.github.com/scheidti/docker-mailserver-aliases/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243786362,"owners_count":20347626,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["daisyui","docker","mailserver","svelte","tailwindcss"],"created_at":"2024-09-25T00:16:40.710Z","updated_at":"2026-01-03T11:14:00.157Z","avatar_url":"https://github.com/scheidti.png","language":"Go","readme":"# Docker Mailserver Aliases\n\n[![License](https://img.shields.io/github/license/scheidti/docker-mailserver-aliases\n)](https://github.com/scheidti/docker-mailserver-aliases?tab=MIT-1-ov-file)\n[![Go Report Card](https://goreportcard.com/badge/github.com/scheidti/docker-mailserver-aliases)](https://goreportcard.com/report/github.com/scheidti/docker-mailserver-aliases)\n\n## Overview\n\nThis project is an addon for the **[Docker Mailserver](https://github.com/docker-mailserver/docker-mailserver)** (DMS) project. It provides a simple web interface to manage email aliases. This addon is packaged as a Docker container that hosts a REST API written in Go and a frontend built with Svelte, Tailwind CSS, and DaisyUI.\n\n## Features\n\n- List existing mail aliases and the email address they redirect to.\n- Add new aliases.\n- Delete existing aliases.\n\n## Technologies\n\n- [Gin Web Framework](https://gin-gonic.com/)\n- [Docker Engine SDK](https://pkg.go.dev/github.com/docker/docker/client)\n- [Svelte](https://svelte.dev/)\n- [Tailwind CSS](https://tailwindcss.com/)\n- [DaisyUI](https://daisyui.com/)\n\n## Installation\n\n### Prerequisites\n\nTo run the Docker container, you will need:\n\n- A working and configured [Docker Mailserver](https://github.com/docker-mailserver/docker-mailserver) instance.\n- (Optional) A reverse proxy, e.g., [Caddy](https://caddyserver.com/), to serve the frontend over HTTPS.\n\n### Configuration\n\nYou can configure the application using the following environment variables:\n\n```bash\n# Change the web server port (default: \":8080\")\nexport GIN_ADDR=\":8080\"\n\n# Configure the Docker Mailserver image name (default: \"mailserver/docker-mailserver\")\nexport DOCKER_MAILSERVER_IMAGE=\"mailserver/docker-mailserver\"\n```\n\nThe `DOCKER_MAILSERVER_IMAGE` environment variable allows you to specify a custom Docker Mailserver image name if you're using a different image or tag than the default.\n\n\u003e **Note**: The application uses partial string matching to identify the Docker Mailserver container. This means the configured value doesn't need to exactly match the full image name - it just needs to be contained within it. For example, setting `DOCKER_MAILSERVER_IMAGE=mailserver` would match containers running `mailserver/docker-mailserver:latest`, `ghcr.io/docker-mailserver/docker-mailserver:edge`, etc.\n\n### Docker Compose\n\nAdd the `mailserver-aliases` container to your `docker-compose.yaml` file:\n\n```yaml\nservices:\n  mailserver-aliases:\n    image: chscheid/docker-mailserver-aliases:1.1.0\n    restart: unless-stopped\n    read_only: true\n    ports:\n      - \"8080:8080\"\n    volumes:\n      - /var/run/docker.sock:/var/run/docker.sock\n    environment:\n      # Optional: specify custom Docker Mailserver image\n      # - DOCKER_MAILSERVER_IMAGE=mailserver/docker-mailserver\n    cap_drop:\n      - ALL\n```\n\n\u003e **Note**: There is no built-in authentication for the frontend, so the web interface will be publicly available under port 8080. You may want to secure it with a reverse proxy and authentication.\n\n#### Why Mounting the Docker Socket is Required\n\nMounting the Docker socket into the container is required for this project because the container needs to communicate with the Docker daemon to manage email aliases on the Docker Mailserver. The Docker Engine SDK is used to interact with the Docker daemon, allowing the REST API to list, add, and delete aliases.\n\n#### Security Considerations\n\nWhile mounting the Docker socket (`/var/run/docker.sock`) into a container grants the container elevated permissions to interact with the Docker daemon, it is a common practice for tools that need to manage Docker containers. Here are some considerations to ensure this setup remains secure:\n\n- **Restrict Access**: Protect the web interface by using a reverse proxy with authentication. This ensures that only authorized users can access the interface and perform actions.\n- **Limit Container Capabilities**: Consider using Docker's security options to drop unnecessary capabilities from the container. For example, you can use the `--cap-drop` option to limit the container’s capabilities. \n\n#### Basic Authentication\n\nHere is an example to serve the frontend with Caddy and Basic Authentication:\n\n`docker-compose.yaml`:\n\n```yaml\nservices:\n  caddy:\n    image: caddy:2.8\n    restart: unless-stopped\n    environment:\n      - FRONTEND_BASIC_AUTH_USER=\"username\"\n      - FRONTEND_BASIC_AUTH_PASSWORD=\"HASHED_PASSWORD\"\n    ports:\n      - \"80:80\"\n      - \"443:443\"\n      - \"443:443/udp\"\n    volumes:\n      - ./Caddyfile:/etc/caddy/Caddyfile\n\n  mailserver-aliases:\n    image: chscheid/docker-mailserver-aliases:1.1.0\n    read_only: true\n    restart: unless-stopped\n    volumes:\n      - /var/run/docker.sock:/var/run/docker.sock\n    environment:\n      # Optional: specify custom Docker Mailserver image\n      # - DOCKER_MAILSERVER_IMAGE=mailserver/docker-mailserver\n    cap_drop:\n      - ALL\n```\n\n`Caddyfile`:\n\n```\naliases.yourdomain.com {\n  basic_auth {\n    {$FRONTEND_BASIC_AUTH_USER} {$FRONTEND_BASIC_AUTH_PASSWORD}\n  }\n  reverse_proxy mailserver-aliases:8080\n}\n```\n\nReplace `username` and `HASHED_PASSWORD` with your values. For more information on configuring Caddy and hashing the password, see the [Caddy documentation](https://caddyserver.com/docs/caddyfile/directives/basic_auth).\n\n## Development\n\nTo develop and contribute to this project, you can run both the backend and frontend locally. You can mock the API for frontend development using [Mockoon](https://mockoon.com/).\n\n### REST API\n\nThe backend REST API is written in Go and provides endpoints to manage aliases. It interacts with the Docker Mailserver instance through the Docker Engine API.\n\n#### Prerequisites\n\n- Go (1.24 or higher)\n\n#### Run Development Server\n\nTo start the development server for the backend:\n\n```bash\ngo run main.go\n```\n\n#### Swagger Documentation\n\nThe Swagger documentation is generated with [Swag](https://github.com/swaggo/swag).\n\nGenerate the documentation with:\n\n```bash\nswag init\n```\n\nYou can view the documentation at:\n\n[http://localhost:8080/docs/index.html](http://localhost:8080/docs/index.html)\n\n### Frontend\n\nThe frontend is built with Svelte, Tailwind CSS, and daisyUI. It communicates with the backend REST API to manage email aliases.\n\n#### Prerequisites\n\n- Node.js (20 or higher)\n\n#### Run Development Server\n\nTo run the frontend locally, follow these steps:\n\n1. Navigate to the `frontend` directory:\n\n   ```bash\n   cd ./frontend\n   ```\n\n2. Install the necessary dependencies:\n\n   ```bash\n   npm install\n   ```\n\n3. Use Mockoon to mock the REST API if the Docker Mailserver is not running:\n\n   ```bash\n   npm run mockoon\n   ```\n\n4. Start the frontend development server:\n\n   ```bash\n   npm run dev\n   ```\n\nThis will start the frontend on [http://localhost:5173/](http://localhost:5173/).\n\n## Contributing\n\nContributions are welcome! If you'd like to contribute to the project, please follow these steps:\n\n1. Fork the repository.\n2. Create a new branch (`git checkout -b feature-branch`).\n3. Make your changes and commit them (`git commit -am 'Add new feature'`).\n4. Push the branch (`git push origin feature-branch`).\n5. Open a pull request.\n\nPlease make sure to update tests as appropriate.\n\n## Future Improvements\n\n### Goal: Remove the Dependency on Docker Socket Mounting\n\nOne of the goals for future development of this project is to eliminate the need to mount the Docker socket (`/var/run/docker.sock`) into the container. Although mounting the Docker socket is currently required for the REST API to interact with the Docker Mailserver, this practice can pose security risks.\n\n## License\n\nThis project is open-source and available under the [MIT License](https://github.com/scheidti/docker-mailserver-aliases/blob/main/LICENCE).","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fscheidti%2Fdocker-mailserver-aliases","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fscheidti%2Fdocker-mailserver-aliases","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fscheidti%2Fdocker-mailserver-aliases/lists"}