Pular para o conteúdo principal

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, declared in the configuration and imported on the first boot.

Three parts are optional and independent of the signing itself: HTTPS through nginx, which the other two require; the Signer:WebhookSecret webhook, through which Signer notifies Bulk Signer of new documents; and Microsoft Entra ID sign-in for operators.

The general Docker installation, for file signing, is specified in Installation. The same Lacuna Signer integration on Amazon Web Services is specified in Amazon ECS Fargate + Lacuna Signer.

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.

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).

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

Connections​

DirectionContentCredential
Container → SignerThe sweep, the read-back of each document, and the start and completion of each signatureSigner:ApiKey, sent as X-Api-Key
Signer → nginx → containerThe webhook, when configured: POST https://<host>/api/signer/notificationsSigner:WebhookSecret, sent as Authorization: Bearer
Operator → nginx → containerThe dashboard and the REST APIAuth:ApiKey, or a Microsoft Entra ID session
Virtual machine → Lacuna's registryThe image downloadThe 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​

AspectBehaviour with the SignerFolder method
Document contentNo 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 holderSigner 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 formatSigner selects the format: PAdES for a PDF, XAdES for XML, CAdES for any other type. The profile's own format setting is ignored.
DiscoveryA 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​

RequirementSpecification
Virtual machineUbuntu 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 credentialsThe credentials Lacuna issued for the container image, and the registry host, image path and version. See Obtaining the product.
LicenceThe PKI SDK licence. See Obtaining the PKI SDK license.
Lacuna Signer organizationAn organization on a Lacuna Signer instance. Registering the webhook requires a user with the organization administrator role.
Lacuna Signer API keyAn API key of that organization (step 1.2).
Signing materialThe 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 identificationThe 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:

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
VariableContent
REGISTRYThe registry host only, for example <name>.azurecr.io. It is the argument of docker login, which does not accept a path.
REPOSITORYThe image's path inside the registry, for example lacuna/bulksigner.
VERSIONThe version to install, for example 2.20.1. Use an explicit version, not latest.
SIGNERThe address of the Lacuna Signer API (step 1.1), without a trailing slash.
HOSTThe public hostname of the deployment. Used only from the HTTPS section on.
DIRThe 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:

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.

PropertySpecification
Access to the Applications menuRestricted 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.
DisplayThe key is displayed once, when it is created.
ScopeThe organization in which it was created. The container reads documents with this key.
Required accessA 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:

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.

RuleSpecification
BindingOne-to-one. Two profiles cannot share a folder.
ScopeThe 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:

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:

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 instanceWhere the setting is defined
On-premisesIn the instance's settings.
Lacuna's cloudBy 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, together with jq:

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.

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 section does.

3. The image​

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:

FileContent
docker-compose.ymlThe container, its mounts and its network.
.envThe secrets, as environment variables. Readable by root only.
config/appsettings.Production.jsonThe signing profile and the Signer connection. Contains no secret.
config/signing.pfxThe certificate and its private key.
data/The SQLite database and the session key ring.
logs/The log files, one per day.
sudo mkdir -p $DIR/config $DIR/data $DIR/logs
cd $DIR

4.1 The compose file​

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
ElementSpecification
imageThe version from VERSION. An upgrade changes this line (Operations).
portsPlain HTTP on 8080. The HTTPS section restricts it to 127.0.0.1.
./dataThe 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.pfxRead at every boot. It must remain at this path for as long as the profile uses it.
networksA fixed subnet, so that the 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:

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
VariableDescription
Signing__PkiSdkLicenseThe PKI SDK licence.
Signing__ProfileSecretsKeyEncrypts the PFX password in the database. The profile is stored in the database (Configuration), and the import on the first boot refuses to store a password without this key.
Signing__Profiles__0__Certificate__Pfx__PasswordThe PFX password, imported into the profile on the first boot.
Signer__ApiKeySent as X-Api-Key on every call to Signer.
Auth__ApiKeyThe 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.

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​

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
SettingSpecification
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.
Namesigner-folder. It cannot be default, and it cannot be changed after the import.
FormatRequired by the configuration, ignored by the method: Signer selects the format.
Verify, ValidateCertificateMust be false; both default to true. Signer validates the certificate and the signature.
SignerFolder:IdThe folder from step 1.3. Name is shown on the profile's page only.
Signer:EndpointThe address of the Signer API. With Signer:ApiKey, required as soon as any key under Signer: is set.
Signer:FolderSweepIntervalSecondsThe 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.

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:

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:

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).

5. Start and verification​

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:

WarningWhenReason
Watched folder 'default' is unassignedEvery bootNo profile takes files from a watched folder.
The migration operation 'PRAGMA foreign_keys = 0;' … cannot be executed in a transactionThe first bootEntity Framework reports a migration that cannot run in a transaction.
No XML encryptor configuredThe first boot, and whenever a new session key is createdThe 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 bootThe 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.1An 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).

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}'
CheckExpected result
/api/health"status":"healthy"
The profile"method": "SignerFolder", "degraded": false
signer-folder-sweepok: true. The first pass runs at boot: the last pass at this instance finished without a failure at …
signer-notificationsnot accepted (Signer:WebhookSecret is not set) until the webhook is configured.
pki-licenseloaded

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:

StateMeaning
QueuedThe document was detected and the job was created.
ProcessingThe container read the document back, started the signature and signed the hash with the PFX's key.
VerifyingThe signature was handed to Signer, which validates it and builds it into the document.
CompletedSigner accepted the signature.

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

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 makes Bulk Signer read the original scheme and client address from nginx's headers, from that network only:

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
SettingEffect
127.0.0.1:8080:8080Port 8080 is no longer reachable from outside the virtual machine, whatever ufw says.
Hosting__ForwardedHeaders__EnabledReads 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__0Trusts 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:

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:

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:

sudo certbot --nginx -d $HOST

6. Verification:

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 section.

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

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:

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.
FieldValueRequirement
URLhttps://<host>/api/signer/notificationsThe scheme must be https: the HTTP listener responds with a redirect, and a redirected POST delivers no notification.
Authentication typeBearerX-Api-Key must not be used. That header is Bulk Signer's own REST credential, and a notification that presents it is refused.
Authentication TokenThe value of Signer__WebhookSecretWithout 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).

3. Verification. Create a document as in step 6. 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). This deployment uses Administrator only. Requires the HTTPS section: Microsoft accepts only an https redirect URI for a host other than localhost.

EffectSpecification
The API-key sign-in formRemoved from the sign-in page.
The REST API's X-API-KeyUnchanged. Auth__ApiKey remains required.
Sessions created with the API keyStop working when the container restarts with the section.
Sign-outEnds the Bulk Signer session only. The Microsoft session remains.

1. The app registration. Give the environment its own registration. New-BulkSignerEntraApp.ps1, 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:

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 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:

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:

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 section are not in effect.

ItemDescription
Client secret expiryThe 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.
RemovalRemove 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.

OperationProcedureNotes
UpgradeBack 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). The sweep runs while the pipeline is paused.
Backupsudo 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 rotationReplace 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 rotationCreate 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 renewalPause 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 changeSave the new folder on the profile's page.Takes effect without a restart. The SignerFolder section of appsettings.Production.json is not read again.
Removalsudo 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 messageOriginMeaningResolution
permission denied on /var/lib/bulksigner or /etc/bulksigner/signing.pfxContainer log, at bootThe mounted directories or the PFX are not owned by UID 1654.Repeat step 4.4.
authentication required on docker pullDockerNo docker login.Repeat step 3 with the credentials Lacuna issued.
not found on docker pullDockerA 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 degradedContainer log and the signing-profile:signer-folder check, at bootThe 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).
A log line that names Signing:ProfileSecretsKeyContainer log, first bootThe import would store the PFX password without the key.Set Signing__ProfileSecretsKey (step 4.2).
A log line that names Signer:Endpoint or Signer:ApiKeyContainer log, at bootA 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:WebhookSecretContainer log, at bootThe secret has fewer than 32 characters, or leading or trailing whitespace.Generate it as in the webhook section.
A log line that names both forwarded-headers switchesContainer log, at bootASPNETCORE_FORWARDEDHEADERS_ENABLED and Hosting__ForwardedHeaders__Enabled are both set.Keep Hosting__ForwardedHeaders__* only.
signer-notification.unauthorizedNotification route, 401The 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-configuredNotification route, 404The container did not receive Signer__WebhookSecret.Check .env and run sudo docker compose up -d.
signer-folder.no-holder-actionJob, FailedThe 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-refusedJob, FailedSigner 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.interruptedJob, FailedThe 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.
AADSTS50011Microsoft Entra ID, at sign-inThe redirect URI sent is http://…, or it does not match the app registration.Check the forwarded headers of the 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.

Symptoms​

SymptomCauseResolution
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.
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.
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.

Limitations​

Not providedAlternative
A signed file on the virtual machineSigner stores the document. Download it from Signer; nothing is written to output/.
Verification of the result by Bulk SignerNone. Verification is disabled for this method, because Signer validates the signature when it builds it into the document.
More than one instanceAzure App Service (cluster mode).
The opposite direction: a file sent to Signer for a person to signThe LacunaSigner method, which uses the same Signer:Endpoint and Signer:ApiKey and is selected per profile. See Lacuna Signer integration.
View as Markdown