docs: polish readme
This commit is contained in:
parent
1d334c7da1
commit
9f8b412d23
GPG key ID:
40E7A58C4AA1EDB2
1 changed files with 229 additions and 7 deletions
236
README.md
236
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.
|
||||
|
||||
[](link-to-ci)
|
||||
|
||||
|
||||
---
|
||||
|
||||
## 🚧 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
|
||||
|
||||
|
||||
*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
|
||||
|
||||
<details>
|
||||
<summary>Install system dependencies (Debian/Ubuntu)</summary>
|
||||
|
||||
```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
|
||||
```
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary>Install asdf</summary>
|
||||
|
||||
```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)
|
||||
```
|
||||
</details>
|
||||
|
||||
### 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: <http://localhost:4000>
|
||||
- Mail UI: <http://localhost:1080>
|
||||
- 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 <name>` — 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.
|
||||
|
||||
---
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue