DocWebSelf-hosted document management

Guide

Installation

DocWeb runs on a Synology NAS or on an ordinary web server. Choose the route that suits your environment – the steps for the OCR tools and the setup after installation apply to both.

Contents

  1. Requirements
  2. Route A: Synology NAS (DSM)
  3. Route B: Standard web server
  4. Setting up the OCR tools
  5. After installation
  6. When something does not work
  7. Sign in

1. Requirements

DocWeb is deliberately undemanding: no framework dependency, no Node.js, no build steps. Essentially you need a web server with PHP and a database.

Required

  • PHP 8.x (tested with 8.2) with the extensions pdo_mysql, mbstring, zip, zlib, json
  • MariaDB 10 (or MySQL with the same feature set), character set utf8mb4
  • Apache or nginx – or Web Station on a Synology
  • Write permission for the web server user in the project folder (for .env, documents/, inbox/, trash/)

Optional – for full-text search in scanned documents

  • Tesseract (OCR for scanned pages and images)
  • Poppler (pdftotext, pdftoppm)
  • shell_exec must be allowed on the server so that the tools can be called
Without these tools DocWeb still works. Embedded text in PDFs is read even without Poppler (a pure PHP fallback), and Office files are evaluated through the zip extension. Only scanned PDFs and images then remain without full text – the file name, category and tags are still searchable.
Space required: DocWeb does not store the documents twice. What is used is the documents, a text cache (search index) and the database. Depending on the size of your collection the text cache needs additional space.

Route A

2. Synology NAS (DSM, Web Station)

The recommended route if DocWeb is to run on your own network on a Synology. Access is then typically possible only on the local network or through a VPN.

  1. Install Web Station, PHP 8 and MariaDB

    In the Synology Package Center install the packages Web Station, PHP 8.x and MariaDB 10. Then, under Web Station → Web service, create a web server with PHP 8 if none exists yet.

  2. Place the app files in the web directory

    Copy the complete project folder to /volume1/web/docweb – that is, the folder containing public/, src/ and sql/. The folders documents/, inbox/ and trash/ are created automatically during installation.

  3. Create the database

    Using phpMyAdmin (or via SSH) create a database together with a user: 

    CREATE DATABASE docweb CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE USER 'docweb'@'localhost' IDENTIFIED BY 'DEIN_PASSWORT';
GRANT ALL PRIVILEGES ON docweb.* TO 'docweb'@'localhost';
FLUSH PRIVILEGES;

  4. Create the configuration file .env

    In the project folder (one level above public/) create a file .env: 

    DB_HOST=localhost
DB_PORT=3307
DB_NAME=docweb
DB_USER=docweb
DB_PASSWORD=DEIN_PASSWORT
    Port: The Synology MariaDB package listens on port 3307 by default, not on 3306. Adjust accordingly for an external database.

  5. Run the installation

    Open http://NAS-ADRESSE/docweb/install.php in the browser and fill in the form. The assistant creates all tables, writes the credentials into .env, creates the folders and sets up the first admin account.

    Alternatively, via SSH in the project folder: php install.php. Without --admin-pass a random password is generated and shown once.

    Then delete install.php. The assistant refuses to work as soon as a user account exists – even so, it does not belong on the server permanently.

  6. Check the PHP settings

    Under Web Station → Script languages → PHP 8.x → Configuration:

    • shell_exec must not be listed in disable_functions (otherwise no OCR)
    • Enable the extensions: pdo_mysql, mbstring, zip, zlib, json

  7. Install the OCR tools (optional)

    For scanned documents set up Tesseract and Poppler – the instructions are in the Setting up the OCR tools. Without this step DocWeb works, just without full text in scans.

  8. Sign in and run the sync

    Sign in at http://NAS-ADRESSE/docweb/ and click Sync in the top bar. Then run Reindex once if the OCR tools were set up – that also captures scans that are already there.

Order for an existing collection: Put the documents into the document folder first, then run the sync. With very many files the first pass takes correspondingly long – it continues in the background with a progress display.

Route B

3. Standard web server (Apache or nginx)

For a rented server, your own machine or a virtual machine. This makes DocWeb reachable from anywhere – so pay particular attention to the security notes at the end of this section.

  1. Install PHP and the database

    On Debian or Ubuntu a few packages are enough: 

    sudo apt install apache2 mariadb-server php php-mysql php-mbstring \
     php-zip php-gd php-curl libapache2-mod-php

sudo mysql_secure_installation

    For nginx instead of Apache, install the same PHP packages with php-fpm.

  2. Upload the project folder

    Copy the complete project folder to the server. Place it outside the publicly reachable directory and point the domain at the public/ subfolder: 

    /var/www/docweb/            <- project folder (not public)├── public/                 <- this is where the domain points├── src/
├── sql/
├── documents/
├── inbox/
└── trash/
    This is the recommended setup. It keeps source code, configuration and documents outside the web root so they cannot be downloaded directly.

    For Apache, for example: 

    <VirtualHost *:443>
    ServerName docweb.example.ch
    DocumentRoot /var/www/docweb/public

    <Directory /var/www/docweb/public>
        AllowOverride All
        Require all granted
    </Directory>
</VirtualHost>

    Alternatively the project folder itself can be the web directory – the application then sits under /public/ and is reachable for example at https://example.ch/public/. That setup is supported too; the first variant is cleaner, however.

  3. Create the database

    sudo mysql -e "CREATE DATABASE docweb CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;"
sudo mysql -e "CREATE USER 'docweb'@'localhost' IDENTIFIED BY 'DEIN_PASSWORT';"
sudo mysql -e "GRANT ALL PRIVILEGES ON docweb.* TO 'docweb'@'localhost'; FLUSH PRIVILEGES;"

  4. Create the configuration file .env

    In the project folder (one level above public/): 

    DB_HOST=127.0.0.1
DB_PORT=3306
DB_NAME=docweb
DB_USER=docweb
DB_PASSWORD=DEIN_PASSWORT

  5. Set the file permissions

    The web server user (on Debian/Ubuntu www-data) must be able to write in the project folder – for .env and the folders documents/, inbox/ and trash/: 

    sudo chown -R www-data:www-data /var/www/docweb
sudo find /var/www/docweb -type d -exec chmod 750 {} \;
sudo find /var/www/docweb -type f -exec chmod 640 {} \;

  6. Run the installation

    Open https://docweb.example.ch/install.php in the browser and fill in the form. Then delete install.php.

    No SSH access? The assistant works entirely in the browser – you do not need any command-line tool. Day-to-day operation works without one as well (see the next step).

  7. Run the first sync

    After signing in, click Sync in the top bar. How the sync runs depends on whether a command-line PHP can be started on the server:

    • With CLI PHP: The sync runs as a background process. If it runs reliably there is nothing more to do. If your server has the PHP binary in an unusual place, enter the path in .env: PHP_CLI=/usr/bin/php
    • Without CLI PHP (typical for shared hosting where shell_exec or popen is blocked): DocWeb switches automatically to the web variant and works through the sync in short steps via the web server. The status bar then shows a note to keep the window open – the process continues as long as the page stays open. If it is closed, the next visit carries on from the last state.
    Adjusting the step length: If the web variant aborts with a timeout error, set a smaller value in .env, for example WEB_WORKER_BUDGET=10 (seconds per step).

  8. Security when publicly reachable

    • Use HTTPS – with Let's Encrypt or your own certificate
    • Point the domain at public/ (see step 2) so that src/, documents/ and .env are not reachable over the web
    • If you wish, keep the document folder outside the project folder – set DOCS_ROOT in .env for that, for example DOCS_ROOT=/srv/documents
    • Enable two-factor sign-in for the user accounts
    • Set up regular backups (DocWeb produces a ZIP of database and documents)

Full text in scans

4. Setting up the OCR tools

These tools are optional. Without them the search finds no text in scanned pages and images. With them the content is recognised and becomes searchable.

On a standard web server

Tesseract and Poppler come from the package manager, along with the language data: 

sudo apt install tesseract-ocr tesseract-ocr-deu tesseract-ocr-eng \
     tesseract-ocr-fra tesseract-ocr-ita poppler-utils

Then check whether the tools are found: 

which pdftotext pdftoppm tesseract
tesseract --list-langs

On a Synology NAS

The former packages for Tesseract and Poppler are no longer available for newer DSM versions. Two routes work: Entware (binaries directly on the file system, recommended) or a Docker-Container that provides the binaries through a directory.

Variant 1: Entware (recommended)

First sign in by SSH as admin and become root with sudo -i. Enable SSH beforehand under Control Panel → Terminal & SNMP. 

# Create a persistent directory (survives DSM updates)
mkdir -p /volume1/@Entware/opt
mount -o bind /volume1/@Entware/opt /opt

# Install Entware – choose the URL matching your CPU architecture
# x86_64 (e.g. RS1221RP):
wget -O - https://bin.entware.net/x64-k3.2/installer/generic.sh | /bin/sh
# ARMv8 (e.g. DS920+):
# wget -O - https://bin.entware.net/aarch64-k3.10/installer/generic.sh | /bin/sh

Then install the packages: 

/opt/bin/opkg update
/opt/bin/opkg install tesseract tesseract-data-eng poppler-utils
Important: The package is called poppler-utils, not poppler. Entware has no German language package – deu has to be installed by hand. 
cd /opt/share/tessdata
wget -O deu.traineddata https://raw.githubusercontent.com/tesseract-ocr/tessdata/main/deu.traineddata
/opt/bin/tesseract --list-langs   # "deu" has to appear

The binaries then live under /opt/bin/. If they are not found automatically, enter them in .env: 

PDFTOTEXT_PATH=/opt/bin/pdftotext
PDFTOPPM_PATH=/opt/bin/pdftoppm
TESSERACT_PATH=/opt/bin/tesseract

So that the tools survive a restart of the NAS, add the supplied script in the Task Scheduler (Control Panel → Task Scheduler → Triggered Task, trigger "On boot", user root): 

/bin/sh /volume1/web/docweb/scripts/entware_boot.sh

The script mounts /opt again, reinstalls Entware and the packages if needed and takes care of the OCR language data.

Variant 2: Docker container

A container provides the binaries through a shared directory: 

docker run -d --name ocr-tools \
  -v /volume1/web/docweb/tools:/tools \
  debian:bookworm-slim \
  bash -c "apt-get update && apt-get install -y tesseract-ocr tesseract-ocr-deu \
           tesseract-ocr-eng poppler-utils && \
           cp /usr/bin/tesseract /usr/bin/pdftotext /usr/bin/pdftoppm /tools/ && sleep infinity"

Since the files are not on the search path, set the paths in .env: 

PDFTOTEXT_PATH=/volume1/web/docweb/tools/pdftotext
PDFTOPPM_PATH=/volume1/web/docweb/tools/pdftoppm
TESSERACT_PATH=/volume1/web/docweb/tools/tesseract

Checking the status

After signing in, the user menu at the top right shows whether the three tools were found: pdftotext (PDF text), pdftoppm (render pages) and tesseract (OCR).

Scans that already exist: After the setup run Reindex once in the top bar. Only then is the full text of all existing documents rebuilt.

5. After installation

First steps

  • Sign in: via Sign in or directly at https://docweb.gregus.ch/.
  • Change the password: change the admin password chosen during setup after the first sign-in.
  • Create more users: the admin, editor and read-only roles control who may see and edit documents.
  • Two-factor sign-in: recommended for accounts with access from outside.
  • Check the document folder: check the storage location under Settings → Database – it can also be changed later, the next sync adopts the new location.
  • Run the sync: reads the document folder and processes only new, changed and removed files.
  • Run reindex: once, after setting up Tesseract and Poppler.

Bringing documents into the collection

  • Straight into the folder: put files into the document folder via a file explorer, SMB or a cloud sync and then run the sync. The folder structure becomes the categories.
  • Through the inbox: new scans arrive in the inbox first, are checked, rotated and renamed there and then filed into a category with tags – if the right category is missing, it can be created directly while filing.
  • Batch scanning: a whole stack with separator sheets is captured in one pass and split into individual PDFs automatically.
  • Mail archiving: fetch e-mails via IMAP or POP3 and file them as PDF.
  • Through the iOS app: capture documents with the camera and file them straight away.

Backup

DocWeb creates a backup of database and documents as a ZIP. Since the documents exist as ordinary files anyway, backing up the document folder with the usual tools is enough for the collection – a complete migration also needs the database and .env.

6. When something does not work

"The server is not responding" or a blank page

Usually a PHP extension is missing or the database is unreachable. Check the PHP error output of the server (Apache: error.log, nginx: /var/log/nginx/error.log). Common causes: pdo_mysql missing, wrong port, wrong password in .env.

The installation reports that src/config.php is missing

Then install.php is not in the project folder, or the level above it contains no src/. Upload the complete project folder – not just the contents of public/. The installer recognises both layouts (project folder and public/) by itself.

A red line appears next to "Folder" or ".env"

The web server user is not allowed to write in the project folder. Set the permissions as in step 5 (route B). On a Synology, check whether the shared folder is writable for the Web Station user.

After the sync the full text is missing in scans

The OCR tools are missing or cannot be called. The user menu shows the status of the three tools. If all three are missing, shell_exec is usually blocked in disable_functions – or the paths have to be set in .env. After correcting that, run Reindex once.

Word, Excel and PowerPoint files cannot be searched

This needs the PHP extension zip. Enable it and start the reindex again.

"The sync could not be started" or the process stops

On servers without a startable command-line PHP the web variant takes over automatically (see step 7 in route B). If the message still appears, check:

  • Is JavaScript enabled in the browser window? The control runs through the browser.
  • If the run aborts after a while, set a smaller value for WEB_WORKER_BUDGET in .env (e.g. 10).
  • Is there a command-line path that could help in .env? PHP_CLI=/usr/bin/php

The run stops when I open other pages

In web mode the browser performs the work steps. If the page is closed the process pauses – nothing is lost. The next visit continues from the last state.

I have forgotten the admin password

The installer does not create a second account once one exists – that is intentional. Reset the password directly in the database or create a new user with the admin role through phpMyAdmin.