Как установить и настроить Documenso на VPS

MAATRIX

DocuSign считает подписи поштучно и упирается в лимит бесплатного плана после третьего документа в месяц, а корпоративные тарифы завязаны на зарубежную карту, которой у вас, возможно, уже нет. Documenso — открытая платформа для электронной подписи документов с тем же набором функций: загрузка PDF, расстановка полей подписи, дат и текста, рассылка ссылок подписантам, аудиторский след. Разворачивается она на обычном VPS через Docker Compose за час, и дальше это ваш сервер, ваши документы и ваш SMTP — без лимитов по количеству подписей и без ежемесячного счёта в долларах.

Что такое Documenso и зачем разворачивать его на своём VPS

Documenso — open-source проект на Next.js с базой PostgreSQL, распространяется под лицензией AGPL. Функционально это конструктор PDF с полями для подписи: вы загружаете документ, расставляете поля (подпись, инициалы, дата, текст, чекбокс), назначаете подписантов по e-mail и порядок подписания — последовательный или параллельный. Каждый подписант получает ссылку, подписывает в браузере без регистрации, а итоговый PDF получает встроенную цифровую подпись и журнал событий (кто, когда, с какого IP открыл и подписал документ).

Self-host имеет смысл в трёх случаях. Первый — объём: у DocuSign и аналогов цена растёт с числом отправленных конвертов, а на своём сервере подписывайте хоть сто документов в день без доплат. Второй — данные не должны покидать вашу инфраструктуру: договоры, NDA, кадровые документы остаются на сервере, который контролируете вы. Третий — оплата: у Documenso Cloud нет варианта платить рублёвой картой или криптовалютой, а VPS с оплатой из России арендовать можно спокойно.

Честно о минусах. Documenso моложе DocuSign и на порядок меньше по штату разработчиков — часть корпоративных функций (продвинутый workflow, интеграции с CRM, шаблоны для команд) либо ещё в разработке, либо доступна только в облачном тарифе проекта. Юридическая значимость электронной подписи регулируется отдельно от технологии — если подпись должна иметь силу по 63-ФЗ или eIDAS, уточняйте требования у юриста до того, как завязываете на неё процесс.

Требования к серверу и подготовка перед установкой

Documenso — не тяжёлое приложение. Next.js-контейнер и Postgres на связке комфортно работают на 1 vCPU / 2 ГБ RAM для команды до 10–15 человек; для активного использования с параллельной генерацией больших PDF и десятками одновременных подписантов закладывайте 2 vCPU / 4 ГБ. Диск — от 20 ГБ, дальше растёт пропорционально архиву подписанных документов (PDF с полями подписи весят немного больше исходника, но не критично).

Понадобится:

• сервер на Ubuntu 24.04 или Debian 12/13 с установленным Docker и Docker Compose plugin;
• домен, направленный A-записью на IP сервера (Documenso работает только по HTTPS — без валидного сертификата не откроется страница подписи в части браузеров из-за политики secure context для криптографии);
• рабочий SMTP-аккаунт для отправки писем подписантам (свой почтовый сервер, Yandex 360, Mailgun, SES — подойдёт любой с логином и паролем на SMTP);
• открытые наружу только 80/443 порта, порт самого приложения наружу не публикуется.

Если Docker ещё не стоит, ставьте из репозитория вендора командой curl -fsSL https://get.docker.com | sh — так вы получите Compose plugin сразу. Про фаервол и базовые правила ufw — в статье как установить и настроить UFW на VPS.

Установка Documenso через Docker Compose

Создаём рабочую директорию и раскладываем файлы:

mkdir -p /opt/documenso/{pgdata,cert}
cd /opt/documenso

Генерируем секреты — три случайных ключа понадобятся Documenso для подписи сессий и шифрования данных в базе:

openssl rand -hex 32   # NEXTAUTH_SECRET
openssl rand -hex 32   # NEXT_PRIVATE_ENCRYPTION_KEY
openssl rand -hex 32   # NEXT_PRIVATE_ENCRYPTION_SECONDARY_KEY

Сохраните вывод каждой команды — эти значения пойдут в .env-файл ниже.

compose.yaml:

services:
  postgres:
    image: postgres:16-alpine
    container_name: documenso-postgres
    restart: unless-stopped
    environment:
      POSTGRES_USER: documenso
      POSTGRES_PASSWORD: ${PG_PASSWORD}
      POSTGRES_DB: documenso
    volumes:
      - ./pgdata:/var/lib/postgresql/data

  documenso:
    image: documenso/documenso:latest
    container_name: documenso
    restart: unless-stopped
    depends_on:
      - postgres
    ports:
      - "127.0.0.1:3000:3000"
    env_file: documenso.env
    volumes:
      - ./cert:/opt/documenso/cert:ro

Порт приложения публикуется только на loopback — наружу его отдаст обратный прокси с HTTPS, о нём в следующем разделе.

documenso.env (заполните своими значениями):

NEXTAUTH_URL=https://sign.example.com
NEXT_PUBLIC_WEBAPP_URL=https://sign.example.com
NEXTAUTH_SECRET=<значение первой openssl rand -hex 32>
NEXT_PRIVATE_ENCRYPTION_KEY=<значение второй>
NEXT_PRIVATE_ENCRYPTION_SECONDARY_KEY=<значение третьей>
NEXT_PRIVATE_DATABASE_URL=postgres://documenso:<пароль_pg>@postgres:5432/documenso
NEXT_PRIVATE_DIRECT_DATABASE_URL=postgres://documenso:<пароль_pg>@postgres:5432/documenso
PORT=3000
NEXT_PRIVATE_SIGNING_LOCAL_FILE_PATH=/opt/documenso/cert/cert.p12
NEXT_PRIVATE_SIGNING_PASSPHRASE=<пароль от p12, задаёте сами>

Пароль базы задайте отдельно и подставьте в оба места (compose.yaml через переменную окружения PG_PASSWORD при запуске, либо пропишите его напрямую вместо ${PG_PASSWORD} — так проще для одиночного сервера):

PG_PASSWORD=$(openssl rand -hex 24)
echo "PG_PASSWORD=$PG_PASSWORD" > .env

Точные имена переменных окружения у Documenso время от времени меняются вместе с релизами — перед запуском сверьтесь с файлом .env.example в репозитории проекта на GitHub, чтобы не ловить неожиданный несовпадающий ключ.

Поднимаем:

docker compose up -d
docker compose logs -f documenso

При первом запуске контейнер сам прогонит миграции Prisma к базе — в логах это видно по строкам Applying migration. Если база пуста и переменные подключения верны, процесс занимает секунды.

Домен, HTTPS и обратный прокси

Documenso жёстко завязан на NEXTAUTH_URL и NEXT_PUBLIC_WEBAPP_URL — эти значения должны совпадать с реальным адресом, по которому открывается сервис, включая схему https://. Несовпадение ломает не только вход, но и ссылки в письмах подписантам: получатель откроет письмо, а ссылка поведёт на неправильный домен или порт.

Проще всего поставить перед контейнером Caddy — он сам получает и продлевает сертификат Let's Encrypt:

# /etc/caddy/Caddyfile
sign.example.com {
    reverse_proxy 127.0.0.1:3000
}

systemctl reload caddy

Подробный разбор установки Caddy с автоматическим HTTPS — в статье как установить и настроить Caddy с авто-SSL на VPS. Если предпочитаете классику — Nginx плюс Certbot, — шаги для этого варианта есть в материале как установить и настроить Let's Encrypt SSL на VPS; принцип тот же: прокси слушает 443, отдаёт трафик на 127.0.0.1:3000.

После того как домен открывается по HTTPS без предупреждений браузера, зайдите на https://sign.example.com и создайте первого пользователя — это будет администратор инстанса.

Почта и сертификат для электронной подписи

Без рабочего SMTP подписанты не получат письмо со ссылкой на документ — вся цепочка подписания остановится на первом шаге. В documenso.env добавьте блок с вашим почтовым сервером:

NEXT_PRIVATE_SMTP_TRANSPORT=smtp-auth
NEXT_PRIVATE_SMTP_HOST=smtp.example.com
NEXT_PRIVATE_SMTP_PORT=587
NEXT_PRIVATE_SMTP_USERNAME=noreply@example.com
NEXT_PRIVATE_SMTP_PASSWORD=<пароль или пароль приложения>
NEXT_PRIVATE_SMTP_FROM_ADDRESS=noreply@example.com
NEXT_PRIVATE_SMTP_FROM_NAME=Documenso

После правки — docker compose restart documenso и проверка: отправьте тестовый документ на свой второй ящик и убедитесь, что письмо дошло и ссылка открывается.

Второй обязательный элемент — сертификат для криптографической подписи PDF. Documenso подписывает готовый документ сертификатом в формате .p12, путь к которому указан в NEXT_PRIVATE_SIGNING_LOCAL_FILE_PATH. Для теста и внутреннего использования достаточно самоподписанного сертификата:

cd /opt/documenso/cert
openssl req -x509 -newkey rsa:2048 -keyout key.pem -out cert.pem \
  -days 3650 -nodes -subj "/CN=Documenso Signing/O=Your Company"
openssl pkcs12 -export -out cert.p12 -inkey key.pem -in cert.pem \
  -passout pass:ваш_пароль_из_signing_passphrase
rm key.pem cert.pem

Важный нюанс: самоподписанный сертификат подтверждает, что документ не менялся после подписания, но не подтверждает личность подписанта перед сторонними системами — Adobe Reader откроет такой PDF с пометкой «подлинность подписи не может быть проверена», потому что сертификат не выпущен доверенным центром. Для документов, которым нужна юридически значимая подпись с доверенной цепочкой, потребуется приобрести сертификат у удостоверяющего центра и использовать его вместо самоподписанного — механизм подключения тот же файл .p12, меняется только источник сертификата.

Бэкапы, обновление и безопасность

Вся ценность инстанса — в базе Postgres и сертификате подписи, остальное можно развернуть заново. Бэкапьте оба:

#!/bin/bash
# /opt/documenso/backup.sh
DATE=$(date +%F)
docker exec documenso-postgres pg_dump -U documenso documenso | gzip > /opt/backups/documenso-db-$DATE.sql.gz
tar czf /opt/backups/documenso-cert-$DATE.tar.gz -C /opt/documenso cert
find /opt/backups -name "documenso-*" -mtime +14 -delete

Добавьте в crontab -e:

0 3 * * * /opt/documenso/backup.sh

Дамп базы без файла сертификата бесполезен — потеряв cert.p12, вы не сможете сгенерировать точно такой же сертификат, и подписывать новые документы прежним ключом уже не выйдет. Копируйте оба файла синхронно и держите архив вне сервера.

Обновление — стандартное для Compose:

docker compose pull documenso
docker compose up -d documenso

Перед обновлением на новую мажорную версию сделайте свежий бэкап базы: миграции схемы применяются автоматически при старте контейнера и откатить их без дампа сложно. Из базовой безопасности — регулярно обновляйте образ postgres, ограничьте SSH-доступ ключами, а сам NEXT_PRIVATE_SIGNING_PASSPHRASE и пароль от базы храните вне репозитория с конфигами, если публикуете compose.yaml куда-либо (например, в приватный git для истории изменений).

Частые вопросы