https://github.com/daemonless/paperless-ngx
A community-supported supercharged document management system: scan, index and archive all your documents
https://github.com/daemonless/paperless-ngx
freebsd oci-image paperless-ngx podman self-hosted
Last synced: 12 days ago
JSON representation
A community-supported supercharged document management system: scan, index and archive all your documents
- Host: GitHub
- URL: https://github.com/daemonless/paperless-ngx
- Owner: daemonless
- Created: 2026-05-11T20:33:55.000Z (about 2 months ago)
- Default Branch: main
- Last Pushed: 2026-06-15T09:01:30.000Z (13 days ago)
- Last Synced: 2026-06-15T11:39:40.853Z (13 days ago)
- Topics: freebsd, oci-image, paperless-ngx, podman, self-hosted
- Language: Dockerfile
- Homepage: https://daemonless.io
- Size: 38.1 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# Paperless-ngx
[](https://github.com/daemonless/paperless-ngx/actions)
[](https://github.com/daemonless/paperless-ngx/commits)
A community-supported open-source document management system that transforms your physical documents into a searchable online archive so you can keep, well, less paper.
| | |
|---|---|
| **Port** | 8000 |
| **Registry** | `ghcr.io/daemonless/paperless-ngx` |
| **Source** | [https://github.com/paperless-ngx/paperless-ngx](https://github.com/paperless-ngx/paperless-ngx) |
| **Website** | [https://paperless-ngx.org/](https://paperless-ngx.org/) |
## Version Tags
| Tag | Description | Best For |
| :--- | :--- | :--- |
| `latest` | **Upstream Binary**. Built from official release. | Most users. Matches Linux Docker behavior. |
## Prerequisites
Before deploying, ensure your host environment is ready. See the [Quick Start Guide](https://daemonless.io/guides/quick-start) for host setup instructions.
## Deployment
### Podman Compose
```yaml
services:
paperless-ngx:
image: ghcr.io/daemonless/paperless-ngx:latest
container_name: paperless-ngx
environment:
- PUID=1000
- PGID=1000
- TZ=UTC
- PAPERLESS_ADMIN_USER=admin
- PAPERLESS_ADMIN_PASSWORD=
volumes:
- "/path/to/containers/paperless-ngx:/config"
- "/path/to/containers/paperless-ngx/config/media/documents:/config/media/documents"
ports:
- 8000:8000
- 5555:5555
restart: unless-stopped
```
### Podman CLI
```bash
podman run -d --name paperless-ngx \
-p 8000:8000 \
-p 5555:5555 \
-e PUID=1000 \
-e PGID=1000 \
-e TZ=UTC \
-e PAPERLESS_ADMIN_USER=admin \
-e PAPERLESS_ADMIN_PASSWORD= \
-v /path/to/containers/paperless-ngx:/config \
-v /path/to/containers/paperless-ngx/config/media/documents:/config/media/documents \
ghcr.io/daemonless/paperless-ngx:latest
```
### Ansible
```yaml
- name: Deploy paperless-ngx
containers.podman.podman_container:
name: paperless-ngx
image: ghcr.io/daemonless/paperless-ngx:latest
state: started
restart_policy: always
env:
PUID: "1000"
PGID: "1000"
TZ: "UTC"
PAPERLESS_ADMIN_USER: "admin"
PAPERLESS_ADMIN_PASSWORD: ""
ports:
- "8000:8000"
- "5555:5555"
volumes:
- "/path/to/containers/paperless-ngx:/config"
- "/path/to/containers/paperless-ngx/config/media/documents:/config/media/documents"
```
## Parameters
### Environment Variables
| Variable | Default | Description |
|----------|---------|-------------|
| `PUID` | `1000` | User ID for the application process |
| `PGID` | `1000` | Group ID for the application process |
| `TZ` | `UTC` | Timezone for the container |
| `PAPERLESS_ADMIN_USER` | `admin` | Optional - Set name of the admin user on first start |
| `PAPERLESS_ADMIN_PASSWORD` | `` | Optional - Set password of the admin user on first start |
### Volumes
| Path | Description |
|------|-------------|
| `/config` | Configuration directory |
| `/config/media/documents` | Optional - the actual document store (originals, archive and thumbnails) |
### Ports
| Port | Protocol | Description |
|------|----------|-------------|
| `8000` | TCP | Web UI |
| `5555` | TCP | Flower monitoring UI available at '/flower', optional |
## First time setup
To configure the admin user with a password during the first startup, you can define some
additional environment variables in your container file:
```yaml
services:
paperlessngx:
env:
- PAPERLESS_ADMIN_USER=""
- PAPERLESS_ADMIN_PASSWORD=""
```
These 2 variables can be removed after the initial setup was done and paperless won't change an existing admin user's
password when these vars are defined.
## Configuration
Configuration is best done using a `.env` file next to your compose.yaml.
If no `.env` file is in compose.yaml, paperless-ngx will use default values.
## Documents directory
If you want to keep your documents in a separate ZFS filesystem, you can mount it at `/config/media/documents`.
This directoru should contain these 3 directories:
```
- archive
- originals
- thumbnails
```
**Architectures:** amd64
**User:** `bsd` (UID/GID via PUID/PGID, defaults to 1000:1000)
**Base:** FreeBSD 15.0
---
Need help? Join our [Discord](https://discord.gg/Kb9tkhecZT) community.