# matrix-paperless-ingest

Monitors a Matrix room for PDF and JPEG files and uploads them to Paperless-ngx.
Designed for rooms bridged from WhatsApp via mautrix-whatsapp.

- Processes the full room history on startup (skips files already in Paperless)
- Listens for new files indefinitely
- Retries failed uploads with exponential backoff
- State is tracked in a local SQLite database

## Requirements

- Python 3.11+
- [uv](https://docs.astral.sh/uv/) (`curl -LsSf https://astral.sh/uv/install.sh | sh`)
- `libolm` + `python-olm` — must be installed via the system package manager
  because `python-olm`'s build system is incompatible with modern CMake

**Arch Linux:**
```bash
sudo pacman -S libolm python-olm
```

**Ubuntu:**
```bash
sudo apt install libolm3 python3-olm
```

## Setup

### 1. Clone and install dependencies

```bash
git clone <repo>
cd matrix-paperless-ingest
uv venv --system-site-packages
uv sync --no-install-package python-olm
```

### 2. Create a Matrix bot account

Create a new Matrix account for the bot on your homeserver (e.g. via Element),
then invite it to the room you want to monitor and accept the invite.

### 3. Generate a Matrix access token

Log in with the bot account to obtain an access token and device ID:

```bash
curl -XPOST 'https://jeena.net/_matrix/client/v3/login' \
  -H 'Content-Type: application/json' \
  -d '{
    "type": "m.login.password",
    "user": "@yourbot:jeena.net",
    "password": "yourpassword"
  }'
```

Copy `access_token` and `device_id` from the response. You can then delete the
password from your notes — it is not needed again.

### 4. Find your Matrix room ID

In Element: open the room → Settings → Advanced → Internal room ID.
It looks like `!abc123:jeena.net`.

### 5. Find your Paperless inbox tag ID

In Paperless-ngx, go to Tags and note the ID of your inbox tag, or look it up
via the API:

```bash
curl -H 'Authorization: Token YOUR_TOKEN' https://paperless.jeena.net/api/tags/
```

### 6. Configure

```bash
cp .env.example .env
$EDITOR .env
```

Fill in all values:

```
MATRIX_HOMESERVER=https://jeena.net
MATRIX_USER=@yourbot:jeena.net
MATRIX_ACCESS_TOKEN=syt_...
MATRIX_DEVICE_ID=ABCDEFGH
MATRIX_ROOM_ID=!abc123:jeena.net

PAPERLESS_URL=https://paperless.jeena.net
PAPERLESS_TOKEN=your_paperless_api_token
PAPERLESS_INBOX_TAG_ID=1
```

### 7. Test

```bash
uv run --no-sync python ingest.py
```

Watch the logs. It will process all historical messages, then listen for new ones.
Press Ctrl-C to stop.

## Install as a systemd service

```bash
# Create a dedicated user
sudo useradd -r -s /bin/false matrix-paperless-ingest

# Copy the project
sudo cp -r . /opt/matrix-paperless-ingest
sudo chown -R matrix-paperless-ingest:matrix-paperless-ingest /opt/matrix-paperless-ingest

# Install and start the service
sudo cp paperless-ingest.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable --now paperless-ingest

# Check logs
sudo journalctl -u paperless-ingest -f
```

## Viewing retry queue

```bash
sqlite3 state.db "SELECT filename, status, retry_count, datetime(next_retry, 'unixepoch') FROM processed_events WHERE status = 'failed';"
```

## Moving to a new server

1. Copy the project directory (including `.env` and `state.db`)
2. Install `uv`, `libolm3`, and `python3-olm` on the new server
3. Run `uv venv --system-site-packages && uv sync --no-install-package python-olm`
4. Install the systemd service as above