chore: update docs for self hosters (#2816)

2026-06-22 04:12:06 +10:00 · 2026-05-14 15:07:10 +10:00
parent 194b2134cc
commit 999942014e
8 changed files with 119 additions and 404 deletions
@@ -83,6 +83,15 @@ npm run prisma:seed -w @documenso/prisma

 </Step>

+<Step>
+### Optional: configure job provider
+
+The default local job provider does not support scheduled jobs required for document reminders.
+
+See the [Background Jobs](/docs/self-hosting/configuration/background-jobs) page for more information.
+
+</Step>
+
 <Step>
 ### Start the application

@@ -105,6 +114,20 @@ Access the Documenso application by visiting `http://localhost:3000` in your web
  certificate](/docs/developers/local-development/signing-certificate)**.
 </Callout>

+## Running Scripts with Environment Variables
+
+If a package script does not automatically load your `.env` and `.env.local` files, wrap it with the `with:env` script:
+
+```bash
+npm run with:env -- npm run myscript
+```
+
+The same works for `npx` when running bin scripts:
+
+```bash
+npm run with:env -- npx myscript
+```
+
 ## See Also

 - [Developer Quickstart](/docs/developers/local-development/quickstart) - Quick Docker-based setup
@@ -26,8 +26,14 @@ docker --version

 ## Pulling the Docker Image

+The Documenso image is available on both DockerHub and GitHub Container Registry:
+
 ```bash
+# DockerHub
 docker pull documenso/documenso:latest
+
+# GitHub Container Registry
+docker pull ghcr.io/documenso/documenso:latest
 ```

 ### Available Tags
@@ -196,6 +202,14 @@ Documenso provides health check endpoints for monitoring:
 | `/api/health`             | Checks database connectivity and certificate status            |
 | `/api/certificate-status` | Returns whether a signing certificate is configured and usable |

+Both endpoints return a JSON response with a `status` field:
+
+| Status      | Meaning                                                              |
+| ----------- | -------------------------------------------------------------------- |
+| `"ok"`      | Everything is working properly                                       |
+| `"warning"` | Application is running but there are certificate issues              |
+| `"error"`   | Critical issues (database unreachable, missing configuration, etc.)  |
+
 ### Docker Health Check

 Add a health check to your container:
@@ -3,6 +3,8 @@ title: Getting Started
 description: Requirements and quick start guide for self-hosting Documenso.
 ---

+import { Callout } from 'fumadocs-ui/components/callout';
+
 <Cards>
  <Card
    title="Requirements"
@@ -15,3 +17,11 @@ description: Requirements and quick start guide for self-hosting Documenso.
    href="/docs/self-hosting/getting-started/quick-start"
  />
 </Cards>
+
+<Callout type="error">
+  **You must generate a signing certificate.** Documenso does not ship with one. Without a
+  certificate, the application starts normally but document signing will fail on completion with
+  errors.
+
+  Please see all the [requirements](/docs/self-hosting/getting-started/requirements) before proceeding.
+</Callout>
@@ -7,14 +7,29 @@ import { Callout } from 'fumadocs-ui/components/callout';

 ## What You Need

-Documenso requires the following external services:
+Documenso requires the following items and external services:

 | Service       | Purpose                      | Minimum Version |
 | ------------- | ---------------------------- | --------------- |
+| Signing certificate | Digital signature for documents | N/A             |
 | PostgreSQL    | Primary database             | 14+             |
 | SMTP server   | Sending emails to recipients | Any             |
 | Reverse proxy | SSL termination, routing     | Any             |

+
+### Signing Certificate
+
+<Callout type="error">
+  Documenso does not ship with a signing certificate. Without one, the application starts normally
+  but all document signing will fail. You must generate or provide a `.p12` certificate before going
+  to production.
+</Callout>
+
+Every completed document is digitally signed using an X.509 certificate. You can generate a self-signed certificate for free or use one from a Certificate Authority (CA).
+
+- [Generate a local certificate](/docs/self-hosting/configuration/signing-certificate/local) — step-by-step instructions to create a `.p12` certificate
+- [All certificate options](/docs/self-hosting/configuration/signing-certificate) — self-signed, CA-issued, and Google Cloud HSM
+
 ### PostgreSQL Database

 Documenso uses PostgreSQL for all data storage including documents, users, and audit logs. You cannot use MySQL, SQLite, or other databases.
@@ -154,6 +154,34 @@ See [Background Jobs Configuration](/docs/self-hosting/configuration/background-

 ---

+## IPv6-Only Deployments
+
+If you are deploying to an environment that uses only IPv6, set the `HOST` environment variable to `::` so the application binds to all IPv6 addresses:
+
+**Docker:**
+
+```bash
+docker run -it -e HOST=:: documenso/documenso:latest npm run start
+```
+
+**Kubernetes or Docker Compose:**
+
+```yaml
+containers:
+  - name: documenso
+    image: documenso/documenso:latest
+    command:
+      - npm
+    args:
+      - run
+      - start
+    env:
+      - name: HOST
+        value: '::'
+```
+
+---
+
 ## Docker File Permissions

 The Documenso container runs as a non-root user (UID 1001). If you mount files into the container (certificates, configuration), ensure they're readable:
@@ -3,6 +3,8 @@ title: Self-Hosting
 description: Deploy and manage your own Documenso instance for complete control over your data, compliance, and customization.
 ---

+import { Callout } from 'fumadocs-ui/components/callout';
+
 ## Getting Started

 <Cards>
@@ -18,6 +20,13 @@ description: Deploy and manage your own Documenso instance for complete control
  />
 </Cards>

+<Callout type="error">
+  **You must generate a signing certificate.** Documenso does not ship with one. Without a
+  certificate, the application starts normally but document signing will fail.
+
+  Please see all the [requirements](/docs/self-hosting/getting-started/requirements) before proceeding.
+</Callout>
+
 ---

 ## Deployment Options