Development: update devcontainer setup, add documentation for pre-commit, set uv cache dir (#11882)

.devcontainer/README.md

@@ -89,6 +89,18 @@ Additional tasks are available for common maintenance operations:
 - **Migrate Database**: To apply database migrations.
 - **Create Superuser**: To create an admin user for the application.
 
+## Committing from the Host Machine
+
+The DevContainer automatically installs pre-commit hooks during setup. However, these hooks are configured for use inside the container.
+
+If you want to commit changes from your host machine (outside the DevContainer), you need to set up pre-commit on your host. This installs it as a standalone tool.
+
+```bash
+uv tool install pre-commit && pre-commit install
+```
+
+After this, you can commit either from inside the DevContainer or from your host machine.
+
 ## Let's Get Started!
 
 Follow the steps above to get your development environment up and running. Happy coding!

.devcontainer/devcontainer.json

@@ -3,26 +3,30 @@
     "dockerComposeFile": "docker-compose.devcontainer.sqlite-tika.yml",
     "service": "paperless-development",
     "workspaceFolder": "/usr/src/paperless/paperless-ngx",
-    "postCreateCommand": "/bin/bash -c 'rm -rf .venv/.*  && uv sync --group dev && uv run pre-commit install'",
+    "containerEnv": {
+        "UV_CACHE_DIR": "/usr/src/paperless/paperless-ngx/.uv-cache"
+    },
+    "postCreateCommand": "/bin/bash -c 'rm -rf .venv/.* && uv sync --group dev && uv run pre-commit install'",
     "customizations": {
         "vscode": {
-          "extensions": [
+            "extensions": [
-            "mhutchie.git-graph",
+                "mhutchie.git-graph",
-            "ms-python.python",
+                "ms-python.python",
-            "ms-vscode.js-debug-nightly",
+                "ms-vscode.js-debug-nightly",
-            "eamodio.gitlens",
+                "eamodio.gitlens",
-            "yzhang.markdown-all-in-one"
+                "yzhang.markdown-all-in-one",
-          ],
+                "pnpm.pnpm"
-          "settings": {
+            ],
-            "python.defaultInterpreterPath": "/usr/src/paperless/paperless-ngx/.venv/bin/python",
+            "settings": {
-            "python.pythonPath": "/usr/src/paperless/paperless-ngx/.venv/bin/python",
+                "python.defaultInterpreterPath": "/usr/src/paperless/paperless-ngx/.venv/bin/python",
-            "python.terminal.activateEnvInCurrentTerminal": true,
+                "python.pythonPath": "/usr/src/paperless/paperless-ngx/.venv/bin/python",
-            "editor.formatOnPaste": false,
+                "python.terminal.activateEnvInCurrentTerminal": true,
-            "editor.formatOnSave": true,
+                "editor.formatOnPaste": false,
-            "editor.formatOnType": true,
+                "editor.formatOnSave": true,
-            "files.trimTrailingWhitespace": true
+                "editor.formatOnType": true,
-          }
+                "files.trimTrailingWhitespace": true
+            }
         }
-      },
+    },
-      "remoteUser": "paperless"
+    "remoteUser": "paperless"
-    }
+}

.devcontainer/vscode/tasks.json

@@ -174,12 +174,22 @@
 		{
 			"label": "Maintenance: Install Frontend Dependencies",
 			"description": "Install frontend (pnpm) dependencies",
-			"type": "pnpm",
+			"type": "shell",
-			"script": "install",
+			"command": "pnpm install",
-			"path": "src-ui",
 			"group": "clean",
 			"problemMatcher": [],
-			"detail": "install dependencies from package"
+			"options": {
+				"cwd": "${workspaceFolder}/src-ui"
+			},
+			"presentation": {
+				"echo": true,
+				"reveal": "always",
+				"focus": true,
+				"panel": "shared",
+				"showReuseMessage": false,
+				"clear": true,
+				"revealProblems": "onProblem"
+			}
 		},
 		{
 			"description": "Clean install frontend dependencies and build the frontend for production",

.gitignore

@@ -40,6 +40,7 @@ htmlcov/
 .coverage
 .coverage.*
 .cache
+.uv-cache
 nosetests.xml
 coverage.xml
 *,cover