Update README.md

Author: github-actions[bot]

README.md

@@ -1 +1,230 @@
+# Mailauth
 
+Mailauth is a Mailbox Manager which enables you too select between your Mailboxes and authenticate with your Mailserver (like [mailcow](https://github.com/mailcow/mailcow-dockerized))
+
+## Screenshots
+
+![mailauth-home](https://github.com/user-attachments/assets/934fb3a3-3160-4fcb-a30e-10b62a804411)
+
+## Getting Started
+
+Get the latest version of the `docker-compose.yaml` file:
+
+```yaml
+---
+services:
+  mailauth:
+    image: ghcr.io/codeshelldev/mailauth:latest
+    container_name: mailauth
+    ports:
+      - "80:80"
+    env_file:
+      - .env
+    restart: unless-stopped
+    networks:
+      mailauth:
+        aliases:
+          - mailauth
+
+  mongodb:
+    image: mongo:latest # Use arm64v8/mongo for ARM Architecture
+    container_name: mailauth-db
+    volumes:
+      - db:/data/db
+      - ./init-mongo.js:/docker-entrypoint-initdb.d/init-mongo.js
+    env_file:
+      - .env
+    networks:
+      mailauth:
+        aliases:
+          - mongo
+    restart: unless-stopped
+
+  redis:
+    image: redis:latest
+    container_name: mailauth-redis
+    command: ["redis-server", "--requirepass", "${REDIS_PASSWORD}"]
+    env_file:
+      - .env
+    networks:
+      mailauth:
+        aliases:
+          - redis
+    restart: unless-stopped
+
+networks:
+  mailauth:
+
+volumes:
+  db:
+```
+
+### Setup
+
+Mailauth _currently_ works by modifying the `email` claim during Token Exchange and Userinfo,
+this means that you **will have to** use a IdP (like [authentik](https://goauthentik.io)).
+
+Create a `.env` file inside of you `docker-compose.yaml` directory and copy the template below
+
+```dotenv
+# Mail
+
+# Get from your IdP (for your mailserver)
+MAIL_CLIENT_ID=
+MAIL_CLIENT_SECRET=
+
+MAIL_AUTHORIZATION_ENDPOINT=
+MAIL_TOKEN_ENDPOINT=
+MAIL_USERINFO_ENDPOINT=
+
+MAIL_REDIRECT_URIS=https://mailauth.domain.com/oauth/mail/callback,https://mailauth.yourdomain.com/oauth/mail/callback
+MAIL_CALLBACK_URIS=https://mail.domain.com,https://mail.yourdomain.com # This is your mailservers oauth callback url
+
+# App
+
+# Get this from your IdP (for mailauth)
+APP_CLIENT_ID= 
+APP_CLIENT_SECRET=
+
+APP_ISSUER=
+APP_AUTHORIZATION_ENDPOINT=
+APP_TOKEN_ENDPOINT=
+APP_USERINFO_ENDPOINT=
+APP_LOGOUT_ENDPOINT=
+
+APP_REDIRECT_PATH=/oauth/app/callback
+
+# DB
+
+MONGO_INITDB_ROOT_USERNAME=admin
+MONGO_INITDB_ROOT_PASSWORD=SECURE_ROOT_PW
+MONGO_INITDB_DATABASE=mailauth
+
+MONGO_USER=mailauth
+MONGO_PW=SECURE_PW
+
+# ---- #
+
+REDIS_PASSWORD=SECURE_REDIS_PW
+
+# General
+
+SESSION_SECRET=SECURE_KEY # Gen with openssl
+
+HOST=https://mailauth.domain.com
+
+PREFIX=/ # Optional
+
+DB_HOST=mongodb://${MONGO_USER}:${MONGO_PW}:27017/${MONGO_INITDB_DATABASE}
+REDIS_HOST=redis://default:${REDIS_PASSWORD}:6379
+```
+
+Now you need to setup a Oauth Authentication Method in your mailserver,
+but instead of using your IdP's endpoints you use:
+
+* `/oauth/mail/authorize`
+* `/oauth/mail/token`
+* `/oauth/mail/userinfo`
+
+And set Redirect URI to the one from your `.env` file.
+
+Next create `init-mongo.js` in your working directory:
+
+```js
+const PASSWORD = process.env.MONGO_PW
+const USER = process.env.MONGO_USER
+const DB = process.env.MONGO_INITDB_DATABASE
+
+db = db.getSiblingDB(DB) // Switch to your target database
+db.createUser({
+	user: USER,
+	pwd: PASSWORD,
+	roles: [
+		{ role: "readWrite", db: DB }, // Give read/write access to 'mailauth'
+	],
+})
+```
+
+### Reverse Proxy
+
+When working with OAuth2 and Auth in general it is recommended to be sure to use secure connections,
+here you will see a Reverse Proxy implementation with traefik:
+
+```yaml
+---
+services:
+  mailauth:
+    image: ghcr.io/codeshelldev/mailauth:latest
+    container_name: mailauth
+    labels:
+      - traefik.enable=true
+      - traefik.http.routers.mailauth-secure.entrypoints=websecure
+      - traefik.http.routers.mailauth-secure.rule=Host(`mailauth.domain.com`)
+      - traefik.http.routers.mailauth-secure.tls=true
+      - traefik.http.routers.mailauth-secure.tls.certresolver=resolver
+      - traefik.http.routers.mailauth-secure.service=mailauth-svc
+      - traefik.http.services.mailauth-svc.loadbalancer.server.port=80
+      - traefik.docker.network=proxy
+    env_file:
+      - .env
+    restart: unless-stopped
+    networks:
+      mailauth:
+        aliases:
+          - mailauth
+      proxy:
+
+  mongodb:
+    image: mongo:latest # Use arm64v8/mongo for ARM Architecture
+    container_name: mailauth-db
+    volumes:
+      - db:/data/db
+      - ./init-mongo.js:/docker-entrypoint-initdb.d/init-mongo.js
+    env_file:
+      - .env
+    networks:
+      mailauth:
+        aliases:
+          - mongo
+    restart: unless-stopped
+
+  redis:
+    image: redis:latest
+    container_name: mailauth-redis
+    command: ["redis-server", "--requirepass", "${REDIS_PASSWORD}"]
+    env_file:
+      - .env
+    networks:
+      mailauth:
+        aliases:
+          - redis
+    restart: unless-stopped
+
+networks:
+  mailauth:
+  proxy:
+    external: true
+
+volumes:
+  db:
+```
+
+## Usage
+
+When authenticating via mailauth you get redirected to your actual IdP then to `/select`,
+where you will be able to select your mailbox, mailauth changes the `email` claim and now you're logged in.
+
+## Contributing
+
+Found an Issue or want to see something implemented into Mailauth?
+Open up an Issue or start a Pull Request!
+
+But always be respectful and patient, we are all volunteers after all.
+
+## Supporting
+
+Found this Project useful? Let others know about Mailauth by ⭐️ this Repo!
+
+## License
+
+[MIT](https://choosealicense.com/licenses/mit/)