Signera dokument med Documenso och Podman utan root

Det här sätter du upp

Documenso skickar ut PDF-filer för signering, ungefär som DocuSign. Du laddar upp ett avtal, placerar fält där varje person ska skriva under, och Documenso mejlar en länk till varje mottagare. De signerar i webbläsaren, utan konto. När alla har skrivit under lägger Documenso till en sida med signeringshistoriken, förseglar PDF-filen med en digital signatur från ert eget certifikat och mejlar den färdiga kopian till alla.

Documenso görs av Documenso, Inc., som säljer en molnversion och en Enterprise Edition. Koden är öppen källkod under AGPL 3.0; några delar, som i koden är märkta som Enterprise Edition, till exempel fakturering och funktionen för e-postdomäner, kräver en betald licens i produktion. Inget i den här guiden använder dem. Som standard skickar Documenso sin version och ett installations-ID till tillverkaren varje timme, enligt dess dokumentation, och i våra tester frågade avbilden npm:s register efter en nyare npm vid varje start. Steg 5 stänger av båda.

Här körs Documenso som en pod under en egen användare som heter documenso, med PostgreSQL för dess data och själva dokumenten, bakom Caddy från Podman-guiden.

Varje steg nedan har körts på en nyinstallerad Melonslab VC-P Alloy (2 vCPU, 8 GB) med Debian 13:

Documenso 2.20.0 startade med PostgreSQL 17 och ett självsignerat certifikat från steg 3, och rapporterade certifikatet som klart.
Det första kontot registrerades och bekräftade sin adress via e-post; en adress på en annan domän nekades. Därefter stängdes registreringen, och registreringssidan skickade besökarna till inloggningssidan. Ett konto som skapades i adminpanelen fick ett mejl för att sätta lösenord och gick med i organisationen via en inbjudan.
En PDF skickades för signering, och mottagaren skrev under via länken i mejlet. Den färdiga PDF-filen kom med e-post med en sida för signeringshistoriken, och pdfsig rapporterade "Signature is Valid" med certifikatet från steg 3, och "Certificate issuer isn't Trusted", som väntat för ett självsignerat certifikat.
Ett dokument skickades utan e-post, med signeringslänkar att kopiera i stället, och signerades via länken.
Signeringshistoriken visade undertecknarens riktiga adress över IPv4 och IPv6, och struntade i en förfalskad X-Forwarded-For-header.
Med inställningarna från steg 5 visade en avlyssning av serverns trafik inga externa anslutningar medan Documenso startade och medan dokument skickades och signerades, förutom uppslagningen av SMTP-servern.
Documenso återställdes från en säkerhetskopia, med nycklarna och certifikatet, och därefter signerades ett väntande dokument och förseglades med det återställda certifikatet. En uppdatering från 2.19.0 till 2.20.0, genom att byta avbildens tagg, gjorde sin ändring i databasen av sig själv, och allt startade igen av sig självt efter en omstart av servern.

Podden använde omkring 300 MB minne i vila och omkring 380 MB efter att ett dokument hade signerats och förseglats, nästan allt för Documenso själv.

Innan du börjar

Du behöver:

en server uppsatt som i Podman-guiden, med Caddy igång;
en A-post och en AAAA-post för sign.example.com som pekar på din server;
ett e-postkonto hos din e-postleverantör som Documenso kan skicka från, med namnet på dess SMTP-server och lösenordet. Documenso går inte att sätta upp utan e-post: ditt konto måste bekräfta sin adress innan det kan logga in.

Exemplen använder sign.example.com för Documenso, example.com som företagets e-postdomän, sign@example.com som avsändare, smtp.example.com som leverantörens SMTP-server och Example AB som företagets namn. Byt ut dem genomgående.

1. Skapa användaren

Som root:

useradd -m -s /bin/bash documenso
loginctl enable-linger documenso
machinectl shell documenso@

Allt fram till steg 6 körs som documenso.

2. Skapa hemligheterna

pw=$(openssl rand -hex 24)
printf %s "$pw" | podman secret create documenso-db-password -
printf 'postgresql://documenso:%s@127.0.0.1:5432/documenso' "$pw" | podman secret create documenso-database-url -
unset pw
openssl rand -hex 32 | tr -d '\n' | podman secret create documenso-auth-secret -
openssl rand -hex 32 | tr -d '\n' | podman secret create documenso-encryption-key -
openssl rand -hex 32 | tr -d '\n' | podman secret create documenso-encryption-key-2 -

De två första innehåller databaslösenordet, en gång för PostgreSQL och en gång i adressen som Documenso ansluter till. Den tredje signerar inloggningar, och de två sista krypterar hemligheter som Documenso sparar i databasen, till exempel tvåfaktorskoder. Steg 10 sparar kopior av nycklarna.

3. Skapa signeringscertifikatet

När den sista personen har skrivit under signerar Documenso själv PDF-filen med ett certifikat, så att vem som helst kan kontrollera att den inte har ändrats sedan dess. Skapa ett eget, giltigt i tio år, med företagets namn:

umask 077
mkdir ~/cert && cd ~/cert
openssl rand -hex 24 | tr -d '\n' > passphrase
openssl req -x509 -newkey rsa:3072 -noenc -keyout key.pem -out cert.pem -days 3650 -subj "/C=SE/O=Example AB/CN=Example AB document signing"
openssl pkcs12 -export -inkey key.pem -in cert.pem -name "Example AB" -passout file:passphrase -out cert.p12
base64 -w0 cert.p12 | podman secret create documenso-signing-cert -
podman secret create documenso-signing-passphrase passphrase
cd && rm -r ~/cert

Certifikatet och dess privata nyckel hamnar i en .p12-fil som skyddas av en slumpad lösenfras, vilket Documenso kräver. Båda sparas som hemligheter i Podman, och filerna raderas. Tio år, i stället för det ena år som Documensos dokumentation använder, gör att du inte behöver byta det i första taget: ett dokument som signeras efter att certifikatet har gått ut får en varning i PDF-läsare.

Certifikatet är självsignerat, så en PDF-läsare kan visa att dokumentet är oförändrat och vem som förseglade det, men inte att en betrodd utfärdare går i god för ert namn, och Adobe Acrobat visar ingen grön bock. Vill du ha den bocken köper du ett certifikat för dokumentsignering från en leverantör på Adobes lista över betrodda utfärdare och lägger det i de två hemligheterna i stället.

4. Spara e-postlösenordet

Documenso mejlar varje signeringsförfrågan, de färdiga dokumenten, inbjudningar och återställning av lösenord. Som documenso sparar du lösenordet till e-postkontot som den skickar från:

printf %s 'the-smtp-password' | podman secret create documenso-smtp-password -

Steg 5 pekar Documenso mot leverantörens SMTP-server på port 587, som använder STARTTLS. Steg 9 listar vad som kräver e-post.

5. Definiera podden

mkdir -p ~/.config/containers/systemd
cd ~/.config/containers/systemd

Skapa documenso.pod:

[Pod]
PodName=documenso
# Only Caddy, on this server, can reach Documenso: the port is not open to the internet.
PublishPort=127.0.0.1:8127:3000

[Install]
WantedBy=default.target

Skapa documenso-db.container:

[Container]
ContainerName=documenso-db
Image=docker.io/library/postgres:17-alpine
Pod=documenso.pod
Volume=documenso-db:/var/lib/postgresql/data
Environment=POSTGRES_USER=documenso POSTGRES_DB=documenso
Secret=documenso-db-password,type=env,target=POSTGRES_PASSWORD
HealthCmd=pg_isready -U documenso -d documenso
HealthInterval=10s
Notify=healthy
AutoUpdate=registry

[Service]
Restart=always

Och documenso-app.container:

[Unit]
Requires=documenso-db.service
After=documenso-db.service

[Container]
ContainerName=documenso-app
Image=docker.io/documenso/documenso:v2.20.0
Pod=documenso.pod
Environment=NEXT_PUBLIC_WEBAPP_URL=https://sign.example.com
Environment=NEXT_PRIVATE_INTERNAL_WEBAPP_URL=http://127.0.0.1:3000
Environment=NEXT_PRIVATE_ALLOWED_SIGNUP_DOMAINS=example.com
Environment=DOCUMENSO_DISABLE_TELEMETRY=true CHECKPOINT_DISABLE=1 NPM_CONFIG_UPDATE_NOTIFIER=false
Secret=documenso-database-url,type=env,target=NEXT_PRIVATE_DATABASE_URL
Secret=documenso-auth-secret,type=env,target=NEXTAUTH_SECRET
Secret=documenso-encryption-key,type=env,target=NEXT_PRIVATE_ENCRYPTION_KEY
Secret=documenso-encryption-key-2,type=env,target=NEXT_PRIVATE_ENCRYPTION_SECONDARY_KEY
Secret=documenso-signing-cert,type=env,target=NEXT_PRIVATE_SIGNING_LOCAL_FILE_CONTENTS
Secret=documenso-signing-passphrase,type=env,target=NEXT_PRIVATE_SIGNING_PASSPHRASE
Environment=NEXT_PRIVATE_SMTP_HOST=smtp.example.com NEXT_PRIVATE_SMTP_PORT=587
Environment=NEXT_PRIVATE_SMTP_USERNAME=sign@example.com
Environment=NEXT_PRIVATE_SMTP_FROM_ADDRESS=sign@example.com "NEXT_PRIVATE_SMTP_FROM_NAME=Example AB"
Secret=documenso-smtp-password,type=env,target=NEXT_PRIVATE_SMTP_PASSWORD

[Service]
Restart=always

Vad inställningarna gör:

NEXT_PUBLIC_WEBAPP_URL är adressen som Documenso sätter i varje länk och mejl. Den måste vara den publika https://-adressen.
NEXT_PRIVATE_INTERNAL_WEBAPP_URL är dit Documenso skickar sina egna bakgrundsjobb, till exempel förseglingen av ett färdigt dokument. Inne i podden skulle den publika adressen nå själva podden i stället för Caddy, som Podman-guiden förklarar, så jobben går direkt till appen.
NEXT_PRIVATE_ALLOWED_SIGNUP_DOMAINS låter bara adresser på er egen domän registrera sig, och först efter att adressen har bekräftats via e-post. Steg 7 stänger registreringen helt när ditt konto finns.
DOCUMENSO_DISABLE_TELEMETRY stoppar rapporten varje timme till Documenso, Inc. med version och installations-ID. CHECKPOINT_DISABLE stoppar en rapport från Prisma, databasverktyget som den använder, och NPM_CONFIG_UPDATE_NOTIFIER=false stoppar npm:s uppdateringskontroll vid varje start.
Signeringscertifikatet ges till Documenso som innehållet i en hemlighet, så ingen fil behöver monteras i containern.
Dokumenten lagras i PostgreSQL, som är Documensos standard, så databasdumpen i steg 10 innehåller varje PDF.
SMTP-raderna skickar e-post via din leverantör med kontot från steg 4. Port 587 börjar okrypterat och byter till TLS med STARTTLS; för port 465, som använder TLS från början, lägger du till NEXT_PRIVATE_SMTP_SECURE=true och byter port.
Avbilden är låst till versionen vi testade, som Documenso rekommenderar; steg 11 uppdaterar den. PostgreSQL ligger kvar på version 17 och får sina mindre uppdateringar från podman auto-update.

Starta den:

systemctl --user daemon-reload
systemctl --user start documenso-pod
systemctl --user enable --now podman-auto-update.timer

Vid första starten laddas omkring 1,8 GB avbilder ner och databasen sätts upp, vilket tar några minuter. Den är klar när det här visar "status":"ok", med ok för både databasen och certifikatet:

curl -s http://127.0.0.1:8127/api/health

6. Sätt Caddy framför

Gå tillbaka till root med exit, byt till machinectl shell caddy@ och lägg till det här blocket sist i ~/Caddyfile:

sign.example.com {
    reverse_proxy 127.0.0.1:8127
}

Starta om Caddy med systemctl --user restart caddy.

Caddy sätter headern X-Forwarded-For till besökarens riktiga adress och ersätter det värde som besökaren eventuellt skickade. Documenso hämtar adressen därifrån till signeringshistoriken, så den registrerar varje undertecknares riktiga adress.

7. Skapa ditt konto och stäng registreringen

Öppna https://sign.example.com/signup och registrera dig med ditt namn, din adress på example.com, ett långt lösenord och en signatur, och välj sedan Create account. Documenso mejlar en länk för att bekräfta adressen; öppna den. En adress på en annan domän får svaret "Signup is currently disabled or not available for your email domain."

Documenso har ingen sida för att skapa den första administratören. Gör ditt konto till administratör i databasen: gå tillbaka till root med exit, byt till machinectl shell documenso@ och kör, med din adress:

podman exec documenso-db psql -U documenso -c "UPDATE \"User\" SET roles = '{ADMIN,USER}' WHERE email = 'you@example.com';"

Det skriver ut UPDATE 1. Logga in på https://sign.example.com, så finns Admin Panel i menyn under ditt namn.

Stäng sedan registreringen. I ~/.config/containers/systemd/documenso-app.container byter du raden med NEXT_PRIVATE_ALLOWED_SIGNUP_DOMAINS mot:

Environment=NEXT_PUBLIC_DISABLE_SIGNUP=true

systemctl --user daemon-reload
systemctl --user restart documenso-app

Nu skickar https://sign.example.com/signup besökaren till inloggningssidan, och nya registreringar nekas. Du lägger själv till personer:

Admin Panel > Users > Create User, med deras e-postadress och namn. Documenso mejlar dem en länk för att sätta ett lösenord.
Bjud in dem till er organisation, så att de kan skicka dokument från den. På https://sign.example.com/settings väljer du Members under Organization Settings och sedan Invite member. De tackar ja i mejlet, eller under View invites när de loggar in. Fram till dess kan de bara signera dokument som skickas till dem.

Ditt konto börjar med en organisation som heter "Personal Organisation" och ett team som heter "Personal Team", som du kan byta namn på under General i deras inställningar. Den som bara ska skriva under dokument behöver inget konto.

8. Skicka ett dokument för signering

På Documents väljer du Upload Document och en PDF-fil.
Under Recipients fyller du i varje persons Email och Name, och lägger till fler med Add Signer. Menyn bredvid varje mottagare anger rollen, till exempel Needs to sign, Needs to approve eller Receives copy.
Add Fields: välj Signature och klicka där mottagaren ska skriva under. Name, Date, Text och de andra fälten fungerar på samma sätt.
Välj Send Document och Send.

Varje mottagare får ett mejl med en länk, öppnar dokumentet, fyller i sina fält och väljer Complete och Sign. När alla har skrivit under förseglar Documenso PDF-filen och mejlar den som bilaga till dig och alla mottagare. Sista sidan är signeringsintyget, med varje undertecknares e-postadress, när dokumentet skickades, visades och signerades, i UTC, och undertecknarens IP-adress och webbläsare.

För att kontrollera förseglingen öppnar du PDF-filen i en läsare som visar signaturer. På Linux skriver pdfsig agreement.pdf från poppler-utils ut namnet från ditt certifikat och "Signature is Valid". Varje ändring i PDF-filen efteråt gör signaturen ogiltig.

Documenso finns inte på svenska. Gränssnittet är översatt till tyska, spanska, franska, italienska, nederländska, polska, portugisiska, albanska, japanska, koreanska och kinesiska, utöver engelska.

9. E-post

Documenso behöver e-post för:

att bekräfta adressen för ett nytt konto, som inte kan logga in innan dess;
länken för att sätta lösenord för ett konto som skapats i adminpanelen, och Forgot your password?;
inbjudningar till en organisation;
signeringsförfrågningar, och det färdiga dokumentet som skickas till alla.

Vi testade att skicka med STARTTLS på port 587 och lösenord, till en testserver för e-post på själva servern, inte via en riktig leverantör.

Utan e-post kan du ändå få dokument signerade: i Send Document väljer du None i stället för Email, och Generate Links. Copy Signing Links på dokumentet ger dig sedan varje mottagares länk att skicka själv, och ingen får något mejl.

10. Säkerhetskopiera

Som documenso:

umask 077
mkdir -p ~/backup
podman exec documenso-db pg_dump -U documenso documenso > ~/backup/documenso.sql
for s in documenso-auth-secret documenso-encryption-key documenso-encryption-key-2 documenso-signing-cert documenso-signing-passphrase; do
  podman secret inspect --showsecret --format '{{.SecretData}}' "$s" > ~/backup/"$s"
done

Databasen innehåller kontona, dokumenten, både de uppladdade och de signerade PDF-filerna, och signeringshistoriken. De andra filerna är nycklarna från steg 2 och signeringscertifikatet med sin lösenfras. Kopiera ~/backup till en annan maskin, till exempel med restic, och förvara den säkert: med certifikatet kan vem som helst försegla PDF-filer i ert företags namn.

För att återställa, som documenso, med säkerhetskopian i ~/backup:

systemctl --user stop documenso-app
podman exec documenso-db dropdb -U documenso --force documenso
podman exec documenso-db createdb -U documenso documenso
podman exec -i documenso-db psql -q -U documenso documenso < ~/backup/documenso.sql
systemctl --user start documenso-app

På en ny server skapar du de fem hemligheterna från säkerhetskopian i stället för nya i steg 2 och 3, innan du startar podden. Databaslösenordet kan vara nytt:

for s in documenso-auth-secret documenso-encryption-key documenso-encryption-key-2 documenso-signing-cert documenso-signing-passphrase; do
  tr -d '\n' < ~/backup/"$s" | podman secret create "$s" -
done

11. Uppdatera

Documenso rekommenderar en låst version i produktion, så den ingår inte i podman auto-update. Läs versionsinformationen på GitHub, på github.com/documenso/documenso/releases, säkerhetskopiera som i steg 10 och byt taggen i documenso-app.container till den nya versionen, till exempel v2.21.0. Kör sedan:

systemctl --user daemon-reload
systemctl --user restart documenso-app

Documenso uppdaterar sin databas när den startar. Vi uppdaterade från 2.19.0 till 2.20.0 på det här sättet och fick logga in igen efteråt.

Felsökning

Hälsokontrollen visar inte ok för certifikatet, eller signeringen misslyckas med "Failed to get private key bags" eller "mac verify failure". Certifikatet eller hemligheten med lösenfrasen är fel. Skapa båda igen som i steg 3, efter podman secret rm documenso-signing-cert documenso-signing-passphrase, och starta om documenso-app. Loggraden "Certificate not found or not readable" vid starten gäller en certifikatfil, som den här uppsättningen inte använder; det är hälsokontrollen som gäller.

Signeringsförfrågningar mejlas inte, och signerade dokument fastnar på "Processing document". NEXT_PRIVATE_INTERNAL_WEBAPP_URL saknas, så Documenso skickar sina bakgrundsjobb till den publika adressen, som inte når någonting inifrån podden. Lägg till den som i steg 5 och starta om. Dokument som signerades under tiden visas under Admin Panel > Unsealed Documents, där Reseal gör dem färdiga.

Inga mejl kommer fram. journalctl --user -u documenso-app visar en rad som [JOBS]: Job send.document.completed.emails failed Error: connect ECONNREFUSED, med orsaken. Kontrollera servernamn, port och användarnamn i documenso-app.container, och lösenordet i documenso-smtp-password; för att byta lösenordet kör du podman secret rm documenso-smtp-password, skapar det igen som i steg 4 och startar om documenso-app.

"Unable to sign in. This account has not been verified." Kontot har inte bekräftat sin adress. Send confirmation email på den sidan skickar länken igen.

Signera dokument med Documenso och Podman utan root

Mer i Företag och övervakning