Self Host Guidance

[gabrielbryk]

I'm interested in self-hosting Papermark and followed the link from your help center article on self-hosting (https://www.papermark.com/help/article/self-hosting).

The article mentions:

"For a complete, step-by-step guide with all the necessary commands and detailed instructions, please visit our GitHub repository. There, you'll find comprehensive documentation on how to set up and configure your self-hosted Papermark instance."

However, upon reviewing the repository, I couldn't locate this comprehensive documentation. The main README lists prerequisites, but doesn't seem to contain the detailed, step-by-step guide referenced in the help article.

Could you please clarify:

• Where can I find the detailed self-hosting setup guide mentioned in the help article?
• If this documentation doesn't exist yet, are there plans to create it?
• What is the official stance on supporting self-hosted instances? Are community support channels the primary avenue, or is there some level of official support?

Having clearer documentation and understanding the support landscape would be very helpful for users looking to self-host Papermark.

[vaisov-gemba]

Same here. I'm battling with trying to run it on VM using pm2. So far I've got until the point that directly accessing the app on port 3000 works, but if I put nginx proxy in front I'm getting following error from pm2

Error handling upgrade request TypeError: Cannot read properties of undefined (reading 'bind')
    at DevServer.handleRequestImpl (/opt/papermark/node_modules/next/dist/server/base-server.js:476:50)
    at async /opt/papermark/node_modules/next/dist/server/dev/next-dev-server.js:339:20
    at async Span.traceAsyncFn (/opt/papermark/node_modules/next/dist/trace/trace.js:154:20)
    at async DevServer.handleRequest (/opt/papermark/node_modules/next/dist/server/dev/next-dev-server.js:336:24)
    at async handleRoute (/opt/papermark/node_modules/next/dist/server/lib/router-utils/resolve-routes.js:313:33)
    at async resolveRoutes (/opt/papermark/node_modules/next/dist/server/lib/router-utils/resolve-routes.js:536:28)
    at async upgradeHandler (/opt/papermark/node_modules/next/dist/server/lib/router-server.js:467:50)
    at async Server.<anonymous> (/opt/papermark/node_modules/next/dist/server/lib/start-server.js:170:13)

Nginx config I'm using:

server {
    listen 80 default_server;
    listen [::]:80 default_server;
    server_name dataroom.domain.com;
    # Redirect all HTTP requests to HTTPS
    return 301 https://\$host\$request_uri;
}

server {
    listen 443 ssl http2 default_server;
    listen [::]:443 ssl http2 default_server;
    server_name dataroom.domain.com;


    ssl_certificate /etc/nginx/ssl/dataroom.pem;
    ssl_certificate_key /etc/nginx/ssl/dataroom.key;

    # SSL settings
    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_prefer_server_ciphers on;
    ssl_ciphers ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:DHE-RSA-AES128-GCM-SHA256:DHE-RSA-AES256-GCM-SHA384;
    ssl_session_cache shared:SSL:10m;
    ssl_session_timeout 1d;
    ssl_session_tickets off;

    location / {
        proxy_pass http://127.0.0.1:3000;
        proxy_http_version 1.1;

        # WebSocket support - use explicit header value
        proxy_set_header Upgrade \$http_upgrade;
        proxy_set_header Connection "upgrade";

        # Standard headers
        proxy_set_header Host \$host;
        proxy_set_header X-Real-IP \$remote_addr;
        proxy_set_header X-Forwarded-For \$proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto \$scheme;
        proxy_set_header X-Forwarded-Host \$host;

        # Increase timeouts for dev server
        proxy_read_timeout 300s;
        proxy_send_timeout 300s;
        proxy_connect_timeout 300s;

        # No buffering for Next.js
        proxy_buffering off;
    }
}

My .env:

NEXT_PUBLIC_BASE_URL=https://dataroom.domain.com
NEXT_PUBLIC_MARKETING_URL=https://dataroom.domain.com

# Database
DATABASE_URL=postgresql://papermark:xxx@localhost:5432/papermark
POSTGRES_PRISMA_URL=postgresql://papermark:xxx@localhost:5432/papermark?pgbouncer=true
POSTGRES_PRISMA_URL_NON_POOLING=postgresql://papermark:xxx@localhost:5432/papermark

# Next Auth
NEXTAUTH_SECRET=xxx
NEXTAUTH_URL=http://localhost:3000 # tried setting public URL here, but that didn't help

# This variable is from Vercel Storage Blob
BLOB_READ_WRITE_TOKEN=

# Google client id and secret for authentication
GOOGLE_CLIENT_ID=
GOOGLE_CLIENT_SECRET=

# This variable is from Resend to send emails
RESEND_API_KEY=

# This variable is from Tinybird to publish and read event data
TINYBIRD_TOKEN=

# These variables are from Vercel and used for setting up custom domains
PROJECT_ID_VERCEL=
TEAM_ID_VERCEL=
AUTH_BEARER_TOKEN=

# Upstash QStash – required for queues and background jobs
# Get your QStash Token here: https://upstash.com/docs/qstash/overall/getstarted
QSTASH_TOKEN=
QSTASH_CURRENT_SIGNING_KEY=
QSTASH_NEXT_SIGNING_KEY=

# HANKO - required for signup with passkey
# Get your HANKO keys here: https://docs.hanko.io/passkey-api/reference/credentials/list-credentials
HANKO_API_KEY=add-your-hanko-api-key
NEXT_PUBLIC_HANKO_TENANT_ID=add-your-hanko-tenent-id

# Trigger v3
TRIGGER_SECRET_KEY=
TRIGGER_API_URL=https://api.trigger.dev

# [[STORAGE]]
# Defines the storage transport to use. Available options: vercel (default) | s3
NEXT_PUBLIC_UPLOAD_TRANSPORT="vercel"
# REQUIRED: Defines the distribution host (without protocol) to use for the storage transport. Either cloudfront, s3, or vercel blob host. Used in next.config.mjs configuration.
NEXT_PRIVATE_UPLOAD_DISTRIBUTION_HOST="<BLOB_STORE_ID>.public.blob.vercel-storage.com" | "<DISTRIBUTION_ID>.cloudfront.net" | "<BUCKET_NAME>.s3.<REGION>.amazonaws.com"
# OPTIONAL: Defines the endpoint to use for the S3 storage transport. Relevant when using third-party S3-compatible providers.
NEXT_PRIVATE_UPLOAD_ENDPOINT=""
# Defines the region to use for the S3 storage transport. Defaults to us-east-1.
NEXT_PRIVATE_UPLOAD_REGION="us-east-1"
# REQUIRED: Defines the bucket to use for the S3 storage transport.
NEXT_PRIVATE_UPLOAD_BUCKET="YOUR_BUCKET_NAME"
# REQUIRED: Defines the access key ID to use for the S3 storage transport.
NEXT_PRIVATE_UPLOAD_ACCESS_KEY_ID=""
# REQUIRED: Defines the secret access key to use for the S3 storage transport.
NEXT_PRIVATE_UPLOAD_SECRET_ACCESS_KEY=""
# Defines the Cloudfront distribution domain to use for the S3 storage transport. Relevant when using Cloudfront.
NEXT_PRIVATE_UPLOAD_DISTRIBUTION_DOMAIN=""
# Defines the public key ID to sign Cloudfront URLs. Relevant when using Cloudfront.
NEXT_PRIVATE_UPLOAD_DISTRIBUTION_KEY_ID=""
# Defines the private key contents to sign Cloudfront URLs. Relevant when using Cloudfront. Should be a PEM-encoded RSA 2048 private key.
NEXT_PRIVATE_UPLOAD_DISTRIBUTION_KEY_CONTENTS=

# Encryption key for document passwords.
NEXT_PRIVATE_DOCUMENT_PASSWORD_KEY=my-superstrong-document-secret

# [[REDIS LOCKER CONFIGURATION]]
# For bulk upload using tus.io, we use a Redis-based locker to prevent corruption of the data.
UPSTASH_REDIS_REST_LOCKER_URL=
UPSTASH_REDIS_REST_LOCKER_TOKEN=

# [[VERIFICATION]]
# Secret used to generate the checksum for the verification URL
NEXT_PRIVATE_VERIFICATION_SECRET=

# [[INCOMING WEBHOOKS]]
NEXT_PUBLIC_WEBHOOK_BASE_URL=
NEXT_PUBLIC_WEBHOOK_BASE_HOST=

[scgreenhalgh]

I just went through this as well, and to be honest, it's probably better to first try and self-host using Vercel as that is where this has been written and designed for, including many other related services that can be tightly integrated with Vercel.

I am working on a fork with the option to host this using docker containers that i will submit back when complete.

[vaisov-gemba]

I just went through this as well, and to be honest, it's probably better to first try and self-host using Vercel as that is where this has been written and designed for, including many other related services that can be tightly integrated with Vercel.

I am working on a fork with the option to host this using docker containers that i will submit back when complete.

Problem is that due to compliance we have to host this solution on-premise.
For now I've worked this around following this PR

Now I can access the login page, but if I use Google SSO after login I just get redirected back to login screen. Not sure what's wrong.

[scgreenhalgh]

Not at my computer right now but I recall fixing this as the session cookie domain was hard coded to papermark.com in nextauth. Change this or make it correctly use the env base url variables and you should be good to go.

[vaisov-gemba]

Yes, these parts are already updated:

-        host?.includes("papermark.io") ||
+        host?.includes(process.env.DOMAIN || "papermark.io") ||

also:

-const VERCEL_DEPLOYMENT = !!process.env.VERCEL_URL;
+const VERCEL_DEPLOYMENT = (!!process.env.VERCEL_URL || !!process.env.DOMAIN);
-        domain: VERCEL_DEPLOYMENT ? ".papermark.com" : undefined,
+        domain: VERCEL_DEPLOYMENT ? `.${process.env.DOMAIN}` : undefined,

And DOMAIN in .env is set to sub.domain.com

But I'm still getting redirected back to login screen after logging in using Google SSO or email (even in incognito mode)

[scgreenhalgh]

try this:

don't change this as its basically used in other places just to see if it has been deployed on Vercel:

-        host?.includes("papermark.io") ||
+        host?.includes(process.env.DOMAIN || "papermark.io") ||

But add this:

-        domain: VERCEL_DEPLOYMENT ? ".papermark.com" : undefined,
+        domain: VERCEL_DEPLOYMENT ? (process.env.NEXT_PUBLIC_BASE_URL ? `.${new URL(process.env.NEXT_PUBLIC_BASE_URL).hostname}` : undefined) : undefined,

[scgreenhalgh]

Oh whoops I forgot you aren't using Vercel so just add your top line too. But it has a syntax error that I am considering is just because it's a copy paste error.

Also I use NEXT_PUBLIC_DOMAIN instead of making a new domain variable. I used the built in tool to take the bare domain from the variable so that it maintains DRY.

[vaisov-gemba]

But add this:

-        domain: VERCEL_DEPLOYMENT ? ".papermark.com" : undefined,
+        domain: VERCEL_DEPLOYMENT ? (process.env.NEXT_PUBLIC_BASE_URL ? `.${new URL(process.env.NEXT_PUBLIC_BASE_URL).hostname}` : undefined) : undefined,

Woohoo! This change helped and it works now, thanks!

[vaisov-gemba]

@scgreenhalgh what other parameters and services I need to set up for it to work? Do I need to set up NEXT_PUBLIC_UPLOAD_* or it stores data locally on disk? Let's say which services are mandatory to set up for it to work? And which are optional?

[scgreenhalgh]

No, all the services use cloud upload blobs like S3 or Vercel blobs. If you want to store locally you'll have to use a s3-compatible object store. I know of MiniIO but never used it, so YMMV:
https://kodelan.medium.com/step-by-step-guide-setting-up-and-self-hosting-an-s3-bucket-for-free-using-minio-object-storage-813e63cfee9a