From e44cfef662c41db0ff8a8f4462d4761ef2d153d0 Mon Sep 17 00:00:00 2001 From: shamoon <4887959+shamoon@users.noreply.github.com> Date: Thu, 26 Dec 2024 10:49:32 -0800 Subject: [PATCH] Documentation: cleanup devcontainer docs and move into tasks and launch config files --- .devcontainer/README.md | 117 ------------------------------- .devcontainer/vscode/launch.json | 4 ++ .devcontainer/vscode/tasks.json | 72 +++++++++---------- docs/development.md | 3 + 4 files changed, 39 insertions(+), 157 deletions(-) delete mode 100644 .devcontainer/README.md diff --git a/.devcontainer/README.md b/.devcontainer/README.md deleted file mode 100644 index 3644d90c3..000000000 --- a/.devcontainer/README.md +++ /dev/null @@ -1,117 +0,0 @@ -# Paperless NGX Development Environment - -## Overview - -Welcome to the Paperless NGX development environment! This setup uses VSCode DevContainers to provide a consistent and seamless development experience. - -### What are DevContainers? - -DevContainers are a feature in VSCode that allows you to develop within a Docker container. This ensures that your development environment is consistent across different machines and setups. By defining a containerized environment, you can eliminate the "works on my machine" problem. - -### Advantages of DevContainers - -- **Consistency**: Same environment for all developers. -- **Isolation**: Separate development environment from your local machine. -- **Reproducibility**: Easily recreate the environment on any machine. -- **Pre-configured Tools**: Include all necessary tools and dependencies in the container. - -## DevContainer Setup - -The DevContainer configuration provides up all the necessary services for Paperless NGX, including: - -- Redis -- Gotenberg -- Tika - -Data is stored using Docker volumes to ensure persistence across container restarts. - -## Configuration Files - -The setup includes debugging configurations (`launch.json`) and tasks (`tasks.json`) to help you manage and debug various parts of the project: - -- **Backend Debugging:** - - `manage.py runserver` - - `manage.py document-consumer` - - `celery` -- **Maintenance Tasks:** - - Create superuser - - Run migrations - - Recreate virtual environment (`.venv` with pipenv) - - Compile frontend assets - -## Getting Started - -### Step 1: Running the DevContainer - -To start the DevContainer: - -1. Open VSCode. -2. Open the project folder. -3. Open the command palette: - - **Windows/Linux**: `Ctrl+Shift+P` - - **Mac**: `Cmd+Shift+P` -4. Type and select `Dev Containers: Rebuild and Reopen in Container`. - -VSCode will build and start the DevContainer environment. - -### Step 2: Initial Setup - -Once the DevContainer is up and running, perform the following steps: - -1. **Compile Frontend Assets**: - - - Open the command palette: - - **Windows/Linux**: `Ctrl+Shift+P` - - **Mac**: `Cmd+Shift+P` - - Select `Tasks: Run Task`. - - Choose `Frontend Compile`. - -2. **Run Database Migrations**: - - - Open the command palette: - - **Windows/Linux**: `Ctrl+Shift+P` - - **Mac**: `Cmd+Shift+P` - - Select `Tasks: Run Task`. - - Choose `Migrate Database`. - -3. **Create Superuser**: - - Open the command palette: - - **Windows/Linux**: `Ctrl+Shift+P` - - **Mac**: `Cmd+Shift+P` - - Select `Tasks: Run Task`. - - Choose `Create Superuser`. - -### Debugging and Running Services - -You can start and debug backend services either as debugging sessions via `launch.json` or as tasks. - -#### Using `launch.json`: - -1. Press `F5` or go to the **Run and Debug** view in VSCode. -2. Select the desired configuration: - - `Runserver` - - `Document Consumer` - - `Celery` - -#### Using Tasks: - -1. Open the command palette: - - **Windows/Linux**: `Ctrl+Shift+P` - - **Mac**: `Cmd+Shift+P` -2. Select `Tasks: Run Task`. -3. Choose the desired task: - - `Runserver` - - `Document Consumer` - - `Celery` - -### Additional Maintenance Tasks - -Additional tasks are available for common maintenance operations: - -- **Recreate .venv**: For setting up the virtual environment using pipenv. -- **Migrate Database**: To apply database migrations. -- **Create Superuser**: To create an admin user for the application. - -## Let's Get Started! - -Follow the steps above to get your development environment up and running. Happy coding! diff --git a/.devcontainer/vscode/launch.json b/.devcontainer/vscode/launch.json index b21226630..0ee2e5129 100644 --- a/.devcontainer/vscode/launch.json +++ b/.devcontainer/vscode/launch.json @@ -3,6 +3,7 @@ "configurations": [ { "name": "Chrome: Debug Angular Frontend", + "description": "Debug the Angular Dev Frontend in Chrome", "type": "chrome", "request": "launch", "url": "http://localhost:4200", @@ -11,6 +12,7 @@ }, { "name": "Debug: Backend Server (manage.py runserver)", + "description": "Debug the Django Backend Server", "type": "python", "request": "launch", "program": "${workspaceFolder}/src/manage.py", @@ -26,6 +28,7 @@ }, { "name": "Debug: Consumer Service (manage.py document_consumer)", + "description": "Debug the Consumer Service which processes files from a directory", "type": "python", "request": "launch", "program": "${workspaceFolder}/src/manage.py", @@ -43,6 +46,7 @@ "compounds": [ { "name": "Debug: FullStack", + "description": "Debug run the Angular dev frontend, Django backend, and consumer service", "configurations": [ "Chrome: Debug Angular Frontend", "Debug: Backend Server (manage.py runserver)", diff --git a/.devcontainer/vscode/tasks.json b/.devcontainer/vscode/tasks.json index d7eaf9d3f..6c58cdaa3 100644 --- a/.devcontainer/vscode/tasks.json +++ b/.devcontainer/vscode/tasks.json @@ -3,6 +3,7 @@ "tasks": [ { "label": "Start: Celery Worker", + "description": "Start the Celery Worker which processes background and consume tasks", "type": "shell", "command": "pipenv run celery --app paperless worker -l DEBUG", "isBackground": true, @@ -26,11 +27,11 @@ "endsPattern": "ready" } } - ], - "detail": "" + ] }, { "label": "Start: Frontend Angular", + "description": "Start the Frontend Angular Dev Server", "type": "shell", "command": "npm start", "isBackground": true, @@ -54,11 +55,11 @@ "endsPattern": "Compiled successfully" } } - ], - "detail": "triggered also by launch option Chrome: Debug Angular Frontend" + ] }, { "label": "Start: Consumer Service (manage.py document_consumer)", + "description": "Start the Consumer Service which processes files from a directory", "type": "shell", "command": "pipenv run python manage.py document_consumer", "group": "build", @@ -77,6 +78,7 @@ }, { "label": "Start: Backend Server (manage.py runserver)", + "description": "Start the Backend Server which serves the Django API and the compiled Angular frontend", "type": "shell", "command": "pipenv run python manage.py runserver", "group": "build", @@ -95,6 +97,7 @@ }, { "label": "Maintenance: manage.py migrate", + "description": "Apply database migrations", "type": "shell", "command": "pipenv run python manage.py migrate", "group": "none", @@ -113,6 +116,7 @@ }, { "label": "Maintenance: Build Documentation", + "description": "Build the documentation with MkDocs", "type": "shell", "command": "pipenv run mkdocs build --config-file mkdocs.yml && pipenv run mkdocs serve", "group": "none", @@ -131,6 +135,7 @@ }, { "label": "Maintenance: manage.py createsuperuser", + "description": "Create a superuser", "type": "shell", "command": "pipenv run python manage.py createsuperuser", "group": "none", @@ -147,44 +152,9 @@ "cwd": "${workspaceFolder}/src" } }, - { - "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" - } - }, - { - "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" - } - }, { "label": "Maintenance: recreate .venv", + "description": "Recreate the python virtual environment and install python dependencies", "type": "shell", "command": "rm -R -v .venv/* || pipenv install --dev", "group": "none", @@ -203,6 +173,7 @@ }, { "label": "Maintenance: Install Frontend Dependencies", + "description": "Install frontend (npm) dependencies", "type": "npm", "script": "install", "path": "src-ui", @@ -210,8 +181,28 @@ "problemMatcher": [], "detail": "install dependencies from package" }, + { + "description": "Clean install frontend dependencies and build the frontend for production", + "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" + } + }, { "label": "Project Setup: Run all Init Tasks", + "description": "Runs all init tasks to setup the project including migrate the database, create a superuser and compile the frontend for production", "dependsOrder": "sequence", "dependsOn": [ "Maintenance: manage.py migrate", @@ -221,6 +212,7 @@ }, { "label": "Project Start: Run all Services", + "description": "Runs all services required to start the project including the Celery Worker, the Consumer Service and the Backend Server", "dependsOn": [ "Start: Celery Worker", "Start: Consumer Service (manage.py document_consumer)", diff --git a/docs/development.md b/docs/development.md index b49a42a2f..53f4ee596 100644 --- a/docs/development.md +++ b/docs/development.md @@ -457,6 +457,9 @@ 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). +The .devcontainer/vscode/tasks.json and .devcontainer/vscode/launch.json files +contain more information about the specific tasks and launch configurations (see the +non-standard "description" field). To get started: