chore: self hosting docs update and certificate issues (#1847)

2025-11-09 20:12:31 +10:00 · 2025-09-09 11:26:42 +00:00
parent 7c8e93b53e
commit 2c0d4f8789
10 changed files with 352 additions and 56 deletions
--- a/docker/Dockerfile
+++ b/docker/Dockerfile
@ -109,7 +109,7 @@ COPY --from=installer --chown=nodejs:nodejs /app/packages/prisma/migrations ./pa
 RUN npx prisma generate --schema ./packages/prisma/schema.prisma


-# Get the start script from docker/start.sh
+# Get the start script from docker/
 COPY --chown=nodejs:nodejs ./docker/start.sh /app/apps/remix/start.sh

 WORKDIR /app/apps/remix
--- a/docker/README.md
+++ b/docker/README.md
@ -18,27 +18,66 @@ This setup includes a PostgreSQL database and the Documenso application. You wil
 3. Create a `.env` file in the same directory and add your SMTP details as well as a few extra environment variables, following the example below:

 ```
+# Generate random secrets (you can use: openssl rand -hex 32)
 NEXTAUTH_SECRET="<your-secret>"
 NEXT_PRIVATE_ENCRYPTION_KEY="<your-key>"
 NEXT_PRIVATE_ENCRYPTION_SECONDARY_KEY="<your-secondary-key>"
+
+# Your application URL
 NEXT_PUBLIC_WEBAPP_URL="<your-url>"
+
+# SMTP Configuration
 NEXT_PRIVATE_SMTP_TRANSPORT="smtp-auth"
 NEXT_PRIVATE_SMTP_HOST="<your-host>"
 NEXT_PRIVATE_SMTP_PORT=<your-port>
 NEXT_PRIVATE_SMTP_USERNAME="<your-username>"
 NEXT_PRIVATE_SMTP_PASSWORD="<your-password>"
+NEXT_PRIVATE_SMTP_FROM_NAME="<your-from-name>"
+NEXT_PRIVATE_SMTP_FROM_ADDRESS="<your-from-email>"
+
+# Certificate passphrase (required)
+NEXT_PRIVATE_SIGNING_PASSPHRASE="<your-certificate-password>"
 ```

-4. Update the volume binding for the cert file in the `compose.yml` file to point to your own key file:
+4. Set up your signing certificate. You have three options:

-Since the `cert.p12` file is required for signing and encrypting documents, you will need to provide your own key file. Update the volume binding in the `compose.yml` file to point to your key file:
+   **Option A: Generate Certificate Inside Container (Recommended)**
+   
+   Start your containers first, then generate a self-signed certificate:
+   ```bash
+   # Start containers
+   docker-compose up -d
+   
+   # Set certificate password securely (won't appear in command history)
+   read -s -p "Enter certificate password: " CERT_PASS
+   echo
+   
+   # Generate certificate inside container using environment variable
+   docker exec -e CERT_PASS="$CERT_PASS" -it documenso-production-documenso-1 bash -c "
+     openssl req -x509 -nodes -days 365 -newkey rsa:2048 \
+       -keyout /tmp/private.key \
+       -out /tmp/certificate.crt \
+       -subj '/C=US/ST=State/L=City/O=Organization/CN=localhost' && \
+     openssl pkcs12 -export -out /app/certs/cert.p12 \
+       -inkey /tmp/private.key -in /tmp/certificate.crt \
+       -passout env:CERT_PASS && \
+     rm /tmp/private.key /tmp/certificate.crt
+   "
+   
+   # Restart container
+   docker-compose restart documenso
+   ```
+   
+   **Option B: Use Existing Certificate**
+   
+   If you have an existing `.p12` certificate, update the volume binding in `compose.yml`:
+   ```yaml
+   volumes:
+     - /path/to/your/cert.p12:/opt/documenso/cert.p12:ro
+   ```
+   

-```yaml
-volumes:
-  - /path/to/your/keyfile.p12:/opt/documenso/cert.p12
-```
-
-1. Run the following command to start the containers:
+5. Run the following command to start the containers:

 ```
 docker-compose --env-file ./.env up -d
@ -46,7 +85,7 @@ docker-compose --env-file ./.env up -d

 This will start the PostgreSQL database and the Documenso application containers.

-5. Access the Documenso application by visiting `http://localhost:3000` in your web browser.
+6. Access the Documenso application by visiting `http://localhost:3000` in your web browser.

 ## Option 2: Standalone Docker Container

@ -69,27 +108,93 @@ docker pull ghcr.io/documenso/documenso
 ```
 docker run -d \
  -p 3000:3000 \
-  -e NEXTAUTH_SECRET="<your-nextauth-secret>"
-  -e NEXT_PRIVATE_ENCRYPTION_KEY="<your-next-private-encryption-key>"
-  -e NEXT_PRIVATE_ENCRYPTION_SECONDARY_KEY="<your-next-private-encryption-secondary-key>"
-  -e NEXT_PUBLIC_WEBAPP_URL="<your-next-public-webapp-url>"
-  -e NEXT_PRIVATE_INTERNAL_WEBAPP_URL="http://localhost:3000"
-  -e NEXT_PRIVATE_DATABASE_URL="<your-next-private-database-url>"
-  -e NEXT_PRIVATE_DIRECT_DATABASE_URL="<your-next-private-database-url>"
-  -e NEXT_PRIVATE_SMTP_TRANSPORT="<your-next-private-smtp-transport>"
-  -e NEXT_PRIVATE_SMTP_FROM_NAME="<your-next-private-smtp-from-name>"
-  -e NEXT_PRIVATE_SMTP_FROM_ADDRESS="<your-next-private-smtp-from-address>"
-  -v /path/to/your/keyfile.p12:/opt/documenso/cert.p12
+  -e NEXTAUTH_SECRET="<your-nextauth-secret>" \
+  -e NEXT_PRIVATE_ENCRYPTION_KEY="<your-next-private-encryption-key>" \
+  -e NEXT_PRIVATE_ENCRYPTION_SECONDARY_KEY="<your-next-private-encryption-secondary-key>" \
+  -e NEXT_PUBLIC_WEBAPP_URL="<your-next-public-webapp-url>" \
+  -e NEXT_PRIVATE_INTERNAL_WEBAPP_URL="http://localhost:3000" \
+  -e NEXT_PRIVATE_DATABASE_URL="<your-next-private-database-url>" \
+  -e NEXT_PRIVATE_DIRECT_DATABASE_URL="<your-next-private-database-url>" \
+  -e NEXT_PRIVATE_SMTP_TRANSPORT="<your-next-private-smtp-transport>" \
+  -e NEXT_PRIVATE_SMTP_FROM_NAME="<your-next-private-smtp-from-name>" \
+  -e NEXT_PRIVATE_SMTP_FROM_ADDRESS="<your-next-private-smtp-from-address>" \
+  -e NEXT_PRIVATE_SIGNING_PASSPHRASE="<your-certificate-password>" \
+  -v /path/to/your/cert.p12:/opt/documenso/cert.p12:ro \
  documenso/documenso
 ```

 Replace the placeholders with your actual database and SMTP details.

-1. Access the Documenso application by visiting the URL you provided in the `NEXT_PUBLIC_WEBAPP_URL` environment variable in your web browser.
+3. Access the Documenso application by visiting the URL you provided in the `NEXT_PUBLIC_WEBAPP_URL` environment variable in your web browser.

 ## Success

-You have now successfully set up Documenso using Docker. You can start organizing and managing your documents efficiently. If you encounter any issues or have further questions, please refer to the official Documenso documentation or seek assistance from the community.
+You have now successfully set up Documenso using Docker. You can start organizing and managing your documents efficiently.
+
+## Troubleshooting
+
+### Certificate Permission Issues
+
+If you encounter errors related to certificate access, here are common solutions:
+
+#### Error: "Failed to read signing certificate"
+
+1. **Check file exists:**
+
+   ```bash
+   ls -la /path/to/your/cert.p12
+   ```
+
+2. **Fix permissions:**
+
+   ```bash
+   chmod 644 /path/to/your/cert.p12
+   chown 1001:1001 /path/to/your/cert.p12
+   ```
+
+3. **Verify Docker mount:**
+   ```bash
+   docker exec -it <container_name> ls -la /opt/documenso/cert.p12
+   ```
+
+
+### Container Logs
+
+Check application logs for detailed error information:
+
+```bash
+# For Docker Compose
+docker-compose logs -f documenso
+
+# For standalone container
+docker logs -f <container_name>
+```
+
+### Health Checks
+
+Check the status of your Documenso instance:
+
+```bash
+# Basic health check (database + certificate)
+curl http://localhost:3000/api/health
+
+# Detailed certificate status
+curl http://localhost:3000/api/certificate-status
+```
+
+The health endpoint will show:
+
+- `status: "ok"` - Everything working properly
+- `status: "warning"` - App running but certificate issues
+- `status: "error"` - Critical issues (database down, etc.)
+
+### Common Issues
+
+1. **Port already in use:** Change the port mapping in compose.yml or your docker run command
+2. **Database connection issues:** Ensure your database is running and accessible
+3. **SMTP errors:** Verify your email server settings in the .env file
+
+If you encounter any issues or have further questions, please refer to the official Documenso documentation or seek assistance from the community.

 ## Advanced Configuration

--- a/docker/production/compose.yml
+++ b/docker/production/compose.yml
@ -63,7 +63,7 @@ services:
    ports:
      - ${PORT:-3000}:${PORT:-3000}
    volumes:
-      - /opt/documenso/cert.p12:/opt/documenso/cert.p12
+      - /opt/documenso/cert.p12:/opt/documenso/cert.p12:ro

 volumes:
  database:
--- a/docker/start.sh
+++ b/docker/start.sh
@ -1,7 +1,31 @@
 #!/bin/sh

-set -x
+# 🚀 Starting Documenso...
+printf "🚀 Starting Documenso...\n\n"

+# 🔐 Check certificate configuration
+printf "🔐 Checking certificate configuration...\n"
+
+CERT_PATH="${NEXT_PRIVATE_SIGNING_LOCAL_FILE_PATH:-/opt/documenso/cert.p12}"
+
+if [ -f "$CERT_PATH" ] && [ -r "$CERT_PATH" ]; then
+    printf "✅ Certificate file found and readable - document signing is ready!\n"
+else
+    printf "⚠️  Certificate not found or not readable\n"
+    printf "💡 Tip: Documenso will still start, but document signing will be unavailable\n"
+    printf "🔧 Check: http://localhost:3000/api/certificate-status for detailed status\n"
+fi
+
+printf "\n📚 Useful Links:\n"
+printf "📖 Documentation: https://docs.documenso.com\n"
+printf "🐳 Self-hosting guide: https://docs.documenso.com/developers/self-hosting\n"
+printf "🔐 Certificate setup: https://docs.documenso.com/developers/self-hosting/signing-certificate\n"
+printf "🏥 Health check: http://localhost:3000/api/health\n"
+printf "📊 Certificate status: http://localhost:3000/api/certificate-status\n"
+printf "👥 Community: https://github.com/documenso/documenso\n\n"
+
+printf "🗄️  Running database migrations...\n"
 npx prisma migrate deploy --schema ../../packages/prisma/schema.prisma

+printf "🌟 Starting Documenso server...\n"
 HOSTNAME=0.0.0.0 node build/server/main.js