Setup MedUX for Development

This guide walks you through setting up a development environment for the MedUX core application. If you only want to develop a plugin, see Developing MedUX Plugins instead.

Prerequisites

• Python 3.13+
• uv (package manager)
• Git

Clone the Repository

git clone git@gitlab.com:nerdocs/medux/medux.git
cd medux

MedUX depends on conjunto and gdaps as local editable packages. Clone them as siblings:

git clone git@gitlab.com:nerdocs/conjunto.git ../conjunto
git clone git@gitlab.com:nerdocs/gdaps.git ../gdaps

Install Dependencies

make dev-local
make bootstrap

make dev-local runs uv sync against the committed lockfile (which during alpha resolves conjunto and gdaps from their Git main branches via [tool.uv.sources]) and then overlays ../conjunto and ../gdaps as editable installs via uv pip install --python .venv/bin/python --no-deps -e .... It never mutates pyproject.toml or uv.lock. make bootstrap then applies migrations, syncs plugins, and creates an admin user (password: admin).

Activate the venv — mandatory for every session

source .venv/bin/activate

Activate the venv, don't use uv run

Every development session must start with source .venv/bin/activate. From that point on, use the tools installed into the venv directly:

bash medux migrate medux runserver pytest ruff check . pre-commit install

Do not prefix them with uv run — uv run implicitly syncs the venv against uv.lock, which removes the editable overlay of ../conjunto and ../gdaps you just installed with make dev-local. You would then have to run make dev-local again to restore it.

uv is still the right tool for dependency management (uv sync, uv add, uv lock) — just not for running tools against the overlay-enhanced venv.

Local vs. Git-main Dependencies

During the alpha phase conjunto and gdaps are not published to PyPI. MedUX's committed pyproject.toml therefore pins their source in [tool.uv.sources]:

[tool.uv.sources]
conjunto = { git = "https://gitlab.com/nerdocs/conjunto.git", rev = "main" }
gdaps    = { git = "https://gitlab.com/nerdocs/gdaps.git",    rev = "main" }

uv sync resolves against these Git URLs and installs the current main HEAD. Local editable sibling checkouts live as an overlay on top of that Git-synced venv:

Command	Effect
make dev-local	uv sync + uv pip install --python .venv/bin/python --no-deps -e ../conjunto ../gdaps
make dev-pypi	uv sync only (no overlay; still resolves from Git main)

The overlay reinstalls conjunto and gdaps from sibling checkouts without touching pyproject.toml or uv.lock. git push no longer needs to stash / switch / restore — the committed state stays pristine and CI resolves from Git main exactly as committed.

Note

uv sync is authoritative: it will remove any package not in uv.lock, including the editable overlay. Re-run make dev-local after every uv sync.

Warning

A pre-commit hook (no-local-uv-sources) guards against accidentally committing a [tool.uv.sources] block with local file paths — only git = "..." entries are allowed in the committed pyproject.

Configure the Environment

Create a .env file in the src/ directory. MedUX defaults to SQLite if no .env is present, which is fine for development.

For PostgreSQL:

DATABASE_ENGINE=django.db.backends.postgresql
DATABASE_NAME=medux
DATABASE_USER=myuser
DATABASE_PASS=mypassword
DEBUG=True

Run the Development Server

medux runserver

Note

As long as MedUX is pre-1.0, database migrations may change without notice. If your database breaks after an update, delete it and re-run make bootstrap. Do not use this in production.

Install External Plugins Locally

Clone a plugin as a sibling directory and install it editable:

git clone git@gitlab.com:nerdocs/medux/medux-device-management.git ../medux-device-management
uv pip install --python .venv/bin/python --no-deps -e ../medux-device-management
medux migrate
medux syncplugins

Useful Make Targets

Target	Description
make bootstrap	Full setup: sync, migrate, syncplugins, init
make dev-local	uv sync + editable overlay of sibling checkouts
make dev-pypi	uv sync only (no overlay)
make sync	Install/update dependencies
make migrate	Run database migrations
make staticfiles	Compile JS i18n and collect static files
make locale	Generate and compile translations
make test	Run pytest
make check	Run ruff linter

Code Style

• Python 3.13+, formatted with Ruff
• Linted with Ruff
• Pre-commit hooks (venv activated): pre-commit install
• Run all checks (venv activated): pre-commit run --all-files