1. Create an account on OwlRelay

   Go to owlrelay.email and create an account.

2. Create an OwlRelay API key

   Once you have created your account, you can create an API key by going to the API keys page.

3. Configure your Papra instance

   Once you have created your API key, you can configure your Papra instance to receive emails by setting the OWLRELAY_API_KEY and INTAKE_EMAILS_WEBHOOK_SECRET environment variables.

   bash Copy

   # Enable intake emails
   INTAKE_EMAILS_IS_ENABLED=true
   
   # Tell your Papra instance to use OwlRelay
   INTAKE_EMAILS_DRIVER=owlrelay
   
   # This is your OwlRelay API key
   OWLRELAY_API_KEY=owrl_*****
   
   # Set a random key that will be transmitted to OwlRelay to sign the requests,
   # this is to authenticate that the emails are coming from OwlRelay
   INTAKE_EMAILS_WEBHOOK_SECRET=a-random-key
   
   # [Optional]
   # This is the URL that OwlRelay will send the emails to,
   # if not provided, the webhook will be inferred from the server URL.
   # Can be relevant if you have multiple urls pointing to your Papra instance
   # or when using tunnel services
   OWLRELAY_WEBHOOK_URL=https://your-instance.com/api/intake-emails/ingest

4. That's it!

   You can now generate intake emails in your Papra instance and send emails with attachments to the email address generated.

1. Create the Email Worker

   There are two ways to create an Email Worker, either from the Cloudflare dashboard or by cloning and deploying the code from the papra-hq/email-proxy repository.

   • Option 1: From the Cloudflare dashboard (easier).

     • Go to the Cloudflare dashboard.
     • Select your domain.
     • Go to the Compute (Workers) tab.
     • Click on the Create Worker button.
     • Name your worker (e.g. email-proxy).
     • Copy the code from the index.js file (from the papra-hq/email-proxy repository) and paste it in the editor.

   • Option 2: Build and deploy the Email Worker

     Clone the papra-hq/email-proxy repository and deploy the worker using Wrangler cli. You will need to have Node.js v24 and pnpm installed.

     bash Copy

     # Clone the repository
     git clone https://github.com/papra-hq/email-proxy.git
     
     # Change directory
     cd email-proxy
     
     # Install dependencies
     pnpm install
     
     # Build the worker
     pnpm build
     
     # Deploy the worker (you will be prompted to login to Cloudflare through wrangler)
     pnpm run deploy

2. Configure the Email Worker

   Add the following environment variables to the worker:

   • WEBHOOK_URL: The email intake endpoint in your Papra instance (basically. https://<your-papra-instance.com>/api/intake-emails/ingest).
   • WEBHOOK_SECRET: The secret key to authenticate the webhook requests, set the same as the INTAKE_EMAILS_WEBHOOK_SECRET environment variable in your Papra instance.

3. Configure your Papra instance

   In your Papra instance, add the following environment variables:

   bash Copy

   # Enable intake emails
   INTAKE_EMAILS_IS_ENABLED=true
   
   # Tell your Papra instance that it can generate any email address from the
   # domain you setup in the Email Worker as it's a wildcard redirection
   INTAKE_EMAILS_DRIVER=catch-all
   
   # This is the domain from which the intake email will be generated 
   # eg. `domain.com`
   INTAKE_EMAILS_CATCH_ALL_DOMAIN=papra.email
   
   # This is the secret key to authenticate the webhook requests
   # set the same as the `WEBHOOK_SECRET` variable in the Email Worker
   INTAKE_EMAILS_WEBHOOK_SECRET=a-random-key

4. Configure the Email Routing

   • Go to the Email Routing tab in the Cloudflare dashboard.
   • Follow the email onboarding process.
   • Add a catch-all rule to forward all emails to the Email Worker you created.

5. Test the setup

   In your Papra instance, go to the Integrations page in your organization and generates an intake email URL, setup an allowed sender (basically your email address), and copy the generated email address. Send an email to the generated address with a file attached, and check if the file is uploaded to your Papra instance.

Troubleshooting Copy Chapter

View logs using wrangler tail Copy Section

To view real-time logs associated with any deployed Worker using Wrangler:

• Go to your Worker project directory.
• Run npx wrangler tail.

This will log any incoming requests to your application available in your local terminal.

Email Worker not receiving emails Copy Section

If the Email Worker is not receiving emails, make sure that the email routing is correctly configured in the Cloudflare dashboard.
Also, check the logs in the Email Worker dashboard for any errors.

Papra instance returning 403 Forbidden Copy Section

If your Papra instance is returning a 403 Forbidden error, make sure that the INTAKE_EMAILS_IS_ENABLED environment variable is set to true in your Papra instance.

Papra instance is returning 401 Unauthorized Copy Section

If your Papra instance is returning a 401 Unauthorized error, make sure that the INTAKE_EMAILS_WEBHOOK_SECRET environment variable is correctly set in your Papra instance.

The worker is not forwarding the email to the Papra instance Copy Section

Make sure that the WEBHOOK_URL and WEBHOOK_SECRET environment variables are correctly set in the Email Worker, and the INTAKE_EMAILS_WEBHOOK_SECRET environment variable is correctly set in your Papra instance.
Also, check the logs in the Email Worker dashboard or the logs in your Papra instance for any errors.

TypeError: Too many redirects. Copy Section

If you get "too many redirects" (check log from wrangler), check that your domain is configured with SSL/TLS Encryption as Full (strict).
Cloudflare dashboard → (domain) → SSL/TLS → Overview → set encryption mode to Full (strict) or at minimum Full. Save, then re-send a test email.

File: apps/docs/src/content/docs/03-guides/03-setup-ingestion-folder.mdx Copy Chapter

title: Setup Ingestion Folder slug: guides/setup-ingestion-folder Copy Chapter

import { Steps } from '@astrojs/starlight/components';
import { Aside } from '@astrojs/starlight/components';
import { FileTree } from '@astrojs/starlight/components';

The ingestion folder is a special folder that is watched by Papra for new files. When a new file is added to the ingestion folder, Papra will automatically import it.

Multi-Organization Structure Copy Chapter

Papra supports multiple organizations within a single instance, each requiring a dedicated ingestion folder. The ingestion system uses a hierarchical structure where:

This allows you to have a single instance of Papra watching multiple organizations' ingestion folders.

Setup Copy Chapter

Add the following to your docker-compose.yml file:

services:
papra:
   container_name: papra
   image: ghcr.io/papra-hq/papra:latest
   restart: unless-stopped
   ports:
      - "1221:1221"
   environment:
      - INGESTION_FOLDER_IS_ENABLED=true
   volumes:
      - ./app-data:/app/app-data
      - <your-ingestion-folder>:/app/ingestion
   user: "${UID}:${GID}"

Then add files to a folder named with the organization id (available in Papra URL, e.g. https://papra.example.com/organizations/<organization-id>, the format is org_<random>).

mkdir -p <your-ingestion-folder>/<org_id>
touch <your-ingestion-folder>/<org_id>/hello.txt

Post-processing Copy Chapter

Once a file has been ingested in your Papra organization, you can configure what happens to it by setting the INGESTION_FOLDER_POST_PROCESSING_STRATEGY environment variable. There are two strategies:

• delete: The file is deleted from the ingestion folder (default strategy)
• move: The file is moved to the INGESTION_FOLDER_POST_PROCESSING_MOVE_FOLDER_PATH folder (default: ./ingestion-done)

Note that the INGESTION_FOLDER_POST_PROCESSING_MOVE_FOLDER_PATH path is relative to the organization ingestion folder.

So with INGESTION_FOLDER_POST_PROCESSING_MOVE_FOLDER_PATH=ingestion-done, the file /<org_id>/file.pdf will be moved to /<org_id>/ingestion-done/file.pdf once ingested.

Safeguards Copy Chapter

To avoid accidental data loss, if for some reason the ingestion fails, the file is moved to the INGESTION_FOLDER_ERROR_FOLDER_PATH folder (default: ./ingestion-error).

Polling Copy Chapter

By default, Papra uses native file watchers to detect changes in the ingestion folder. On some OS (like Windows), this can be flaky with Docker. To avoid this issue, you can enable polling by setting the INGESTION_FOLDER_WATCHER_USE_POLLING environment variable to true.

The default polling interval is 2 seconds, you can change it by setting the INGESTION_FOLDER_WATCHER_POLLING_INTERVAL_MS environment variable.

environment:
   - INGESTION_FOLDER_WATCHER_USE_POLLING=true
   - INGESTION_FOLDER_WATCHER_POLLING_INTERVAL_MS=2000

Configuration Copy Chapter

You can find the list of all configuration options in the configuration reference, the related variables are prefixed with INGESTION_FOLDER_.

Edge cases and behaviors Copy Chapter

• The ingestion folder is watched recursively.
• Files in the ingestion folder done and error folders are ignored.
• When a file from the ingestion folder is already present (and not in the trash) in the organization, no ingestion is done, but the file is post-processed (deleted or moved) as successfully ingested.
• When a file is moved to "done" or "error" folder
  • If a file with the same name and same content is present in the destination folder, the original file is deleted
  • If a file with the same name but different content is present in the destination folder, the original file is moved and a timestamp is added to the filename
• Some files are ignored by default (.DS_Store, Thumbs.db, desktop.ini, etc.) see ingestion-folders.constants.ts for the list of ignored files and patterns. You can change this by setting the INGESTION_FOLDER_IGNORED_PATTERNS environment variable.

File: apps/docs/src/content/docs/03-guides/04-setup-custom-oauth2.mdx Copy Chapter

title: Setup Custom OAuth2 Providers slug: guides/setup-custom-oauth2-providers Copy Chapter

import { Aside } from '@astrojs/starlight/components';
import { Steps } from '@astrojs/starlight/components';

This guide will show you how to configure custom OAuth2 providers for authentication in your Papra instance.

Prerequisites Copy Chapter

In order to follow this guide, you need:

• A custom OAuth2 provider
• An accessible Papra instance
• Basic understanding of OAuth2 flows

Configuration Copy Chapter

To set up custom OAuth2 providers, you'll need to configure the AUTH_PROVIDERS_CUSTOMS environment variable with an array of provider configurations. Here's an example:

AUTH_PROVIDERS_CUSTOMS='[
  {
    "providerId": "custom-oauth2",
    "providerName": "Custom OAuth2",
    "providerIconUrl": "https://api.iconify.design/tabler:login-2.svg",
    "clientId": "your-client-id",
    "clientSecret": "your-client-secret",
    "type": "oidc",
    "discoveryUrl": "https://your-provider.tld/.well-known/openid-configuration",
    "scopes": ["openid", "profile", "email"]
  }
]'

Each provider configuration supports the following fields:

• providerId: A unique identifier for the OAuth provider
• providerName: The display name of the provider
• providerIconUrl: URL of the icon to display (optional) you can use a base64 encoded image or an url to a remote image.
• clientId: OAuth client ID
• clientSecret: OAuth client secret
• type: Type of OAuth flow ("oauth2" or "oidc")
• discoveryUrl: URL to fetch OAuth 2.0 configuration (recommended for OIDC providers)
• authorizationUrl: URL for the authorization endpoint (required for OAuth2 if not using discoveryUrl)
• tokenUrl: URL for the token endpoint (required for OAuth2 if not using discoveryUrl)
• userInfoUrl: URL for the user info endpoint (required for OAuth2 if not using discoveryUrl)
• scopes: Array of OAuth scopes to request
• redirectURI: Custom redirect URI (optional)
• responseType: OAuth response type (defaults to "code")
• prompt: Controls the authentication experience ("select_account", "consent", "login", "none")
• pkce: Whether to use PKCE (Proof Key for Code Exchange)
• accessType: Access type for the authorization request

Setup Copy Chapter

Troubleshooting Copy Chapter

Providers Not Showing Up Copy Section

If your OAuth2 providers are not showing up on the login page:

• Check that the JSON configuration in AUTH_PROVIDERS_CUSTOMS is valid
• Ensure all required fields are provided
• Verify that the provider IDs are unique

Authentication Fails Copy Section

If authentication fails:

• Verify that the redirect URI is correctly configured in your OAuth2 provider
• Check that the client ID and client secret are correct
• Ensure the required scopes are properly configured
• Check the Papra logs for any error messages

OIDC Discovery Issues Copy Section

If you're using OIDC and experiencing issues:

• Verify that the discoveryUrl is accessible
• Check that the provider supports OIDC discovery
• Ensure the provider's configuration is properly exposed through the discovery endpoint

Security Considerations Copy Chapter

Multiple Providers Copy Chapter

You can configure multiple custom OAuth2 providers by adding them to the array:

[
  {
    "providerId": "custom-oauth2-1",
    "providerName": "Custom OAuth2 Provider 1",
    "type": "oidc",
    "discoveryUrl": "https://provider1.tld/.well-known/openid-configuration",
    "clientId": "client-id-1",
    "clientSecret": "client-secret-1",
    "scopes": ["openid", "profile", "email"]
  },
  {
    "providerId": "custom-oauth2-2",
    "providerName": "Custom OAuth2 Provider 2",
    "type": "oidc",
    "discoveryUrl": "https://provider2.tld/.well-known/openid-configuration",
    "clientId": "client-id-2",
    "clientSecret": "client-secret-2",
    "scopes": ["openid", "profile", "email"]
  }
]

File: apps/docs/src/content/docs/02-self-hosting/01-using-docker.mdx Copy Chapter

title: Installing Papra using Docker slug: self-hosting/using-docker Copy Chapter

import { Steps } from '@astrojs/starlight/components';
import { Tabs, TabItem } from '@astrojs/starlight/components';
import SecretKeyGenerator from '../../../components/random-hex-key-generator.astro';

Papra provides optimized Docker images for streamlined deployment. This method is recommended for users seeking a production-ready setup with minimal maintenance overhead.

• Simplified management: Single container handles all components
• Lightweight: Optimized image sizes across architectures
• Cross-platform support: Compatible with arm64, arm/v7, and x86_64 systems
• Security options: Supports both rootless (recommended) and rootful configurations

Prerequisites Copy Chapter

Ensure Docker is installed on your host system. Official installation guides are available at:
docker.com/get-started

Verify Docker installation with:

docker --version

Quick Deployment Copy Chapter

Papra requires an AUTH_SECRET to run. Generate a secure one using the generator below or the OpenSSL command:

Then launch Papra with default configuration using:

docker run -d \
  --name papra \
  --restart unless-stopped \
  --env APP_BASE_URL=http://localhost:1221 \
  --env AUTH_SECRET=<your-auth-secret> \
  -p 1221:1221 \
  ghcr.io/papra-hq/papra:latest

This command will:

1. Pull the latest rootless image from GitHub Container Registry
2. Expose the web interface on http://localhost:1221
3. Configure automatic restarts for service continuity

Image Variants Copy Chapter

Choose between two security models based on your requirements:

• Rootless: Tagged as latest, latest-rootless or <version>-rootless (like 0.2.1-rootless). Recommended for most users.
• Root: Tagged as latest-root or <version>-root (like 0.2.1-root). Only use if you need to run Papra as the root user.

The :latest tag always references the latest rootless build.

Persistent Data Configuration Copy Chapter

For production deployments, mount host directories to preserve application data between container updates.

Image Registries Copy Chapter

Papra images are distributed through multiple channels:

Primary Source (GHCR):

docker pull ghcr.io/papra-hq/papra:latest
docker pull ghcr.io/papra-hq/papra:latest-rootless
docker pull ghcr.io/papra-hq/papra:latest-root

Community Mirror (Docker Hub):

docker pull corentinth/papra:latest
docker pull corentinth/papra:latest-rootless
docker pull corentinth/papra:latest-root

Updating Papra Copy Chapter

Regularly pull updated images and recreate containers to receive security patches and feature updates.

docker pull ghcr.io/papra-hq/papra:latest
# Or
docker pull corentinth/papra:latest

File: apps/docs/src/content/docs/02-self-hosting/02-using-docker-compose.mdx Copy Chapter

title: Using Docker Compose slug: self-hosting/using-docker-compose Copy Chapter

import { Steps } from '@astrojs/starlight/components';
import { Tabs, TabItem } from '@astrojs/starlight/components';
import SecretKeyGenerator from '../../../components/random-hex-key-generator.astro';

This guide covers how to deploy Papra using Docker Compose, ideal for users who prefer declarative configurations or plan to integrate Papra into a broader service stack.

Using Docker Compose provides:

• A single, versioned configuration file
• Easy integration with volumes, networks, and service dependencies
• Simplified updates and re-deployments

This method supports both rootless and rootful Papra images, please refer to the Docker guide for more information about the difference between the two. The following example uses the recommended rootless setup.

Prerequisites Copy Chapter

Ensure Docker and Docker Compose are installed on your host system. Official installation guides are available at: docker.com/get-started

Verify Docker installation with:

docker --version
docker compose version

Maintenance Copy Chapter

Check logs

docker compose logs -f

Stop the service

docker compose down

Update Papra

docker compose pull
docker compose up -d

You're all set! Enjoy managing your documents with Papra.