Development: devcontainer improvements (#8553)

---------

Co-authored-by: shamoon <4887959+shamoon@users.noreply.github.com>

diff --git a/.devcontainer/devcontainer.json b/.devcontainer/devcontainer.json
index 337c96e3b4dbd525e453400b46f0867b5cce9c7c..34446caea486276b24b9ffcbbc0bde5e52f19e45 100644 (file)
--- a/.devcontainer/devcontainer.json
+++ b/.devcontainer/devcontainer.json
@@ -3,14 +3,26 @@
     "dockerComposeFile": "docker-compose.devcontainer.sqlite-tika.yml",
     "service": "paperless-development",
     "workspaceFolder": "/usr/src/paperless/paperless-ngx",
-    "postCreateCommand": "pipenv install --dev && pipenv run pre-commit install && pipenv shell",
+    "postCreateCommand": "pipenv install --dev && pipenv run pre-commit install",
     "customizations": {
         "vscode": {
-            "extensions": [
-              "mhutchie.git-graph",
-              "ms-python.python"
-            ]
+          "extensions": [
+            "mhutchie.git-graph",
+            "ms-python.python",
+            "ms-vscode.js-debug-nightly",
+            "eamodio.gitlens",
+            "yzhang.markdown-all-in-one"
+          ],
+          "settings": {
+            "python.defaultInterpreterPath": "/usr/src/paperless/paperless-ngx/.venv/bin/python",
+            "python.pythonPath": "/usr/src/paperless/paperless-ngx/.venv/bin/python",
+            "python.terminal.activateEnvInCurrentTerminal": true,
+            "editor.formatOnPaste": false,
+            "editor.formatOnSave": true,
+            "editor.formatOnType": true,
+            "files.trimTrailingWhitespace": true
+          }
         }
-    },
-    "remoteUser": "paperless"
-  }
+      },
+      "remoteUser": "paperless"
+    }

diff --git a/.devcontainer/docker-compose.devcontainer.sqlite-tika.yml b/.devcontainer/docker-compose.devcontainer.sqlite-tika.yml
index cd978ebcb36c673380b738a8e5f21ee74905d570..7209339e1b1ef9451e5279cfdef81b8fc3fdbe72 100644 (file)
--- a/.devcontainer/docker-compose.devcontainer.sqlite-tika.yml
+++ b/.devcontainer/docker-compose.devcontainer.sqlite-tika.yml
@@ -27,7 +27,7 @@ services:
     image: docker.io/library/redis:7
     restart: unless-stopped
     volumes:
-      - redisdata:/data
+      - ./redisdata:/data
 
   # No ports need to be exposed; the VSCode DevContainer plugin manages them.
   paperless-development:
@@ -43,14 +43,16 @@ services:
     volumes:
       - ..:/usr/src/paperless/paperless-ngx:delegated
       - ../.devcontainer/vscode:/usr/src/paperless/paperless-ngx/.vscode:delegated # VSCode config files
-      - pipenv:/usr/src/paperless/paperless-ngx/.venv # Pipenv environment persisted in volume
+      - pipenv:/usr/src/paperless/paperless-ngx/.venv
       - /usr/src/paperless/paperless-ngx/src/documents/static/frontend # Static frontend files exist only in container
       - /usr/src/paperless/paperless-ngx/src/.pytest_cache
       - /usr/src/paperless/paperless-ngx/.ruff_cache
       - /usr/src/paperless/paperless-ngx/htmlcov
       - /usr/src/paperless/paperless-ngx/.coverage
-      - data:/usr/src/paperless/paperless-ngx/data
-      - media:/usr/src/paperless/paperless-ngx/media
+      - ./data:/usr/src/paperless/paperless-ngx/data
+      - ./media:/usr/src/paperless/paperless-ngx/media
+      - ./consume:/usr/src/paperless/paperless-ngx/consume
+      - ~/.gitconfig:/usr/src/paperless/.gitconfig:ro
     environment:
       PAPERLESS_REDIS: redis://broker:6379
       PAPERLESS_TIKA_ENABLED: 1
@@ -78,7 +80,4 @@ services:
     restart: unless-stopped
 
 volumes:
-  data:
-  media:
-  redisdata:
   pipenv:

diff --git a/.devcontainer/vscode/launch.json b/.devcontainer/vscode/launch.json
index 2c50af44b5c2a585c0b906fa073f589102543eac..b212266301612beb404dc57c8fa6912ce898cdb5 100644 (file)
--- a/.devcontainer/vscode/launch.json
+++ b/.devcontainer/vscode/launch.json
@@ -2,42 +2,53 @@
     "version": "0.2.0",
     "configurations": [
         {
-            "name": "manage.py runserver",
-            "type": "python",
+            "name": "Chrome: Debug Angular Frontend",
+            "type": "chrome",
             "request": "launch",
-            "program": "${workspaceFolder}/src/manage.py",
-            "console": "integratedTerminal",
-            "justMyCode": true,
-            "args": ["runserver"],
-            "django": true
+            "url": "http://localhost:4200",
+            "webRoot": "${workspaceFolder}/src-ui",
+            "preLaunchTask": "Start: Frontend Angular"
         },
         {
-            "name": "manage.py document_consumer",
+            "name": "Debug: Backend Server (manage.py runserver)",
             "type": "python",
             "request": "launch",
             "program": "${workspaceFolder}/src/manage.py",
+            "args": [
+                "runserver"
+            ],
+            "django": true,
             "console": "integratedTerminal",
-            "justMyCode": true,
-            "args": ["document_consumer"],
-            "django": true
+            "env": {
+                "PYTHONPATH": "${workspaceFolder}/src"
+            },
+            "python": "${workspaceFolder}/.venv/bin/python"
         },
         {
-            "name": "celery",
+            "name": "Debug: Consumer Service (manage.py document_consumer)",
             "type": "python",
-            "cwd": "${workspaceFolder}/src",
             "request": "launch",
-            "module": "celery",
+            "program": "${workspaceFolder}/src/manage.py",
+            "args": [
+                "document_consumer"
+            ],
+            "django": true,
             "console": "integratedTerminal",
             "env": {
                 "PYTHONPATH": "${workspaceFolder}/src"
-              },
-            "args": [
-                "-A",
-                "paperless",
-                "worker",
-                "-l",
-                "DEBUG"
-            ]
+            },
+            "python": "${workspaceFolder}/.venv/bin/python"
+        }
+    ],
+    "compounds": [
+        {
+            "name": "Debug: FullStack",
+            "configurations": [
+                "Chrome: Debug Angular Frontend",
+                "Debug: Backend Server (manage.py runserver)",
+                "Debug: Consumer Service (manage.py document_consumer)"
+            ],
+            "preLaunchTask": "Start: Celery Worker"
         }
     ]
 }

diff --git a/.devcontainer/vscode/tasks.json b/.devcontainer/vscode/tasks.json
index fa27ba6bc09bb6523eb69196d8bc38c5b7228552..d7eaf9d3fa1f1eaf5272af66aa6c47fcdc368b01 100644 (file)
--- a/.devcontainer/vscode/tasks.json
+++ b/.devcontainer/vscode/tasks.json
@@ -1,27 +1,82 @@
 {
        "version": "2.0.0",
        "tasks": [
-       {
-               "label": "manage.py document_consumer",
-               "type": "shell",
-               "command": "pipenv run python manage.py document_consumer",
-               "group": "build",
-               "presentation": {
-                       "echo": true,
-                       "reveal": "always",
-                       "focus": false,
-                       "panel": "shared",
-                       "showReuseMessage": false,
-                       "clear": true,
-                       "revealProblems": "onProblem"
+               {
+                       "label": "Start: Celery Worker",
+                       "type": "shell",
+                       "command": "pipenv run celery --app paperless worker -l DEBUG",
+                       "isBackground": true,
+                       "options": {
+                               "cwd": "${workspaceFolder}/src"
+                       },
+                       "problemMatcher": [
+                               {
+                                       "owner": "custom",
+                                       "pattern": [
+                                               {
+                                                       "regexp": ".",
+                                                       "file": 1,
+                                                       "location": 2,
+                                                       "message": 3
+                                               }
+                                       ],
+                                       "background": {
+                                               "activeOnStart": true,
+                                               "beginsPattern": "celery.*",
+                                               "endsPattern": "ready"
+                                       }
+                               }
+                       ],
+                       "detail": ""
                },
-               "options": {
-                       "cwd": "${workspaceFolder}/src"
-               }
-
+               {
+                       "label": "Start: Frontend Angular",
+                       "type": "shell",
+                       "command": "npm start",
+                       "isBackground": true,
+                       "options": {
+                               "cwd": "${workspaceFolder}/src-ui"
+                       },
+                       "problemMatcher": [
+                               {
+                                       "owner": "custom",
+                                       "pattern": [
+                                               {
+                                                       "regexp": ".",
+                                                       "file": 1,
+                                                       "location": 2,
+                                                       "message": 3
+                                               }
+                                       ],
+                                       "background": {
+                                               "activeOnStart": true,
+                                               "beginsPattern": ".*",
+                                               "endsPattern": "Compiled successfully"
+                                       }
+                               }
+                       ],
+                       "detail": "triggered also by launch option Chrome: Debug Angular Frontend"
+               },
+               {
+                       "label": "Start: Consumer Service (manage.py document_consumer)",
+                       "type": "shell",
+                       "command": "pipenv run python manage.py document_consumer",
+                       "group": "build",
+                       "presentation": {
+                               "echo": true,
+                               "reveal": "always",
+                               "focus": false,
+                               "panel": "shared",
+                               "showReuseMessage": false,
+                               "clear": true,
+                               "revealProblems": "onProblem"
+                       },
+                       "options": {
+                               "cwd": "${workspaceFolder}/src"
+                       }
                },
                {
-                       "label": "manage.py runserver",
+                       "label": "Start: Backend Server (manage.py runserver)",
                        "type": "shell",
                        "command": "pipenv run python manage.py runserver",
                        "group": "build",
@@ -37,100 +92,140 @@
                        "options": {
                                "cwd": "${workspaceFolder}/src"
                        }
-
+               },
+               {
+                       "label": "Maintenance: manage.py migrate",
+                       "type": "shell",
+                       "command": "pipenv run python manage.py migrate",
+                       "group": "none",
+                       "presentation": {
+                               "echo": true,
+                               "reveal": "always",
+                               "focus": true,
+                               "panel": "shared",
+                               "showReuseMessage": false,
+                               "clear": true,
+                               "revealProblems": "onProblem"
                        },
-         {
-               "label": "Maintenance: manage.py migrate",
-               "type": "shell",
-               "command": "pipenv run python manage.py migrate",
-               "group": "none",
-               "presentation": {
-                       "echo": true,
-                       "reveal": "always",
-                       "focus": true,
-                       "panel": "shared",
-                       "showReuseMessage": false,
-                       "clear": true,
-                       "revealProblems": "onProblem"
+                       "options": {
+                               "cwd": "${workspaceFolder}/src"
+                       }
                },
-               "options": {
-                       "cwd": "${workspaceFolder}/src"
-               }
-         },
-         {
-               "label": "Maintenance: manage.py createsuperuser",
-               "type": "shell",
-               "command": "pipenv run python manage.py createsuperuser",
-               "group": "none",
-               "presentation": {
-                       "echo": true,
-                       "reveal": "always",
-                       "focus": true,
-                       "panel": "shared",
-                       "showReuseMessage": false,
-                       "clear": true,
-                       "revealProblems": "onProblem"
+               {
+                       "label": "Maintenance: Build Documentation",
+                       "type": "shell",
+                       "command": "pipenv run mkdocs build --config-file mkdocs.yml && pipenv run mkdocs serve",
+                       "group": "none",
+                       "presentation": {
+                               "echo": true,
+                               "reveal": "always",
+                               "focus": true,
+                               "panel": "shared",
+                               "showReuseMessage": false,
+                               "clear": true,
+                               "revealProblems": "onProblem"
+                       },
+                       "options": {
+                               "cwd": "${workspaceFolder}"
+                       }
                },
-               "options": {
-                       "cwd": "${workspaceFolder}/src"
-               }
-         },
-         {
-               "label": "compile frontend",
-               "type": "shell",
-               "command": "npm ci && ./node_modules/.bin/ng build --configuration production",
-               "group": "none",
-               "presentation": {
-                       "echo": true,
-                       "reveal": "always",
-                       "focus": true,
-                       "panel": "shared",
-                       "showReuseMessage": false,
-                       "clear": true,
-                       "revealProblems": "onProblem"
+               {
+                       "label": "Maintenance: manage.py createsuperuser",
+                       "type": "shell",
+                       "command": "pipenv run python manage.py createsuperuser",
+                       "group": "none",
+                       "presentation": {
+                               "echo": true,
+                               "reveal": "always",
+                               "focus": true,
+                               "panel": "shared",
+                               "showReuseMessage": false,
+                               "clear": true,
+                               "revealProblems": "onProblem"
+                       },
+                       "options": {
+                               "cwd": "${workspaceFolder}/src"
+                       }
                },
-               "options": {
-                       "cwd": "${workspaceFolder}/src-ui"
-               }
-         },
-         {
-               "label": "Maintenance: recreate .venv",
-               "type": "shell",
-               "command": "rm -R -v .venv/* || pipenv install --dev",
-               "group": "none",
-               "presentation": {
-                       "echo": true,
-                       "reveal": "always",
-                       "focus": true,
-                       "panel": "shared",
-                       "showReuseMessage": false,
-                       "clear": true,
-                       "revealProblems": "onProblem"
+               {
+                       "label": "Maintenance: Install Angular CLI",
+                       "type": "shell",
+                       "command": "npm ci && ./node_modules/.bin/ng build --configuration production",
+                       "group": "none",
+                       "presentation": {
+                               "echo": true,
+                               "reveal": "always",
+                               "focus": true,
+                               "panel": "shared",
+                               "showReuseMessage": false,
+                               "clear": true,
+                               "revealProblems": "onProblem"
+                       },
+                       "options": {
+                               "cwd": "${workspaceFolder}/src-ui"
+                       }
                },
-               "options": {
-                       "cwd": "${workspaceFolder}"
-               }
-         },
-         {
-               "label": "Celery Worker",
-               "type": "shell",
-               "command": "pipenv run celery --app paperless worker -l DEBUG",
-               "group": {
-                 "kind": "build",
-                 "isDefault": true
+               {
+                       "label": "Maintenance: Compile frontend for production",
+                       "type": "shell",
+                       "command": "npm ci && ./node_modules/.bin/ng build --configuration production",
+                       "group": "none",
+                       "presentation": {
+                               "echo": true,
+                               "reveal": "always",
+                               "focus": true,
+                               "panel": "shared",
+                               "showReuseMessage": false,
+                               "clear": true,
+                               "revealProblems": "onProblem"
+                       },
+                       "options": {
+                               "cwd": "${workspaceFolder}/src-ui"
+                       }
                },
-               "presentation": {
-                       "echo": true,
-                       "reveal": "always",
-                       "focus": true,
-                       "panel": "shared",
-                       "showReuseMessage": false,
-                       "clear": true,
-                       "revealProblems": "onProblem"
+               {
+                       "label": "Maintenance: recreate .venv",
+                       "type": "shell",
+                       "command": "rm -R -v .venv/* || pipenv install --dev",
+                       "group": "none",
+                       "presentation": {
+                               "echo": true,
+                               "reveal": "always",
+                               "focus": true,
+                               "panel": "shared",
+                               "showReuseMessage": false,
+                               "clear": true,
+                               "revealProblems": "onProblem"
+                       },
+                       "options": {
+                               "cwd": "${workspaceFolder}"
+                       }
+               },
+               {
+                       "label": "Maintenance: Install Frontend Dependencies",
+                       "type": "npm",
+                       "script": "install",
+                       "path": "src-ui",
+                       "group": "clean",
+                       "problemMatcher": [],
+                       "detail": "install dependencies from package"
                },
-               "options": {
-                       "cwd": "${workspaceFolder}/src"
+               {
+                       "label": "Project Setup: Run all Init Tasks",
+                       "dependsOrder": "sequence",
+                       "dependsOn": [
+                               "Maintenance: manage.py migrate",
+                               "Maintenance: manage.py createsuperuser",
+                               "Maintenance: Compile frontend for production"
+                       ]
+               },
+               {
+                       "label": "Project Start: Run all Services",
+                       "dependsOn": [
+                               "Start: Celery Worker",
+                               "Start: Consumer Service (manage.py document_consumer)",
+                               "Start: Backend Server (manage.py runserver)"
+                       ]
                }
-         }
        ]
-  }
+}

diff --git a/.gitignore b/.gitignore
index 3351a924beb0fd328623a502de278adc7771d64b..0fd9d7bcd5aa87b935691524ec32677b7f928244 100644 (file)
--- a/.gitignore
+++ b/.gitignore
@@ -100,3 +100,9 @@ scripts/nuke
 
 # celery schedule file
 celerybeat-schedule*
+
+# ignore .devcontainer sub folders
+/.devcontainer/consume/
+/.devcontainer/data/
+/.devcontainer/media/
+/.devcontainer/redisdata/

diff --git a/docs/development.md b/docs/development.md
index 44a2f69863d65b40514b61ad04ae11f2426c9990..b49a42a2f9f0a30345ee29eecec0b48701e92b0c 100644 (file)
--- a/docs/development.md
+++ b/docs/development.md
@@ -450,3 +450,23 @@ def myparser_consumer_declaration(sender, **kwargs):
     mime types have many extensions associated with them and the Python
     methods responsible for guessing the extension do not always return
     the same value.
+
+## Using Visual Studio Code devcontainer
+
+Another easy way to get started with development is to use Visual Studio
+Code devcontainers. This approach will create a preconfigured development
+environment with all of the required tools and dependencies.
+[Learn more about devcontainers](https://code.visualstudio.com/docs/devcontainers/containers).
+
+To get started:
+
+1. Clone the repository on your machine and open the Paperless-ngx folder in VS Code.
+
+2. VS Code will prompt you with "Reopen in container". Do so and wait for the environment to start.
+
+3. Initialize the project by running the task **Project Setup: Run all Init Tasks**. This
+   will initialize the database tables and create a superuser. Then you can compile the front end
+   for production or run the frontend in debug mode.
+
+4. The project is ready for debugging, start either run the fullstack debug or individual debug
+   processes. Yo spin up the project without debugging run the task **Project Start: Run all Services**