From 9f8b412d2323ec30cafa47943a9dcffb18469f71 Mon Sep 17 00:00:00 2001 From: Simon Date: Thu, 2 Oct 2025 15:23:46 +0200 Subject: [PATCH] docs: polish readme --- README.md | 236 ++++++++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 229 insertions(+), 7 deletions(-) diff --git a/README.md b/README.md index 38013f4..00aa220 100644 --- a/README.md +++ b/README.md @@ -1,18 +1,240 @@ -# mitgliederverwaltung +# Mila -## Testing SSO with rauthy +**Mila** β€” simple, usable, self-hostable membership management for small to mid-sized clubs. + +[![CI Status](https://img.shields.io/badge/build-pending-lightgrey.svg)](link-to-ci) +![License](https://img.shields.io/badge/license-TBD-blue) + +--- + +## 🚧 Project Status + +⚠️ **Early development** β€” not production-ready. Expect breaking changes. +Contributions and feedback are welcome! + +--- + +## ✨ Overview + +Mila is a free and open-source membership management tool designed for real club needs. +It is **self-hosting friendly**, aims for **accessibility and GDPR compliance**, and focuses on **usability** instead of feature overload. + +--- + +## πŸ’‘ Why Mila? + +Most membership tools for clubs are either: + +* **Too complex** β€” overloaded with features small and mid-sized clubs don’t need +* **Too expensive** β€” hidden fees, closed ecosystems, vendor lock-in +* **Too rigid** β€” no way to adapt fields, processes, or roles to your club’s reality + +**Mila** is different: + +* **Simple**: Focused on what clubs really need β€” members, dues, communication. +* **Usable**: Clean, accessible UI, GDPR-compliant, designed with everyday volunteers in mind. +* **Flexible**: Custom fields, role-based permissions, and self-service for members. +* **Truly open**: 100% free and open source β€” no lock-in, transparent code, self-host friendly. + +Our philosophy: **software should help people spend less time on administration and more time on their community.** + +--- + +## πŸ“Έ Screenshots + +![Screenshot placeholder](docs/images/screenshot.png) +*This is how Mila might look in action.* + +--- + +## πŸ”‘ Features + +- βœ… Manage member data with ease +- 🚧 Overview of membership fees & payment status +- βœ… Full-text search +- 🚧 Sorting & filtering +- 🚧 Roles & permissions (e.g. board, treasurer) +- βœ… Custom fields (flexible per club needs) +- βœ… SSO via OIDC (tested with Rauthy) +- 🚧 Self-service & online application +- 🚧 Accessibility, GDPR, usability improvements +- 🚧 Email sending + +--- + +## πŸš€ Quick Start (Development) + +### Prerequisites + +We recommend using **[asdf](https://asdf-vm.com/)** for managing tool versions. +- Tested with: `asdf 0.16.5` +- Required versions are documented in `.tool-versions` in this repo + +
+Install system dependencies (Debian/Ubuntu) + +```bash +# Debian 12 +apt-get -y install build-essential autoconf m4 libncurses-dev libwxgtk3.2-dev libwxgtk-webview3.2-dev libgl1-mesa-dev libglu1-mesa-dev libpng-dev libssh-dev unixodbc-dev xsltproc fop libxml2-utils openjdk-17-jdk icu-devtools bison flex pkg-config + +# Ubuntu 24 +apt-get -y install build-essential autoconf m4 libwxgtk3.2-dev libwxgtk-webview3.2-dev libgl1-mesa-dev libglu1-mesa-dev libpng-dev libssh-dev unixodbc-dev xsltproc fop libxml2-utils libncurses-dev openjdk-11-jdk icu-devtools bison flex libreadline-dev +``` +
+ +
+Install asdf + +```bash +mkdir ~/.asdf +cd ~/.asdf +wget https://github.com/asdf-vm/asdf/releases/download/v0.16.5/asdf-v0.16.5-linux-amd64.tar.gz +tar -xvf asdf-v0.16.5-linux-amd64.tar.gz +ln -s ~/.asdf/asdf ~/.local/bin/asdf +``` + +Then follow the official β€œShell Configuration” steps in the asdf docs. + +*Fish example* (`~/.config/fish/config.fish`): + +```fish +asdf completion fish > ~/.config/fish/completions/asdf.fish +set -gx PATH "$HOME/.asdf/shims" $PATH +``` + +*Bash example* (`~/.bash_profile` and `~/.bashrc`): + +```bash +export PATH="${ASDF_DATA_DIR:-$HOME/.asdf}/shims:$PATH" +. <(asdf completion bash) +``` +
+ +### Install project dependencies + +```bash +git clone https://git.local-it.org/local-it/mitgliederverwaltung.git mila +cd mila +asdf install + +# Inside the repo folder: +mix local.hex 2.1.1 +mix archive.install hex phx_new 1.7.20 +``` + +> Note: running `mix local.hex` must be done inside the repo folder, +> because `.tool-versions` defines the Erlang/Elixir versions. + +--- + +### Run the app + +1. Copy env file: + ```bash + cp .env.example .env + # Set OIDC_CLIENT_SECRET inside .env + ``` + +2. Start everything (database, Mailcrab, Rauthy, app): + ```bash + just run + ``` + +3. Services will be available at: + - App: + - Mail UI: + - Postgres: `localhost:5000` + +--- + +## πŸ” Testing SSO locally + +Mila uses OIDC for Single Sign-On. In development, a local **Rauthy** instance is provided. 1. `just run` -1. go to [localhost:8080](http://localhost:8080), go to the Admin area -1. Login with "admin@localhost" and password from `BOOTSTRAP_ADMIN_PASSWORD_PLAIN` in docker-compose.yml -1. add client from the admin panel +2. go to [localhost:8080](http://localhost:8080), go to the Admin area +3. Login with "admin@localhost" and password from `BOOTSTRAP_ADMIN_PASSWORD_PLAIN` in docker-compose.yml +4. add client from the admin panel - Client ID: mv - redirect uris: http://localhost:4000/auth/user/rauthy/callback - Authorization Flows: authorization_code - allowed origins: http://localhost:4000 - access/id token algortihm: RS256 (EDDSA did not work for me, found just few infos in the ashauthentication docs) -1. copy client secret to `.env` file -1. abort and run `just run` again +5. copy client secret to `.env` file +6. abort and run `just run` again +Now you can log in to Mila via OIDC! +--- +## βš™οΈ Configuration + +- **Env vars:** see `.env.example` + - `OIDC_CLIENT_SECRET` β€” secret for your OIDC client +- Database defaults (Docker Compose): + - Host: `localhost` + - Port: `5000` + - User/pass: `postgres` / `postgres` + - DB: `mila_dev` + +--- + +## πŸ—οΈ Architecture + +- **Backend:** Elixir, Phoenix 1.8, LiveView 1.1, Ash Framework +- **Frontend:** Phoenix LiveView + TailwindCSS + Heroicons +- **Database:** PostgreSQL (via AshPostgres) +- **Auth:** AshAuthentication (OIDC + password strategy) +- **Mail:** Swoosh +- **i18n:** Gettext + +Code structure: +- `lib/mv/` β€” core Ash resources/domains (`Accounts`, `Membership`) +- `lib/mv_web/` β€” Phoenix controllers, LiveViews, components +- `assets/` β€” frontend assets (Tailwind, JS, etc.) + +--- + +## πŸ§‘β€πŸ’» Development + +Useful `just` commands: +- `just run` β€” start DB, Mailcrab, Rauthy, app +- `just test` β€” run tests +- `just lint` β€” run code style checks (credo, formatter) +- `just audit` β€” run security audits +- `just reset-database` β€” reset local DB +- `just regen-migrations ` β€” regenerate migrations + +--- + +## πŸ“¦ Deployment + +A production release image is built via the provided `Dockerfile`. +Entrypoint: `/app/bin/server`. + +More detailed deployment docs are planned. + +--- + +## 🀝 Contributing + +We welcome contributions! +- Open issues and PRs in this repo. +- Please follow existing code style and conventions. +- Expect breaking changes while the project is in early development. + +--- + +## πŸ“„ License + +**License: TBD** (Free and Open Source). +A proper license file will be added soon. + +--- + +## πŸ“¬ Contact + +- Issues: [GitLab Issues](https://git.local-it.org/local-it/mitgliederverwaltung/-/issues) +- Community links: coming soon. + +---