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="" +GOOGLE_VERTEX_API_KEY="" +# Optional, defaults to "global" +GOOGLE_VERTEX_LOCATION="global" +``` + + + 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. + + +## 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: + + +### 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. + + + +## 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="" NEXT_PRIVATE_SMTP_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 @@ -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 `support@documenso.com`). | -| `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 `support@documenso.com`). | +| `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