No description
  • Elixir 97.2%
  • CSS 1%
  • HTML 0.8%
  • JavaScript 0.5%
  • Shell 0.2%
  • Other 0.1%
Find a file
Repository files (latest commit first)
Filename Latest commit message Latest commit date
Simon cd602f1973
All checks were successful
continuous-integration/drone/push Build is passing
Merge pull request 'chore(deps): update mix dependencies' (#699) from renovate/mix-dependencies into main
Reviewed-on: #699
2026-11-20 09:03:58 +01:00
.forgejo docs(ci): describe what CI runs on each event and which check protects main 2026-11-13 14:09:12 +01:00
.opencode/screenshots docs(opencode): add publiccode.yml, logo and screenshots for software directory 2026-06-04 15:00:31 +02:00
assets Merge remote-tracking branch 'origin/main' into issue/mitgliederverwaltung-669 2026-11-19 12:55:51 +01:00
ci ci(skip-check): stop the branch tests once a pull request opens for the branch 2026-11-13 18:10:02 +01:00
config Merge remote-tracking branch 'origin/main' into chore/prepare-1.6.0 2026-11-19 00:16:10 +01:00
dev feat(ui): add a view dialog that only shows content, closed with Close 2026-11-18 13:12:53 +01:00
docs docs(test): name the five patterns behind random red test runs 2026-11-19 16:33:49 +01:00
lib Merge remote-tracking branch 'origin/main' into issue/mitgliederverwaltung-669 2026-11-19 12:55:51 +01:00
priv feat(whats-new): tell staff they now choose what members see of each data field 2026-11-19 13:04:41 +01:00
rauthy-bootstrap fix(auth): trigger RP-initiated logout at OIDC provider 2026-06-01 19:59:52 +02:00
rel/overlays/bin Run bootstrap seeds in production; add RUN_DEV_SEEDS support 2026-03-09 15:16:02 +01:00
test test(join): run the end-to-end join flow async with a process-local settings override 2026-11-19 16:33:49 +01:00
.credo.exs ci(credo): gate function size, module coupling and duplication as a ratchet 2026-11-13 13:51:06 +01:00
.deps_audit_ignore fix(auth): close the ash_authentication advisories by upgrading to 4.15 with OIDC user identities 2026-10-08 00:47:20 +02:00
.dialyzer_ignore.exs feat(dialyzer): add typecheck stage to full CI pipelines 2026-06-01 23:45:07 +02:00
.dockerignore Add Release scripts & Dockerfile 2025-05-22 02:12:20 +02:00
.drone.jsonnet chore(deps): update postgres:18.7-alpine docker digest to b6972e1 2026-11-16 00:02:54 +00:00
.editorconfig configure renovate 2025-05-14 16:39:57 +02:00
.env.example fix(auth): take the client address from proxy headers only behind a trusted proxy 2026-11-18 12:33:25 +01:00
.formatter.exs ci(lint): fail on empty plural translations and on a JavaScript bundle that does not build 2026-11-13 13:17:16 +01:00
.gitattributes test(export): pin the CSV export format and both controllers' error responses 2026-10-15 14:34:13 +02:00
.gitignore chore: pin nodejs for browser-test tooling; ignore /node_modules 2026-06-08 11:53:27 +02:00
.igniter.exs chore(AshAuthenticationPhoenix): added library and updated ressources testing password strategy 2025-07-02 17:03:37 +02:00
.sobelow-conf Add basic CI setup (#30) 2025-04-28 14:24:30 +02:00
.tool-versions chore(deps): update node.js to v26.13.1 2026-11-12 00:02:53 +00:00
CHANGELOG.md Merge remote-tracking branch 'origin/main' into issue/mitgliederverwaltung-669 2026-11-19 12:55:51 +01:00
CODE_GUIDELINES.md docs(test): name the five patterns behind random red test runs 2026-11-19 16:33:49 +01:00
DESIGN_GUIDELINES.md Merge remote-tracking branch 'origin/main' into issue/mitgliederverwaltung-669 2026-11-19 12:55:51 +01:00
docker-compose.prod.yml chore(deps): update postgres docker tag to v18.7 2026-11-13 00:02:25 +00:00
docker-compose.yml chore(deps): update postgres docker tag to v18.7 2026-11-13 00:02:25 +00:00
Dockerfile ci(release): promote the tested main image for a release instead of rebuilding it 2026-11-09 20:03:15 +01:00
Justfile test: fail a full run when a serial test module grows past its time limit 2026-11-13 14:09:12 +01:00
LICENSE feat: add license closes #150 2025-10-02 17:12:06 +02:00
logo.png docs(opencode): add publiccode.yml, logo and screenshots for software directory 2026-06-04 15:00:31 +02:00
mix.exs Merge pull request 'chore(deps): update mix dependencies' (#689) from renovate/mix-dependencies into main 2026-11-19 12:51:19 +01:00
mix.lock chore(deps): update mix dependencies 2026-11-20 00:02:40 +00:00
publiccode.yml chore(release): release 1.6.0 2026-11-19 12:27:20 +01:00
README.md docs(readme): point the upgrade step at the changelog's upgrade notes 2026-11-19 12:11:17 +01:00
renovate.json ci: check each tree once, gate merges on the pull request check and test on the Postgres of production 2026-11-13 14:09:12 +01:00
renovate_backend_config.js configure renovate 2025-05-14 16:39:57 +02:00

Mila

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

Build Status License

🚧 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-versions in 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.hex must be done inside the repo folder,
because .tool-versions defines the Erlang/Elixir versions.

Run the app

  1. Copy env file:

    cp .env.example .env
    

    The dev OIDC_CLIENT_SECRET is already preset — no manual GUI step needed.

  2. Start everything (database, Mailcrab, Rauthy, app):

    just run
    
  3. Services will be available at:

🔐 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:

  1. Create an OAuth2/OpenID Provider in Authentik

  2. Set the redirect URI to: https://your-domain.com/auth/user/oidc/callback

  3. 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_FILE
    

    Set OIDC_REDIRECT_URI=https://your-domain.com/auth/user/oidc/callback as 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= or OIDC_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_SECRET and VEREINFACHT_API_KEY (and the SMTP_PASSWORD_FILE / OIDC_CLIENT_SECRET_FILE files) 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_PASSWORD wins over SMTP_PASSWORD_FILE, while OIDC_CLIENT_SECRET_FILE wins over OIDC_CLIENT_SECRET; the settings page names the variable the value in effect comes from.
  • Single fields. OIDC_ONLY, MAIL_FROM_NAME and MAIL_FROM_EMAIL each override only their own field.
  • Club name. ASSOCIATION_NAME is 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 domains
  • lib/mv_web/ — Phoenix controllers, LiveViews, components
  • lib/mv/ — Shared helpers and business logic
  • assets/ — Tailwind, JavaScript, static files
  • test/ — 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:

  1. Generate secrets:

    mix phx.gen.secret  # for SECRET_KEY_BASE
    mix phx.gen.secret  # for TOKEN_SIGNING_SECRET
    
  2. Create .env file:

    # Copy template and edit
    cp .env.example .env
    nano .env
    
  3. Start production environment:

    docker compose -f docker-compose.prod.yml up
    
  4. 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"
    
  5. Access the production app:

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:

  1. Use an external OIDC provider (not the local Rauthy)
  2. Update docker-compose.prod.yml:
    • Remove network_mode: host
    • Set OIDC_BASE_URL to your production OIDC provider
    • Configure proper Docker networks
  3. Set up SSL/TLS (e.g., via reverse proxy like Nginx/Traefik) and let the proxy pass on the client address (see below)
  4. Use secure secrets management — The secret environment variables except VEREINFACHT_API_KEY support a _FILE suffix for Docker secrets (e.g., SECRET_KEY_BASE_FILE=/run/secrets/secret_key_base); a blank _FILE variable counts as unset. See docker-compose.prod.yml for an example setup with Docker secrets.
  5. Configure database backups
  6. 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, or none). 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 to X-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 needs proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;, HAProxy option forwardfor. A trusted proxy that passes the client's X-Forwarded-For on unchanged lets every client choose its own address, so check this before you upgrade. X-Real-IP is 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, set TRUSTED_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, set TRUSTED_PROXIES to the proxy's address then. docker-compose.prod.yml publishes 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-For entry 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