---
title: "Signing Lacuna Signer documents with Docker on Ubuntu 24.04"
description: "Procedure for deploying Bulk Signer as one Docker container on an Ubuntu 24.04 virtual machine, with a local SQLite database and a PFX certificate, and for signing documents created in a Lacuna Signer folder with the SignerFolder method; with optional HTTPS through nginx, the Signer:WebhookSecret webhook and Microsoft Entra ID sign-in."
canonical: "https://docs.lacunasoftware.com/en-us/articles/bulk-signer/docker-ubuntu-signer-folder"
locale: "en"
product: "Bulk Signer"
last_updated: "2026-11-17"
---

# Signing Lacuna Signer documents with Docker on Ubuntu 24.04

This page specifies a single-instance deployment of Bulk Signer on one Ubuntu 24.04 LTS virtual machine
that signs documents created in **Lacuna Signer**. A user or the API creates a document in a Signer folder
bound to a Bulk Signer signing profile; Bulk Signer signs it with the organization's certificate, whose
private key is held in a **PFX file on the virtual machine**, and Signer stores the signed document. The
deployment consists of:

- the Bulk Signer container image, running as **one** Docker container managed by Docker Compose;
- the operational store in a local **SQLite** database, on the virtual machine's disk;
- the signing certificate in a **PFX file**, mounted read-only into the container;
- a signing profile that uses the
  [`SignerFolder` method](https://docs.lacunasoftware.com/en-us/articles/bulk-signer/lacuna-signer#signing-in-a-lacuna-signer-folder--signerfolder), declared in the
  configuration and imported on the first boot.

Three parts are optional and independent of the signing itself: [HTTPS through nginx](https://docs.lacunasoftware.com/en-us/articles/bulk-signer/docker-ubuntu-signer-folder#https), which the
other two require; the [`Signer:WebhookSecret` webhook](https://docs.lacunasoftware.com/en-us/articles/bulk-signer/docker-ubuntu-signer-folder#webhook), through which Signer notifies Bulk
Signer of new documents; and [Microsoft Entra ID sign-in](https://docs.lacunasoftware.com/en-us/articles/bulk-signer/docker-ubuntu-signer-folder#entra-id) for operators.

The general Docker installation, for file signing, is specified in
[Installation](https://docs.lacunasoftware.com/en-us/articles/bulk-signer/installation#docker--compose). The same Lacuna Signer integration on Amazon Web Services
is specified in [Amazon ECS Fargate + Lacuna Signer](https://docs.lacunasoftware.com/en-us/articles/bulk-signer/aws-signer-folder).

> **Info: Minimum version: 2.16.0**
>
> The `SignerFolder` method and the `Signer:WebhookSecret` key were introduced in 2.16.0. Earlier images
> refuse the configuration on this page at boot.

> **Danger: Single-instance constraint**
>
> One Bulk Signer instance per Lacuna Signer folder. A second container, or a second virtual machine, bound
> to the same folder is not supported. A deployment that requires more than one instance must use
> [Azure App Service (cluster mode)](https://docs.lacunasoftware.com/en-us/articles/bulk-signer/azure).

## Architecture

[![Signing in a Lacuna Signer folder with Docker on Ubuntu: a user or the API creates a document at Signer; the container finds it by the sweep or the optional webhook, signs with the PFX's key and returns the signature to Signer](https://docs.lacunasoftware.com/images/bulk-signer/docker-ubuntu-signer-folder-architecture.svg)](https://docs.lacunasoftware.com/images/bulk-signer/docker-ubuntu-signer-folder-architecture.svg)

### Connections

| Direction | Content | Credential |
|---|---|---|
| Container → Signer | The sweep, the read-back of each document, and the start and completion of each signature | `Signer:ApiKey`, sent as `X-Api-Key` |
| Signer → nginx → container | The webhook, when configured: `POST https://<host>/api/signer/notifications` | `Signer:WebhookSecret`, sent as `Authorization: Bearer` |
| Operator → nginx → container | The dashboard and the REST API | `Auth:ApiKey`, or a Microsoft Entra ID session |
| Virtual machine → Lacuna's registry | The image download | The registry credentials issued by Lacuna |

Every connection to Signer starts from the virtual machine, except the webhook. Without the webhook, the
virtual machine needs no inbound access from the internet.

### Differences from file signing

| Aspect | Behaviour with the `SignerFolder` method |
|---|---|
| Document content | No file passes through Bulk Signer. Signer sends the hash to sign, the container signs it with the PFX's private key, and Signer builds the signature into the document and stores it. Nothing enters a watched folder and nothing is written to `output/`. The signed document is downloaded from Signer. |
| Identification of the holder | Signer matches the participant of the document to the CPF contained in the profile's certificate. The certificate must therefore be an ICP-Brasil **e-CPF** or **e-CNPJ** (which contains the CPF of its responsible person). |
| Signature format | Signer selects the format: PAdES for a PDF, XAdES for XML, CAdES for any other type. The profile's own format setting is ignored. |
| Discovery | A sweep every `Signer:FolderSweepIntervalSeconds` (60 seconds on this page). With the webhook, within seconds. The sweep remains the delivery guarantee: a document is delayed, never lost. |

## Prerequisites

| Requirement | Specification |
|---|---|
| Virtual machine | **Ubuntu 24.04 LTS**, 64-bit x86 (`amd64`), with `sudo`. Outbound HTTPS to `download.docker.com`, to Lacuna's registry and to the Lacuna Signer instance. |
| Registry credentials | The credentials Lacuna issued for the container image, and the registry host, image path and version. See [Obtaining the product](https://docs.lacunasoftware.com/en-us/articles/bulk-signer/installation#obtaining-the-product). |
| Licence | The **PKI SDK licence**. See [Obtaining the PKI SDK license](https://docs.lacunasoftware.com/en-us/articles/bulk-signer/installation#obtaining-the-pki-sdk-license). |
| Lacuna Signer organization | An **organization** on a Lacuna Signer instance. Registering the webhook requires a user with the organization administrator role. |
| Lacuna Signer API key | An **API key** of that organization (step 1.2). |
| Signing material | The **PFX** file of an ICP-Brasil **e-CPF** or **e-CNPJ** certificate, and its password. A certificate that contains no CPF leaves the profile degraded. |
| Holder identification | The **CPF** contained in the certificate. Documents must name the holder as a participant with exactly that CPF. |
| HTTPS (optional) | A **hostname** that resolves to the virtual machine, inbound TCP **80** and **443**, and write access to its DNS zone. Required by the webhook and by Entra ID. |
| Microsoft Entra ID (optional) | A tenant, and an account with the **Cloud Application Administrator** role or higher. |

### Shell variables

All commands on this page run in one shell session on the virtual machine, initialised with the following
variables:

```bash
REGISTRY=<Lacuna registry host>
REPOSITORY=<image path in the registry>
VERSION=<version>
SIGNER=https://<Lacuna Signer address>
HOST=bulksigner.example.com           # the public hostname; HTTPS section only
DIR=/opt/bulksigner
```

| Variable | Content |
|---|---|
| `REGISTRY` | The registry host only, for example `<name>.azurecr.io`. It is the argument of `docker login`, which does not accept a path. |
| `REPOSITORY` | The image's path inside the registry, for example `lacuna/bulksigner`. |
| `VERSION` | The version to install, for example `2.20.1`. Use an explicit version, not `latest`. |
| `SIGNER` | The address of the Lacuna Signer API (step 1.1), without a trailing slash. |
| `HOST` | The public hostname of the deployment. Used only from the [HTTPS](https://docs.lacunasoftware.com/en-us/articles/bulk-signer/docker-ubuntu-signer-folder#https) section on. |
| `DIR` | The installation directory. Every file of the deployment is under it. |

## 1. Lacuna Signer preparation

### 1.1 API address

`SIGNER` is the address on which the Signer instance's API responds, which is not necessarily the address
of the product's home page. Without a key, the API returns `401`:

```bash
curl -s -o /dev/null -w '%{http_code}\n' $SIGNER/api/documents      # 401
```

### 1.2 API key

Create an application in the organization and generate its key, as specified in
[step 1 of Getting started with the Signer API](https://docs.lacunasoftware.com/en-us/articles/signer/get-started#step-1-create-the-application-and-the-api-key).

| Property | Specification |
|---|---|
| Access to the **Applications** menu | Restricted to the instance's system administrator. Without that access, request a key of the organization from the administrator of the Signer instance. |
| Format | `<application>\|<secret>`. The application part may contain spaces. |
| Display | The key is displayed once, when it is created. |
| Scope | The organization in which it was created. The container reads documents with this key. |
| Required access | A role that grants access to the folders and documents of the organization. |

Read the key into the shell from a prompt that does not echo. Step 4 writes it to the configuration:

```bash
read -rsp 'Lacuna Signer API key: ' SIGNER_API_KEY; echo
```

### 1.3 Folder

In **Folders**, select the organization and create a folder with the **New folder** icon.

| Rule | Specification |
|---|---|
| Binding | One-to-one. Two profiles cannot share a folder. |
| Scope | The folder itself. A document in one of its subfolders is not signed. |

The profile on this page is declared in the configuration, which names the folder by its **ID**. List the
organization's folders with the API key:

```bash
curl -s -H "X-Api-Key: $SIGNER_API_KEY" $SIGNER/api/folders | jq -r '.items[] | "\(.id)  \(.name)"'
```

Each line shows a folder's ID and its name. The response is the first page of the listing; in an
organization with many folders, locate the folder by name. Keep the ID and the name:

```bash
FOLDER_ID=<the folder's ID>
FOLDER_NAME=<the folder's name>
```

`jq` is installed in step 2. Run this command after it, or read the ID from the same response without `jq`.

### 1.4 PDF signature policy

Whether a PDF signed with an ICP-Brasil certificate receives the ICP-Brasil policy (AD-RB) or a basic
PAdES signature is determined by Signer's `UseBrazilianPdfSigningPolicies` setting, not by Bulk Signer.
The setting belongs to the Signer instance:

| Signer instance | Where the setting is defined |
|---|---|
| On-premises | In the instance's [settings](https://docs.lacunasoftware.com/en-us/articles/signer/on-premises/settings). |
| Lacuna's cloud | By Lacuna. Request confirmation of the value in effect. |

Define the policy before the first document is signed.

## 2. Docker Engine

Install Docker Engine and the Compose plugin from Docker's apt repository, as specified in
[Install Docker Engine on Ubuntu](https://docs.docker.com/engine/install/ubuntu/), together with `jq`:

```bash
sudo apt update
sudo apt install -y ca-certificates curl jq
sudo install -m 0755 -d /etc/apt/keyrings
sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc
sudo chmod a+r /etc/apt/keyrings/docker.asc

sudo tee /etc/apt/sources.list.d/docker.sources > /dev/null <<EOF
Types: deb
URIs: https://download.docker.com/linux/ubuntu
Suites: $(. /etc/os-release && echo "${UBUNTU_CODENAME:-$VERSION_CODENAME}")
Components: stable
Architectures: $(dpkg --print-architecture)
Signed-By: /etc/apt/keyrings/docker.asc
EOF

sudo apt update
sudo apt install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
sudo systemctl enable --now docker
sudo docker compose version
```

Every `docker` command on this page runs with `sudo`.

> **Warning: Docker bypasses ufw**
>
> A port that Docker publishes is reachable even when `ufw` denies it: Docker writes its own packet-filter
> rules. Restrict access to port 8080 with the network or cloud firewall, or publish it on `127.0.0.1` only,
> as the [HTTPS](https://docs.lacunasoftware.com/en-us/articles/bulk-signer/docker-ubuntu-signer-folder#https) section does.

## 3. The image

```bash
sudo docker login $REGISTRY --username <registry-username>     # prompts for the token
sudo docker pull $REGISTRY/$REPOSITORY:$VERSION
```

The credential is stored in `/root/.docker/config.json`. The repository is private: a pull without
`docker login` answers `authentication required`.

## 4. Configuration

Every file of the deployment is under `$DIR`:

| File | Content |
|---|---|
| `docker-compose.yml` | The container, its mounts and its network. |
| `.env` | The secrets, as environment variables. Readable by root only. |
| `config/appsettings.Production.json` | The signing profile and the Signer connection. Contains no secret. |
| `config/signing.pfx` | The certificate and its private key. |
| `data/` | The SQLite database and the session key ring. |
| `logs/` | The log files, one per day. |

```bash
sudo mkdir -p $DIR/config $DIR/data $DIR/logs
cd $DIR
```

### 4.1 The compose file

```bash
sudo tee docker-compose.yml > /dev/null <<EOF
services:
  bulksigner:
    image: $REGISTRY/$REPOSITORY:$VERSION
    container_name: bulksigner
    restart: unless-stopped
    ports:
      - "8080:8080"
    volumes:
      - ./data:/var/lib/bulksigner
      - ./logs:/var/log/bulksigner
      - ./config/appsettings.Production.json:/app/appsettings.Production.json:ro
      - ./config/signing.pfx:/etc/bulksigner/signing.pfx:ro
    env_file:
      - .env
    networks:
      - bulksigner

networks:
  bulksigner:
    ipam:
      config:
        - subnet: 172.30.0.0/24
EOF
```

| Element | Specification |
|---|---|
| `image` | The version from `VERSION`. An upgrade changes this line ([Operations](https://docs.lacunasoftware.com/en-us/articles/bulk-signer/docker-ubuntu-signer-folder#day-two)). |
| `ports` | Plain HTTP on 8080. The [HTTPS](https://docs.lacunasoftware.com/en-us/articles/bulk-signer/docker-ubuntu-signer-folder#https) section restricts it to `127.0.0.1`. |
| `./data` | The SQLite database (`db/`) and the session key ring (`keys/`). Without this mount, every replacement of the container loses the job history and signs every operator out. |
| `./config/signing.pfx` | Read at every boot. It must remain at this path for as long as the profile uses it. |
| `networks` | A fixed subnet, so that the [HTTPS](https://docs.lacunasoftware.com/en-us/articles/bulk-signer/docker-ubuntu-signer-folder#https) section can trust forwarded headers from this network only. If `172.30.0.0/24` is in use on the virtual machine, choose another private range and use it in both places. |

The image's own health check polls `/api/health` every 30 seconds.

### 4.2 The secrets

Read the values that a person types from prompts that do not echo, and generate the others:

```bash
read -rsp 'PKI SDK licence: ' LICENSE; echo
read -rsp 'PFX password: ' PFX_PASSWORD; echo

sudo install -m 600 /dev/null .env
sudo tee .env > /dev/null <<EOF
Signing__PkiSdkLicense='$LICENSE'
Signing__ProfileSecretsKey='$(openssl rand -base64 36)'
Signing__Profiles__0__Certificate__Pfx__Password='$PFX_PASSWORD'
Signer__ApiKey='$SIGNER_API_KEY'
Auth__ApiKey='$(openssl rand -hex 24)'
EOF
unset LICENSE PFX_PASSWORD
```

| Variable | Description |
|---|---|
| `Signing__PkiSdkLicense` | The PKI SDK licence. |
| `Signing__ProfileSecretsKey` | Encrypts the PFX password in the database. The profile is stored in the database ([Configuration](https://docs.lacunasoftware.com/en-us/articles/bulk-signer/configuration#signingprofilesecretskey--what-stored-profile-secrets-are-encrypted-under)), and the import on the first boot refuses to store a password without this key. |
| `Signing__Profiles__0__Certificate__Pfx__Password` | The PFX password, imported into the profile on the first boot. |
| `Signer__ApiKey` | Sent as `X-Api-Key` on every call to Signer. |
| `Auth__ApiKey` | The dashboard's sign-in key and the REST API's `X-API-Key`. At least 16 characters. |

The values are enclosed in single quotes so that Docker Compose does not interpret a `$`, a space or a `|`
in them. A value that itself contains a single quote must be edited in the file by hand.

> **Danger: Store Signing__ProfileSecretsKey outside the virtual machine**
>
> Copy it to the password manager now: `sudo grep ^Signing__ProfileSecretsKey= .env`. Without it, the stored
> PFX password cannot be decrypted, the profile is degraded, and its certificate must be configured again.
> There is no recovery.

### 4.3 The settings

```bash
sudo tee config/appsettings.Production.json > /dev/null <<EOF
{
  "Signing": {
    "Profiles": [
      {
        "Name": "signer-folder",
        "Format": "Pades",
        "Method": "SignerFolder",
        "Verify": false,
        "ValidateCertificate": false,
        "SignerFolder": { "Id": "$FOLDER_ID", "Name": "$FOLDER_NAME" },
        "Certificate": {
          "Source": "Pfx",
          "Pfx": { "Path": "/etc/bulksigner/signing.pfx" }
        }
      }
    ]
  },
  "Signer": {
    "Endpoint": "$SIGNER",
    "FolderSweepIntervalSeconds": 60
  }
}
EOF
```

| Setting | Specification |
|---|---|
| `Signing:Profiles[0]` | The **seed** (initial load) of the signing profile, imported on the first boot against an empty database only. From then on the profile is stored in the database and edited on its page in the dashboard; a later change to this section is reported as ignored at boot. No `default` profile is created. |
| `Name` | `signer-folder`. It cannot be `default`, and it cannot be changed after the import. |
| `Format` | Required by the configuration, ignored by the method: Signer selects the format. |
| `Verify`, `ValidateCertificate` | Must be `false`; both default to `true`. Signer validates the certificate and the signature. |
| `SignerFolder:Id` | The folder from step 1.3. `Name` is shown on the profile's page only. |
| `Signer:Endpoint` | The address of the Signer API. With `Signer:ApiKey`, required as soon as any key under `Signer:` is set. |
| `Signer:FolderSweepIntervalSeconds` | The interval between listings of the folder, from 60 to 86400 seconds; the default is 300. 60 suits a deployment without the webhook. With the webhook, the default suffices. |

The complete specification of these keys is in
[Configuration](https://docs.lacunasoftware.com/en-us/articles/bulk-signer/configuration#signing-in-a-lacuna-signer-folder--method--signerfolder).

### 4.4 The certificate and the permissions

The PFX has to be on the virtual machine. Copy it from the workstation that holds it, for example with
`scp <file>.pfx <user>@<virtual machine>:`.

The container runs as the user with ID **1654**, not as root:

```bash
sudo cp <path to the PFX> config/signing.pfx
sudo chown -R 1654:1654 data logs config/signing.pfx
sudo chmod 0400 config/signing.pfx
```

Check the password of step 4.2 against the file before the first boot:

```bash
sudo openssl pkcs12 -in config/signing.pfx -noout -legacy      # prompts for the PFX password
```

A password that opens the file produces no output. `Mac verify error: invalid password?` means a wrong
password or a different file. The password in `.env` is imported into the database on the first boot
only; after it, correcting `.env` has no effect ([Error reference](https://docs.lacunasoftware.com/en-us/articles/bulk-signer/docker-ubuntu-signer-folder#when-something-refuses)).

## 5. Start and verification

```bash
sudo docker compose up -d
sudo docker compose logs -f bulksigner        # Ctrl+C stops following; the container keeps running
```

The first boot creates the database, imports the profile (`Imported 1 signing profile into the
operational store from Signing:Profiles.`) and ends with the **Service ready** summary. The following
warnings (`[WRN]`) are expected and do not indicate a problem:

| Warning | When | Reason |
|---|---|---|
| `Watched folder 'default' is unassigned` | Every boot | No profile takes files from a watched folder. |
| `The migration operation 'PRAGMA foreign_keys = 0;' … cannot be executed in a transaction` | The first boot | Entity Framework reports a migration that cannot run in a transaction. |
| `No XML encryptor configured` | The first boot, and whenever a new session key is created | The session key ring is written to `data/keys` without an encryption of its own, which Linux does not offer. |
| `Overriding HTTP_PORTS '8080' and HTTPS_PORTS ''` | Every boot | The image sets `ASPNETCORE_URLS`, which takes precedence over the base image's default port. Both values are port 8080. |
| `The query uses the 'First'/'FirstOrDefault' operator without 'OrderBy'` | Every boot, on 2.20.1 | An Entity Framework warning about an internal query. |

On later boots, the profile import is replaced by `Signing:Profiles names 1 profile(s) and is being
ignored` (step 4.3).

```bash
KEY=$(sudo grep ^Auth__ApiKey= .env | cut -d= -f2- | tr -d "'")
curl -s http://localhost:8080/api/health
curl -s -H "X-API-Key: $KEY" http://localhost:8080/api/profiles/signer-folder | jq '{name, method, degraded}'
curl -s -H "X-API-Key: $KEY" http://localhost:8080/api/ready/details | jq '.checks[] | {name, ok, detail}'
```

| Check | Expected result |
|---|---|
| `/api/health` | `"status":"healthy"` |
| The profile | `"method": "SignerFolder"`, `"degraded": false` |
| `signer-folder-sweep` | `ok: true`. The first pass runs at boot: `the last pass at this instance finished without a failure at …` |
| `signer-notifications` | `not accepted (Signer:WebhookSecret is not set)` until the [webhook](https://docs.lacunasoftware.com/en-us/articles/bulk-signer/docker-ubuntu-signer-folder#webhook) is configured. |
| `pki-license` | `loaded` |

The reason a profile is degraded is shown on its page in the dashboard (**This profile cannot sign**) and
in the `signing-profile:signer-folder` check of `/api/ready/details`. The usual reasons are a certificate
without a CPF and a folder that does not exist in Signer.

## 6. Signing test

In Lacuna Signer:

1. Select **New document**, upload a PDF, and select the organization and **the bound folder**.
2. Add the certificate holder as a participant of type **Signer**, with the name, the **CPF contained in
   the certificate** and the e-mail address. The holder can be the only participant or follow other
   participants; the container acts only when the pending action is the holder's.
3. Select **Send**.

Within the sweep interval, or within seconds with the webhook, the dashboard's **Jobs** page
(`http://<virtual machine>:8080/jobs`) lists a job with the document's name, under the `signer-folder`
profile. The job passes through the following states:

| State | Meaning |
|---|---|
| **Queued** | The document was detected and the job was created. |
| **Processing** | The container read the document back, started the signature and signed the hash with the PFX's key. |
| **Verifying** | The signature was handed to Signer, which validates it and builds it into the document. |
| **Completed** | Signer accepted the signature. |

In Lacuna Signer, the holder's action is concluded and the document contains the signature. From the
command line:

```bash
curl -s -H "X-API-Key: $KEY" "http://localhost:8080/api/jobs?profile=signer-folder" | jq
curl -s -H "X-API-Key: $KEY" http://localhost:8080/api/metrics | grep bulksigner_signer_folder_signatures_total
```

`bulksigner_signer_folder_signatures_total{outcome="signed"}` increases once per signature accepted by
Signer. The deployment is complete at this point; the following three sections are optional.

## HTTPS through nginx (optional)

Bulk Signer listens on plain HTTP. nginx on the same virtual machine terminates TLS with a Let's Encrypt
certificate and forwards to the container, which becomes reachable from the virtual machine only.

**1. DNS and firewall.** Create an `A` record for `$HOST` with the virtual machine's public address, and
admit inbound TCP 80 and 443 in the network or cloud firewall. Let's Encrypt validates the name on port 80.

**2. Publish the container on the loopback interface and trust the proxy.** nginx connects through the
published port, and the container sees the connection arrive from the gateway of the network of
step 4.1. [`Hosting:ForwardedHeaders`](https://docs.lacunasoftware.com/en-us/articles/bulk-signer/configuration#hosting) makes Bulk Signer read the original scheme
and client address from nginx's headers, from that network only:

```bash
sudo sed -i 's/"8080:8080"/"127.0.0.1:8080:8080"/' docker-compose.yml
sudo tee -a .env > /dev/null <<'EOF'
Hosting__ForwardedHeaders__Enabled=true
Hosting__ForwardedHeaders__KnownNetworks__0=172.30.0.0/24
EOF
sudo docker compose up -d
```

| Setting | Effect |
|---|---|
| `127.0.0.1:8080:8080` | Port 8080 is no longer reachable from outside the virtual machine, whatever `ufw` says. |
| `Hosting__ForwardedHeaders__Enabled` | Reads `X-Forwarded-Proto` and `X-Forwarded-For`. Without it, Bulk Signer sees `http`, and the Entra ID sign-in builds an `http://` redirect URI that Microsoft refuses. |
| `Hosting__ForwardedHeaders__KnownNetworks__0` | Trusts forwarded headers from the network of step 4.1 only. It must equal the `subnet` of the compose file. |

Do not set `ASPNETCORE_FORWARDEDHEADERS_ENABLED` as well: setting both is refused at boot.

**3. Install nginx and Certbot:**

```bash
sudo apt install -y nginx certbot python3-certbot-nginx
```

**4. The site.** The dashboard keeps a WebSocket connection open, which requires the `Upgrade` and
`Connection` headers:

```bash
sudo tee /etc/nginx/sites-available/bulksigner > /dev/null <<EOF
map \$http_upgrade \$connection_upgrade {
    default upgrade;
    ''      close;
}

server {
    listen 80;
    server_name $HOST;
    client_max_body_size 10m;

    location / {
        proxy_pass         http://127.0.0.1:8080;
        proxy_http_version 1.1;
        proxy_set_header   Host              \$host;
        proxy_set_header   X-Forwarded-For   \$proxy_add_x_forwarded_for;
        proxy_set_header   X-Forwarded-Proto \$scheme;
        proxy_set_header   Upgrade           \$http_upgrade;
        proxy_set_header   Connection        \$connection_upgrade;
        proxy_read_timeout 300s;
    }
}
EOF
sudo ln -s /etc/nginx/sites-available/bulksigner /etc/nginx/sites-enabled/
sudo rm -f /etc/nginx/sites-enabled/default
sudo nginx -t && sudo systemctl reload nginx
```

**5. The certificate.** Certbot obtains it, adds the HTTPS listener and the redirect from HTTP to the site,
and installs its renewal:

```bash
sudo certbot --nginx -d $HOST
```

**6. Verification:**

```bash
curl -s https://$HOST/api/health
```

The response is `"status":"healthy"`. From another machine, `http://<virtual machine>:8080` no longer
connects. The dashboard is at `https://$HOST/`.

## The webhook in Lacuna Signer (optional)

Without the webhook, a document waits for the next sweep, up to `Signer:FolderSweepIntervalSeconds`. With
it, Signer calls `POST https://$HOST/api/signer/notifications` when a document is created, signed or
approved, and the document is signed within seconds. The notification identifies which document to read;
no other content of it is trusted, and the document is read back from Signer with `Signer:ApiKey` before a
job is created. Requires the [HTTPS](https://docs.lacunasoftware.com/en-us/articles/bulk-signer/docker-ubuntu-signer-folder#https) section.

**1. The secret.** At least 32 characters, without leading or trailing whitespace:

```bash
echo "Signer__WebhookSecret='$(openssl rand -hex 32)'" | sudo tee -a .env > /dev/null
sudo docker compose up -d
curl -s -o /dev/null -w '%{http_code}\n' -X POST https://$HOST/api/signer/notifications    # 401
```

`401` means the route is enabled and requires the token. `404` means the container did not receive the
secret.

**2. Registration.** Display the secret to copy it, then clear the screen:

```bash
sudo grep ^Signer__WebhookSecret= .env | cut -d= -f2- | tr -d "'"
```

In Lacuna Signer, signed in as an administrator of the organization:

1. Open **Organizations** and select the organization.
2. In the **Integration** section, below the **Webhooks** card, select the **+** button. A new
   **Webhook N** panel opens. An existing webhook of another system is not affected.
3. Fill in the fields as specified below, and select **Save**.

| Field | Value | Requirement |
|---|---|---|
| **URL** | `https://<host>/api/signer/notifications` | The scheme must be `https`: the HTTP listener responds with a redirect, and a redirected `POST` delivers no notification. |
| **Authentication type** | **Bearer** | **X-Api-Key** must not be used. That header is Bulk Signer's own REST credential, and a notification that presents it is refused. |
| **Authentication Token** | The value of `Signer__WebhookSecret` | Without the word `Bearer`. Signer adds the prefix. |

Signer delivers every event of the organization to every webhook of the organization. Bulk Signer acts on
`DocumentsCreated`, `DocumentSigned` and `DocumentApproved` and answers every other event `204`. Signer
retries a delivery that does not receive a `2xx` response ([Webhooks](https://docs.lacunasoftware.com/en-us/articles/signer/webhooks)).

**3. Verification.** Create a document as in [step 6](https://docs.lacunasoftware.com/en-us/articles/bulk-signer/docker-ubuntu-signer-folder#sign-a-document). It is signed within seconds, and
the `signer-notifications` check reports `accepted; the last arrived at this instance at <time>`. With the
webhook in place, `Signer__FolderSweepIntervalSeconds` can return to the default of 300.

## Microsoft Entra ID sign-in (optional)

By default the dashboard's sign-in page asks for `Auth__ApiKey`. With an `Auth:EntraId` section it offers
**Sign in with Microsoft** instead, and two app roles control access: **Administrator** for the operator
dashboard and **Approver** for the approver pages
([Configuration](https://docs.lacunasoftware.com/en-us/articles/bulk-signer/configuration#authentraid--optional-microsoft-entra-id-sign-in)). This deployment uses
**Administrator** only. Requires the [HTTPS](https://docs.lacunasoftware.com/en-us/articles/bulk-signer/docker-ubuntu-signer-folder#https) section: Microsoft accepts only an `https` redirect
URI for a host other than `localhost`.

| Effect | Specification |
|---|---|
| The API-key sign-in form | Removed from the sign-in page. |
| The REST API's `X-API-Key` | Unchanged. `Auth__ApiKey` remains required. |
| Sessions created with the API key | Stop working when the container restarts with the section. |
| Sign-out | Ends the Bulk Signer session only. The Microsoft session remains. |

**1. The app registration.** Give the environment its own registration.
[`New-BulkSignerEntraApp.ps1`](https://docs.lacunasoftware.com/en-us/articles/bulk-signer/samples#powershell-7--new-bulksignerentraappps1), run from any
workstation with PowerShell 7, creates a single-tenant registration with the redirect URI
`https://<host>/signin-oidc`, the two app roles, the `email` claim, and an enterprise application with
**Assignment required**:

```powershell
pwsh ./New-BulkSignerEntraApp.ps1 -BaseUrl https://<host> -DisplayName "Lacuna Bulk Signer"
```

At the end the script prints, once, the `Auth__EntraId__TenantId`, `Auth__EntraId__ClientId` and
`Auth__EntraId__ClientSecret` block. To create the registration by hand instead, follow
[Microsoft Entra ID sign-in](https://docs.lacunasoftware.com/en-us/articles/bulk-signer/installation#microsoft-entra-id-sign-in-optional) in Installation.

**2. Assign people.** In the Entra admin center, under **Enterprise applications → the application →
Users and groups**, assign the **Administrator** app role to each operator. An account with no assignment
cannot sign in, and an account that authenticates with neither role is refused.

**3. The configuration.** The client secret is read from a prompt that does not echo:

```bash
read -rsp 'Client secret: ' VALUE; echo
sudo tee -a .env > /dev/null <<EOF
Auth__EntraId__TenantId='<the Auth__EntraId__TenantId value>'
Auth__EntraId__ClientId='<the Auth__EntraId__ClientId value>'
Auth__EntraId__ClientSecret='$VALUE'
EOF
unset VALUE
sudo nano .env          # replace the two placeholders
sudo docker compose up -d
```

The three keys are required together: a partially filled section stops the container at boot, and the log
names the missing key.

**4. Verification.** Follow the sign-in's first redirect without signing in:

```bash
curl -s -o /dev/null -w '%{redirect_url}\n' https://$HOST/api/auth/entra-login
```

The URL must point to `login.microsoftonline.com/<tenant>/oauth2/v2.0/authorize`, with the application ID
and `redirect_uri=https%3A%2F%2F<host>%2Fsignin-oidc`. The `https` scheme is the value to confirm: `http`
means the forwarded headers of the [HTTPS](https://docs.lacunasoftware.com/en-us/articles/bulk-signer/docker-ubuntu-signer-folder#https) section are not in effect.

| Item | Description |
|---|---|
| Client secret expiry | The script's default lifetime is twelve months. An expired secret fails only at sign-in, with an `AADSTS` error. Create a new secret in the registration, replace `Auth__EntraId__ClientSecret` in `.env`, and run `sudo docker compose up -d`. |
| Removal | Remove the three `Auth__EntraId__` lines from `.env` and run `sudo docker compose up -d`. The API-key sign-in returns. |

## Operations

Every command runs in `$DIR`. A change to `.env` or to the compose file takes effect with
`sudo docker compose up -d`, which recreates the container.

| Operation | Procedure | Notes |
|---|---|---|
| Upgrade | Back up, pause the pipeline (`POST /api/pipeline/pause`), wait until no job is `Processing` or `Verifying`, change the version on the `image:` line, run `sudo docker compose pull && sudo docker compose up -d`, and resume (`POST /api/pipeline/resume`). | Migrations run at boot. A container stopped during a signature requires the next boot to ask Signer how the job ended, and some of those jobs end `Failed` with `signer-folder.interrupted` ([Lacuna Signer integration](https://docs.lacunasoftware.com/en-us/articles/bulk-signer/lacuna-signer#when-the-run-signing-it-ends)). The sweep runs while the pipeline is paused. |
| Backup | `sudo docker compose stop`, then archive `data/`, `config/`, `.env` and `docker-compose.yml`, then `sudo docker compose start`. | The archive holds the certificate, its encrypted password and the key that decrypts it. Store it as the certificate itself, outside the virtual machine. |
| Webhook secret rotation | Replace `Signer__WebhookSecret` in `.env`, run `sudo docker compose up -d`, then enter the new value in the webhook in Signer. | Between the two changes, notifications are answered `401`; Signer retries them and the sweep detects the remaining documents. |
| Signer API key rotation | Create the new key in Signer, replace `Signer__ApiKey` in `.env`, run `sudo docker compose up -d`, and only then revoke the previous key. | With a revoked key, every sweep fails, and the `signer-folder-sweep` check fails after three consecutive failed passes. |
| Certificate renewal | Pause the pipeline. Replace `config/signing.pfx` (with the ownership and mode of step 4.4) and, if the password changed, enter it on the profile's page under **Edit certificate**. Restart with `sudo docker compose restart` and resume. | The certificate is read at boot. If the new certificate contains a **different CPF**, documents pending in Signer for the previous CPF have no action for the new holder; each is recorded once as `Failed` with `signer-folder.no-holder-action`. |
| Folder change | Save the new folder on the profile's page. | Takes effect without a restart. The `SignerFolder` section of `appsettings.Production.json` is not read again. |
| Removal | `sudo docker compose down`, remove the webhook in Signer, and `sudo docker logout $REGISTRY`. | `data/`, `config/` and `.env` remain in `$DIR` until deleted. |

## Error reference

| Code or message | Origin | Meaning | Resolution |
|---|---|---|---|
| `permission denied` on `/var/lib/bulksigner` or `/etc/bulksigner/signing.pfx` | Container log, at boot | The mounted directories or the PFX are not owned by UID 1654. | Repeat step 4.4. |
| `authentication required` on `docker pull` | Docker | No `docker login`. | Repeat step 3 with the credentials Lacuna issued. |
| `not found` on `docker pull` | Docker | A `REPOSITORY` or `VERSION` that does not exist, or credentials that cannot see the repository. | Check the shell variables and the credentials Lacuna issued. |
| `did not open with the PKCS#12 password given` (`IncorrectPinException`), with the profile degraded | Container log and the `signing-profile:signer-folder` check, at boot | The password does not open `config/signing.pfx`: a wrong password, or a different file. Correcting `.env` has no effect after the first boot, because the password has already been imported into the database. | Check with the `openssl` command of step 4.4. A wrong password: enter the correct one on the profile page, under **Edit certificate**, and run `sudo docker compose restart`. A wrong file: replace it as in Certificate renewal ([Operations](https://docs.lacunasoftware.com/en-us/articles/bulk-signer/docker-ubuntu-signer-folder#day-two)). |
| A log line that names `Signing:ProfileSecretsKey` | Container log, first boot | The import would store the PFX password without the key. | Set `Signing__ProfileSecretsKey` (step 4.2). |
| A log line that names `Signer:Endpoint` or `Signer:ApiKey` | Container log, at boot | A key under `Signer:` is set without those two. | Complete `.env` and `appsettings.Production.json` (steps 4.2 and 4.3). |
| A log line that names `Signer:WebhookSecret` | Container log, at boot | The secret has fewer than 32 characters, or leading or trailing whitespace. | Generate it as in the [webhook](https://docs.lacunasoftware.com/en-us/articles/bulk-signer/docker-ubuntu-signer-folder#webhook) section. |
| A log line that names both forwarded-headers switches | Container log, at boot | `ASPNETCORE_FORWARDEDHEADERS_ENABLED` and `Hosting__ForwardedHeaders__Enabled` are both set. | Keep `Hosting__ForwardedHeaders__*` only. |
| `signer-notification.unauthorized` | Notification route, `401` | The token registered in Signer differs from the secret, was entered with the word `Bearer`, or the authentication type is not **Bearer**. | Correct the webhook in Signer. |
| `signer-notification.not-configured` | Notification route, `404` | The container did not receive `Signer__WebhookSecret`. | Check `.env` and run `sudo docker compose up -d`. |
| `signer-folder.no-holder-action` | Job, `Failed` | The document is in the bound folder but has no signing action for the certificate's CPF. | Add the holder as a signer with the CPF. The next sweep detects the new action. Not retriable. |
| `signer-folder.signature-refused` | Job, `Failed` | Signer refused the signature; its validation results are in the job history. The usual cause is the certificate (revoked, expired, or not the participant's). | Correct the cause reported by Signer, then retry the job. |
| `signer-folder.interrupted` | Job, `Failed` | The container stopped during the signature. | Check the document in Signer, then retry the job. A retry ends `Canceled` if the holder's action is already concluded. |
| `AADSTS50011` | Microsoft Entra ID, at sign-in | The redirect URI sent is `http://…`, or it does not match the app registration. | Check the forwarded headers of the [HTTPS](https://docs.lacunasoftware.com/en-us/articles/bulk-signer/docker-ubuntu-signer-folder#https) section and the registration's `https://<host>/signin-oidc` URI. |

A job that ends `Canceled` carries no code: the document was cancelled, refused or expired in Signer, or was
already signed by the holder, before the container signed it. This is not a fault. Every `signer-folder.*`
code is specified in
[Troubleshooting](https://docs.lacunasoftware.com/en-us/articles/bulk-signer/troubleshooting#a-lacuna-signer-folder-job-ends-failed-or-canceled).

### Symptoms

| Symptom | Cause | Resolution |
|---|---|---|
| The profile is degraded, with a reason about the certificate's CPF. | The certificate contains no CPF. | Use an ICP-Brasil e-CPF or e-CNPJ. See [Troubleshooting](https://docs.lacunasoftware.com/en-us/articles/bulk-signer/troubleshooting#a-signer-folder-profile-is-degraded-saying-its-certificate-carries-no-cpf). |
| The `signer-folder-sweep` check fails. | Three consecutive passes failed. The usual cause is an incorrect `Signer:ApiKey`, or a `Signer:Endpoint` that is not the API address. | See [Troubleshooting](https://docs.lacunasoftware.com/en-us/articles/bulk-signer/troubleshooting#the-signer-folder-sweep-row-on-apireadydetails-is-red). |
| A document is never detected. | The document is in a subfolder, the holder was added without the certificate's CPF, or the pending action is another participant's. | Correct the document in Signer. A document whose turn has not come is detected once it does. |
| `signer-notifications` reports that none has arrived after a document was created. | Signer does not reach `https://<host>`: an incorrect URL, `http://`, or a firewall that does not admit port 443. | Correct the URL in Signer or the firewall. |
| Documents are signed, but up to a minute after their creation. | The notification does not arrive, and documents are detected by the sweep. | See [Troubleshooting](https://docs.lacunasoftware.com/en-us/articles/bulk-signer/troubleshooting#lacuna-signer-documents-are-found-only-at-the-sweep-interval-not-within-seconds). |

## Limitations

| Not provided | Alternative |
|---|---|
| A signed file on the virtual machine | Signer stores the document. Download it from Signer; nothing is written to `output/`. |
| Verification of the result by Bulk Signer | None. Verification is disabled for this method, because Signer validates the signature when it builds it into the document. |
| More than one instance | [Azure App Service (cluster mode)](https://docs.lacunasoftware.com/en-us/articles/bulk-signer/azure). |
| The opposite direction: a file sent to Signer for a person to sign | The `LacunaSigner` method, which uses the same `Signer:Endpoint` and `Signer:ApiKey` and is selected per profile. See [Lacuna Signer integration](https://docs.lacunasoftware.com/en-us/articles/bulk-signer/lacuna-signer). |
