Bizdocs e-Signature in Docker

This workflow runs the Bizdocs e-signature service inside a Debian Docker container while keeping the Arch host clean. The host provides the smart card reader through pcscd and the container runs Bizdocs, GUI forwarding, Java, and signing tools. The normal browser on the host can sign documents through the Bizdocs local service.

Overview

• Use the Arch host only for Docker, X11 access, and pcscd.
• Use the Debian container for Bizdocs, GUI libraries, Java, and signing tools.
• Share the smart card reader with the container through /run/pcscd/pcscd.comm.
• Share documents and installers through ./work mounted as /work.
• Run Bizdocs inside the container and keep the host browser outside the container.
• Use network_mode: host so the host browser can reach the Bizdocs service on 127.0.0.1:2151.

Working result

The completed setup uses this chain. This confirms that signing can work from the normal host browser while Bizdocs runs inside the container.

Arch browser
-> http://127.0.0.1:2151
-> Bizdocs service inside Debian container
-> /run/pcscd/pcscd.comm from Arch host
-> ACS ACR39T / ACR39U reader
-> e-signature card
-> signed document

Install host packages

Install the low-level smart card stack on the Arch host. This keeps the reader support on the host and avoids installing the signing application directly on the host.

sudo pacman -S pcsclite ccid pcsc-tools xorg-xhost
sudo systemctl enable --now pcscd.service

Test the smart card reader on the host

Plug in the ACS reader and insert the card. pcsc_scan should detect the reader, card state, and ATR. Stop the command with Ctrl+C after confirming the card is visible.

pcsc_scan

A successful result shows the ACS reader and Card inserted. The reader may appear as ACR39T or ACR39U depending on the device firmware and driver reporting.

Create the workspace

Create one movable workspace for the compose file, installers, test PDFs, and signed outputs. The work folder is mounted into the container as /work.

mkdir -p ~/projects/esign/work
cd ~/projects/esign

Place the Bizdocs Debian package in the work folder.

ls work
# bizdocs-eimza_1.2.6_amd64.deb

Create compose.yaml

Use Debian as the container base. Host networking is used because the host browser must reach the Bizdocs local service. X11 is mounted so the Bizdocs GUI can open from the container.

nano compose.yaml

services:
  esign:
    image: debian:12
    container_name: esign
    network_mode: host
    stdin_open: true
    tty: true
    environment:
      - DISPLAY=${DISPLAY}
      - LIBGL_ALWAYS_SOFTWARE=1
    volumes:
      - /run/pcscd/pcscd.comm:/run/pcscd/pcscd.comm
      - /tmp/.X11-unix:/tmp/.X11-unix
      - ./work:/work
    working_dir: /work

Start the container

Start the container and enter it. The prompt changes to root inside the container. The /work folder inside the container maps to ./work on the host.

cd ~/projects/esign
docker compose up -d
docker exec -it esign bash

pwd
ls
cat /etc/os-release

Install container packages

Install tools for smart card testing, GUI forwarding, TLS certificates, and basic runtime support. iproute2 provides ss for checking the local Bizdocs service port.

apt update
apt install -y \
  pcsc-tools \
  opensc \
  ca-certificates \
  curl \
  wget \
  unzip \
  default-jre \
  file \
  iproute2 \
  libgl1 \
  libglx-mesa0 \
  libegl1 \
  libx11-6 \
  libxcursor1 \
  libxrandr2 \
  libxinerama1 \
  libxi6 \
  libxxf86vm1 \
  libxrender1 \
  libxext6 \
  libxfixes3 \
  libxkbcommon0 \
  libxkbcommon-x11-0 \
  libgtk-3-0 \
  libnss3 \
  libasound2 \
  x11-apps

update-ca-certificates

Test the reader inside the container

Run pcsc_scan inside the container. This proves that the container can reach the card through the host pcscd socket.

pcsc_scan

• Expected reader: ACS ACR39U ICC Reader or similar.
• Expected state: Card inserted.
• Expected card data: ATR is printed.
• Stop pcsc_scan with Ctrl+C after confirming detection.

Enable host GUI access

Run xhost on the Arch host, not inside the container. This allows the container to open GUI windows through the host X11 session.

xhost +local:docker

Then enter the container and test with xclock. If a small clock window opens, GUI forwarding is working.

docker exec -it esign bash
xclock

Install Bizdocs

Install the Bizdocs Debian package from the shared /work folder. The package installs the launcher under /opt/bizdocs-eimza.

cd /work
apt install -y ./bizdocs-eimza_1.2.6_amd64.deb

If dependencies are missing, fix broken dependencies and run the install command again.

apt --fix-broken install -y
apt install -y ./bizdocs-eimza_1.2.6_amd64.deb

Confirm the launcher exists.

ls -la /opt/bizdocs-eimza
file /opt/bizdocs-eimza/BIZdocs-eLauncher

Start Bizdocs

Run the Bizdocs launcher from inside the container. Wait until the GUI says the signature service is ready.

/opt/bizdocs-eimza/BIZdocs-eLauncher

• Expected GUI state: İmza servise hazır.
• Bizdocs may update itself on first launch.
• Keep the Bizdocs window open while signing from the browser.

Check the local signing service

With Bizdocs running, check that BIZdocs.Core listens on the local service port.

ss -lntp

Expected service:

127.0.0.1:2151 users:(("BIZdocs.Core",pid=...,fd=...))

From the Arch host, test the same port. A 404 response is acceptable because the root path is not the signing endpoint. The important part is that the connection is not refused.

curl http://127.0.0.1:2151
# 404 page not found

Sign from the host browser

Use the normal browser on the Arch host. The browser talks to the Bizdocs local service through 127.0.0.1:2151 while Bizdocs runs inside the container.

• Start the container.
• Start Bizdocs inside the container.
• Wait until Bizdocs shows İmza servise hazır.
• Open the signing page in the host browser.
• Start the signing operation.
• Choose the certificate and enter the PIN if requested.
• Confirm that the signed document is completed.

TLS certificate fix

If Bizdocs fails while downloading the signing package and shows x509: certificate signed by unknown authority, update the container certificate store and restart Bizdocs.

apt install -y ca-certificates curl
update-ca-certificates

curl -I https://example-signing-domain.com

If curl returns HTTP 200 or another valid HTTP response, restart Bizdocs and retry signing.

pkill -f BIZdocs || true
pkill -f BIZdocs.Core || true
pkill -f BIZdocs-eLauncher || true

/opt/bizdocs-eimza/BIZdocs-eLauncher

Daily start and stop

Use this daily flow after the setup is complete. docker compose stop keeps the installed Bizdocs files inside the container.

cd ~/projects/esign
docker compose up -d
docker exec -it esign bash
/opt/bizdocs-eimza/BIZdocs-eLauncher

After signing is complete, exit the container shell and stop the container.

exit
docker compose stop

Stop versus down

Use stop for normal daily use. Use down only when you intentionally want to remove and recreate the container.

Useful checks

# Host: check running containers
docker ps

# Host: enter the container
docker exec -it esign bash

# Container: confirm Debian base
cat /etc/os-release

# Container: confirm smart card access
pcsc_scan

# Container: confirm Bizdocs service port
ss -lntp | grep 2151

# Host: confirm browser can reach Bizdocs service
curl http://127.0.0.1:2151

# Container: check Bizdocs files
ls -la /opt/bizdocs-eimza

# Container: check Bizdocs logs
ls -la /opt/bizdocs-eimza/logs
tail -n 100 /opt/bizdocs-eimza/logs/* 2>/dev/null

Workspace layout

Keep the workspace simple and movable. The work folder is safe because it is stored on the host.

~/projects/esign/
|-- compose.yaml
`-- work/
    |-- bizdocs-eimza_1.2.6_amd64.deb
    |-- input-documents
    `-- signed-output

Notes

• The ACS reader may be shown as ACR39U even when the physical model is ACR39T.
• A 404 response from http://127.0.0.1:2151 is acceptable for the root path.
• The real signing page calls a specific Bizdocs endpoint, not the root path.
• If xclock opens, the container GUI layer is working.
• If pcsc_scan works inside the container, the card reader layer is working.
• If Bizdocs says İmza servise hazır, the local signing service is ready.
• Keep the Bizdocs window open while signing from the browser.
• Run xhost -local:docker after finishing if local Docker GUI access should be revoked.

xhost -local:docker