Improve local development setup with uv

Author: Simrayz

.env.template

@@ -0,0 +1,16 @@
+# Copy this file to .env and fill in the values.
+# uv run will automatically load .env when running commands.
+#
+# For a full overview of environment variables, see the section
+# "Site-specific settings" of the documentation.
+
+DEBUG=1
+EMAIL_HOST=localhost
+EMAIL_PORT=25
+# Run `uv run manage.py gen_secret_key` to create a SECRET_KEY
+SECRET_KEY=
+
+# Use argus.site.settings.dev for defaults, or a local settings.py file (see docs)
+DJANGO_SETTINGS_MODULE=
+# Syntax: postgresql://argus:<LOCAL DB PASSWORD>@localhost:5432/argus
+DATABASE_URL=

.gitignore

@@ -9,6 +9,7 @@
 !.readthedocs.yaml
 !.sonarcloud.properties
 !.mailmap
+!.env.template
 
 # local config files
 cmd.sh

Makefile

@@ -1,10 +1,17 @@
-.PHONY: clean testclean distclean coverageclean cacheclean nuke tailwind docclean upgrade-tailwind tailwind-watch
+.PHONY: clean testclean distclean coverageclean cacheclean nuke tailwind docclean upgrade-tailwind tailwind-watch install run
 
 TAILWINDDIR=src/argus/htmx/tailwindtheme
 STATICDIR=src/argus/htmx/static
 PYTHONPATH=./src
 
 
+install:
+	uv sync --extra dev
+
+run:
+	uv run manage.py runserver
+
+
 clean:
 	-find . -name __pycache__ -print0 | xargs -0 rm -rf
 	-find . -name "*.pyc" -print0 | xargs -0 rm -rf

README.md

@@ -38,7 +38,7 @@ There are several ways to install Argus.
 
 * Python 3.10+
 * Django 5.2
-* pip
+* [uv](https://docs.astral.sh/uv/)
 * PostgreSQL 14+
 
 #### Optional requirements
@@ -76,10 +76,10 @@ the release was tested on. The file `constraints.txt` is for controlling
 versions of sub-dependencies so as to not poison the pyproject.toml. The wheel
 package does not contain either of these two files.
 
-To install from the lock-file use pip:
+To install from the lock-file use uv:
 
 ```console
-$ pip install -c constraints.txt --upgrade -r requirements.txt
+$ uv pip install -c constraints.txt --upgrade -r requirements.txt
 ```
 
 ### First run
@@ -110,7 +110,7 @@ $ python manage.py runserver
 To update the dependency lock-files, use `tox`:
 
 ```console
-$ pip install "tox>=4"
+$ uv pip install "tox>=4" tox-uv
 $ tox run -e upgrade-deps -- -U
 ```
 
@@ -171,39 +171,34 @@ $ git clone https://github.com/Uninett/Argus.git
 $ cd Argus
 ```
 
-We recommend using virtualenv or virtualenvwrapper to create
-a place to stash Argus' dependencies.
-
 Create and activate a Python virtual environment.
 ```console
-$ python -m venv venv
-$ source venv/bin/activate
+$ uv venv
+$ source .venv/bin/activate
 ```
 
 Install Argus' requirements into the virtual env.
 ```console
-$ pip install -r requirements-django52.txt
-$ pip install -r requirements/dev.txt
+$ uv pip install -r requirements-django52.txt
+$ uv pip install -r requirements/dev.txt
 ```
 
 ### Step 2: Setting environment variables and Django settings
 
-Copy the `cmd.sh-template` to `cmd.sh` and make it executable
+Copy `.env.template` to `.env` and fill in the values.
 ```console
-$ cp cmd.sh-template cmd.sh
-$ chmod u+x cmd.sh
+$ cp .env.template .env
 ```
-Now set the environment variables in the file using an editor.
 
-Required settings in `cmd.sh` are
+Required settings in `.env` are
 
 - `DATABASE_URL`,
 - `DJANGO_SETTINGS_MODULE` and
 - `SECRET_KEY`.
 
 `DJANGO_SETTINGS_MODULE` can be set to `argus.site.settings.dev`.
 
-If you need more complex settings than environment variables and ``cmd.sh`` can provide,
+If you need more complex settings than environment variables can provide,
 we recommend having a `localsettings.py` in the same directory as `manage.py` with any
 overrides.
 
@@ -217,10 +212,10 @@ See https://argus-server.readthedocs.io/en/latest/reference/htmx-frontend.html.
 
 ### Step 3: Run Argus in development
 
-Afterwards, run the initial Argus setup and start the server.
+`uv run` automatically loads the `.env` file. Run the initial Argus setup and start the server.
 ```console
-$ python manage.py initial_setup
-$ python manage.py runserver
+$ uv run manage.py initial_setup
+$ uv run manage.py runserver
 ```
 
 You will find Argus running at http://localhost:8000/.

docs/development/howtos/change-settings.rst

@@ -42,7 +42,7 @@ A settings file may override anything set via environment variable.
 ``argus.site.settings.prod`` is a good starting point for production.
 
 .. note:: The development settings file assumes that the optional development
-   dependencies are installed. You can get them via ``pip install argus-server[dev]``.
+   dependencies are installed. You can get them via ``uv sync --extra dev``.
 
 Development
 ~~~~~~~~~~~

docs/development/howtos/regenerate-the-ER-diagram.rst

@@ -11,7 +11,7 @@ Get dependencies
 
 You need to have installed the development dependencies to regenerate the diagram::
 
-    pip install argus-server[dev]
+    uv sync --extra dev
 
 This will install ``django_extensions`` which has the diagram generator we use.
 

docs/development/howtos/toggle-django-debug-toolbar.rst

@@ -15,15 +15,15 @@ Make sure it is installed
 You need to have ``django-debug-toolbar`` installed for this, it's part of the
 dev-dependencies so you can get it through any of::
 
-        pip install django-debug-toolbar
+        uv pip install django-debug-toolbar
 
 or::
 
-        pip install argus-server[dev]
+        uv pip install argus-server[dev]
 
 or::
 
-        pip install -r requirements/dev.txt
+        uv sync --extra dev
 
 Set up extra-apps with django-debug-toolbar
 -------------------------------------------

docs/development/makefile-rules.rst

@@ -4,11 +4,25 @@
 Makefile rules
 ==============
 
-The repo has a ``Makefile`` to help with development. None of the rules depend
-on a virtualenv being activated, but may depend on having python 3 in the path.
+The repo has a ``Makefile`` to help with development. The rules depend on having
+``uv`` installed.
 
 Always run ``make`` from the root of the repository.
 
+Rules for development setup
+===========================
+
+install
+-------
+
+Runs ``uv sync --extra dev`` to create a virtual environment and install all
+dependencies including dev extras.
+
+run
+---
+
+Runs the Django development server via ``uv run manage.py runserver``.
+
 Rules that delete files
 =======================
 

docs/development/management-commands.rst

@@ -53,7 +53,7 @@ as such:
 Generate a secret key
 ---------------------
 
-To generate a secret key to be used in the `cmd.sh` file one can use
+To generate a secret key to be used in the `.env` file one can use
 the command `gen_secret_key`:
 
     .. code:: console

docs/development/notes.rst

@@ -17,14 +17,9 @@ in Argus:
 2. using a ``settings.py`` file.
 
 For development, a simple and good practice is to define environment variables in a
-``cmd.sh`` file.
-This file serves as a "wrapper" to call ``manage.py`` with a defined set of environment
-variables, and simplifies the development process.
-
-You may find it useful to have several ``cmd.sh`` files for different purposes, for
-instance to invoke different databases.
-The files can be named ``cmd-local.sh``, ``cmd-prod.sh`` and ``cmd-demo.sh`` or
-similar.
+``.env`` file. Copy ``.env.template`` to ``.env`` and fill in the values. The dev
+settings (``argus.site.settings.dev``) will automatically load ``.env`` via
+``python-dotenv``.
 
 The limitation of environment variables is that they can only contain numbers, Boolean
 values (``0``/``1``) and strings.
@@ -44,5 +39,5 @@ files later.
         ``True``.
         Otherwise, logentries will appear twice.
 
-.. warning:: Do not check your ``cmd.sh`` or ``settings.py`` files into version control,
+.. warning:: Do not check your ``.env`` or ``settings.py`` files into version control,
         since they contain passwords and sensitive data.