mitgliederverwaltung/README.md

# Mila

**Mila** — simple, usable, self-hostable membership management for small to mid-sized clubs.  

[![Build Status](https://drone.dev.local-it.cloud/api/badges/local-it/mitgliederverwaltung/status.svg)](https://drone.dev.local-it.cloud/local-it/mitgliederverwaltung)
![License](https://img.shields.io/badge/license-AGPL--v3-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**: Customize what data you collect about members, 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  

<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 
mix archive.install hex phx_new 
```

> 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`
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)
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, LiveView, Ash Framework  
- **Frontend:** Phoenix LiveView + DaisyUI + 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: AGPLv3**  
See the [LICENSE](LICENSE) file for details.  

## 📬 Contact

- Issues: [GitLab Issues](https://git.local-it.org/local-it/mitgliederverwaltung/-/issues)  
- Community links: coming soon.