From e05c65b328509d439af7c40c600416e5061a1b84 Mon Sep 17 00:00:00 2001 From: mjarkk Date: Sat, 13 Jul 2024 22:23:33 +0200 Subject: [PATCH] Updated the readme --- README.md | 117 +++++++++++++++++++++++++++++------------------------- 1 file changed, 63 insertions(+), 54 deletions(-) diff --git a/README.md b/README.md index ca04e7e..d90e6be 100644 --- a/README.md +++ b/README.md @@ -2,85 +2,107 @@ ![Screenshot](/screenshot.jpg?raw=true "Screnshot") -A alternative take on a development testing email server. +A alternative take on a development / testing email server. -## Why - -Something something reinventing the wheel :^) - -But besides the fun of reinventing the wheel I do have some reasons for making this. -I used maildev before this and I have some annoyances with it. It's an awesome project and has improved my life, but after using it for many years I have also noticed it's not without its flaws. So here is `mini-mail-dev`, my take on a mail development server and with fixes for my maildev problems. +Features: -Here are things this project aims to improve / do different compared to maildev: +- Get started with a single command +- Simple UI +- Fast +- Can handle a vast amounts of emails -- Attachments not hidden behind a button -- By default a fixed max amount of emails and when exceeded old emails are removed. _(So you can safely deploy this on a server without much storage or cpu as the server does not have to store a shitload of emails when sending a shitload of emails on a staging server hehe)_ -- Different server side language. _Mail dev has a tendency to break when running it on a server and sending more than the "average" amound of mails (my experience is at around 5.000 emails). By applying the above and using a language that is better suited for these kinds of things I can deploy this on every potato in the world._ +## Run -## Install - -**Go Install** - -_(you might not have the latest version if you have installed it earlier)_ +**Docker** ```bash -go install github.com/mjarkk/mini-mail-dev@latest -mini-mail-dev +docker run -it --rm -p 1080:1080 -p 1025:1025 ghcr.io/mjarkk/mini-mail-dev:latest ``` -**Git clone & Go install** +**Docker build** ```bash git clone https://github.com/mjarkk/mini-mail-dev cd mini-mail-dev -go install -mini-mail-dev +docker build -t mini-mail-dev . +docker run -it --rm -p 1080:1080 -p 1025:1025 mini-mail-dev ``` -**Docker** +**Go Install** + +_(you might not have the latest version if you have installed it earlier)_ ```bash -docker run -it --rm -p 1080:1080 -p 1025:1025 ghcr.io/mjarkk/mini-mail-dev:latest +go install github.com/mjarkk/mini-mail-dev@latest +mini-mail-dev ``` -**Docker build** +**Git clone & Go build** ```bash git clone https://github.com/mjarkk/mini-mail-dev cd mini-mail-dev -docker build -t mini-mail-dev . -docker run -it --rm -p 1080:1080 -p 1025:1025 mini-mail-dev +go build +./mini-mail-dev ``` ## Usage ```sh -mini-mail-dev +mini-mail-dev [--flags] ``` Options: -| name | Flag | Envourment variable | Default | -|---|---|---|---| -| Disable web | `--disable-web` | `DISABLE_WEB` | `false` | -| HTTP address | `--http` | `HTTP_ADDR` | `0.0.0.0:1080` | -| HTTP password | `--http-pass` | `HTTP_PASS` | | -| HTTP username | `--http-user` | `HTTP_USER` | | -| Max emails | `--max-emails` | `MAX_EMAILS` | `200` | -| SMTP address | `--smtp` | `SMTP_ADDR` | `0.0.0.0:1025` | -| SMTP domain | `--smtp-domain` | `SMTP_DOMAIN` | `localhost` | -| SMTP incoming password | `--smtp-incoming-pass` | `SMTP_INCOMING_PASS` | | -| SMTP incoming username | `--smtp-incoming-user` | `SMTP_INCOMING_USER` | | +| name | Flag | Envourment variable | Default | +| ---------------------- | ---------------------- | -------------------- | -------------- | +| Disable web | `--disable-web` | `DISABLE_WEB` | `false` | +| HTTP address | `--http` | `HTTP_ADDR` | `0.0.0.0:1080` | +| HTTP password | `--http-pass` | `HTTP_PASS` | | +| HTTP username | `--http-user` | `HTTP_USER` | | +| Max emails | `--max-emails` | `MAX_EMAILS` | `200` | +| SMTP address | `--smtp` | `SMTP_ADDR` | `0.0.0.0:1025` | +| SMTP domain | `--smtp-domain` | `SMTP_DOMAIN` | `localhost` | +| SMTP incoming password | `--smtp-incoming-pass` | `SMTP_INCOMING_PASS` | | +| SMTP incoming username | `--smtp-incoming-user` | `SMTP_INCOMING_USER` | | -*Note that authentication is only enabled if you provided the relevant envourment variables* +_Note that authentication is only enabled if you provided the relevant envourment variables_ -## Build & Run +## Why + +Something something reinventing the wheel :^) + +But besides the fun of reinventing the wheel I do have some reasons for making this. +I used maildev before this and I have some annoyances with it. It's an awesome project and has improved my life, but after using it for many years I have also noticed it's not without its flaws. So here is `mini-mail-dev`, my take on a mail development server and with fixes for my maildev problems. + +Here are things this project aims to improve / do different compared to maildev: + +- Attachments not hidden behind a button +- By default a fixed max amount of emails and when exceeded old emails are removed. _(So you can safely deploy this on a server without much storage or cpu as the server does not have to store a shitload of emails when sending a shitload of emails on a staging server hehe)_ +- Different server side language. _Mail dev has a tendency to break when running it on a server and sending more than the "average" amound of mails (my experience is at around 5.000 emails). By applying the above and using a language that is better suited for these kinds of things I can deploy this on every potato in the world._ + +## Development: Requirements: -- Golang v1.21.2 + +- Golang v1.21 + - Nodejs +### Dev + +```bash +go run . +# In another terminal tab run: +npm run dev + +# For sending a few testing mails to the server run +go run test/test_email.go +``` + +_The javascript files are hot module reloaded only when going to [localhost:**3001**](http://localhost:3001), the go files are not reloaded on changes made_ + +### Create and run a release build + ```bash # Build frontend npm i @@ -96,16 +118,3 @@ Now you can start `mini-mail-dev` using ```bash ./mini-mail-dev ``` - -## Dev - -```bash -go run . -# In another terminal tab run: -npm run dev - -# For sending a few testing mails to the server run -go run test/test_email.go -``` - -_The javascript files are hot module reloaded only when going to [localhost:**3001**](http://localhost:3001), the go files are not reloaded on changes made_