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
withuv
) - Compile frontend assets
Getting Started
Step 1: Running the DevContainer
To start the DevContainer:
- Open VSCode.
- Open the project folder.
- Open the command palette:
- Windows/Linux:
Ctrl+Shift+P
- Mac:
Cmd+Shift+P
- Windows/Linux:
- 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:
-
Compile Frontend Assets:
- Open the command palette:
- Windows/Linux:
Ctrl+Shift+P
- Mac:
Cmd+Shift+P
- Windows/Linux:
- Select
Tasks: Run Task
. - Choose
Frontend Compile
.
- Open the command palette:
-
Run Database Migrations:
- Open the command palette:
- Windows/Linux:
Ctrl+Shift+P
- Mac:
Cmd+Shift+P
- Windows/Linux:
- Select
Tasks: Run Task
. - Choose
Migrate Database
.
- Open the command palette:
-
Create Superuser:
- Open the command palette:
- Windows/Linux:
Ctrl+Shift+P
- Mac:
Cmd+Shift+P
- Windows/Linux:
- Select
Tasks: Run Task
. - Choose
Create Superuser
.
- Open the command palette:
Debugging and Running Services
You can start and debug backend services either as debugging sessions via launch.json
or as tasks.
Using launch.json
- Press
F5
or go to the Run and Debug view in VSCode. - Select the desired configuration:
Runserver
Document Consumer
Celery
Using Tasks
- Open the command palette:
- Windows/Linux:
Ctrl+Shift+P
- Mac:
Cmd+Shift+P
- Windows/Linux:
- Select
Tasks: Run Task
. - 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
uv
. - 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!