DocuSeal: Self-Hosted Document Signing Under AGPL-3.0

What DocuSeal solves, and who actually needs it

The problem is narrow and familiar. You have a PDF that needs a signature, an initial, a date, or an uploaded file from someone outside your organisation, and you want that to happen in a browser without a per-envelope invoice. DocuSeal is a web application that lets you place form fields on a PDF, send a link, and collect the filled and signed result. The README describes it as an open source platform for digital document signing and processing, with a WYSIWYG PDF form field builder and 12 field types including signature, date, file and checkbox. Multiple submitters can act on one document, which is the case that matters for anything with a countersignature.

The audience is teams that already run their own infrastructure and treat document data as something they would rather not hand to a third party. The Docker deployment path is the clearest signal here: a single image, a volume for data, and an optional database URL. If you are a solo user who signs two PDFs a year, the operational overhead of a container, a volume and a reverse proxy is larger than the task. If you are a company that needs a signing step inside an existing product, the API and webhooks listed in the README are the relevant part, not the web UI.

One boundary is worth stating early. The README splits its feature list into standard and Pro. Automated reminders, user roles, conditional fields, bulk send with CSV or XLSX import, SSO/SAML and identity verification via SMS sit on the Pro side. A self-hosted install gives you the signing core; it does not give you the whole product as marketed.

How the signing flow is put together

The repository layout tells you most of the architecture. This is a Ruby on Rails application (app/, config/, db/, Gemfile, config.ru) with a Shakapacker and webpack front end (package.json, config/webpack, tailwind configs). The Dockerfile is multi-stage: a download stage that fetches fonts and a pdfium binary, a webpack stage that compiles assets with yarn, and presumably a runtime stage after that. The presence of a pinned pdfium binary and a downloaded ONNX model from the docusealco/fields-detection release suggests that field detection runs locally inside the container rather than as an external service call.

Data flow is conventional for this class of application. A document is stored on disk or in S3, Google Storage or Azure, per the README feature list. Submitters interact through the web tool, which the README describes as mobile-optimized. Notifications go out over SMTP. Integrations attach through the API and webhooks. The database defaults to SQLite inside the container and switches to PostgreSQL or MySQL when DATABASE_URL is set, which the README states explicitly. That default is the single most consequential design choice for operators: it makes the first run trivial and makes concurrent production use a decision you have to make deliberately.

The docker-compose.yml in the repository shows what the maintainers consider a realistic deployment: an app service, a postgres:18 service with a healthcheck, and Caddy acting as a reverse proxy that issues certificates. The app service passes FORCE_SSL set to the HOST value and a DATABASE_URL pointing at the postgres service. If you want to know what a supported setup looks like, that file is a better guide than the one-line docker run.

Installing DocuSeal with Docker and signing your first document

The README gives a single command for the quickest start. It runs the published image, maps port 3000, and mounts the current directory as /data so the SQLite database and uploaded files survive a container restart.

docker run --name docuseal -p 3000:3000 -v.:/data docuseal/docuseal

After that, the application should be reachable on port 3000 of the host. The README does not document the first-run account creation step, so treat the initial page as something you discover rather than something you are walked through.

If you would rather run the supported stack with PostgreSQL and automatic HTTPS, the README points at the compose file in the repository. Download it, then start it with HOST set to a domain whose DNS already points at the server, because Caddy issues certificates during startup.

curl https://raw.githubusercontent.com/docusealco/docuseal/master/docker-compose.yml > docker-compose.yml
sudo HOST=your-domain-name.com docker compose up

To move off SQLite, set DATABASE_URL to a PostgreSQL or MySQL connection string. The compose file shows the expected shape for the bundled Postgres service:

environment:
  - FORCE_SSL=${HOST}
  - DATABASE_URL=postgresql://postgres:postgres@postgres:5432/docuseal

Once the app is up, the practical first exercise is to upload a PDF, place a signature field and a date field on it, and send it to yourself. That covers the field builder, the submitter view and the completed-document storage path in one pass. The README also lists PDF signature verification as a feature, which is the step to check on the returned file if you care about proving the signature rather than just collecting it.

Where DocuSeal is the wrong tool

The licence is the first limitation, and it is not a footnote. DocuSeal is distributed under AGPL-3.0 with Section 7(b) additional terms, and the repository carries a separate LICENSE_ADDITIONAL_TERMS file. Section 7(b) is the mechanism a licensor uses to attach extra conditions to an AGPL grant. The README does not summarise what those terms say, so anyone embedding DocuSeal in a product that users reach over a network needs to read both files rather than assume the AGPL text alone governs. This article is not legal advice, and the licence files are the only authority here.

The second limitation is the standard-versus-Pro split. Several capabilities that people assume come with a signing platform, notably automated reminders, SSO/SAML, SMS identity verification and bulk send from a spreadsheet, are listed as Pro features. A self-hosted deployment does not turn those on. If your workflow depends on reminders because submitters ignore email, you are either building that on top of the webhooks or paying.

The third is operational. The default SQLite database is fine for a single instance and a low volume of documents, but the README presents PostgreSQL and MySQL as the alternative for a reason. Anything with concurrent submitters, multiple app replicas or a backup policy that does not involve copying a file out of a container volume should move to a real database server before it carries production traffic. The README does not document rollback, migration between database backends, or a backup procedure, so those are gaps you have to close yourself.

Finally, the project is not aimed at you if you want a managed service with a support contract and no server. The README links to a cloud sign-up for exactly that, and the self-hosted path is the one that assumes you own the uptime.

DocuSeal compared with DocuSign, and with building it yourself

The comparison people search for is DocuSeal versus DocuSign, and the honest difference is not feature parity. DocuSign is a hosted service where the vendor operates the infrastructure, the signing certificate chain and the compliance paperwork. DocuSeal is software you run. That flips who is responsible for availability, data location, backups and the audit trail. For a team that already has a server, a database and a backup routine, that trade is attractive. For a team without any of those, DocuSign is buying operations, not just signatures.

The second alternative is not a product at all: assembling the same capability from a PDF library and your own form handling. That is viable when the requirement is genuinely one signature field on one template, and it avoids adopting a Rails application and its upgrade cadence. It stops being viable the moment you need multiple submitters, a mobile-friendly signing page, field placement that a non-developer can adjust, or a webhook that tells your system when the document is complete. Those are the parts DocuSeal already implements, and rebuilding them is the actual cost comparison, not the price of a licence.

A third option worth naming is the embedded route. The repository links separate React, Vue and Angular packages for embedded signing and embedded form building, and the README documents an HTML API and a PDF or DOCX field-tag API for template creation. If your goal is to put signing inside an existing application rather than run a standalone portal, those integration surfaces are the reason to pick DocuSeal over a generic PDF signing library.

Maintenance, upgrade cost and the licence question

The repository is not archived, and the last push was on 2026-08-25, which is recent enough that the project is being worked on rather than parked. Release numbering is in the 3.x line, with 3.2.0, 3.2.1 and 3.2.2 all published in August 2026. A patch cadence that tight usually means fixes are moving quickly, and it also means you should not pin to a stale image and forget it.

The upgrade cost is dominated by two things. First, the Dockerfile pins ruby:4.0.5-alpine and pulls a specific pdfium release and a specific ONNX model version. Those are baked into the image, so rebuilding from the Dockerfile is not the same operation as pulling a newer tag. Second, the database schema lives in db/, which means a version jump can carry migrations. The README does not describe a downgrade path or a schema compatibility policy, so the safe assumption is that upgrades go forward and that you test them against a copy of your data before touching the live instance. Back up the /data volume or the PostgreSQL database first; that is the only recovery mechanism the repository supports.

On licence: AGPL-3.0 with Section 7(b) additional terms, plus the LICENSE_ADDITIONAL_TERMS file in the repository root. The practical implication for most readers is that if you modify DocuSeal and let users interact with it over a network, the AGPL obligations are likely to attach to your modified version, and the additional terms may add conditions on top. Whether that is acceptable for your product is a question for your own counsel, and the two licence files are what they should read. Nothing in the README substitutes for that.

Editorial conclusion

Adopt DocuSeal if you need a self-hosted signing flow, are comfortable running a Rails application in Docker, and can live with the AGPL-3.0 additional terms. Do not adopt it if you need the Pro features (white-label, SSO/SAML, SMS verification, bulk CSV send) without paying, or if your legal team rejects the Section 7(b) terms. Before you commit, verify two things: whether the features you actually need sit on the Pro list, and whether your intended use matches the additional terms attached to the licence. Start with the single-container run and a throwaway PDF before you point a domain at it.

Frequently asked questions

Official sources

1. Official documentation
2. Official README
3. Project repository
4. Release notes