Oct 20, 2024 3 min read

Docspell: Self-Hosting Made Simple

Docspell: Self-Hosting Made Simple
Table of Contents

Docspell is a powerful, self-hosted document management and organization tool designed to help you digitize, organize, and retrieve documents efficiently. Its ability to automate workflows, integrate with external systems, and maintain data privacy makes it an excellent choice for tech-savvy users who value control and customization. In this guide, we’ll walk through installing, configuring, and managing Docspell, covering setup, reverse proxy configurations, logging, backups, updates, and leveraging its unique features.

Installing Docspell

πŸ“¦ Docker/Docker Compose Setup: Docspell provides an official Docker image, making it simple to deploy. Below is a docker-compose.yml file tailored for Docspell:


version: '3.8'

services:

db:

image: postgres:14

container_name: docspell-db

environment:

POSTGRES_USER: docspell

POSTGRES_PASSWORD: docspellpassword

POSTGRES_DB: docspell

volumes:

- db_data:/var/lib/postgresql/data

restserver:

image: eikek0/docspell-restserver:latest

container_name: docspell-restserver

environment:

DOCSPELL_DB_HOST: db

DOCSPELL_DB_NAME: docspell

DOCSPELL_DB_USER: docspell

DOCSPELL_DB_PASS: docspellpassword

ports:

- "7880:7880"

depends_on:

- db

joex:

image: eikek0/docspell-joex:latest

container_name: docspell-joex

environment:

DOCSPELL_DB_HOST: db

DOCSPELL_DB_NAME: docspell

DOCSPELL_DB_USER: docspell

DOCSPELL_DB_PASS: docspellpassword

depends_on:

- db

volumes:

db_data:

After creating the docker-compose.yml file, use the commands below to deploy Docspell:


docker-compose up -d

## Verify the services are running

docker ps

πŸš€ Manual Installation: For users who prefer manual setup, install Docspell directly on a Linux server. Here’s an example for an Ubuntu system:


## Install dependencies

sudo apt update && sudo apt install -y openjdk-17-jre-headless postgresql wget unzip

## Create a PostgreSQL database and user

sudo -i -u postgres psql -c "CREATE DATABASE docspell;"

sudo -i -u postgres psql -c "CREATE USER docspell WITH ENCRYPTED PASSWORD 'docspellpassword';"

sudo -i -u postgres psql -c "GRANT ALL PRIVILEGES ON DATABASE docspell TO docspell;"

## Download and extract Docspell binaries

wget https://github.com/eikek/docspell/releases/latest/download/docspell-restserver.zip

wget https://github.com/eikek/docspell/releases/latest/download/docspell-joex.zip

unzip docspell-restserver.zip -d /opt/docspell-restserver

unzip docspell-joex.zip -d /opt/docspell-joex

## Start the services

cd /opt/docspell-restserver && ./bin/restserver

cd /opt/docspell-joex && ./bin/joex

Configuring Nginx as a Reverse Proxy

🌐 Nginx Configuration: Set up Nginx to route traffic to Docspell for better performance and flexibility. Create an Nginx server block:


server {

listen 80;

server_name yourdomain.com;

location / {

proxy_pass http://localhost:7880; # Docspell REST server

proxy_set_header Host $host;

proxy_set_header X-Real-IP $remote_addr;

proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;

}

}

πŸ”’ SSL/TLS Setup: Secure your Nginx configuration with Let’s Encrypt. Install Certbot and generate certificates:


sudo apt install -y certbot python3-certbot-nginx

sudo certbot --nginx -d yourdomain.com

πŸ› οΈ Testing and Reloading Nginx: Validate the configuration and reload Nginx:


sudo nginx -t

sudo systemctl reload nginx

Logging and Debugging Docspell

πŸ—ƒοΈ Enabling Debug Logs: Adjust logging levels in the application.conf file for Docspell.


## Example logging configuration

sed -i 's/loglevel = "INFO"/loglevel = "DEBUG"/' /opt/docspell-restserver/application.conf

πŸ“„ Viewing Logs: Access logs via Docker or directly from log files:


## Docker logs

docker logs docspell-restserver

## Manual installation logs

tail -f /opt/docspell-restserver/logs/application.log

πŸ› οΈ Troubleshooting Common Issues: Analyze logs for errors like database connection issues. For example:


grep "ERROR" /opt/docspell-restserver/logs/application.log

πŸ“€ Exporting Logs: Forward logs to ELK Stack using Filebeat or a similar tool.


## Example Filebeat configuration

filebeat.inputs:

- type: log

paths:

- /opt/docspell-restserver/logs/application.log

output.elasticsearch:

hosts: ["localhost:9200"]

Backup and Restore

πŸ—‚οΈ File-Based Backups: Create snapshots of critical directories:


tar -czvf docspell-config-backup.tar.gz /opt/docspell-restserver /opt/docspell-joex

πŸ”„ Database Backups: Dump the PostgreSQL database:


sudo -i -u postgres pg_dump docspell > docspell-db-backup.sql

πŸ“… Automated Backup Scripts: Schedule periodic backups using cron:


## Add to crontab

0 2 * * * tar -czvf /backups/docspell-config-$(date +\%F).tar.gz /opt/docspell-restserver /opt/docspell-joex

0 3 * * * pg_dump docspell > /backups/docspell-db-$(date +\%F).sql

Updating and Upgrading Docspell

⬆️ Updating Docker Images: Pull the latest versions and redeploy:


docker-compose pull

docker-compose up -d

πŸ› οΈ Manual Updates: Download and replace binaries for manual installations:


wget https://github.com/eikek/docspell/releases/latest/download/docspell-restserver.zip

unzip -o docspell-restserver.zip -d /opt/docspell-restserver

πŸ” Checking for Updates: Monitor Docspell’s GitHub repository or release feed.

Leveraging Docspell’s Unique Features

πŸ”§ Enabling APIs: Activate Docspell’s REST API by enabling it in the configuration file.


## Example REST API configuration

echo 'restapi.enabled = true' >> /opt/docspell-restserver/application.conf

🌟 Advanced Configurations: Integrate OCR tools like Tesseract by linking it with the Docspell configuration.


## Example OCR setting

echo 'ocr.tool = "tesseract"' >> /opt/docspell-joex/application.conf

Wrapping Up

In this guide, we covered the essential steps for deploying, configuring, and managing Docspell, from setting up Docker containers to securing your setup with Nginx and automating backups. By following these steps, you can leverage Docspell’s powerful document organization and workflow automation features while maintaining full control over your data in a self-hosted environment. Start implementing these configurations today and unlock the full potential of Docspell!

Great! You’ve successfully signed up.
Welcome back! You've successfully signed in.
You've successfully subscribed to Selfhosted Ninja.
Your link has expired.
Success! Check your email for magic link to sign-in.
Success! Your billing info has been updated.
Your billing was not updated.