The Open Source DocuSign Alternative.
TypeScript digital-signaturedocument-signingdocusign-alternativee-signatureesignesignaturenext-authnextjsopen-sourcepades-standardpdfpdf-signpdf-signaturepostgresqlprismaself-hostedsigningtypescript
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.jsindex 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.mdxnew file mode 100644index 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.mdxindex 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 thThe 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. |## Telemetrydiff --git a/apps/documentation/pages/users/documents/_meta.js b/apps/documentation/pages/users/documents/_meta.jsindex 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.mdxnew file mode 100644index 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.++++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.+++++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.webpnew file mode 100644index 000000000..0bad99e65Binary files /dev/null and b/apps/documentation/public/document-signing/ai-field-detection-button.webp differdiff --git a/apps/documentation/public/document-signing/ai-field-detection-dialog.webp b/apps/documentation/public/document-signing/ai-field-detection-dialog.webpnew file mode 100644index 000000000..a586bf9e8Binary files /dev/null and b/apps/documentation/public/document-signing/ai-field-detection-dialog.webp differdiff --git a/apps/documentation/public/document-signing/ai-recipient-detect-button.webp b/apps/documentation/public/document-signing/ai-recipient-detect-button.webpnew file mode 100644index 000000000..a22c6a1b6Binary files /dev/null and b/apps/documentation/public/document-signing/ai-recipient-detect-button.webp differ