Skip to content

The Open Source DocuSign Alternative.

chore: add docs for ai features (#2284)

Lucas Smith74ad6af47de4
diff --git a/apps/documentation/pages/developers/self-hosting/_meta.js b/apps/documentation/pages/developers/self-hosting/_meta.js
index 04897c3b9..b8edc6838 100644
--- a/apps/documentation/pages/developers/self-hosting/_meta.js
+++ b/apps/documentation/pages/developers/self-hosting/_meta.js
@@ -4,4 +4,5 @@ export default {
'how-to': 'How To',
'setting-up-oauth-providers': 'Setting up OAuth Providers',
telemetry: 'Telemetry',
+ 'ai-features': 'AI Recipient & Field Detection',
};
diff --git a/apps/documentation/pages/developers/self-hosting/ai-features.mdx b/apps/documentation/pages/developers/self-hosting/ai-features.mdx
new file mode 100644
index 000000000..6b7e934b0
--- /dev/null
+++ b/apps/documentation/pages/developers/self-hosting/ai-features.mdx
@@ -0,0 +1,72 @@
+---
+title: AI Recipient & Field Detection (Self-hosting)
+description: Configure Google Vertex AI so Documenso can detect recipients and fields automatically.
+---
+
+import { Callout, Steps } from 'nextra/components';
+
+# AI Recipient & Field Detection (Self-hosting)
+
+This guide covers how to enable the AI recipient and field detection features when you self-host Documenso.
+
+## What this enables
+
+- Detect recipients from uploaded PDFs (roles, names, emails when present).
+- Detect and place fields (signature, initials, name, email, date, text, number, radio, checkbox) onto draft envelopes.
+- Built-in rate limits (3 requests per minute per IP) to prevent abuse.
+
+## Prerequisites
+
+- A Google Cloud project with the **Vertex AI API** enabled and billing active.
+- A **Vertex AI Express API key** with access to Gemini models (create via the [Vertex AI Express flow](https://cloud.google.com/vertex-ai/generative-ai/docs/start/express-mode/overview) and manage keys in [API keys](https://cloud.google.com/vertex-ai/generative-ai/docs/start/api-keys)).
+- Documenso version that includes the AI detection feature and the corresponding database migration.
+
+## Configure environment variables
+
+Add these variables to your deployment `.env` (or secret manager):
+
+```
+GOOGLE_VERTEX_PROJECT_ID="<your-gcp-project-id>"
+GOOGLE_VERTEX_API_KEY="<your-vertex-api-key>"
+# Optional, defaults to "global"
+GOOGLE_VERTEX_LOCATION="global"
+```
+
+<Callout type="info">
+ Use a region close to your users if you need data residency considerations (e.g. `europe-west1`).
+ If you omit the location, Documenso uses `global`. Not all models are available in every region;
+ if a model is unavailable, switch to a supported region.
+</Callout>
+
+## Deploy with the published container
+
+- Use the official Documenso image (DockerHub or GHCR) and supply the Vertex env vars above.
+- Ensure migrations run on startup (the container runs `prisma migrate deploy` in production mode).
+- Restart the container after adding or changing Vertex env vars.
+
+## Enable the feature in Documenso
+
+Once the service is running with the Vertex env vars:
+
+<Steps>
+### Organisation settings
+
+Go to **Settings → Document Preferences → AI Features** and set to **Enabled**. Teams that inherit organisation defaults will pick this up.
+
+### Team settings
+
+If a team overrides organisation defaults, go to **Team Settings → Document Preferences → AI Features** and choose **Enabled** (or **Inherit** to follow the organisation).
+
+### Verify in the editor
+
+Open a draft envelope. In **Recipients**, you should see the sparkle button for AI detection. In **Fields**, you should see **Detect with AI** available.
+
+</Steps>
+
+## Troubleshooting
+
+- **Too many requests**: Wait a minute or two and retry (rate limit is 3/min per IP).
+- **AI options hidden**: Ensure the env vars are set, the server was restarted after setting them, and `aiFeaturesEnabled` is enabled at organisation/team level.
+- **Detection fails immediately**: Confirm the Vertex API key is valid and the project has Vertex AI enabled. Check server logs for status codes from Vertex.
+
+If issues persist, recheck env vars, restart the service, and confirm the Prisma migration was applied.
diff --git a/apps/documentation/pages/developers/self-hosting/how-to.mdx b/apps/documentation/pages/developers/self-hosting/how-to.mdx
index 32096965a..936c99bd6 100644
--- a/apps/documentation/pages/developers/self-hosting/how-to.mdx
+++ b/apps/documentation/pages/developers/self-hosting/how-to.mdx
@@ -119,6 +119,8 @@ NEXT_PRIVATE_SMTP_USERNAME="<your-username>"
NEXT_PRIVATE_SMTP_PASSWORD="<your-password>"
```
+For full AI setup details (including model availability notes), see the [AI Recipient & Field Detection (Self-hosting)](./ai-features) page.
+
### Set Up Your Signing Certificate
<Callout type="warning">
@@ -267,58 +269,63 @@ You can access the Documenso application by visiting the URL you provided for th
The environment variables listed above are a subset of those available for configuring Documenso. The table below provides a complete list of environment variables and their descriptions.
-| Variable | Description |
-| -------------------------------------------- | --------------------------------------------------------------------------------------------------- |
-| `PORT` | The port on which the Documenso application runs. It defaults to `3000`. |
-| `NEXTAUTH_SECRET` | The secret key used by NextAuth.js for encryption and signing. |
-| `NEXT_PRIVATE_ENCRYPTION_KEY` | The primary encryption key for symmetric encryption and decryption (at least 32 characters). |
-| `NEXT_PRIVATE_ENCRYPTION_SECONDARY_KEY` | The secondary encryption key for symmetric encryption and decryption (at least 32 characters). |
-| `NEXT_PRIVATE_GOOGLE_CLIENT_ID` | The Google client ID for Google authentication (optional). |
-| `NEXT_PRIVATE_GOOGLE_CLIENT_SECRET` | The Google client secret for Google authentication (optional). |
-| `NEXT_PRIVATE_MICROSOFT_CLIENT_ID` | The Microsoft client ID for Microsoft authentication (optional). |
-| `NEXT_PRIVATE_MICROSOFT_CLIENT_SECRET` | The Microsoft client secret for Microsoft authentication (optional). |
-| `NEXT_PRIVATE_OIDC_CLIENT_ID` | The OIDC client ID for OIDC authentication (optional). |
-| `NEXT_PRIVATE_OIDC_CLIENT_SECRET` | The OIDC client secret for OIDC authentication (optional). |
-| `NEXT_PRIVATE_OIDC_WELL_KNOWN` | The well-known URL for the OIDC provider (optional). |
-| `NEXT_PRIVATE_OIDC_PROVIDER_LABEL` | The label to display for the OIDC provider button (optional). |
-| `NEXT_PRIVATE_OIDC_SKIP_VERIFY` | Whether to skip email verification for OIDC accounts (optional, default `false`). |
-| `NEXT_PUBLIC_WEBAPP_URL` | The URL for the web application. |
-| `NEXT_PUBLIC_SUPPORT_EMAIL` | The support email address displayed to users (default `[email protected]`). |
-| `NEXT_PRIVATE_DATABASE_URL` | The URL for the primary database connection (with connection pooling). |
-| `NEXT_PRIVATE_DIRECT_DATABASE_URL` | The URL for the direct database connection (without connection pooling). |
-| `NEXT_PRIVATE_SIGNING_TRANSPORT` | The signing transport to use. Available options: local (default) |
-| `NEXT_PRIVATE_SIGNING_PASSPHRASE` | The passphrase for the key file. |
-| `NEXT_PRIVATE_SIGNING_LOCAL_FILE_CONTENTS` | The base64-encoded contents of the key file will be used instead of the file path. |
-| `NEXT_PRIVATE_SIGNING_LOCAL_FILE_PATH` | The path to the key file, default `/opt/documenso/cert.p12`. |
-| `NEXT_PUBLIC_UPLOAD_TRANSPORT` | The transport for file uploads (database or s3). |
-| `NEXT_PRIVATE_UPLOAD_ENDPOINT` | The endpoint for the S3 storage transport (for third-party S3-compatible providers). |
-| `NEXT_PRIVATE_UPLOAD_FORCE_PATH_STYLE` | Whether to force path-style URLs for the S3 storage transport. |
-| `NEXT_PRIVATE_UPLOAD_REGION` | The region for the S3 storage transport (defaults to us-east-1). |
-| `NEXT_PRIVATE_UPLOAD_BUCKET` | The bucket to use for the S3 storage transport. |
-| `NEXT_PRIVATE_UPLOAD_ACCESS_KEY_ID` | The access key ID for the S3 storage transport. |
-| `NEXT_PRIVATE_UPLOAD_SECRET_ACCESS_KEY` | The secret access key for the S3 storage transport. |
-| `NEXT_PRIVATE_SMTP_TRANSPORT` | The transport to send emails (smtp-auth, smtp-api, resend, or mailchannels). |
-| `NEXT_PRIVATE_SMTP_HOST` | The host for the SMTP server for SMTP transports. |
-| `NEXT_PRIVATE_SMTP_PORT` | The port for the SMTP server for SMTP transports. |
-| `NEXT_PRIVATE_SMTP_USERNAME` | The username for the SMTP server for the `smtp-auth` transport. |
-| `NEXT_PRIVATE_SMTP_PASSWORD` | The password for the SMTP server for the `smtp-auth` transport. |
-| `NEXT_PRIVATE_SMTP_APIKEY_USER` | The API key user for the SMTP server for the `smtp-api` transport. |
-| `NEXT_PRIVATE_SMTP_APIKEY` | The API key for the SMTP server for the `smtp-api` transport. |
-| `NEXT_PRIVATE_SMTP_SECURE` | Whether to force the use of TLS for the SMTP server for SMTP transports. |
-| `NEXT_PRIVATE_SMTP_UNSAFE_IGNORE_TLS` | Whether to ignore TLS errors for the SMTP server (useful for self-signed certificates). |
-| `NEXT_PRIVATE_SMTP_FROM_ADDRESS` | The email address for the "from" address. |
-| `NEXT_PRIVATE_SMTP_FROM_NAME` | The sender name for the "from" address. |
-| `NEXT_PRIVATE_RESEND_API_KEY` | The API key for Resend.com for the `resend` transport. |
-| `NEXT_PRIVATE_MAILCHANNELS_API_KEY` | The optional API key for MailChannels (if using a proxy) for the `mailchannels` transport. |
-| `NEXT_PRIVATE_MAILCHANNELS_ENDPOINT` | The optional endpoint for the MailChannels API (if using a proxy) for the `mailchannels` transport. |
-| `NEXT_PRIVATE_MAILCHANNELS_DKIM_DOMAIN` | The domain for DKIM signing with MailChannels for the `mailchannels` transport. |
-| `NEXT_PRIVATE_MAILCHANNELS_DKIM_SELECTOR` | The selector for DKIM signing with MailChannels for the `mailchannels` transport. |
-| `NEXT_PRIVATE_MAILCHANNELS_DKIM_PRIVATE_KEY` | The private key for DKIM signing with MailChannels for the `mailchannels` transport. |
-| `NEXT_PUBLIC_DOCUMENT_SIZE_UPLOAD_LIMIT` | The maximum document upload limit displayed to the user (in MB). |
-| `NEXT_PUBLIC_POSTHOG_KEY` | The optional PostHog key for analytics and feature flags. |
-| `NEXT_PUBLIC_DISABLE_SIGNUP` | Whether to disable user signups through the /signup page. |
-| `NEXT_PRIVATE_BROWSERLESS_URL` | The URL for a Browserless.io instance to generate PDFs (optional). |
-| `DOCUMENSO_DISABLE_TELEMETRY` | Set to `true` to disable anonymous telemetry (see [Telemetry](#telemetry) section below). |
+For AI setup specifics, see the [AI Recipient & Field Detection (Self-hosting)](./ai-features) page.
+
+| Variable | Description |
+| -------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `PORT` | The port on which the Documenso application runs. It defaults to `3000`. |
+| `NEXTAUTH_SECRET` | The secret key used by NextAuth.js for encryption and signing. |
+| `NEXT_PRIVATE_ENCRYPTION_KEY` | The primary encryption key for symmetric encryption and decryption (at least 32 characters). |
+| `NEXT_PRIVATE_ENCRYPTION_SECONDARY_KEY` | The secondary encryption key for symmetric encryption and decryption (at least 32 characters). |
+| `NEXT_PRIVATE_GOOGLE_CLIENT_ID` | The Google client ID for Google authentication (optional). |
+| `NEXT_PRIVATE_GOOGLE_CLIENT_SECRET` | The Google client secret for Google authentication (optional). |
+| `NEXT_PRIVATE_MICROSOFT_CLIENT_ID` | The Microsoft client ID for Microsoft authentication (optional). |
+| `NEXT_PRIVATE_MICROSOFT_CLIENT_SECRET` | The Microsoft client secret for Microsoft authentication (optional). |
+| `NEXT_PRIVATE_OIDC_CLIENT_ID` | The OIDC client ID for OIDC authentication (optional). |
+| `NEXT_PRIVATE_OIDC_CLIENT_SECRET` | The OIDC client secret for OIDC authentication (optional). |
+| `NEXT_PRIVATE_OIDC_WELL_KNOWN` | The well-known URL for the OIDC provider (optional). |
+| `NEXT_PRIVATE_OIDC_PROVIDER_LABEL` | The label to display for the OIDC provider button (optional). |
+| `NEXT_PRIVATE_OIDC_SKIP_VERIFY` | Whether to skip email verification for OIDC accounts (optional, default `false`). |
+| `NEXT_PUBLIC_WEBAPP_URL` | The URL for the web application. |
+| `NEXT_PUBLIC_SUPPORT_EMAIL` | The support email address displayed to users (default `[email protected]`). |
+| `NEXT_PRIVATE_DATABASE_URL` | The URL for the primary database connection (with connection pooling). |
+| `NEXT_PRIVATE_DIRECT_DATABASE_URL` | The URL for the direct database connection (without connection pooling). |
+| `NEXT_PRIVATE_SIGNING_TRANSPORT` | The signing transport to use. Available options: local (default) |
+| `NEXT_PRIVATE_SIGNING_PASSPHRASE` | The passphrase for the key file. |
+| `NEXT_PRIVATE_SIGNING_LOCAL_FILE_CONTENTS` | The base64-encoded contents of the key file will be used instead of the file path. |
+| `NEXT_PRIVATE_SIGNING_LOCAL_FILE_PATH` | The path to the key file, default `/opt/documenso/cert.p12`. |
+| `NEXT_PUBLIC_UPLOAD_TRANSPORT` | The transport for file uploads (database or s3). |
+| `NEXT_PRIVATE_UPLOAD_ENDPOINT` | The endpoint for the S3 storage transport (for third-party S3-compatible providers). |
+| `NEXT_PRIVATE_UPLOAD_FORCE_PATH_STYLE` | Whether to force path-style URLs for the S3 storage transport. |
+| `NEXT_PRIVATE_UPLOAD_REGION` | The region for the S3 storage transport (defaults to us-east-1). |
+| `NEXT_PRIVATE_UPLOAD_BUCKET` | The bucket to use for the S3 storage transport. |
+| `NEXT_PRIVATE_UPLOAD_ACCESS_KEY_ID` | The access key ID for the S3 storage transport. |
+| `NEXT_PRIVATE_UPLOAD_SECRET_ACCESS_KEY` | The secret access key for the S3 storage transport. |
+| `NEXT_PRIVATE_SMTP_TRANSPORT` | The transport to send emails (smtp-auth, smtp-api, resend, or mailchannels). |
+| `NEXT_PRIVATE_SMTP_HOST` | The host for the SMTP server for SMTP transports. |
+| `NEXT_PRIVATE_SMTP_PORT` | The port for the SMTP server for SMTP transports. |
+| `NEXT_PRIVATE_SMTP_USERNAME` | The username for the SMTP server for the `smtp-auth` transport. |
+| `NEXT_PRIVATE_SMTP_PASSWORD` | The password for the SMTP server for the `smtp-auth` transport. |
+| `NEXT_PRIVATE_SMTP_APIKEY_USER` | The API key user for the SMTP server for the `smtp-api` transport. |
+| `NEXT_PRIVATE_SMTP_APIKEY` | The API key for the SMTP server for the `smtp-api` transport. |
+| `NEXT_PRIVATE_SMTP_SECURE` | Whether to force the use of TLS for the SMTP server for SMTP transports. |
+| `NEXT_PRIVATE_SMTP_UNSAFE_IGNORE_TLS` | Whether to ignore TLS errors for the SMTP server (useful for self-signed certificates). |
+| `NEXT_PRIVATE_SMTP_FROM_ADDRESS` | The email address for the "from" address. |
+| `NEXT_PRIVATE_SMTP_FROM_NAME` | The sender name for the "from" address. |
+| `NEXT_PRIVATE_RESEND_API_KEY` | The API key for Resend.com for the `resend` transport. |
+| `NEXT_PRIVATE_MAILCHANNELS_API_KEY` | The optional API key for MailChannels (if using a proxy) for the `mailchannels` transport. |
+| `NEXT_PRIVATE_MAILCHANNELS_ENDPOINT` | The optional endpoint for the MailChannels API (if using a proxy) for the `mailchannels` transport. |
+| `NEXT_PRIVATE_MAILCHANNELS_DKIM_DOMAIN` | The domain for DKIM signing with MailChannels for the `mailchannels` transport. |
+| `NEXT_PRIVATE_MAILCHANNELS_DKIM_SELECTOR` | The selector for DKIM signing with MailChannels for the `mailchannels` transport. |
+| `NEXT_PRIVATE_MAILCHANNELS_DKIM_PRIVATE_KEY` | The private key for DKIM signing with MailChannels for the `mailchannels` transport. |
+| `NEXT_PUBLIC_DOCUMENT_SIZE_UPLOAD_LIMIT` | The maximum document upload limit displayed to the user (in MB). |
+| `NEXT_PUBLIC_POSTHOG_KEY` | The optional PostHog key for analytics and feature flags. |
+| `NEXT_PUBLIC_DISABLE_SIGNUP` | Whether to disable user signups through the /signup page. |
+| `NEXT_PRIVATE_BROWSERLESS_URL` | The URL for a Browserless.io instance to generate PDFs (optional). |
+| `DOCUMENSO_DISABLE_TELEMETRY` | Set to `true` to disable anonymous telemetry (see [Telemetry](#telemetry) section below). |
+| `GOOGLE_VERTEX_PROJECT_ID` | Google Cloud project ID used for Vertex AI (required for AI detection). |
+| `GOOGLE_VERTEX_API_KEY` | Vertex AI Express API key with access to Gemini models (required for AI detection). See [AI Recipient & Field Detectionfor](./ai-features) for details. |
+| `GOOGLE_VERTEX_LOCATION` | Optional Vertex region, defaults to `global`. Not all models are available in every region. |
## Telemetry
diff --git a/apps/documentation/pages/users/documents/_meta.js b/apps/documentation/pages/users/documents/_meta.js
index b7a45ef0f..15d3d729b 100644
--- a/apps/documentation/pages/users/documents/_meta.js
+++ b/apps/documentation/pages/users/documents/_meta.js
@@ -4,4 +4,5 @@ export default {
'document-visibility': 'Document Visibility',
fields: 'Document Fields',
'email-preferences': 'Email Preferences',
+ 'ai-detection': 'AI Recipient & Field Detection',
};
diff --git a/apps/documentation/pages/users/documents/ai-detection.mdx b/apps/documentation/pages/users/documents/ai-detection.mdx
new file mode 100644
index 000000000..5eac2df52
--- /dev/null
+++ b/apps/documentation/pages/users/documents/ai-detection.mdx
@@ -0,0 +1,68 @@
+---
+title: AI Recipient & Field Detection
+description: Use Documenso’s AI helpers to detect recipients and fields in draft documents.
+---
+
+# AI Recipient & Field Detection
+
+Documenso can suggest recipients and place fields automatically using Google Vertex AI (Gemini). The feature is optional and only available when your organisation or team has **AI Features** enabled. Documents are processed securely and providers do not retain your data for training.
+
+## Requirements
+
+- AI Features must be enabled in **Document Preferences** for your organisation or team.
+- The envelope must be in **Draft** status.
+- Helpful rate limits are in place (up to 3 detection requests per minute per IP) to prevent abuse. If you see a “too many requests” message, wait a minute or two and try again.
+
+### Enable AI features
+
+1. **Organisation settings**:
+
+Settings → Document Preferences → **AI Features** → Enabled.
+
+_This applies to teams that inherit organisation defaults._
+
+2. **Team settings**:
+
+Team Settings → Document Preferences → **AI Features** → choose Enabled, Disabled, or Inherit.
+
+## Detect recipients
+
+Use this to identify who needs to sign or approve.
+
+1. Open a draft document/template and go to the **Recipients** panel.
+2. Select the **sparkle** button to start detection. If AI is enabled, uploads launched from the dashboard will open the detector automatically.
+
+![Detect recipients with AI button in the Recipients panel](/document-signing/ai-recipient-detect-button.webp)
+
+3. Wait for progress to finish, then review the suggested recipients.
+4. Remove any incorrect entries, then **Add recipients** to apply them. Existing recipients and duplicates are preserved.
+
+Notes:
+
+- Detection is unavailable once an envelope is completed.
+- You can re-run detection if you update the document; each run counts toward the rate limit.
+
+## Detect fields
+
+Use this to auto-place fields on the pages of a draft.
+
+1. Open the envelope editor and switch to the **Fields** tab.
+2. Select **Detect with AI**. Provide optional context (e.g., “Alice is the tenant, Bob is the landlord”) to improve recipient assignment.
+
+![AI field detection dialog with context input](/document-signing/ai-field-detection-button.webp)
+![AI field detection dialog with context input](/document-signing/ai-field-detection-dialog.webp)
+
+3. Watch the progress indicators; they update per page and total fields found.
+4. Review the summary and choose **Add fields** to place them in the editor.
+
+Notes:
+
+- Works only for draft envelopes and teams with AI features enabled.
+- Existing fields are masked during detection to avoid duplicates.
+- Fields are assigned to recipients based on nearby labels and your context message; you can edit them after adding.
+
+## Best practices
+
+- Keep labels near the intended fields (e.g., “Tenant signature”, “Buyer email”).
+- Provide short context when roles are ambiguous.
+- Always review suggestions before sending; AI assists but does not replace final checks.
diff --git a/apps/documentation/public/document-signing/ai-field-detection-button.webp b/apps/documentation/public/document-signing/ai-field-detection-button.webp
new file mode 100644
index 000000000..0bad99e65
Binary files /dev/null and b/apps/documentation/public/document-signing/ai-field-detection-button.webp differ
diff --git a/apps/documentation/public/document-signing/ai-field-detection-dialog.webp b/apps/documentation/public/document-signing/ai-field-detection-dialog.webp
new file mode 100644
index 000000000..a586bf9e8
Binary files /dev/null and b/apps/documentation/public/document-signing/ai-field-detection-dialog.webp differ
diff --git a/apps/documentation/public/document-signing/ai-recipient-detect-button.webp b/apps/documentation/public/document-signing/ai-recipient-detect-button.webp
new file mode 100644
index 000000000..a22c6a1b6
Binary files /dev/null and b/apps/documentation/public/document-signing/ai-recipient-detect-button.webp differ