
* fix: container setup and task description * feat: enable dependabot for devcontainer * fix: dont install latest uv and dont install uvx * Cleanup decontainer readme * Fix the reset venv command --------- Co-authored-by: shamoon <4887959+shamoon@users.noreply.github.com>
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 and choose
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, run the Project Setup: Run all Init Tasks
task to initialize the project.
Alternatively, the Project Setup can be done with individual tasks:
- Compile Frontend Assets:
Maintenance: Compile frontend for production
. - Run Database Migrations:
Maintenance: manage.py migrate
. - Create Superuser:
Maintenance: manage.py createsuperuser
.
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 and 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!