+++ /dev/null
-# 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!
"configurations": [
{
"name": "Chrome: Debug Angular Frontend",
+ "description": "Debug the Angular Dev Frontend in Chrome",
"type": "chrome",
"request": "launch",
"url": "http://localhost:4200",
},
{
"name": "Debug: Backend Server (manage.py runserver)",
+ "description": "Debug the Django Backend Server",
"type": "python",
"request": "launch",
"program": "${workspaceFolder}/src/manage.py",
},
{
"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",
"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)",
"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,
"endsPattern": "ready"
}
}
- ],
- "detail": ""
+ ]
},
{
"label": "Start: Frontend Angular",
+ "description": "Start the Frontend Angular Dev Server",
"type": "shell",
"command": "npm start",
"isBackground": true,
"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",
},
{
"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",
},
{
"label": "Maintenance: manage.py migrate",
+ "description": "Apply database migrations",
"type": "shell",
"command": "pipenv run python manage.py migrate",
"group": "none",
},
{
"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",
},
{
"label": "Maintenance: manage.py createsuperuser",
+ "description": "Create a superuser",
"type": "shell",
"command": "pipenv run python manage.py createsuperuser",
"group": "none",
}
},
{
- "label": "Maintenance: Install Angular CLI",
+ "label": "Maintenance: recreate .venv",
+ "description": "Recreate the python virtual environment and install python dependencies",
"type": "shell",
- "command": "npm ci && ./node_modules/.bin/ng build --configuration production",
+ "command": "rm -R -v .venv/* || pipenv install --dev",
"group": "none",
"presentation": {
"echo": true,
"revealProblems": "onProblem"
},
"options": {
- "cwd": "${workspaceFolder}/src-ui"
+ "cwd": "${workspaceFolder}"
}
},
{
+ "label": "Maintenance: Install Frontend Dependencies",
+ "description": "Install frontend (npm) dependencies",
+ "type": "npm",
+ "script": "install",
+ "path": "src-ui",
+ "group": "clean",
+ "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",
"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"
- },
- "options": {
- "cwd": "${workspaceFolder}"
- }
- },
- {
- "label": "Maintenance: Install Frontend Dependencies",
- "type": "npm",
- "script": "install",
- "path": "src-ui",
- "group": "clean",
- "problemMatcher": [],
- "detail": "install dependencies from package"
- },
{
"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",
},
{
"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)",
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:
projects / thirdparty / paperless-ngx.git / commitdiff
