mirror of
https://github.com/documenso/documenso.git
synced 2026-07-26 01:45:08 +10:00
feat: docs v2 (#2460)
Co-authored-by: Catalin Pit <catalinpit@gmail.com>
This commit is contained in:
Lucas Smith
GitHub
@@ -0,0 +1,106 @@
|
||||
---
|
||||
title: AI Recipient & Field Detection (Self-hosting)
|
||||
description: Configure Google Vertex AI so Documenso can detect recipients and fields automatically.
|
||||
---
|
||||
|
||||
import { Accordion, Accordions } from 'fumadocs-ui/components/accordion';
|
||||
import { Callout } from 'fumadocs-ui/components/callout';
|
||||
import { Step, Steps } from 'fumadocs-ui/components/steps';
|
||||
|
||||
## Overview
|
||||
|
||||
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:
|
||||
|
||||
{/* prettier-ignore */}
|
||||
<Steps>
|
||||
<Step>
|
||||
### Organisation settings
|
||||
|
||||
Go to **Settings** → **Document Preferences** → **AI Features** and set to **Enabled**.
|
||||
|
||||
Teams that inherit organisation defaults will get this automatically.
|
||||
|
||||
</Step>
|
||||
<Step>
|
||||
### Team settings
|
||||
|
||||
If a team overrides organisation defaults:
|
||||
|
||||
- Go to **Team Settings** → **Document Preferences** → **AI Features**
|
||||
- Choose **Enabled**, or **Inherit** to follow the organisation
|
||||
|
||||
</Step>
|
||||
<Step>
|
||||
### Verify in the editor
|
||||
|
||||
Open a draft envelope and check:
|
||||
|
||||
- **Recipients**: sparkle button for AI detection is visible
|
||||
- **Fields**: **Detect with AI** is available
|
||||
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
<Accordions type="multiple">
|
||||
<Accordion title="Too many requests">
|
||||
Wait a minute or two and retry (rate limit is 3/min per IP).
|
||||
</Accordion>
|
||||
<Accordion title="AI options hidden">
|
||||
Ensure the env vars are set, the server was restarted after setting them, and
|
||||
`aiFeaturesEnabled` is enabled at organisation/team level.
|
||||
</Accordion>
|
||||
<Accordion title="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.
|
||||
</Accordion>
|
||||
</Accordions>
|
||||
|
||||
If issues persist, recheck env vars, restart the service, and confirm the Prisma migration was applied.
|
||||
|
||||
---
|
||||
|
||||
## See Also
|
||||
|
||||
- [AI Detection (User Guide)](/docs/users/documents/advanced/ai-detection) - How to use AI detection features
|
||||
- [Environment Variables](/docs/self-hosting/configuration/environment) - All configuration options
|
||||
@@ -0,0 +1,17 @@
|
||||
---
|
||||
title: Advanced
|
||||
description: Optional configuration for OAuth providers, AI features, and other advanced settings.
|
||||
---
|
||||
|
||||
<Cards>
|
||||
<Card
|
||||
title="OAuth Providers"
|
||||
description="Configure Google, GitHub, and OIDC authentication."
|
||||
href="/docs/self-hosting/configuration/advanced/oauth-providers"
|
||||
/>
|
||||
<Card
|
||||
title="AI Features"
|
||||
description="Enable AI-powered recipient and field detection."
|
||||
href="/docs/self-hosting/configuration/advanced/ai-features"
|
||||
/>
|
||||
</Cards>
|
||||
@@ -0,0 +1,4 @@
|
||||
{
|
||||
"title": "Advanced",
|
||||
"pages": ["oauth-providers", "ai-features"]
|
||||
}
|
||||
@@ -0,0 +1,155 @@
|
||||
---
|
||||
title: Setting up OAuth Providers
|
||||
description: Learn how to set up OAuth providers for your own instance of Documenso.
|
||||
---
|
||||
|
||||
import { Step, Steps } from 'fumadocs-ui/components/steps';
|
||||
|
||||
## Google OAuth (Gmail)
|
||||
|
||||
To use Google OAuth, you will need to create a Google Cloud Platform project and enable the Google Identity and Access Management (IAM) API. You will also need to create a new OAuth client ID and download the client secret.
|
||||
|
||||
### Create and configure a new OAuth client ID
|
||||
|
||||
{/* prettier-ignore */}
|
||||
<Steps>
|
||||
<Step>
|
||||
### Open Google Cloud Console
|
||||
|
||||
Go to the [Google Cloud Platform Console](https://console.cloud.google.com/) and select a project or create a new one from the projects list.
|
||||
|
||||
</Step>
|
||||
<Step>
|
||||
### Open APIs & services
|
||||
|
||||
From the console's left side menu, select **APIs & services** (if not already open).
|
||||
|
||||
</Step>
|
||||
<Step>
|
||||
### Open Credentials
|
||||
|
||||
On the left, click **Credentials**.
|
||||
|
||||
</Step>
|
||||
<Step>
|
||||
### Create OAuth client ID
|
||||
|
||||
Click **New Credentials**, then select **OAuth client ID**. When prompted, select **Web application**.
|
||||
|
||||
</Step>
|
||||
<Step>
|
||||
### Name and create the client
|
||||
|
||||
Enter a name for your client ID and click **Create**. Click the download button to download the client secret.
|
||||
|
||||
</Step>
|
||||
<Step>
|
||||
### Set authorized origins and redirect URIs
|
||||
|
||||
Set:
|
||||
|
||||
- **Authorized JavaScript origins**: `https://<documenso-domain>`
|
||||
- **Authorized redirect URIs**: `https://<documenso-domain>/api/auth/callback/google`
|
||||
|
||||
</Step>
|
||||
<Step>
|
||||
### Set environment variables
|
||||
|
||||
In your Documenso environment, set:
|
||||
|
||||
```
|
||||
NEXT_PRIVATE_GOOGLE_CLIENT_ID=<your-client-id>
|
||||
NEXT_PRIVATE_GOOGLE_CLIENT_SECRET=<your-client-secret>
|
||||
```
|
||||
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
Finally verify sign-in with Google by signing in with your Google account and checking the email address in your profile.
|
||||
|
||||
## Microsoft OAuth (Azure AD)
|
||||
|
||||
To use Microsoft OAuth, you will need to create an Azure AD application registration in the Microsoft Azure portal. This will allow users to sign in with their Microsoft accounts.
|
||||
|
||||
### Create and configure a new Azure AD application
|
||||
|
||||
{/* prettier-ignore */}
|
||||
<Steps>
|
||||
<Step>
|
||||
### Open Azure Portal
|
||||
|
||||
Go to the [Azure Portal](https://portal.azure.com/) and navigate to **Azure Active Directory** (or **Microsoft Entra ID** in newer portals).
|
||||
|
||||
</Step>
|
||||
<Step>
|
||||
### Start app registration
|
||||
|
||||
In the left sidebar, click **App registrations**, then **New registration**.
|
||||
|
||||
</Step>
|
||||
<Step>
|
||||
### Name and choose account types
|
||||
|
||||
Enter a name (e.g. "Documenso").
|
||||
|
||||
Under **Supported account types**, select both:
|
||||
|
||||
- Accounts in any organizational directory (Any Azure AD directory - Multitenant)
|
||||
- Personal Microsoft accounts (e.g. Skype, Xbox)
|
||||
|
||||
This allows any Microsoft account to sign in.
|
||||
|
||||
</Step>
|
||||
<Step>
|
||||
### Set redirect URI and register
|
||||
|
||||
Under **Redirect URI**, select **Web** and enter:
|
||||
|
||||
```bash
|
||||
https://<documenso-domain>/api/auth/callback/microsoft
|
||||
```
|
||||
|
||||
Click **Register**.
|
||||
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
### Configure the application
|
||||
|
||||
{/* prettier-ignore */}
|
||||
<Steps>
|
||||
<Step>
|
||||
### Copy the Application (client) ID
|
||||
|
||||
After registration you're on the app overview page. Copy the **Application (client) ID** for `NEXT_PRIVATE_MICROSOFT_CLIENT_ID`.
|
||||
|
||||
</Step>
|
||||
<Step>
|
||||
### Create a client secret
|
||||
|
||||
- In the left sidebar, click **Certificates & secrets**
|
||||
- Under **Client secrets**, click **New client secret**
|
||||
- Add a description and select an expiration period, then click **Add**
|
||||
- Copy the **Value** (not the Secret ID): this is your `NEXT_PRIVATE_MICROSOFT_CLIENT_SECRET`
|
||||
|
||||
</Step>
|
||||
<Step>
|
||||
### Set environment variables
|
||||
|
||||
In your Documenso environment, set:
|
||||
|
||||
```
|
||||
NEXT_PRIVATE_MICROSOFT_CLIENT_ID=<your-application-client-id>
|
||||
NEXT_PRIVATE_MICROSOFT_CLIENT_SECRET=<your-client-secret-value>
|
||||
```
|
||||
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
---
|
||||
|
||||
## See Also
|
||||
|
||||
- [Environment Variables](/docs/self-hosting/configuration/environment) - All configuration options
|
||||
- [Single Sign-On](/docs/users/organisations/single-sign-on) - Configure SSO for your organisation
|
||||
- [Microsoft Entra ID](/docs/users/organisations/single-sign-on/microsoft-entra-id) - Detailed Entra ID setup guide
|
||||
Reference in New Issue
Block a user