Services & Background Processes

DocuMan runs as four standard Windows services on your server. This page explains what each one does, how to check whether it's running, and how to start, stop, restart, or troubleshoot it. The services are registered with NSSM by the installer and managed exactly like any other Windows service.

What's Running on the Server

A typical DocuMan installation has the following moving parts. All of them install automatically — you do not need to set them up manually.

Display Name	Service Name	What It Does
JimRan DocuMan Web API	JimRanDocuManAPI	The core web server. Serves the browser UI on https://localhost, handles authentication, document uploads, search, permissions, and all REST API traffic. Everything else talks to this service.
JimRan DocuMan OCR Worker	JimRanDocuManOCR	Processes the OCR queue. When a document is uploaded, the API adds an OCR job. This worker picks jobs off the queue, runs them through Tesseract, and writes the extracted text back so it becomes searchable.
JimRan DocuMan AI Worker	JimRanDocuManAI	Processes AI filing jobs queued by the watch folder monitor. Sends document content to the configured AI connection (Ollama or cloud), parses the response, and places the suggested filing into the Review Queue.
JimRan DocuMan Watch Folders	JimRanDocuManWatcher	Polls every configured watch folder on its interval, picks up new files, and imports them into the correct cabinet/folder. Responsible for both standard and AI watch folders. See Watch Folders and AI Watch Folders.

All four services depend on PostgreSQL and will not start until it is up. Two third-party services round out the picture:

Component	Type	What It Does
PostgreSQL	Third-party service (postgresql-x64-18)	The database that stores all DocuMan metadata, users, permissions, OCR text, audit logs, and queue state. Installed separately. If this is down, nothing else works — the four DocuMan services are configured to depend on it and will wait at boot until it is running.
Ollama (optional)	Third-party service	Runs self-hosted AI models for AI Watch Folders. Only required if you are using AI features with local models. See the Ollama setup steps in AI Watch Folders.

Quick Status Check with install_services.py

The fastest way to see whether all four services are running is to use the helper script that ships with DocuMan. From the install directory (typically C:\Program Files\JimRan DocuMan), open an administrator command prompt and run:

python service\install_services.py status

Output looks like this:

  ✓ JimRan DocuMan Web API: RUNNING
  ✓ JimRan DocuMan OCR Worker: RUNNING
  ✓ JimRan DocuMan AI Worker: RUNNING
  ✓ JimRan DocuMan Watch Folders: RUNNING

The same script also supports install and remove commands, but you should only use those when you have a specific reason — the official installer and uninstaller cover the normal cases.

Using the Windows Services Console

Every DocuMan service is a standard Windows service. You can manage them from services.msc, which is the authoritative source for start/stop behavior and auto-start configuration.

1. Open the Services console
   Press Win+R, type services.msc, and press Enter. Or open Task Manager, switch to the Services tab, and click Open Services.
2. Find the DocuMan services
   Click the Name column to sort alphabetically. Scroll to services beginning with JimRan DocuMan. You should see all four: JimRan DocuMan Web API, JimRan DocuMan OCR Worker, JimRan DocuMan AI Worker, and JimRan DocuMan Watch Folders.
3. Check status
   The Status column shows Running, blank (stopped), or Starting/Stopping. The Startup Type should be Automatic for all of them so they come up at boot.
4. Start, stop, or restart
   Right-click a service and choose Start, Stop, or Restart. Restart is a stop-then-start as a single operation.
5. Change startup type
   Right-click the service, choose Properties, and change Startup type to Automatic, Automatic (Delayed Start), Manual, or Disabled. The installer configures all four as Automatic with a hard dependency on postgresql-x64-18, so they won't start until PostgreSQL is up — you should rarely need to override this.
6. Review recovery options
   On the Properties dialog, the Recovery tab controls what Windows does if the service crashes. NSSM monitors the underlying Python process and restarts it automatically on failure. Do not change this unless you have a specific reason.

Managing Services from PowerShell

When you are remoting into the server, scripting a restart, or working from a deployment pipeline, PowerShell is the fastest path. Open PowerShell as administrator.

List all DocuMan services and their status

Get-Service -Name 'JimRanDocuMan*' | Format-Table Name, Status, StartType

Check a specific service

Get-Service -Name 'JimRanDocuManAPI'

Start / stop / restart

Start-Service   -Name 'JimRanDocuManAPI'
Stop-Service    -Name 'JimRanDocuManAPI'
Restart-Service -Name 'JimRanDocuManAPI'

Restart everything DocuMan

Get-Service -Name 'JimRanDocuMan*' | Restart-Service -Force

The -Force flag tells Windows to stop dependent services if any are tied to the service being restarted.

Change startup type

Set-Service -Name 'JimRanDocuManAPI' -StartupType Automatic

Wait for a service to be running (useful in scripts)

$svc = Get-Service -Name 'JimRanDocuManAPI'
$svc.WaitForStatus('Running', '00:01:00')

Managing Services with sc.exe

sc.exe is the classic Windows service controller. It is available on every Windows installation and does not require PowerShell.

sc query JimRanDocuManAPI
sc start JimRanDocuManAPI
sc stop  JimRanDocuManAPI
sc config JimRanDocuManAPI start= auto

Note the space after start= — that is required by sc.exe.

Log Files

Every DocuMan service writes its stdout and stderr streams to separate log files via NSSM. Logs are the first place to look when something is not working.

Default Log Locations

Logs live in the backend\logs\ folder under the install directory (typically C:\Program Files\JimRan DocuMan\backend\logs\). Each service produces a stdout file and a stderr file:

backend\logs\
  ├── jimrandocumanapi_stdout.log
  ├── jimrandocumanapi_stderr.log
  ├── jimrandocumanocr_stdout.log
  ├── jimrandocumanocr_stderr.log
  ├── jimrandocumanai_stdout.log
  ├── jimrandocumanai_stderr.log
  ├── jimrandocumanwatcher_stdout.log
  └── jimrandocumanwatcher_stderr.log

Application messages (request logs, queue activity, info-level traces) end up in _stdout.log. Crashes, tracebacks, and warnings end up in _stderr.log. When troubleshooting a service that won't start, the stderr file is almost always where the answer is.

Opening Logs Quickly

• Run dialog: Press Win+R, type "C:\Program Files\JimRan DocuMan\backend\logs", press Enter.
• PowerShell: Invoke-Item "C:\Program Files\JimRan DocuMan\backend\logs"

Tailing a Log Live

To watch a log in real-time as the service runs (the equivalent of tail -f):

Get-Content "C:\Program Files\JimRan DocuMan\backend\logs\jimrandocumanapi_stdout.log" -Wait -Tail 100

-Tail 100 shows the last 100 lines to give you context, and -Wait keeps the window open and appends new lines as the service writes them. Ctrl+C stops tailing.

Log Rotation

NSSM is configured to append to each log file rather than rotate, so the files grow over time. If they get too large, you can stop the service, rename or delete the file, and start the service again — NSSM will recreate the file on first write. There is no automatic retention; manage size manually or via a scheduled task if needed.

Restart Order & Dependencies

The four services have two relationships you should understand:

• All four depend on PostgreSQL (postgresql-x64-18). Windows enforces this at boot — the DocuMan services will not start until PostgreSQL reports running. Stopping PostgreSQL with -Force will cascade-stop all four DocuMan services.
• The API service is the hub. The OCR, AI, and Watcher workers talk to the API (or to the database directly). For a full restart, Restart-Service -Force on the wildcard handles everything, but if you are restarting by hand:

Clean Restart Sequence

1. Stop JimRan DocuMan Watch Folders.
2. Stop JimRan DocuMan AI Worker.
3. Stop JimRan DocuMan OCR Worker.
4. Stop JimRan DocuMan Web API.
5. (Optional) Confirm PostgreSQL is running: Get-Service postgresql-x64-18.
6. Start JimRan DocuMan Web API. Wait until it reports ready (tail jimrandocumanapi_stdout.log).
7. Start JimRan DocuMan OCR Worker.
8. Start JimRan DocuMan AI Worker.
9. Start JimRan DocuMan Watch Folders.

Stopping the workers first lets any in-flight jobs finish cleanly. Starting the API first gives the workers something to connect to. If you stop or start in a different order, nothing is permanently broken — workers retry their connections — but you may see short bursts of "connection refused" messages in the worker stderr logs during the gap.

Troubleshooting

A service will not start

1. Open the service's stderr log file (e.g., jimrandocumanapi_stderr.log) in backend\logs\ and read the last 50 lines. The root cause is almost always there.
2. Verify PostgreSQL is running: Get-Service postgresql-x64-18. If it's stopped, start it first — the DocuMan services depend on it and will not start without it.
3. Check the .env file in the DocuMan install directory for a bad database password or hostname.
4. Check that the service account has read/write access to the configured storage paths and the backend\logs\ directory.
5. Look in Windows Event Viewer → Windows Logs → Application and filter by source nssm for OS-level failures (missing DLL, permission denied, port already in use).

Browser shows "This site can't be reached" at https://localhost

1. Check the API service: Get-Service JimRanDocuManAPI. If it's stopped, start it (and check the stderr log for why it stopped).
2. If the API is running, check that nothing else is holding port 443: Get-NetTCPConnection -LocalPort 443.
3. If the certificate is expired or untrusted, you will see a warning rather than a connection failure — that is expected with the self-signed default cert. Proceed past the warning or install a proper certificate.

OCR jobs are piling up

1. Confirm the OCR worker is running: Get-Service JimRanDocuManOCR.
2. Open jimrandocumanocr_stderr.log. Look for Tesseract errors, missing language packs, or out-of-memory messages.
3. If the queue is simply backlogged, increase the Max Workers setting in Configuration.

Watch folder not importing files

1. Confirm the Watcher service is running: Get-Service JimRanDocuManWatcher.
2. Open jimrandocumanwatcher_stderr.log. Permission-denied errors on the source path are the most common cause.
3. Verify the DocuMan service account has read + delete permission on the source path (files are moved, not copied).
4. For UNC paths, make sure the service account is a domain account with network access to the share.

AI Watch Folder is not processing

1. Confirm the AI worker is running: Get-Service JimRanDocuManAI.
2. Open jimrandocumanai_stderr.log. Look for connection errors to Ollama or the cloud provider.
3. If using Ollama, run ollama list on the Ollama host to confirm the model is present.
4. Verify the AI connection's URL and model name in Administration → AI Connections match reality.

Old DocuMan* services still showing in services.msc

1. This means a pre-v26.4 install left orphan service registrations behind. Run python service\install_services.py install from the install directory as administrator — the installer will detect and remove the legacy unprefixed services.
2. If that does not clear them, manually delete each one with sc delete DocuManAPI (and the same for DocuManOCR, DocuManAI, DocuManWatcher) from an administrator prompt.

Uninstalling or Reinstalling Services

You should not need to manually register or unregister services — the installer handles this. If you need to fully remove DocuMan services (for example, to upgrade a corrupted installation), run the official uninstaller from Settings → Apps in Windows and then reinstall.

If you need to reinstall just the service registrations without touching the rest of the install (rare), run as administrator from the install directory:

python service\install_services.py remove
python service\install_services.py install

Manually removing a service with sc.exe delete is not recommended for current installs. It leaves configuration, log directories, and database connections in an inconsistent state. Always prefer the installer or the helper script above.

---

Back to: Documentation Overview • Related: Configuration, Watch Folders, AI Watch Folders