Documenso на Ubuntu 24.04: пошаговая установка

MAATRIX

DocuSign работает через VPN и с карты российского банка не оплачивается — это первая стена, в которую упирается любой, кому нужно собрать пару подписей под договором. Documenso — открытая платформа электронной подписи документов: загружаете PDF, расставляете поля для подписи, отправляете ссылку получателю — и всё это можно развернуть на своём сервере, без привязки к чужому биллингу. Разворачиваем её на Ubuntu 24.04 в Docker: от чистой системы до рабочего инстанса с сертификатом подписи, почтой и HTTPS.

Что такое Documenso и что он умеет

Documenso — open source альтернатива DocuSign и Adobe Sign: загрузка PDF, произвольная расстановка полей (подпись, дата, текст, чекбокс), рассылка ссылок получателям по очереди или параллельно, отслеживание статуса и итоговый подписанный документ с журналом действий внутри файла. Проект распространяется под лицензией AGPLv3, и базовый сценарий — один documenso-инстанс для команды или личного использования — полностью открыт и бесплатен. Часть функций (SSO, продвинутые командные роли, отдельные интеграции) в разных версиях проекта была вынесена в платное Enterprise-издание — перед тем как полагаться на конкретную функцию, стоит свериться с актуальным списком возможностей community-версии на GitHub проекта.

Важный юридический нюанс: самостоятельно сгенерированный сертификат для подписи (об этом ниже) даёт технически валидную цифровую подпись формата PAdES — она подтверждает целостность документа и факт подписания, встраивается прямо в PDF и проверяется любым просмотрщиком. Но это не то же самое, что квалифицированная электронная подпись, юридический статус которой закреплён законодательством конкретной страны. Для внутренних процессов, согласований, договоров с фрилансерами и партнёрами, где стороны заранее договорились принимать такую подпись, Documenso полностью закрывает задачу. Если нужна КЭП с полной юридической силой без дополнительных соглашений сторон — это отдельная история про удостоверяющие центры, Documenso её не заменяет.

Приложение — это Next.js-монорепозиторий на Prisma с базой PostgreSQL, поэтому под него нужен сервер весомее, чем под лёгкий бэкенд-сервис: комфортно работать от 2 ядер и 4 ГБ памяти, а для первого запуска и накопления вложений документов стоит сразу заложить диск с запасом — сканы и подписанные PDF со временем занимают заметно больше места, чем кажется на старте. У MAATRIX такой VPS на Ubuntu 24.04 оплачивается из России картой, по СБП, криптой или токеном MAAT, локацию можно взять под задачу — RU или UK ближе к российским и европейским получателям документов.

Шаг 1. Подготовка сервера и домена

Обновите систему и закройте периметр фаерволом — снаружи должны остаться только SSH и веб-порты:

apt update && apt upgrade -y
ufw allow 22/tcp && ufw allow 80,443/tcp && ufw enable

Заведите домен или поддомен и направьте его A-запись на IP сервера — он нужен и для HTTPS-сертификата, и для корректных ссылок в письмах-приглашениях, которые Documenso отправляет получателям документа. Если настраиваете домен и DNS впервые, разбор с нуля есть в статье про настройку домена и DNS на Ubuntu 24.04. После добавления записи проверьте распространение командой dig +short vash-domen.ru — она должна вернуть IP сервера.

Установите Docker официальным скриптом — подробности разобраны в статье про установку Docker с нуля:

curl -fsSL https://get.docker.com | sh
docker compose version

Создайте рабочую директорию проекта — в неё сложатся конфиги, сертификат подписи и docker-compose.yml:

mkdir -p /opt/documenso/certs
cd /opt/documenso

Шаг 2. Сертификат для цифровой подписи документов

Это шаг, которого нет у большинства других self-hosted сервисов, но без него Documenso не сможет ставить криптографическую подпись на PDF. Нужен файл сертификата в формате PKCS#12 (.p12) — сгенерируйте его прямо на сервере через openssl:

cd /opt/documenso/certs
openssl req -x509 -newkey rsa:2048 -keyout key.pem -out cert.pem -days 3650 -nodes -subj "/CN=documenso"
openssl pkcs12 -export -out cert.p12 -inkey key.pem -in cert.pem -passout pass:ЗамениНаСвойПароль
chmod 600 cert.p12

Флаг -days 3650 задаёт срок действия сертификата в десять лет — для внутреннего инструмента этого достаточно, продлевать раньше не придётся. Пароль из -passout понадобится в переменных окружения на следующем шаге, сохраните его в менеджере паролей — без него Documenso не сможет открыть файл сертификата при старте контейнера.

Обратите внимание: это сертификат для подписи документов, он не имеет отношения к TLS-сертификату для HTTPS — тот получится отдельно и автоматически через реверс-прокси в шаге 5. Если важна цепочка доверия к конкретному удостоверяющему центру, а не самоподписанный сертификат, тот же способ подойдёт для сертификата от вашего CA — достаточно заменить пару cert.pem/key.pem на выданные удостоверяющим центром перед экспортом в .p12.

Шаг 3. Docker Compose, база данных и переменные окружения

Создайте docker-compose.yml с сервисами PostgreSQL и самим приложением. Порт наружу не открываем — доступ пойдёт через реверс-прокси:

services:
  database:
    image: postgres:16
    restart: always
    environment:
      POSTGRES_USER: documenso
      POSTGRES_PASSWORD: StrongPassHere
      POSTGRES_DB: documenso
    volumes:
      - documenso_db:/var/lib/postgresql/data

  documenso:
    image: documenso/documenso:latest
    restart: always
    depends_on:
      - database
    env_file: .env
    volumes:
      - ./certs/cert.p12:/opt/documenso/cert.p12:ro
      - documenso_uploads:/app/uploads
    ports:
      - "127.0.0.1:3000:3000"

volumes:
  documenso_db:
  documenso_uploads:

Официальный образ на Docker Hub избавляет от сборки монорепозитория на сервере — в отличие от многих Next.js-проектов, здесь не нужно ждать долгую компиляцию, контейнер стартует из готового образа. Теперь создайте .env рядом с compose-файлом:

NEXTAUTH_URL=https://vash-domen.ru
NEXT_PUBLIC_WEBAPP_URL=https://vash-domen.ru
NEXTAUTH_SECRET=<сгенерированная строка>
DATABASE_URL=postgresql://documenso:StrongPassHere@database:5432/documenso

NEXT_PRIVATE_ENCRYPTION_KEY=<сгенерированная строка>
NEXT_PRIVATE_ENCRYPTION_SECONDARY_KEY=<вторая сгенерированная строка>

NEXT_PRIVATE_SIGNING_TRANSPORT=local
NEXT_PRIVATE_SIGNING_LOCAL_FILE_PATH=/opt/documenso/cert.p12
NEXT_PRIVATE_SIGNING_PASSPHRASE=ЗамениНаСвойПароль

NEXT_PRIVATE_SMTP_TRANSPORT=smtp-auth
NEXT_PRIVATE_SMTP_HOST=smtp.vash-provider.ru
NEXT_PRIVATE_SMTP_PORT=587
NEXT_PRIVATE_SMTP_USERNAME=noreply@vash-domen.ru
NEXT_PRIVATE_SMTP_PASSWORD=<пароль-smtp>
NEXT_PRIVATE_SMTP_FROM_ADDRESS=noreply@vash-domen.ru
NEXT_PRIVATE_SMTP_FROM_NAME=Documenso

Секреты и ключи шифрования генерируются одной командой, для каждой переменной — отдельным запуском:

openssl rand -hex 32

NEXT_PRIVATE_ENCRYPTION_KEY и NEXT_PRIVATE_ENCRYPTION_SECONDARY_KEY шифруют чувствительные данные в базе; менять их после первого запуска нельзя, иначе расшифровка старых записей сломается, так что сгенерируйте и сохраните сразу. Без корректного SMTP-блока приложение всё равно поднимется, но письма с приглашением подписать документ уходить не будут — для инструмента, который по сути и есть переписка с получателями, это критично. Названия переменных у проекта время от времени меняются между релизами, поэтому стоит свериться с файлом .env.example в официальном репозитории на GitHub — если переменная переименована, в логах контейнера при старте это обычно видно сразу.

Если предпочитаете вынести базу на отдельный сервер вместо контейнера — общий подход описан в статье про установку PostgreSQL на Ubuntu 24.04, а в DATABASE_URL тогда указывается адрес этого сервера вместо имени сервиса database.

Шаг 4. Запуск

Скачайте образ и поднимите оба сервиса:

docker compose pull
docker compose up -d
docker compose logs -f documenso

При первом старте приложение само применяет миграции базы данных — в логах должны появиться записи о применённых миграциях Prisma, а следом сообщение о готовности сервера на порту 3000. Если контейнер перезапускается в цикле сразу после старта — почти всегда причина в опечатке одной из переменных окружения (особенно в пути к сертификату или в DATABASE_URL) либо в правах доступа к файлу cert.p12 внутри контейнера. Проверьте, что путь в NEXT_PRIVATE_SIGNING_LOCAL_FILE_PATH совпадает с точкой монтирования в docker-compose.yml.

Шаг 5. HTTPS через реверс-прокси

Отправлять документы и принимать подписи по незашифрованному каналу нельзя — через форму проходят персональные данные подписантов и содержимое договоров. Проще всего поставить перед контейнером Caddy — сертификат он выпустит и продлит сам, разбор есть в статье про Caddy с автоматическим SSL. Минимальный конфиг:

vash-domen.ru {
    reverse_proxy 127.0.0.1:3000
}

Если используете Nginx — тот же принцип: серверный блок с доменом, проксирование запросов на локальный порт 3000, сертификат от certbot, увеличенный лимит client_max_body_size (сканы договоров и многостраничные PDF легко превышают дефолтный 1 МБ):

server {
    listen 443 ssl;
    server_name vash-domen.ru;
    client_max_body_size 25m;

    location / {
        proxy_pass http://127.0.0.1:3000;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    }
}

После настройки прокси наружу торчит только 443-й порт, приложение остаётся доступным исключительно с локального адреса сервера.

Шаг 6. Первый вход и отправка документа на подпись

Откройте домен в браузере после того, как сертификат выпустился и DNS распространился. Documenso предложит зарегистрировать первую учётную запись — она автоматически становится администратором организации в этом инстансе. Задайте надёжный пароль и, если версия это поддерживает, сразу включите двухфакторную аутентификацию в настройках профиля — от аккаунта администратора зависит доступ ко всем загруженным договорам.

Дальше рабочий цикл простой: загружаете PDF, расставляете поля (подпись, дата, инициалы, текстовое поле, чекбокс) для каждого получателя, задаёте порядок подписания при необходимости и отправляете. Получатель переходит по ссылке из письма, ставит подпись прямо в браузере без регистрации, и итоговый файл с встроенной подписью и журналом событий приходит всем сторонам на почту. Для регулярной отправки одного типа договора удобно сохранить шаблон — это экономит время на повторной расстановке полей.

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