# Project pack: DocuSeal @ 8f8f69f

Facts about **DocuSeal** for an AI following the [BespokeAI handover guide](https://handoff.bespokeai.software/guide/v2.md). This pack is pinned to one version and never changes after publication.

> DocuSeal lets you send documents to be signed online, like DocuSign but running on your own server. Upload a PDF or Word file, drag signature, date and text boxes onto it, and email a link to each person who needs to sign. They can sign on a phone or a computer, and everyone gets a signed PDF with a record of who signed and when. Good for tenancy agreements, client contracts, consent forms and club sign-ups.

## Version and source
- Repository: https://github.com/docusealco/docuseal
- Pinned commit: `8f8f69f0bc6ac2e59746cd6efac54a852289bec3`. Use exactly this version.
- Fresh checkout: use the setup below in an empty folder. If you already have this exact source checked out, keep your branch and use the development command instead; do not clone again or reset local changes.
- Or download a zip: https://github.com/docusealco/docuseal/archive/8f8f69f0bc6ac2e59746cd6efac54a852289bec3.zip
- Official docs: https://www.docuseal.com/docs
- Live demo: https://demo.docuseal.tech. Official live demo linked from the README. Don't upload real documents.
- Licence: **AGPL-3.0-only**. Free to use and change. If you run a changed version that other people use over the internet (for example clients who sign your documents), you must offer them your source code under the same licence. An extra term says you must keep the DocuSeal attribution visible in the app's screens. Some features (company logo, reminders, SMS, bulk sending, conditional fields) are only in the paid Pro edition.

## Running the pinned source
- Fresh pinned-source setup (skip clone and checkout in an existing worktree):

  ```sh
  git clone https://github.com/docusealco/docuseal bespoke-docuseal
  cd bespoke-docuseal
  git checkout --detach 8f8f69f0bc6ac2e59746cd6efac54a852289bec3
  # Prepare development requirements and local configuration first.
  # Setup notes: and in another terminal: bundle exec ./bin/shakapacker-dev-server (both listed in Procfile.dev)
  bundle install && yarn install && bundle exec rails db:create db:migrate && bundle exec rails s -p 3000
  ```

The commands below are a starting point from the reviewed source. Prepare the listed tools, local configuration and companion services before starting the app. These instructions have not yet been validated in participant sessions.

### Separate trial of the current release
This tries an upstream release, which may differ from the pinned source above. It does not run your source changes. Use only sample data and a separate data directory or volume. Check the upstream documentation before running it.

  ```sh
  docker run --name docuseal -p 3000:3000 -v docuseal-data:/data docuseal/docuseal
  # then open http://localhost:3000 and create the first (admin) account.
  # For a public server with HTTPS, use the repo's docker-compose.yml instead:
  #   sudo HOST=your-domain.com docker compose up
  ```

- Needs: Docker, For development, Ruby 4.0.5, Node 20 with Yarn, libvips and leptonica, plus PostgreSQL or SQLite
- Develop: `bundle install && yarn install && bundle exec rails db:create db:migrate && bundle exec rails s -p 3000   # and in another terminal: bundle exec ./bin/shakapacker-dev-server (both listed in Procfile.dev)`
- Test: `bundle exec rspec   # system tests need Chrome; see .github/workflows/ci.yml`
- Check/lint: `bundle exec rubocop && bundle exec erb_lint ./app && ./node_modules/eslint/bin/eslint.js 'app/javascript/**/*.js'`
- Stack: ruby, javascript, vue (Ruby on Rails 8, Hotwire Turbo, Vue 3, Tailwind CSS, daisyUI, Shakapacker, Sidekiq, HexaPDF). Difficulty for a non-developer with an AI: **moderate**. A standard Rails app. Email wording, the message after signing, policy links, languages, storage and webhooks are settings. Screens are ERB templates in app/views/ with small JavaScript elements; the drag-and-drop form builder (app/javascript/template_builder/) and the signing form (app/javascript/submission_form/) are Vue apps. PDF handling and signing logic is delicate, so code changes need care and testing.

## Customisation points (settings → extend → code)
- **email-templates-and-messages** [settings]: Wording of the signing request and completion emails, the message and button shown after signing, and policy links. → `Settings → Personalization (app/views/personalization_settings/show.html.erb)`
- **email-and-storage** [settings]: Connect your own mail server and choose where documents are kept. → `Settings → Email and Settings → Storage (app/controllers/email_smtp_settings_controller.rb, storage_settings_controller.rb)`
- **languages** [settings]: The app comes in several languages and signers can see the form in 14 languages. → `User profile and signing form language (config/application.rb available_locales, config/locales/i18n.yml)`
- **webhooks** [extend]: Tell another tool (n8n, Zapier, a spreadsheet script) when a document is opened, signed or declined. → `Settings → Webhooks (app/controllers/webhook_settings_controller.rb)`
- **api** [extend]: Create submissions from your own scripts, e.g. send a contract when someone books. → `Settings → API (app/controllers/api_settings_controller.rb); API controllers in app/controllers/api/; docs at docuseal.com/docs/api`
- **mcp** [extend]: Let an AI assistant search templates, create a template and send documents for signing through DocuSeal's built-in MCP server. → `Settings → MCP (app/controllers/mcp_settings_controller.rb); endpoint /mcp (app/controllers/mcp_controller.rb)`
- **signing-form** [code]: How the signing page looks and behaves for the person signing. → `app/javascript/submission_form/ (Vue) and app/views/submit_form/`
- **form-builder** [code]: The drag-and-drop editor where you place fields on a document. → `app/javascript/template_builder/ (Vue)`
- **backend** [code]: New behaviour or data. Database changes need a Rails migration. → `app/controllers/, app/models/, lib/submissions/, lib/templates/, db/migrate/`

## Must keep working
- Signed documents and their audit trail. Never change or delete completed submissions; back up before upgrades or code changes.
- The digital signature on finished PDFs and the signature verification page.
- Keep the DocuSeal attribution visible in the screens; the licence's additional terms require it.
- Signing links already sent out must keep working.
- Database changes need a Rails migration in db/migrate/.

## Staying updatable
Personalisation settings, webhooks, the API and the MCP endpoint cover most needs without a fork. Several features you may want (logo, reminders, conditional fields) are in the paid Pro edition, so rebuilding them yourself is possible under the AGPL but makes merging upstream updates harder. There is no AGENTS.md or contributing guide upstream.

## Data, costs and safety
- Personal data: **yes**. Stored in: SQLite database and uploaded files in /data/docuseal inside the container (the docuseal-data volume), or PostgreSQL/MySQL plus S3, Google Cloud or Azure storage if configured. Signed contracts, names, email addresses, IP addresses and signatures. Back up the whole data folder (it also holds the generated secret key) or the database plus file storage. Signed PDFs can be downloaded from each submission.
- Service: Email (SMTP) (optional, free with most providers): Sends signing invitations and the finished, signed copies. Without it you share signing links yourself.
- Service: AWS S3, Google Cloud Storage or Azure Blob Storage (optional, pay-per-use): Store documents in the cloud instead of on the server's disk.
- Service: DocuSeal Pro licence (optional, paid (see docuseal.com/pricing)): Company logo and white-label, user roles, automatic reminders, SMS verification, conditional fields, bulk sending, SSO.
- Setting `DATABASE_URL` (**secret**: the person enters it themselves, never in chat): PostgreSQL or MySQL connection string. Leave unset to use the built-in SQLite database in /data.
- Setting `SECRET_KEY_BASE` (**secret**: the person enters it themselves, never in chat): Main encryption key. Created and saved in the data folder on first start if unset. Back it up and never paste it into an AI chat.
- Setting `FORCE_SSL`: Set to your domain when DocuSeal is served over HTTPS (the compose file does this from HOST).
- Setting `HOST`: Your domain name, used by the docker-compose file to get an HTTPS certificate with Caddy.
- Setting `SMTP_ADDRESS`: Mail server for sending emails. SMTP_PORT, SMTP_USERNAME, SMTP_PASSWORD and SMTP_DOMAIN go with it. You can also set email up in Settings.
- Setting `SMTP_PASSWORD` (**secret**: the person enters it themselves, never in chat): Password for the mail server.
- Setting `REDIS_URL`: External Redis for background jobs. The Docker image runs its own if unset.
- Signers must be able to reach your DocuSeal from the internet, so put it behind HTTPS (the compose file uses Caddy for this) and keep it updated.
- Documents often hold addresses, ID numbers and signatures. Limit who has admin accounts and back up the data folder securely.
- API keys, MCP tokens and webhook secrets give full access to your documents. Keep them out of AI chats and shared files.
- An e-signature's legal standing depends on your country and the document type. DocuSeal records an audit trail, but check what your situation needs.

---

# Customising DocuSeal

DocuSeal is a Ruby on Rails app with two Vue screens (the form builder and the signing form). **Most small-business needs are settings, templates, webhooks or the API.** Signing and PDF code is delicate, so treat code changes with care.

## Level 1: Settings (no code)
- **Templates:** upload a PDF, Word file or image, drag fields onto it (signature, initials, date, text, checkbox, file, and more) and choose who fills in each field. Reuse the template for every new client.
- **Email wording:** Settings → Personalization. Edit the signing request email, the "here is your copy" email and the completion email sent to you.
- **After signing:** in the same page, set the message shown after signing, a redirect button and policy links.
- **Email server:** Settings → Email (or `SMTP_*` environment variables). Without it you copy signing links and send them yourself.
- **Storage:** Settings → Storage. Keep files on disk, or use S3, Google Cloud Storage or Azure.
- **Language:** the app has several interface languages and the signing form supports 14.
- **Users:** add colleagues in Settings → Users.

Company logo, automatic reminders, SMS checks, conditional fields and bulk sending are in the paid Pro edition.

## Level 2: Extend (no fork)
- **Webhooks** (Settings → Webhooks): get a POST when a form is viewed, started, completed or declined. Connect it to n8n, Zapier, Make or a small script.
- **REST API** (Settings → API for the key; reference at https://www.docuseal.com/docs/api): create submissions from templates, prefill fields, download signed documents.
- **MCP server** (Settings → MCP for a token; endpoint `/mcp`): lets an AI assistant search templates, load or create a template, send documents and search signed documents.
- **Embedding:** official React, Vue, Angular and JavaScript components exist, but embedding is a Pro feature.

## Level 3: Code
There is no upstream AGENTS.md. Follow normal Rails conventions and the existing RuboCop and ESLint settings.

| Change | Where |
|---|---|
| Signing page for signers | `app/javascript/submission_form/` (Vue) and `app/views/submit_form/` |
| Drag-and-drop form builder | `app/javascript/template_builder/` (Vue) |
| Other screens | `app/views/**` (ERB with Tailwind/daisyUI), small custom elements in `app/javascript/elements/` |
| Settings pages | `app/controllers/*_settings_controller.rb` + `app/views/*_settings/` |
| Submission and template logic | `lib/submissions/`, `lib/templates/` |
| API | `app/controllers/api/` |
| Data | `app/models/` + a migration in `db/migrate/` |
| Text and translations | `config/locales/i18n.yml` |

## Running locally
- **Just use it:** `docker run --name docuseal -p 3000:3000 -v docuseal-data:/data docuseal/docuseal`, then open http://localhost:3000 and create the admin account.
- **Public server with HTTPS:** download `docker-compose.yml` from the repo and run `sudo HOST=your-domain.com docker compose up` (Postgres + Caddy).
- **Develop:**
  1. Install Ruby 4.0.5, Node 20 with Yarn, libvips and leptonica.
  2. Run `bundle install` and `yarn install`.
  3. Run `bundle exec rails db:create db:migrate`.
  4. Start `bundle exec rails s -p 3000` and `bundle exec ./bin/shakapacker-dev-server` (see `Procfile.dev`).
- **Check:** `bundle exec rubocop`, `bundle exec erb_lint ./app`, ESLint on `app/javascript/**/*.js`, `bundle exec rspec`.

## Pitfalls
- Back up the data folder first. It holds signed contracts and the generated `SECRET_KEY_BASE`; lose the key and encrypted settings are unreadable.
- Never edit completed submissions or their PDFs. That would break the signature and the audit trail.
- The licence's extra term requires the DocuSeal attribution to stay visible in the screens. Don't remove it.
- Test the full flow (create template, send, sign on a phone, download the signed PDF) after any change.

---
Machine-readable: [bespoke.yaml](https://handoff.bespokeai.software/p/docuseal/8f8f69f/r2/bespoke.yaml) · Hosting options: [hosting.md](https://handoff.bespokeai.software/p/docuseal/8f8f69f/r2/hosting.md) · Agent skill: [SKILL.md](https://handoff.bespokeai.software/p/docuseal/8f8f69f/r2/SKILL.md)