Building from source

This page shows developers how to build DocView Capture from its source code, run the tests, and start the web app, the DocView Worker and the Scan Agent on a development PC.

Prerequisites

The solution file is DocViewCapture.slnx.

Get the language data for OCR

The Tesseract OCR engine needs language files. Download English and the orientation data once:

./tools/get-tessdata.ps1 -Languages eng

The files go to %ProgramData%\DocViewCapture\tessdata. Add more languages as needed, for example -Languages eng,deu,fra. See OCR engines and languages.

Build and test

From the repository root:

dotnet build DocViewCapture.slnx
dotnet test --solution DocViewCapture.slnx

Warnings are treated as errors, so the build fails on any compiler warning.

The test suites include:

• unit tests for the domain and application layers;
• integration tests against SQL Server LocalDB (localdb)\MSSQLLocalDB;
• real Tesseract OCR tests;
• web host tests;
• Scan Agent tests with a demo scanner;
• architecture tests for the layer rules and forbidden packages.

The Azure Blob Storage test is skipped unless the Azurite emulator is running.

Where build output goes

On Windows, build output goes to %LOCALAPPDATA%\DocViewCapture\artifacts instead of bin and obj folders in the source tree. This keeps synchronised folders (such as cloud drives) free of build files. To build in the source tree instead, set:

$env:DOCVIEW_INTREE_BUILD = 'true'

Linux and Docker builds use the normal layout.

Run the web app and the DocView Worker

1. Set the password of the first administrator in user secrets (development only):

   dotnet user-secrets set "Bootstrap:AdminPassword" "<a strong password>" --project src/DocView.Capture.Web
   

   Without it, the setup wizard asks you to create the administrator the first time you open the site. In development the database is .\SQLEXPRESS / DocViewCapture (appsettings.Development.json), so the wizard skips its database step.

2. Start the web app:

   dotnet run --project src/DocView.Capture.Web
   

   It listens on https://localhost:7210 (and http://localhost:5210).

3. In a second terminal, start the DocView Worker:

   dotnet run --project src/DocView.Capture.Worker
   

   Its health endpoint is http://localhost:5211/health/live.

4. Open https://localhost:7210 and sign in as admin.

On first start, the database DocViewCapture is created and migrated automatically, and a sample Batch Setup, Sample Invoices, is created. Set Bootstrap:SeedSampleBatchClass to false to skip the sample.

To build the self-installing DocView Worker package that Administration › Downloads offers, run ./tools/build-worker.ps1 (it writes DocViewWorker-Setup-<version>.zip to %ProgramData%\DocViewCapture\Downloads).

Tip: The folder samples/invoices holds generated test invoices. ./tools/load-master-data.ps1 -Csv samples/master-data/suppliers.csv loads the sample supplier list into a SQL Server table for the "Suppliers" lookup.

Run the Scan Agent

dotnet run --project src/DocView.Capture.ScanAgent

With DOTNET_ENVIRONMENT=Development, the agent allows http://localhost:5210 and offers a demo scanner, so you can test scanning without hardware. An icon appears in the notification area.

To scan from the HTTPS site, trust the development certificate once:

dotnet dev-certs https --trust

To build the agent installers, run ./tools/build-scan-agent.ps1. See Scan Agent.

Run with Docker Compose

Docker Compose starts SQL Server Express, the web app and the DocView Worker in Linux containers:

cp .env.example .env        # set MSSQL_SA_PASSWORD and DOCVIEW_ADMIN_PASSWORD
docker compose up -d --build

Open http://localhost:8080 and sign in as DocView with DOCVIEW_ADMIN_PASSWORD. The images include Tesseract with English and orientation data. Page images are kept on the shared docview-storage volume.

For production containers, protect the key ring with a certificate (DOCVIEW_DATAPROTECTION_CERT) and put a TLS reverse proxy in front of the web container with ReverseProxy__Enabled=true.

Run DocView OmniRead

DocView OmniRead (see DocView OmniRead) is the src/DocView.Capture.OmniRead project. Download the models once, then run it with a key and point DocView at it:

dotnet run --project src/DocView.Capture.OmniRead -- download-models --all
dotnet run --project src/DocView.Capture.OmniRead -- --OmniRead:Key dev-key --OmniRead:EnableVlm true   # http://localhost:5300

In Administration › DocView OmniRead add http://localhost:5300; the key must match (set it with OmniRead__Key from Show the key, or the other way round). ./tools/build-omniread.ps1 builds the installer, -Docker the Linux image.

The OmniRead accuracy tests in tests/DocView.Capture.OmniRead.Tests skip themselves until the models are in %ProgramData%\DocViewCapture\OmniRead\models (or DOCVIEW_OMNIREAD_MODELS); the vision-model test also needs DOCVIEW_OMNIREAD_VLM=1. The benchmark compares the engines on the synthetic ground truth and the sample invoices (samples/invoices/*.json, written by make-ground-truth.py):

dotnet run --project tools/omniread-benchmark -c Release -- --scale 2 --out C:\Temp\omniread-benchmark   # add --vlm for the vision model

Azure and Google take part when DOCVIEW_AZURE_ENDPOINT and DOCVIEW_AZURE_KEY, or DOCVIEW_GOOGLE_CREDENTIALS (path to the service account JSON), are set.

Database changes

Every schema change is an EF Core migration. The apps apply migrations when they start (Database:InitializeOnStartup, default true).

When you change the model:

1. Add a migration to the Infrastructure project.
2. Give new columns defaults, or a data backfill in the migration, so existing databases upgrade cleanly.
3. Run the tests, which include migration tests.

Rules for contributors

• Clean architecture: references point inwards only. See Architecture and plugins.
• New engines, rules and connectors go behind the plugin interfaces.
• Use structured logging, and never swallow exceptions.
• Add unit tests for core logic.
• Never commit secrets. Use user secrets locally.
• Licences: only MIT, Apache 2.0, BSD, MS-PL, or dynamically linked LGPL packages. Never GPL or AGPL. Check the licence before you add any package and follow the internal licence process; the notices required by these licences ship in NOTICES.txt. Package versions are managed centrally in Directory.Packages.props.

Build a release

To build the release packages, see Releases and versioning.

Related pages

• Architecture and plugins
• Configuration reference
• Releases and versioning
• Install on a workstation