paperless-ngx/.devcontainer/README.md

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 uv)
  • 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 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!