- Elixir 97.2%
- CSS 1%
- HTML 0.8%
- JavaScript 0.5%
- Shell 0.2%
- Other 0.1%
| Filename | Latest commit message | Latest commit date |
|---|---|---|
|
All checks were successful
continuous-integration/drone/push Build is passing
Reviewed-on: #699 |
||
| .forgejo | ||
| .opencode/screenshots | ||
| assets | ||
| ci | ||
| config | ||
| dev | ||
| docs | ||
| lib | ||
| priv | ||
| rauthy-bootstrap | ||
| rel/overlays/bin | ||
| test | ||
| .credo.exs | ||
| .deps_audit_ignore | ||
| .dialyzer_ignore.exs | ||
| .dockerignore | ||
| .drone.jsonnet | ||
| .editorconfig | ||
| .env.example | ||
| .formatter.exs | ||
| .gitattributes | ||
| .gitignore | ||
| .igniter.exs | ||
| .sobelow-conf | ||
| .tool-versions | ||
| CHANGELOG.md | ||
| CODE_GUIDELINES.md | ||
| DESIGN_GUIDELINES.md | ||
| docker-compose.prod.yml | ||
| docker-compose.yml | ||
| Dockerfile | ||
| Justfile | ||
| LICENSE | ||
| logo.png | ||
| mix.exs | ||
| mix.lock | ||
| publiccode.yml | ||
| README.md | ||
| renovate.json | ||
| renovate_backend_config.js | ||
Mila
Mila — simple, usable, self-hostable membership management for small to mid-sized clubs.
🚧 Project Status
⚠️ First Version — 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.
User Documentation (German)
You can find our documentation for users here: https://wiki.local-it.org/s/mila-user-dokumentation
🔑 Features
- ✅ Manage member data with ease
- ✅ Membership fees & payment status tracking
- ✅ Full-text search with fuzzy matching
- ✅ Sorting & filtering
- ✅ Roles & permissions (RBAC system with 4 permission sets)
- ✅ Custom fields (flexible per club needs)
- ✅ SSO via OIDC (works with Authentik, Rauthy, Keycloak, etc.)
- ✅ Sidebar navigation (standard-compliant, accessible)
- ✅ Global settings management
- ✅ Self-service & online application
- ✅ Accessibility improvements (WCAG 2.1 AA compliant keyboard navigation)
- ✅ Email sending
- ✅ Integration of Accounting-Software (Vereinfacht)
🚀 Quick Start (Development)
Prerequisites
We recommend using asdf for managing tool versions.
- Tested with:
asdf 0.16.5 - Required versions are documented in
.tool-versionsin this repo
Install system dependencies (Debian/Ubuntu)
# 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
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):
asdf completion fish > ~/.config/fish/completions/asdf.fish
set -gx PATH "$HOME/.asdf/shims" $PATH
Bash example (~/.bash_profile and ~/.bashrc):
export PATH="${ASDF_DATA_DIR:-$HOME/.asdf}/shims:$PATH"
. <(asdf completion bash)
Install project dependencies
git clone https://git.local-it.org/local-it/mitgliederverwaltung.git mila
cd mila
asdf plugin add elixir
asdf plugin add erlang
asdf plugin add just
asdf install
# Inside the repo folder:
mix local.hex
mix archive.install hex phx_new
Note: running
mix local.hexmust be done inside the repo folder,
because.tool-versionsdefines the Erlang/Elixir versions.
Run the app
-
Copy env file:
cp .env.example .envThe dev
OIDC_CLIENT_SECRETis already preset — no manual GUI step needed. -
Start everything (database, Mailcrab, Rauthy, app):
just run -
Services will be available at:
- App: http://localhost:4000
- Mail UI: http://localhost:1080
- Postgres:
localhost:5000
🔐 Testing SSO locally
A local Rauthy instance is provided in dev. The mv client is auto-seeded from rauthy-bootstrap/clients.json on first start (and after docker compose down -v), so the secret in .env.example always matches.
Rauthy admin UI: http://localhost:8080 — login admin@localhost, password from BOOTSTRAP_ADMIN_PASSWORD_PLAIN in docker-compose.yml.
OIDC with other providers (Authentik, Keycloak, etc.)
Mila works with any OIDC-compliant provider. The internal strategy is named :oidc — it works with any OIDC-compliant provider.
Important: The redirect URI must always end with /auth/user/oidc/callback.
Example for Authentik:
-
Create an OAuth2/OpenID Provider in Authentik
-
Set the redirect URI to:
https://your-domain.com/auth/user/oidc/callback -
Configure environment variables:
DOMAIN=your-domain.com # or PHX_HOST=your-domain.com OIDC_CLIENT_ID=your-client-id OIDC_BASE_URL=https://auth.example.com/application/o/your-app OIDC_CLIENT_SECRET=your-client-secret # or use OIDC_CLIENT_SECRET_FILESet
OIDC_REDIRECT_URI=https://your-domain.com/auth/user/oidc/callbackas well: once one non-secret OIDC variable is set, all OIDC connection values come from the environment (see below).
Environment variables and the settings page
SMTP, OIDC and the Vereinfacht integration can be configured in the settings page or through environment variables. The same rules apply to all three:
- A blank variable counts as unset.
OIDC_CLIENT_ID=orOIDC_CLIENT_ID=${OIDC_CLIENT_ID}with an empty host variable falls back to the settings page. - Each integration switches as a whole. As soon as one non-secret variable of an integration is
set (e.g.
SMTP_PORT,OIDC_BASE_URL,VEREINFACHT_CLUB_ID), all its non-secret values come from the environment. The settings page shows them read-only, says above them that the integration comes from the environment and how many required values are missing, and names each field's variable below it. - Secrets one by one.
SMTP_PASSWORD,OIDC_CLIENT_SECRETandVEREINFACHT_API_KEY(and theSMTP_PASSWORD_FILE/OIDC_CLIENT_SECRET_FILEfiles) can also be set alone; the other values of that integration then stay editable in the settings page. When both a variable and its file are set,SMTP_PASSWORDwins overSMTP_PASSWORD_FILE, whileOIDC_CLIENT_SECRET_FILEwins overOIDC_CLIENT_SECRET; the settings page names the variable the value in effect comes from. - Single fields.
OIDC_ONLY,MAIL_FROM_NAMEandMAIL_FROM_EMAILeach override only their own field. - Club name.
ASSOCIATION_NAMEis only used when the database is set up for the first time; afterwards the club name is edited in the settings page and the variable is ignored.
⚙️ Configuration
- Env vars: see
.env.example
🏗️ Architecture
Tech Stack Overview:
- Backend: Elixir + Phoenix + Ash Framework
- Frontend: Phoenix LiveView + Tailwind CSS + DaisyUI
- Database: PostgreSQL
- Auth: AshAuthentication (OIDC + password)
Code Structure:
lib/mv/accounts/&lib/mv/membership/&lib/mv/membership_fees/&lib/mv/authorization/— Ash resources and domainslib/mv_web/— Phoenix controllers, LiveViews, componentslib/mv/— Shared helpers and business logicassets/— Tailwind, JavaScript, static filestest/— All tests
📚 Full tech stack details: See CODE_GUIDELINES.md
📖 Implementation history: See docs/development-progress-log.md
🗄️ Database schema: See docs/database-schema-readme.md
🧑💻 Development
Common commands:
just run # Start full dev environment
just test # Run test suite
just lint # Code style checks
just audit # Security audits
just reset-database # Reset local DB
📚 Full development guidelines: See CODE_GUIDELINES.md
📦 Production Deployment
Local Production Testing
For testing the production Docker build locally:
-
Generate secrets:
mix phx.gen.secret # for SECRET_KEY_BASE mix phx.gen.secret # for TOKEN_SIGNING_SECRET -
Create
.envfile:# Copy template and edit cp .env.example .env nano .env -
Start production environment:
docker compose -f docker-compose.prod.yml up -
Database migrations run automatically on app start. For manual migration:
docker compose -f docker-compose.prod.yml exec app /app/bin/mv eval "Mv.Release.migrate" -
Access the production app:
- Production App: http://localhost:4001
- Uses same Rauthy instance as dev (localhost:8080)
Note: The local production setup uses network_mode: host to share localhost with the development Rauthy instance. For real production deployment, configure an external OIDC provider and remove network_mode: host.
Real Production Deployment
For actual production deployment:
- Use an external OIDC provider (not the local Rauthy)
- Update
docker-compose.prod.yml:- Remove
network_mode: host - Set
OIDC_BASE_URLto your production OIDC provider - Configure proper Docker networks
- Remove
- Set up SSL/TLS (e.g., via reverse proxy like Nginx/Traefik) and let the proxy pass on the client address (see below)
- Use secure secrets management — The secret environment variables except
VEREINFACHT_API_KEYsupport a_FILEsuffix for Docker secrets (e.g.,SECRET_KEY_BASE_FILE=/run/secrets/secret_key_base); a blank_FILEvariable counts as unset. Seedocker-compose.prod.ymlfor an example setup with Docker secrets. - Configure database backups
- Before every upgrade, back up the database and read the Upgrade notes in the CHANGELOG of every release since the one you run, oldest first. Skipping releases is fine; migrations run at start.
Reverse proxy and client address
Mila limits sign-in attempts, password reset requests and join requests per client address. Behind a reverse proxy, every request comes from the proxy, so Mila reads the client address from the proxy's headers — but only when the request comes from a trusted proxy:
- Trusted proxies are set with
TRUSTED_PROXIES(addresses and CIDR networks, separated by commas, e.g.TRUSTED_PROXIES=10.0.0.0/8,192.0.2.10, ornone). Unset, loopback and the private networks (10.0.0.0/8,172.16.0.0/12,192.168.0.0/16,fc00::/7) are trusted, which covers a proxy on the same host or in the same Docker network. Mila does not start with an invalid entry. - From a trusted proxy, Mila takes the last entry of
X-Forwarded-For(over all lines of the header). The proxy must therefore append the client address toX-Forwarded-For, as an entry or a line of its own. Traefik (also in the Co-op Cloud recipe) and Caddy do this by default. Nginx needsproxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;, HAProxyoption forwardfor. A trusted proxy that passes the client'sX-Forwarded-Foron unchanged lets every client choose its own address, so check this before you upgrade.X-Real-IPis not read: a proxy that does not set it passes on whatever the client sent. - Requests from any other address are keyed on that address; their headers are ignored.
- Without a proxy, or when clients can reach the app port (
4001) on a private network, setTRUSTED_PROXIES=none: otherwise a client on that network can choose its own address. The same holds when Docker hands connections on from its private gateway address (e.g. a published port reached over IPv6); behind a proxy, setTRUSTED_PROXIESto the proxy's address then.docker-compose.prod.ymlpublishes the port for local testing; in production, publish it only to the proxy. - Only one proxy hop is supported: behind two proxies, the last
X-Forwarded-Forentry is the inner proxy. List only the proxy that talks to Mila. - The limits are kept per Mila node in memory and reset on restart.
Container images and tags
Images are published to git.local-it.org/local-it/mitgliederverwaltung. Pick the tag by what you need:
| Tag | Points at | Changes | Use it if you … |
|---|---|---|---|
latest |
the newest release | with every release | want the current stable version without choosing one |
1.4, 1 |
the newest patch of 1.4, the newest 1.x release | with every release of that line | want patch updates within a line |
1.4.0 |
exactly that release | never | pin a version and upgrade deliberately (recommended for production) |
main |
the tip of the main branch, rebuilt on every push |
with every merge | follow development with a pull-based updater, or test unreleased changes |
<sha> (8 characters) |
one commit of main |
never | deploy from CI: deploy the commit you just built, and roll back to an earlier one |
Do not let an updater move you across versions unattended. Database migrations run on start and only forwards, so going back to an older image after an upgrade is not supported. An auto-updater (Watchtower or similar) on latest, 1 or main upgrades — and migrates — without you deciding to; prefer an exact version and read the changelog before each upgrade.
Continuous deployment should deploy the immutable <sha> tag it just built, not main: a moving tag leaves open which build actually runs. main is meant for pull-based updaters and manual testing.
The running version is shown to admins at the end of the settings page (Basic settings → Version): the release number, or "development build after X.Y.Z" for anything else, and the commit. The image carries the same as the labels org.opencontainers.image.version and org.opencontainers.image.revision.
Releasing a version
How maintainers release a version, and what CI checks for it, is described in docs/releasing.md; what CI runs on each push, pull request and merge in docs/ci.md.
🤝 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 file for details.
📬 Contact
- Issues: GitLab Issues
- E-Mail: info@local-it.org