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!
