Skip to content

armgit / papra

Public Imported from GitHub
0

The minimalistic document archiving platform.

docs(docker): improved docker and docker-compose instructions for Papra deployment (#201)

Corentin Thomassetfd0f79feb0b2
diff --git a/apps/docs/src/content/docs/02-self-hosting/01-using-docker.md b/apps/docs/src/content/docs/02-self-hosting/01-using-docker.md
deleted file mode 100644
index 5f3c2486..00000000
--- a/apps/docs/src/content/docs/02-self-hosting/01-using-docker.md
+++ /dev/null
@@ -1,55 +0,0 @@
----
-title: Installing Papra using Docker
-description: Self-host Papra using Docker.
-slug: self-hosting/using-docker
----
-
-Papra can be easily installed and run using Docker. This method is recommended for users who want a quick and straightforward way to deploy their own instance of Papra with minimal setup.
-
-- Single lightweight image
-- Only one container to manage
-- Available for all platforms (arm64, arm/v7, x86_64)
-- Root and Rootless image variants
-
-## Prerequisites
-
-Before you begin, ensure that you have Docker installed on your system. You can download and install Docker from the official [Docker website](https://www.docker.com/get-started).
-
-Verify your installation:
-
-```bash frame="none"
-docker --version
-```
-
-## Installation
-
-You can run Papra using the following command:
-
-```bash frame="none"
-docker run -d --name papra --restart unless-stopped -p 1221:1221 ghcr.io/papra-hq/papra
-```
-
-It will automatically download the latest image and start the container. The application will be available at [http://localhost:1221](http://localhost:1221).
-
-## Root and Rootless installation
-
-Papra can be installed in two different ways:
-
-- **Rootless** (recommended): This method does not require root privileges to run. The images are suffixed with `-rootless` like `corentinth/papra:latest-rootless` or `corentinth/papra:1.0.0-rootless` and the default `:latest` tag points to the latest rootless image.
-- **Root**: This is the default installation method. It requires root privileges to run. The images are suffixed with `-root` like `corentinth/papra:latest-root` or `corentinth/papra:1.0.0-root`.
-
-## Image Sources
-
-Papra Docker images are available on both **Docker Hub** and **GitHub Container Registry** (GHCR). You can choose the source that best suits your needs.
-
-```bash frame="none"
-# Using Docker Hub
-docker pull corentinth/papra:latest
-docker pull corentinth/papra:latest-rootless
-docker pull corentinth/papra:latest-root
-
-# Using GitHub Container Registry
-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
-```
diff --git a/apps/docs/src/content/docs/02-self-hosting/01-using-docker.mdx b/apps/docs/src/content/docs/02-self-hosting/01-using-docker.mdx
new file mode 100644
index 00000000..6c912963
--- /dev/null
+++ b/apps/docs/src/content/docs/02-self-hosting/01-using-docker.mdx
@@ -0,0 +1,111 @@
+---
+title: Installing Papra using Docker
+description: Self-host Papra using Docker.
+slug: self-hosting/using-docker
+---
+import { Steps } from '@astrojs/starlight/components';
+
+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
+
+Ensure Docker is installed on your host system. Official installation guides are available at:
+[docker.com/get-started](https://www.docker.com/get-started)
+
+Verify Docker installation with:
+
+```bash
+docker --version
+```
+
+## Quick Deployment
+
+Launch Papra with default configuration using:
+
+```bash
+docker run -d \
+ --name papra \
+ --restart unless-stopped \
+ -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](http://localhost:1221)
+3. Configure automatic restarts for service continuity
+
+## Image Variants
+
+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
+
+For production deployments, mount host directories to preserve application data between container updates.
+
+<Steps>
+
+1. Create Storage Directories
+
+ Create a directory for Papra data `./papra-data`, with `./papra-data/db` and `./papra-data/documents` subdirectories:
+
+ ```bash
+ mkdir -p ./papra-data/{db,documents}
+ ```
+
+2. Launch Container with Volume Binding
+
+ ```bash
+ docker run -d \
+ --name papra \
+ --restart unless-stopped \
+ -p 1221:1221 \
+ -v $(pwd)/papra-data:/app/app-data \
+ --user $(id -u):$(id -g) \
+ ghcr.io/papra-hq/papra:latest
+ ```
+
+ This configuration:
+ - Maintains data integrity across container lifecycle events
+ - Enforces proper file ownership without manual permission adjustments
+ - Stores both database files and document assets persistently
+
+</Steps>
+
+## Image Registries
+
+Papra images are distributed through multiple channels:
+
+**Primary Source (GHCR):**
+```bash
+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):**
+```bash
+docker pull corentinth/papra:latest
+docker pull corentinth/papra:latest-rootless
+docker pull corentinth/papra:latest-root
+```
+
+## Updating Papra
+
+Regularly pull updated images and recreate containers to receive security patches and feature updates.
+
+```bash
+docker pull ghcr.io/papra-hq/papra:latest
+# Or
+docker pull corentinth/papra:latest
+```
diff --git a/apps/docs/src/content/docs/02-self-hosting/02-using-docker-compose.mdx b/apps/docs/src/content/docs/02-self-hosting/02-using-docker-compose.mdx
index bf3662ca..ad99b92e 100644
--- a/apps/docs/src/content/docs/02-self-hosting/02-using-docker-compose.mdx
+++ b/apps/docs/src/content/docs/02-self-hosting/02-using-docker-compose.mdx
@@ -5,18 +5,35 @@ slug: self-hosting/using-docker-compose
import { Steps } from '@astrojs/starlight/components';
-Docker Compose makes it easy to deploy Papra on your server or local machine. Follow these simple steps to get your instance up and running quickly.
+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](/self-hosting/using-docker) guide for more information about the difference between the two. The following example uses the recommended `rootless` setup.
+
+## Prerequisites
+
+Ensure Docker and Docker Compose are installed on your host system. Official installation guides are available at: [docker.com/get-started](https://www.docker.com/get-started)
+
+Verify Docker installation with:
+
+```bash
+docker --version
+docker compose version
+```
-<Steps>
-1. Prepare your environment
+<Steps>
- Make sure you have [Docker](https://www.docker.com/get-started) and [Docker Compose](https://docs.docker.com/compose/install/) installed on your system.
+1. Initialize Project Structure
- Verify your installation:
+ Create working directory and persistent storage subdirectories:
- ```bash frame="none"
- docker --version
+ ```bash
+ mkdir -p papra/app-data/{db,documents} && cd papra
```
2. Create Docker Compose file
@@ -26,16 +43,14 @@ Docker Compose makes it easy to deploy Papra on your server or local machine. Fo
```yaml
services:
papra:
- image: corentinth/papra:latest-rootless
+ container_name: papra
+ image: ghcr.io/papra-hq/papra:latest
+ restart: unless-stopped
ports:
- - '1221:1221'
+ - "1221:1221"
volumes:
- - papra-data:/app/app-data
- restart: unless-stopped
-
- volumes:
- papra-data:
- driver: local
+ - ./app-data:/app/app-data
+ user: "${UID}:${GID}"
```
3. Start Papra
@@ -43,10 +58,10 @@ Docker Compose makes it easy to deploy Papra on your server or local machine. Fo
From the directory containing your `docker-compose.yml` file, run:
```bash
- docker compose up -d
+ UID=$(id -u) GID=$(id -g) docker compose up -d
```
- This command downloads the latest Papra image, sets up the container, and starts the Papra service.
+ This command downloads the latest Papra image, sets up the container, and starts the Papra service. The `UID` and `GID` variables are used to set the user and group for the container, ensuring proper file ownership. If you don't want to use the `UID` and `GID` variables, you can replace the image with the rootful variant.
4. Access Papra