---
title: "Assinando documentos do Lacuna Signer com Docker no Ubuntu 24.04"
description: "Procedimento para implantar o Bulk Signer como um container Docker em uma máquina virtual Ubuntu 24.04, com um banco SQLite local e um certificado em PFX, e para assinar documentos criados em uma pasta do Lacuna Signer com o método SignerFolder; com HTTPS pelo nginx, o webhook do Signer:WebhookSecret e o login pelo Microsoft Entra ID como opcionais."
canonical: "https://docs.lacunasoftware.com/articles/bulk-signer/docker-ubuntu-signer-folder"
locale: "pt-BR"
product: "Bulk Signer"
last_updated: "2026-11-17"
---

# Assinando documentos do Lacuna Signer com Docker no Ubuntu 24.04

Esta página especifica uma implantação de instância única do Bulk Signer em uma máquina virtual Ubuntu
24.04 LTS que assina documentos criados no **Lacuna Signer**. Um usuário ou a API cria um documento em uma
pasta do Signer vinculada a um perfil de assinatura do Bulk Signer; o Bulk Signer o assina com o
certificado da organização, cuja chave privada fica armazenada em um **arquivo PFX na máquina virtual**, e
o Signer armazena o documento assinado. A implantação é composta por:

- a imagem de container do Bulk Signer, executada como **um** container Docker gerenciado pelo Docker
  Compose;
- o banco operacional em um banco **SQLite** local, no disco da máquina virtual;
- o certificado de assinatura em um **arquivo PFX**, montado somente leitura no container;
- um perfil de assinatura que usa o
  [método `SignerFolder`](https://docs.lacunasoftware.com/articles/bulk-signer/lacuna-signer#assinando-em-uma-pasta-do-lacuna-signer--signerfolder), declarado na
  configuração e importado no primeiro boot.

Três partes são opcionais e independentes da assinatura em si: o [HTTPS pelo nginx](https://docs.lacunasoftware.com/articles/bulk-signer/docker-ubuntu-signer-folder#https), que as outras
duas exigem; o [webhook do `Signer:WebhookSecret`](https://docs.lacunasoftware.com/articles/bulk-signer/docker-ubuntu-signer-folder#webhook), pelo qual o Signer notifica o Bulk Signer de
novos documentos; e o [login pelo Microsoft Entra ID](https://docs.lacunasoftware.com/articles/bulk-signer/docker-ubuntu-signer-folder#entra-id) para os operadores.

A instalação geral com Docker, para a assinatura de arquivos, está especificada em
[Instalação](https://docs.lacunasoftware.com/articles/bulk-signer/installation#docker--compose). A mesma integração com o Lacuna Signer na Amazon Web Services
está especificada em [Amazon ECS Fargate + Lacuna Signer](https://docs.lacunasoftware.com/articles/bulk-signer/aws-signer-folder).

> **Info: Versão mínima: 2.16.0**
>
> O método `SignerFolder` e a chave `Signer:WebhookSecret` foram introduzidos na 2.16.0. Imagens anteriores
> recusam no boot a configuração desta página.

> **Perigo: Restrição de instância única**
>
> Uma instância do Bulk Signer por pasta do Lacuna Signer. Um segundo container, ou uma segunda máquina
> virtual, vinculado à mesma pasta não é suportado. Uma implantação que exige mais de uma instância deve usar
> o [Azure App Service (modo cluster)](https://docs.lacunasoftware.com/articles/bulk-signer/azure).

## Arquitetura

[![Assinatura em uma pasta do Lacuna Signer com Docker no Ubuntu: usuário ou API cria um documento no Signer; o container o encontra pela varredura ou pelo webhook opcional, assina com a chave do PFX e devolve a assinatura ao Signer](https://docs.lacunasoftware.com/images/bulk-signer/docker-ubuntu-signer-folder-architecture-pt.svg)](https://docs.lacunasoftware.com/images/bulk-signer/docker-ubuntu-signer-folder-architecture-pt.svg)

### Conexões

| Direção | Conteúdo | Credencial |
|---|---|---|
| Container → Signer | A varredura, a releitura de cada documento, e o início e a conclusão de cada assinatura | `Signer:ApiKey`, enviada como `X-Api-Key` |
| Signer → nginx → container | O webhook, quando configurado: `POST https://<host>/api/signer/notifications` | `Signer:WebhookSecret`, enviado como `Authorization: Bearer` |
| Operador → nginx → container | O dashboard e a API REST | `Auth:ApiKey`, ou uma sessão do Microsoft Entra ID |
| Máquina virtual → registry da Lacuna | O download da imagem | As credenciais do registry emitidas pela Lacuna |

Toda conexão com o Signer parte da máquina virtual, exceto o webhook. Sem o webhook, a máquina virtual não
precisa de acesso de entrada a partir da internet.

### Diferenças em relação à assinatura de arquivos

| Aspecto | Comportamento com o método `SignerFolder` |
|---|---|
| Conteúdo do documento | Nenhum arquivo passa pelo Bulk Signer. O Signer envia o hash a assinar, o container o assina com a chave privada do PFX, e o Signer incorpora a assinatura ao documento e o armazena. Nada entra em uma pasta monitorada e nada é gravado em `output/`. O documento assinado é baixado do Signer. |
| Identificação do titular | O Signer associa o participante do documento ao CPF contido no certificado do perfil. O certificado precisa, portanto, ser um **e-CPF** ou um **e-CNPJ** da ICP-Brasil (que contém o CPF do responsável). |
| Formato da assinatura | O Signer escolhe o formato: PAdES para um PDF, XAdES para XML, CAdES para qualquer outro tipo. A configuração de formato do próprio perfil é ignorada. |
| Descoberta | Uma varredura a cada `Signer:FolderSweepIntervalSeconds` (60 segundos nesta página). Com o webhook, em segundos. A varredura continua sendo a garantia de entrega: um documento é atrasado, nunca perdido. |

## Pré-requisitos

| Requisito | Especificação |
|---|---|
| Máquina virtual | **Ubuntu 24.04 LTS**, x86 de 64 bits (`amd64`), com `sudo`. HTTPS de saída para `download.docker.com`, para o registry da Lacuna e para a instância do Lacuna Signer. |
| Credenciais do registry | As credenciais que a Lacuna emitiu para a imagem de container, e o host do registry, o caminho da imagem e a versão. Veja [Obtendo o produto](https://docs.lacunasoftware.com/articles/bulk-signer/installation#obtendo-o-produto). |
| Licença | A **licença do PKI SDK**. Veja [Obtendo a licença do PKI SDK](https://docs.lacunasoftware.com/articles/bulk-signer/installation#obtendo-a-licença-do-pki-sdk). |
| Organização no Lacuna Signer | Uma **organização** em uma instância do Lacuna Signer. O cadastro do webhook exige um usuário com o papel de administrador da organização. |
| Chave de API do Lacuna Signer | Uma **chave de API** dessa organização (passo 1.2). |
| Material de assinatura | O arquivo **PFX** de um certificado **e-CPF** ou **e-CNPJ** da ICP-Brasil, e a senha dele. Um certificado que não contém CPF deixa o perfil degradado. |
| Identificação do titular | O **CPF** contido no certificado. Os documentos devem indicar o titular como participante com exatamente esse CPF. |
| HTTPS (opcional) | Um **hostname** que resolva para a máquina virtual, TCP **80** e **443** de entrada, e acesso de escrita à zona DNS dele. Exigido pelo webhook e pelo Entra ID. |
| Microsoft Entra ID (opcional) | Um tenant, e uma conta com o papel **Cloud Application Administrator** ou superior. |

### Variáveis de shell

Todos os comandos desta página são executados em uma única sessão de shell na máquina virtual,
inicializada com as variáveis a seguir:

```bash
REGISTRY=<host do registry da Lacuna>
REPOSITORY=<caminho da imagem no registry>
VERSION=<versão>
SIGNER=https://<endereço do Lacuna Signer>
HOST=bulksigner.example.com           # o hostname público; somente a partir da seção HTTPS
DIR=/opt/bulksigner
```

| Variável | Conteúdo |
|---|---|
| `REGISTRY` | Somente o host do registry, por exemplo `<nome>.azurecr.io`. É o argumento do `docker login`, que não aceita um caminho. |
| `REPOSITORY` | O caminho da imagem dentro do registry, por exemplo `lacuna/bulksigner`. |
| `VERSION` | A versão a instalar, por exemplo `2.20.1`. Use uma versão explícita, não `latest`. |
| `SIGNER` | O endereço da API do Lacuna Signer (passo 1.1), sem barra no final. |
| `HOST` | O hostname público da implantação. Usado somente a partir da seção [HTTPS](https://docs.lacunasoftware.com/articles/bulk-signer/docker-ubuntu-signer-folder#https). |
| `DIR` | O diretório da instalação. Todos os arquivos da implantação ficam nele. |

## 1. Preparação do Lacuna Signer

### 1.1 Endereço da API

`SIGNER` é o endereço em que a API da instância do Signer responde, que não é necessariamente o endereço
da página inicial do produto. Sem uma chave, a API retorna `401`:

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

### 1.2 Chave de API

Crie uma aplicação na organização e gere a chave dela, conforme especificado no
[passo 1 de Primeiros passos com a API do Signer](https://docs.lacunasoftware.com/articles/signer/get-started#passo-1-crie-a-aplicação-e-a-chave-de-api).

| Propriedade | Especificação |
|---|---|
| Acesso ao menu **Aplicações** | Restrito ao administrador de sistema da instância. Sem esse acesso, solicite uma chave da organização ao administrador da instância do Signer. |
| Formato | `<aplicação>\|<segredo>`. A parte da aplicação pode conter espaços. |
| Exibição | A chave é exibida uma única vez, na criação. |
| Escopo | A organização em que foi criada. O container lê os documentos com essa chave. |
| Acesso exigido | Um papel que dê acesso às pastas e aos documentos da organização. |

Leia a chave no shell a partir de um prompt que não a exibe. O passo 4 a grava na configuração:

```bash
read -rsp 'Chave de API do Lacuna Signer: ' SIGNER_API_KEY; echo
```

### 1.3 Pasta

Em **Pastas**, selecione a organização e crie uma pasta com o ícone **Criar pasta**.

| Regra | Especificação |
|---|---|
| Vínculo | De um para um. Dois perfis não podem compartilhar uma pasta. |
| Alcance | A própria pasta. Um documento em uma subpasta dela não é assinado. |

O perfil desta página é declarado na configuração, que identifica a pasta pelo **ID**. Liste as pastas da
organização com a chave de API:

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

Cada linha mostra o ID de uma pasta e o nome dela. A resposta é a primeira página da listagem; em uma
organização com muitas pastas, localize a pasta pelo nome. Guarde o ID e o nome:

```bash
FOLDER_ID=<o ID da pasta>
FOLDER_NAME=<o nome da pasta>
```

O `jq` é instalado no passo 2. Execute este comando depois dele, ou leia o ID na mesma resposta sem o `jq`.

### 1.4 Política de assinatura em PDF

Se um PDF assinado com um certificado ICP-Brasil recebe a política da ICP-Brasil (AD-RB) ou uma assinatura
PAdES básica é determinado pela configuração `UseBrazilianPdfSigningPolicies` do Signer, e não pelo Bulk
Signer. A configuração pertence à instância do Signer:

| Instância do Signer | Onde a configuração é definida |
|---|---|
| On-premises | Nas [configurações](https://docs.lacunasoftware.com/articles/signer/on-premises/settings) da instância. |
| Nuvem da Lacuna | Pela Lacuna. Solicite a confirmação do valor em vigor. |

Defina a política antes de o primeiro documento ser assinado.

## 2. Docker Engine

Instale o Docker Engine e o plugin do Compose a partir do repositório apt do Docker, conforme especificado
em [Install Docker Engine on Ubuntu](https://docs.docker.com/engine/install/ubuntu/), junto com o `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
```

Todo comando `docker` desta página é executado com `sudo`.

> **Aviso: O Docker ignora o ufw**
>
> Uma porta publicada pelo Docker fica acessível mesmo quando o `ufw` a nega: o Docker grava as próprias
> regras de filtragem de pacotes. Restrinja o acesso à porta 8080 com o firewall da rede ou da nuvem, ou
> publique-a somente em `127.0.0.1`, como faz a seção [HTTPS](https://docs.lacunasoftware.com/articles/bulk-signer/docker-ubuntu-signer-folder#https).

## 3. A imagem

```bash
sudo docker login $REGISTRY --username <usuário do registry>     # pede o token
sudo docker pull $REGISTRY/$REPOSITORY:$VERSION
```

A credencial fica armazenada em `/root/.docker/config.json`. O repositório é privado: um pull sem
`docker login` responde `authentication required`.

## 4. Configuração

Todos os arquivos da implantação ficam em `$DIR`:

| Arquivo | Conteúdo |
|---|---|
| `docker-compose.yml` | O container, as montagens e a rede dele. |
| `.env` | Os segredos, como variáveis de ambiente. Legível somente pelo root. |
| `config/appsettings.Production.json` | O perfil de assinatura e a conexão com o Signer. Não contém segredo. |
| `config/signing.pfx` | O certificado e a chave privada dele. |
| `data/` | O banco SQLite e o key ring de sessão. |
| `logs/` | Os arquivos de log, um por dia. |

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

### 4.1 O arquivo do Compose

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

| Elemento | Especificação |
|---|---|
| `image` | A versão de `VERSION`. Uma atualização altera esta linha ([Operação](https://docs.lacunasoftware.com/articles/bulk-signer/docker-ubuntu-signer-folder#day-two)). |
| `ports` | HTTP simples na porta 8080. A seção [HTTPS](https://docs.lacunasoftware.com/articles/bulk-signer/docker-ubuntu-signer-folder#https) a restringe a `127.0.0.1`. |
| `./data` | O banco SQLite (`db/`) e o key ring de sessão (`keys/`). Sem essa montagem, cada substituição do container perde o histórico de jobs e desconecta todos os operadores. |
| `./config/signing.pfx` | Lido a cada boot. Deve permanecer neste caminho enquanto o perfil o usar. |
| `networks` | Uma sub-rede fixa, para que a seção [HTTPS](https://docs.lacunasoftware.com/articles/bulk-signer/docker-ubuntu-signer-folder#https) confie em headers encaminhados somente desta rede. Se `172.30.0.0/24` estiver em uso na máquina virtual, escolha outra faixa privada e use-a nos dois lugares. |

O health check da própria imagem consulta `/api/health` a cada 30 segundos.

### 4.2 Os segredos

Leia os valores que uma pessoa digita a partir de prompts que não os exibem, e gere os demais:

```bash
read -rsp 'Licença do PKI SDK: ' LICENSE; echo
read -rsp 'Senha do PFX: ' 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
```

| Variável | Descrição |
|---|---|
| `Signing__PkiSdkLicense` | A licença do PKI SDK. |
| `Signing__ProfileSecretsKey` | Criptografa a senha do PFX no banco. O perfil fica armazenado no banco ([Configuração](https://docs.lacunasoftware.com/articles/bulk-signer/configuration#signingprofilesecretskey--a-chave-que-criptografa-os-segredos-dos-perfis-armazenados)), e a importação do primeiro boot se recusa a armazenar uma senha sem essa chave. |
| `Signing__Profiles__0__Certificate__Pfx__Password` | A senha do PFX, importada para o perfil no primeiro boot. |
| `Signer__ApiKey` | Enviada como `X-Api-Key` em toda chamada ao Signer. |
| `Auth__ApiKey` | A chave de login do dashboard e o `X-API-Key` da API REST. No mínimo 16 caracteres. |

Os valores ficam entre aspas simples para que o Docker Compose não interprete um `$`, um espaço ou um `|`
neles. Um valor que contenha uma aspa simples deve ser editado no arquivo à mão.

> **Perigo: Armazene a Signing__ProfileSecretsKey fora da máquina virtual**
>
> Copie-a agora para o gerenciador de senhas: `sudo grep ^Signing__ProfileSecretsKey= .env`. Sem ela, a senha
> do PFX armazenada não pode ser descriptografada, o perfil fica degradado, e o certificado dele precisa ser
> configurado de novo. Não há recuperação.

### 4.3 As configurações

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

| Configuração | Especificação |
|---|---|
| `Signing:Profiles[0]` | O **seed** (carga inicial) do perfil de assinatura, importado somente no primeiro boot com o banco vazio. A partir daí o perfil fica armazenado no banco e é editado na página dele no dashboard; uma alteração posterior nesta seção é informada como ignorada no boot. Nenhum perfil `default` é criado. |
| `Name` | `signer-folder`. Não pode ser `default` e não pode ser alterado depois da importação. |
| `Format` | Exigido pela configuração, ignorado pelo método: o Signer escolhe o formato. |
| `Verify`, `ValidateCertificate` | Devem ser `false`; o padrão das duas é `true`. O Signer valida o certificado e a assinatura. |
| `SignerFolder:Id` | A pasta do passo 1.3. `Name` é exibido somente na página do perfil. |
| `Signer:Endpoint` | O endereço da API do Signer. Junto com `Signer:ApiKey`, obrigatório assim que qualquer chave em `Signer:` é definida. |
| `Signer:FolderSweepIntervalSeconds` | O intervalo entre as listagens da pasta, de 60 a 86400 segundos; o padrão é 300. 60 serve a uma implantação sem o webhook. Com o webhook, o padrão basta. |

A especificação completa dessas chaves está em
[Configuração](https://docs.lacunasoftware.com/articles/bulk-signer/configuration#assinando-em-uma-pasta-do-lacuna-signer--method--signerfolder).

### 4.4 O certificado e as permissões

O PFX precisa estar na máquina virtual. Copie-o da estação em que ele está, por exemplo com
`scp <arquivo>.pfx <usuário>@<máquina virtual>:`.

O container é executado como o usuário de ID **1654**, e não como root:

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

Confira a senha do passo 4.2 contra o arquivo antes do primeiro boot:

```bash
sudo openssl pkcs12 -in config/signing.pfx -noout -legacy      # pede a senha do PFX
```

Uma senha que abre o arquivo não produz saída. `Mac verify error: invalid password?` significa uma senha
errada ou outro arquivo. A senha do `.env` é importada para o banco somente no primeiro boot; depois dele,
corrigir o `.env` não tem efeito ([Referência de erros](https://docs.lacunasoftware.com/articles/bulk-signer/docker-ubuntu-signer-folder#when-something-refuses)).

## 5. Início e verificação

```bash
sudo docker compose up -d
sudo docker compose logs -f bulksigner        # Ctrl+C para de acompanhar; o container continua rodando
```

O primeiro boot cria o banco, importa o perfil (`Imported 1 signing profile into the operational store
from Signing:Profiles.`) e termina com o resumo **Service ready**. Os avisos (`[WRN]`) a seguir são
esperados e não indicam um problema:

| Aviso | Quando | Motivo |
|---|---|---|
| `Watched folder 'default' is unassigned` | A cada boot | Nenhum perfil recebe arquivos de uma pasta monitorada. |
| `The migration operation 'PRAGMA foreign_keys = 0;' … cannot be executed in a transaction` | No primeiro boot | O Entity Framework informa uma migração que não pode ser executada em uma transação. |
| `No XML encryptor configured` | No primeiro boot, e quando uma nova chave de sessão é criada | O key ring de sessão é gravado em `data/keys` sem uma criptografia própria, que o Linux não oferece. |
| `Overriding HTTP_PORTS '8080' and HTTPS_PORTS ''` | A cada boot | A imagem define `ASPNETCORE_URLS`, que prevalece sobre a porta padrão da imagem base. Os dois valores são a porta 8080. |
| `The query uses the 'First'/'FirstOrDefault' operator without 'OrderBy'` | A cada boot, na 2.20.1 | Um aviso do Entity Framework sobre uma consulta interna. |

Nos boots seguintes, a importação do perfil é substituída por `Signing:Profiles names 1 profile(s) and is
being ignored` (passo 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}'
```

| Verificação | Resultado esperado |
|---|---|
| `/api/health` | `"status":"healthy"` |
| O perfil | `"method": "SignerFolder"`, `"degraded": false` |
| `signer-folder-sweep` | `ok: true`. A primeira passagem é feita no boot: `the last pass at this instance finished without a failure at …` |
| `signer-notifications` | `not accepted (Signer:WebhookSecret is not set)` até o [webhook](https://docs.lacunasoftware.com/articles/bulk-signer/docker-ubuntu-signer-folder#webhook) ser configurado. |
| `pki-license` | `loaded` |

O motivo de um perfil degradado aparece na página dele no dashboard (**Este perfil não consegue assinar**) e
na verificação `signing-profile:signer-folder` de `/api/ready/details`. Os motivos usuais são um
certificado sem CPF e uma pasta que não existe no Signer.

## 6. Teste de assinatura

No Lacuna Signer:

1. Selecione **Novo documento**, faça upload de um PDF e selecione a organização e **a pasta vinculada**.
2. Inclua o titular do certificado como participante do tipo **Signatário**, com o nome, o **CPF contido
   no certificado** e o e-mail. O titular pode ser o único participante ou vir depois de outros; o
   container só age quando a ação pendente é a do titular.
3. Selecione **Enviar**.

Dentro do intervalo da varredura, ou em segundos com o webhook, a página **Jobs** do dashboard
(`http://<máquina virtual>:8080/jobs`) lista um job com o nome do documento, no perfil `signer-folder`. O
job passa pelos seguintes status:

| Status | Significado |
|---|---|
| **Na fila** | O documento foi detectado e o job foi criado. |
| **Processando** | O container releu o documento, iniciou a assinatura e assinou o hash com a chave do PFX. |
| **Verificando** | A assinatura foi entregue ao Signer, que a valida e a incorpora ao documento. |
| **Concluído** | O Signer aceitou a assinatura. |

No Lacuna Signer, a ação do titular está concluída e o documento contém a assinatura. Pela linha de
comando:

```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"}` aumenta uma vez por assinatura aceita pelo
Signer. A implantação está completa neste ponto; as três seções a seguir são opcionais.

## HTTPS pelo nginx (opcional)

O Bulk Signer escuta em HTTP simples. O nginx, na mesma máquina virtual, termina o TLS com um certificado
do Let's Encrypt e encaminha para o container, que passa a ser acessível somente a partir da máquina
virtual.

**1. DNS e firewall.** Crie um registro `A` para `$HOST` com o endereço público da máquina virtual, e
libere TCP 80 e 443 de entrada no firewall da rede ou da nuvem. O Let's Encrypt valida o nome pela porta 80.

**2. Publique o container na interface de loopback e confie no proxy.** O nginx se conecta pela porta
publicada, e o container vê a conexão chegar do gateway da rede do passo 4.1.
[`Hosting:ForwardedHeaders`](https://docs.lacunasoftware.com/articles/bulk-signer/configuration#hosting) faz o Bulk Signer ler o esquema e o endereço
originais do cliente nos headers do nginx, somente a partir dessa rede:

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

| Configuração | Efeito |
|---|---|
| `127.0.0.1:8080:8080` | A porta 8080 deixa de ser acessível de fora da máquina virtual, independentemente do `ufw`. |
| `Hosting__ForwardedHeaders__Enabled` | Lê `X-Forwarded-Proto` e `X-Forwarded-For`. Sem ela, o Bulk Signer vê `http`, e o login pelo Entra ID monta uma URI de redirecionamento `http://` que a Microsoft recusa. |
| `Hosting__ForwardedHeaders__KnownNetworks__0` | Confia em headers encaminhados somente a partir da rede do passo 4.1. Deve ser igual à `subnet` do arquivo do Compose. |

Não defina também a `ASPNETCORE_FORWARDEDHEADERS_ENABLED`: definir as duas é recusado no boot.

**3. Instale o nginx e o Certbot:**

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

**4. O site.** O dashboard mantém uma conexão WebSocket aberta, que exige os headers `Upgrade` e
`Connection`:

```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. O certificado.** O Certbot o obtém, acrescenta ao site o listener HTTPS e o redirecionamento de HTTP,
e instala a renovação dele:

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

**6. Verificação:**

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

A resposta é `"status":"healthy"`. De outra máquina, `http://<máquina virtual>:8080` não conecta mais. O
dashboard fica em `https://$HOST/`.

## O webhook no Lacuna Signer (opcional)

Sem o webhook, um documento espera a próxima varredura, até `Signer:FolderSweepIntervalSeconds`. Com ele, o
Signer chama `POST https://$HOST/api/signer/notifications` quando um documento é criado, assinado ou
aprovado, e o documento é assinado em segundos. A notificação identifica qual documento ler; nenhum outro
conteúdo dela é considerado confiável, e o documento é relido do Signer com a `Signer:ApiKey` antes de um
job ser criado. Exige a seção [HTTPS](https://docs.lacunasoftware.com/articles/bulk-signer/docker-ubuntu-signer-folder#https).

**1. O segredo.** No mínimo 32 caracteres, sem espaços no início ou no fim:

```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` significa que a rota está habilitada e exige o token. `404` significa que o container não recebeu o
segredo.

**2. Cadastro.** Exiba o segredo para copiá-lo, e depois limpe a tela:

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

No Lacuna Signer, com um administrador da organização:

1. Abra **Organizações** e selecione a organização.
2. Na seção **Integração**, abaixo do card **Webhooks**, selecione o botão **+**. Um novo painel
   **Webhook N** é aberto. Um webhook existente de outro sistema não é afetado.
3. Preencha os campos conforme especificado abaixo e selecione **Salvar**.

| Campo | Valor | Requisito |
|---|---|---|
| **URL** | `https://<host>/api/signer/notifications` | O esquema deve ser `https`: o listener HTTP responde com um redirecionamento, e um `POST` redirecionado não entrega nenhuma notificação. |
| **Tipo de autenticação** | **Bearer** | **X-Api-Key** não deve ser usado. Esse header é a credencial REST do próprio Bulk Signer, e uma notificação que o apresenta é recusada. |
| **Token de Autenticação** | O valor de `Signer__WebhookSecret` | Sem a palavra `Bearer`. O Signer acrescenta o prefixo. |

O Signer entrega todo evento da organização a todo webhook da organização. O Bulk Signer age sobre
`DocumentsCreated`, `DocumentSigned` e `DocumentApproved` e responde `204` a todo outro evento. O Signer
tenta de novo uma entrega que não recebe uma resposta `2xx` ([Webhooks](https://docs.lacunasoftware.com/articles/signer/webhooks)).

**3. Verificação.** Crie um documento como no [passo 6](https://docs.lacunasoftware.com/articles/bulk-signer/docker-ubuntu-signer-folder#sign-a-document). Ele é assinado em segundos, e a
verificação `signer-notifications` informa `accepted; the last arrived at this instance at <hora>`. Com o
webhook em funcionamento, `Signer__FolderSweepIntervalSeconds` pode voltar ao padrão de 300.

## Login pelo Microsoft Entra ID (opcional)

Por padrão, a página de login do dashboard pede a `Auth__ApiKey`. Com uma seção `Auth:EntraId`, ela oferece
**Entrar com a Microsoft** no lugar, e dois app roles controlam o acesso: **Administrator** para o
dashboard do operador e **Approver** para as páginas do aprovador
([Configuração](https://docs.lacunasoftware.com/articles/bulk-signer/configuration#authentraid--login-opcional-pelo-microsoft-entra-id)). Esta implantação usa
somente **Administrator**. Exige a seção [HTTPS](https://docs.lacunasoftware.com/articles/bulk-signer/docker-ubuntu-signer-folder#https): a Microsoft só aceita uma URI de redirecionamento
`https` para um host que não seja `localhost`.

| Efeito | Especificação |
|---|---|
| O formulário de login com a chave de API | Removido da página de login. |
| O `X-API-Key` da API REST | Inalterado. A `Auth__ApiKey` continua obrigatória. |
| Sessões criadas com a chave de API | Deixam de funcionar quando o container reinicia com a seção. |
| Saída | Encerra somente a sessão do Bulk Signer. A sessão da Microsoft permanece. |

**1. O registro de aplicativo.** Dê ao ambiente um registro próprio.
[`New-BulkSignerEntraApp.ps1`](https://docs.lacunasoftware.com/articles/bulk-signer/samples#powershell-7--new-bulksignerentraappps1), executado de qualquer
estação de trabalho com o PowerShell 7, cria um registro de tenant único com a URI de redirecionamento
`https://<host>/signin-oidc`, os dois app roles, a claim `email` e um aplicativo empresarial com
**Assignment required**:

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

Ao final, o script imprime, uma única vez, o bloco `Auth__EntraId__TenantId`, `Auth__EntraId__ClientId` e
`Auth__EntraId__ClientSecret`. Para criar o registro manualmente, siga
[Login pelo Microsoft Entra ID](https://docs.lacunasoftware.com/articles/bulk-signer/installation#login-pelo-microsoft-entra-id-opcional) em Instalação.

**2. Atribua as pessoas.** No Entra admin center, em **Enterprise applications → o aplicativo → Users and
groups**, atribua o app role **Administrator** a cada operador. Uma conta sem atribuição não consegue
entrar, e uma conta que se autentica sem nenhum dos dois roles é recusada.

**3. A configuração.** O client secret é lido a partir de um prompt que não o exibe:

```bash
read -rsp 'Client secret: ' VALUE; echo
sudo tee -a .env > /dev/null <<EOF
Auth__EntraId__TenantId='<o valor de Auth__EntraId__TenantId>'
Auth__EntraId__ClientId='<o valor de Auth__EntraId__ClientId>'
Auth__EntraId__ClientSecret='$VALUE'
EOF
unset VALUE
sudo nano .env          # substitua os dois marcadores
sudo docker compose up -d
```

As três chaves são exigidas em conjunto: uma seção preenchida pela metade interrompe o container no boot,
e o log cita a chave que falta.

**4. Verificação.** Siga o primeiro redirecionamento do login sem entrar:

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

A URL deve apontar para `login.microsoftonline.com/<tenant>/oauth2/v2.0/authorize`, com o ID do
aplicativo e `redirect_uri=https%3A%2F%2F<host>%2Fsignin-oidc`. O esquema `https` é o valor a confirmar:
`http` significa que os headers encaminhados da seção [HTTPS](https://docs.lacunasoftware.com/articles/bulk-signer/docker-ubuntu-signer-folder#https) não estão em vigor.

| Item | Descrição |
|---|---|
| Expiração do client secret | O tempo de vida padrão do script é de doze meses. Um secret expirado só falha no login, com um erro `AADSTS`. Crie um novo secret no registro, substitua `Auth__EntraId__ClientSecret` no `.env` e execute `sudo docker compose up -d`. |
| Remoção | Remova as três linhas `Auth__EntraId__` do `.env` e execute `sudo docker compose up -d`. O login com a chave de API volta. |

## Operação

Todo comando é executado em `$DIR`. Uma alteração no `.env` ou no arquivo do Compose entra em vigor com
`sudo docker compose up -d`, que recria o container.

| Operação | Procedimento | Observações |
|---|---|---|
| Atualização | Faça o backup, pause o pipeline (`POST /api/pipeline/pause`), espere até nenhum job estar `Processing` ou `Verifying`, altere a versão na linha `image:`, execute `sudo docker compose pull && sudo docker compose up -d`, e retome (`POST /api/pipeline/resume`). | As migrações são executadas no boot. Um container interrompido durante uma assinatura faz o próximo boot perguntar ao Signer como o job terminou, e alguns desses jobs terminam `Failed` com `signer-folder.interrupted` ([Integração com o Lacuna Signer](https://docs.lacunasoftware.com/articles/bulk-signer/lacuna-signer#quando-a-execução-que-o-assinava-termina)). A varredura continua com o pipeline pausado. |
| Backup | `sudo docker compose stop`, depois arquive `data/`, `config/`, `.env` e `docker-compose.yml`, depois `sudo docker compose start`. | O arquivo contém o certificado, a senha criptografada dele e a chave que a descriptografa. Armazene-o como o próprio certificado, fora da máquina virtual. |
| Rotação do segredo do webhook | Substitua `Signer__WebhookSecret` no `.env`, execute `sudo docker compose up -d`, e depois informe o novo valor no webhook no Signer. | Entre as duas alterações, as notificações recebem `401`; o Signer as tenta de novo e a varredura detecta os documentos restantes. |
| Rotação da chave de API do Signer | Crie a nova chave no Signer, substitua `Signer__ApiKey` no `.env`, execute `sudo docker compose up -d`, e só então revogue a chave anterior. | Com uma chave revogada, toda varredura falha, e a verificação `signer-folder-sweep` falha depois de três passagens seguidas com falha. |
| Renovação do certificado | Pause o pipeline. Substitua `config/signing.pfx` (com o dono e as permissões do passo 4.4) e, se a senha mudou, informe-a na página do perfil, em **Editar certificado**. Reinicie com `sudo docker compose restart` e retome. | O certificado é lido no boot. Se o novo certificado contiver um **CPF diferente**, os documentos pendentes no Signer para o CPF anterior não têm ação para o novo titular; cada um é registrado uma vez como `Failed` com `signer-folder.no-holder-action`. |
| Troca de pasta | Salve a nova pasta na página do perfil. | Entra em vigor sem reinício. A seção `SignerFolder` do `appsettings.Production.json` não é lida de novo. |
| Remoção | `sudo docker compose down`, remova o webhook no Signer e `sudo docker logout $REGISTRY`. | `data/`, `config/` e `.env` permanecem em `$DIR` até serem excluídos. |

## Referência de erros

| Código ou mensagem | Origem | Significado | Solução |
|---|---|---|---|
| `permission denied` em `/var/lib/bulksigner` ou em `/etc/bulksigner/signing.pfx` | Log do container, no boot | Os diretórios montados ou o PFX não pertencem ao UID 1654. | Repita o passo 4.4. |
| `authentication required` no `docker pull` | Docker | Sem `docker login`. | Repita o passo 3 com as credenciais emitidas pela Lacuna. |
| `not found` no `docker pull` | Docker | Um `REPOSITORY` ou uma `VERSION` que não existe, ou credenciais que não enxergam o repositório. | Confira as variáveis de shell e as credenciais emitidas pela Lacuna. |
| `did not open with the PKCS#12 password given` (`IncorrectPinException`), com o perfil degradado | Log do container e verificação `signing-profile:signer-folder`, no boot | A senha não abre `config/signing.pfx`: uma senha errada, ou outro arquivo. Corrigir o `.env` não tem efeito depois do primeiro boot, porque a senha já foi importada para o banco. | Confira com o `openssl` do passo 4.4. Uma senha errada: informe a correta na página do perfil, em **Editar certificado**, e execute `sudo docker compose restart`. Um arquivo errado: substitua-o como na Renovação do certificado ([Operação](https://docs.lacunasoftware.com/articles/bulk-signer/docker-ubuntu-signer-folder#day-two)). |
| Uma linha de log que cita `Signing:ProfileSecretsKey` | Log do container, primeiro boot | A importação armazenaria a senha do PFX sem a chave. | Defina `Signing__ProfileSecretsKey` (passo 4.2). |
| Uma linha de log que cita `Signer:Endpoint` ou `Signer:ApiKey` | Log do container, no boot | Uma chave em `Signer:` está definida sem essas duas. | Complete o `.env` e o `appsettings.Production.json` (passos 4.2 e 4.3). |
| Uma linha de log que cita `Signer:WebhookSecret` | Log do container, no boot | O segredo tem menos de 32 caracteres, ou espaços no início ou no fim. | Gere-o como na seção do [webhook](https://docs.lacunasoftware.com/articles/bulk-signer/docker-ubuntu-signer-folder#webhook). |
| Uma linha de log que cita as duas chaves de headers encaminhados | Log do container, no boot | `ASPNETCORE_FORWARDEDHEADERS_ENABLED` e `Hosting__ForwardedHeaders__Enabled` estão definidas. | Mantenha somente `Hosting__ForwardedHeaders__*`. |
| `signer-notification.unauthorized` | Rota de notificações, `401` | O token cadastrado no Signer difere do segredo, foi informado com a palavra `Bearer`, ou o tipo de autenticação não é **Bearer**. | Corrija o webhook no Signer. |
| `signer-notification.not-configured` | Rota de notificações, `404` | O container não recebeu a `Signer__WebhookSecret`. | Verifique o `.env` e execute `sudo docker compose up -d`. |
| `signer-folder.no-holder-action` | Job, `Failed` | O documento está na pasta vinculada, mas não tem ação de assinatura para o CPF do certificado. | Inclua o titular como signatário com o CPF. A próxima varredura detecta a nova ação. Não admite nova tentativa. |
| `signer-folder.signature-refused` | Job, `Failed` | O Signer recusou a assinatura; os resultados da validação dele estão no histórico do job. A causa usual é o certificado (revogado, expirado ou que não é o do participante). | Corrija a causa informada pelo Signer e faça uma nova tentativa do job. |
| `signer-folder.interrupted` | Job, `Failed` | O container parou durante a assinatura. | Verifique o documento no Signer e faça uma nova tentativa do job. A nova tentativa termina `Canceled` se a ação do titular já estiver concluída. |
| `AADSTS50011` | Microsoft Entra ID, no login | A URI de redirecionamento enviada é `http://…`, ou não corresponde ao registro de aplicativo. | Verifique os headers encaminhados da seção [HTTPS](https://docs.lacunasoftware.com/articles/bulk-signer/docker-ubuntu-signer-folder#https) e a URI `https://<host>/signin-oidc` do registro. |

Um job que termina `Canceled` não traz código: o documento foi cancelado, recusado ou expirou no Signer, ou
já tinha sido assinado pelo titular, antes de o container assiná-lo. Isso não é uma falha. Todo código
`signer-folder.*` está especificado em
[Solução de problemas](https://docs.lacunasoftware.com/articles/bulk-signer/troubleshooting#um-job-de-pasta-do-lacuna-signer-termina-failed-ou-canceled).

### Sintomas

| Sintoma | Causa | Solução |
|---|---|---|
| O perfil está degradado, com um motivo sobre o CPF do certificado. | O certificado não contém CPF. | Use um e-CPF ou um e-CNPJ da ICP-Brasil. Veja [Solução de problemas](https://docs.lacunasoftware.com/articles/bulk-signer/troubleshooting#um-perfil-de-pasta-do-signer-está-degradado-dizendo-que-o-certificado-não-tem-cpf). |
| A verificação `signer-folder-sweep` falha. | Três passagens seguidas falharam. A causa usual é uma `Signer:ApiKey` incorreta, ou um `Signer:Endpoint` que não é o endereço da API. | Veja [Solução de problemas](https://docs.lacunasoftware.com/articles/bulk-signer/troubleshooting#a-linha-signer-folder-sweep-em-apireadydetails-está-vermelha). |
| Um documento nunca é detectado. | O documento está em uma subpasta, o titular foi incluído sem o CPF do certificado, ou a ação pendente é de outro participante. | Corrija o documento no Signer. Um documento cuja vez ainda não chegou é detectado quando ela chega. |
| `signer-notifications` informa que nenhuma notificação chegou depois de um documento ser criado. | O Signer não acessa `https://<host>`: uma URL incorreta, `http://`, ou um firewall que não libera a porta 443. | Corrija a URL no Signer ou o firewall. |
| Os documentos são assinados, mas até um minuto depois de criados. | A notificação não chega, e os documentos são detectados pela varredura. | Veja [Solução de problemas](https://docs.lacunasoftware.com/articles/bulk-signer/troubleshooting#documentos-do-lacuna-signer-só-são-encontrados-no-intervalo-da-varredura-e-não-em-segundos). |

## Limitações

| Não oferecido | Alternativa |
|---|---|
| Um arquivo assinado na máquina virtual | O Signer armazena o documento. Baixe-o do Signer; nada é gravado em `output/`. |
| Verificação do resultado pelo Bulk Signer | Nenhuma. A verificação fica desabilitada neste método, porque o Signer valida a assinatura ao incorporá-la ao documento. |
| Mais de uma instância | [Azure App Service (modo cluster)](https://docs.lacunasoftware.com/articles/bulk-signer/azure). |
| A direção oposta: um arquivo enviado ao Signer para uma pessoa assinar | O método `LacunaSigner`, que usa os mesmos `Signer:Endpoint` e `Signer:ApiKey` e é escolhido por perfil. Veja [Integração com o Lacuna Signer](https://docs.lacunasoftware.com/articles/bulk-signer/lacuna-signer). |
