---
title: Deploy Paperless-ngx with AI on Blossom
url: "/deploy/paperless-ngx/"
canonical_url: https://docs.blossom88.com/deploy/paperless-ngx/
markdown_url: https://docs.blossom88.com/deploy/paperless-ngx.md
summary: Deploy Paperless-ngx with AI on Blossom. Turn scanned PDFs into searchable
  documents with OCR, managed PostgreSQL and Redis, and persistent file storage.
categories:
- deployment
- productivity
---

# Deploy Paperless-ngx with AI on Blossom

[Paperless-ngx](https://docs.paperless-ngx.com/) turns scanned paperwork into a
searchable document library. Upload a scan, let OCR read its text, and find it
later without remembering the filename.

It's written in Python with Django and an Angular frontend. PostgreSQL stores
document records; Redis supports background processing. Browse the
[source on GitHub](https://github.com/paperless-ngx/paperless-ngx).

This setup uses a [Persistent Service](/docs/apps/persistent-services/)
for the application and document files, with managed PostgreSQL and Redis.

[Install the Blossom CLI and skill](/learn/getting-started/install/)
on your agent's machine and choose a Blossom Cloud Location when you log in.
You can also use
[Blossom BYOC (bring your own cloud)](/learn/getting-started/choose-your-cloud/#blossom-byoc).

## Ask Your Agent

> **Ask your AI agent:** Deploy Paperless-ngx on Blossom with managed Postgres. Help me turn scanned PDFs into searchable documents.

> Follow this guide: https://docs.blossom88.com/deploy/paperless-ngx/



Your agent checks the current
[deployment requirements](https://docs.paperless-ngx.com/setup/), chooses a
maintained image, and saves the configuration.

| Part | Purpose |
|---|---|
| Persistent Paperless-ngx Service | Dashboard, OCR workers, originals, and searchable archives |
| Managed PostgreSQL | Accounts, document records, and extracted text |
| Managed Redis | Background processing coordination |

Keep the dashboard behind **Blossom Account access** and Paperless sign-in.
Create the owner privately and keep the application secret stable.

## Turn a Scan Into a Searchable Document

> **Ask your AI agent:** Help me upload a sample scanned PDF, search for a phrase inside it, and download the searchable version.

> Follow this guide: https://docs.blossom88.com/deploy/paperless-ngx/



Upload a PDF or image through the dashboard. Wait for processing, then search
for a distinctive word or reference printed on the page. Open the result to
see the document and its extracted text.

![Paperless-ngx displaying a scanned sample invoice and its extracted text.](/assets/images/guides/paperless-ngx/document.png)

Download the original and the searchable archive. The original keeps the file
you uploaded; the archive adds a text layer you can search in a PDF reader.

<details class="optional-reading" markdown="1">
<summary>Commands behind the deployment</summary>

Create a prebuilt-image Environment, managed PostgreSQL and Redis, then connect
and configure the Service:

    blossom app:create --data app.yml
    blossom environment:create --data environment.yml
    blossom database_instance:create --data postgres.yml --follow
    blossom cache_instance:create --data redis.yml --follow
    blossom environment_link:create --data database-link.yml
    blossom environment_link:create --data redis-link.yml
    blossom env_var:push --environment environment-100 --file .env.production
    blossom service:create --data paperless-service.yml
    blossom environment:deploy --id environment-100 --follow

Use a stable `PAPERLESS_SECRET_KEY`, a private initial administrator password,
and the generated public URL for `PAPERLESS_URL`. Map the linked database URL
to Paperless's `PAPERLESS_DB*` settings and use the linked Redis URL for
`PAPERLESS_REDIS`.

Mount a Volume at `/usr/src/paperless/data`. Set `PAPERLESS_MEDIA_ROOT` and
`PAPERLESS_CONSUMPTION_DIR` to subdirectories of that mount so originals,
archives, and consumed files survive replacement. Keep
`PAPERLESS_DATA_DIR` on the same Volume. Review any additional export or
custom-script paths against the selected release's storage requirements.

Start the image through its supported `/init` entrypoint, which prepares the
application and starts its processes. Give initialization and OCR enough
memory and startup time. Use Python's HTTP client for the readiness command;
request `http://localhost:8000/` so the probe uses a hostname the application
allows. The image does not need curl for that check.

Keep one Container attached to this Volume. For updates, stop it before
starting its replacement:

    blossom service:scale --id service-100 --desired-size 0 --follow
    blossom environment:deploy --id environment-100 --follow
    blossom service:scale --id service-100 --desired-size 1 --follow

</details>

## Keep Your Documents Through Updates

> **Ask your AI agent:** Update Paperless-ngx and check that my saved documents, OCR search, and downloads still work.

> Follow this guide: https://docs.blossom88.com/deploy/paperless-ngx/



Preserve the Volume, PostgreSQL, Redis, and application secret. After the
replacement starts, sign in again, search for a saved document, and download
both versions. Upload another scan to check that the new OCR worker can
process documents too.

## What You Get

- A private, searchable document library
- OCR for scanned PDFs and images
- Original files and searchable archives on a persistent Volume
- Managed PostgreSQL and Redis, with documents that survive Container replacement
