Public API

cloudServerUrl

export const cloudServerUrl: string; // "http://localhost:8080/app"

The Parse Server mount URL used internally by cloud functions and adapters. Override via SERVER_URL env var logic if you change the port or path.

serverAppId

export const serverAppId: string; // defaults to "opensign"

The Parse application ID read from process.env.APP_ID. Pass this as the applicationId when initialising a Parse JS SDK client that talks to this server.

replaceMailVaribles

export function replaceMailVaribles(
  subject: string,
  body: string,
  variables: Record<string, string>
): { subject: string; body: string };

Replaces {{variable}} placeholders in email subject and body strings. Use it when building custom email notifications before handing them to a transporter.

runDbMigrations

export default async function runDbMigrations(): Promise<void>;

Runs all pending database migrations (creates indexes on the Contacts and Documents collections). Called once at boot; safe to re-run idempotently.

SSOAuth

export const SSOAuth: object; // Parse Server auth adapter

Drop-in Parse Server auth adapter for SSO. Pass it in the auth config object when instantiating ParseServer.

validateSignedLocalUrl

export function validateSignedLocalUrl(req: Request, res: Response, next: NextFunction): void;

Express middleware that validates signed local file URLs. Mounted by index.js before serving the files/ directory.

Working examples

Scenario - Start the Parse Server with S3 storage

Demonstrates importing core constants and booting the server programmatically in a wrapper script.

import dotenv from 'dotenv';
dotenv.config();
import { ParseServer } from 'parse-server';
import { serverAppId, cloudServerUrl, appName } from './source/Utils.js';
import { SSOAuth } from './source/auth/authadapter.js';

const server = new ParseServer({
  appId: serverAppId,
  appName: appName,
  masterKey: process.env.MASTER_KEY!,
  serverURL: cloudServerUrl,
  databaseURI: process.env.DATABASE_URI!,
  cloud: './source/cloud/main.js',
  auth: { sso: SSOAuth },
});

await server.start();
console.log(`Parse Server running at ${cloudServerUrl}`);

Scenario - Replace template variables in an outgoing email

Shows how to use replaceMailVaribles to hydrate a stored email template before dispatch.

import { replaceMailVaribles } from './source/Utils.js';

const template = {
  subject: 'Please sign: {{documentName}}',
  body: 'Hi {{signerName}}, your document "{{documentName}}" is ready to sign.',
};

const vars = { documentName: 'Service Agreement', signerName: 'Alice' };
const { subject, body } = replaceMailVaribles(template.subject, template.body, vars);

console.log(subject); // "Please sign: Service Agreement"
console.log(body);    // "Hi Alice, your document "Service Agreement" is ready to sign."

Scenario - Run DB migrations manually before accepting traffic

Useful when you orchestrate the server yourself and want migrations to complete before any request hits the API.

import runDbMigrations from './source/migrationdb/index.js';

async function boot() {
  console.log('Running database migrations...');
  await runDbMigrations();
  console.log('Migrations complete. Starting HTTP server...');
  // start your Express app here
}

boot().catch((err) => {
  console.error('Boot failed:', err);
  process.exit(1);
});

File walkthrough

• index.js - Entry point. Creates the Parse Server instance, wires S3 or local file adapter, configures nodemailer/Mailgun transporter, mounts custom Express routes, and starts the HTTP server.
• Utils.js - Shared constants (cloudServerUrl, serverAppId, appName, color palette), the replaceMailVaribles helper, file-usage tracking, and signed-URL utilities.
• cloud/main.js - Imports and registers every Parse Cloud Function and trigger (AfterSave, BeforeSave, AfterFind hooks). This is the cloud entry point passed to ParseServer.
• cloud/customRoute/customApp.js - A standalone Express app instance that handles routes not served by Parse (PDF decrypt, docx-to-PDF, account deletion).
• cloud/parsefunction/ - One module per cloud function: document lifecycle, contact management, signing, template operations, user management, reporting, etc.
• auth/authadapter.js - Exports SSOAuth, the Parse Server-compatible SSO authentication adapter.
• migrationdb/index.js - Orchestrates idempotent MongoDB index creation migrations on boot.
• utils/fileUtils.js - Low-level file parsing helpers used by Utils.js.
• font/ - Font files consumed by PDF generation functions in cloud/parsefunction/pdf/.
• databases/ - Database-level helpers consumed by cloud functions.
• public/ - Static files (HTML, assets) served directly by Express.

Common pitfalls and fixes

• ESM-only package: "type": "module" must be in package.json. Using require() anywhere will throw ERR_REQUIRE_ESM. Fix: convert all local wrappers to import.
• APP_ID defaults silently: If APP_ID is missing from .env, it falls back to "opensign". A second Parse Server instance with the same app ID and different master key will cause auth failures. Fix: always set APP_ID explicitly.
• S3 adapter silently falls back to local: If any S3 env var is missing or the endpoint is malformed, index.js catches the error and switches to FSFilesAdapter. Files then accumulate on disk unnoticed. Fix: validate all DO_* env vars at startup.
• USE_LOCAL is a string, not a boolean: The guard is useLocal !== 'true'. Passing USE_LOCAL=false (as a boolean) will evaluate as truthy for S3 but the string 'false' will also enable S3 since 'false' !== 'true'. Fix: always set USE_LOCAL=true or omit the variable.
• dotenv quiet option: The code calls dotenv.config({ quiet: true }). If your .env file is missing entirely, no error is raised, and all env vars will be undefined. Fix: add a startup validation step that asserts required keys.
• Parse Server version pinning: parse-server has breaking changes across minor versions affecting cloud function signatures and adapter interfaces. Fix: pin the exact version from the upstream package.json rather than using a range.

Vibe-coding prompt template

I have purchased the "opensign" AVCP block. The source is in ./source/ and
the integration guide is in USAGE.md (read it first).

The upstream npm package is user@example.com (backend only, Node.js/Express +
Parse Server). My project is a Node.js/TypeScript REST API and I need to
integrate the OpenSign backend into it.

Please do the following step by step:
1. Read USAGE.md fully before writing any code.
2. Install all required dependencies listed in USAGE.md into my project.
3. Copy or import from source/ the minimum files needed to spin up the
   Parse Server with cloud functions (index.js, cloud/main.js, Utils.js,
   auth/authadapter.js, migrationdb/index.js).
4. Wire the .env variables from USAGE.md into my existing environment
   configuration (dotenv or config package).
5. Add a startup sequence that runs runDbMigrations() before the HTTP
   server accepts connections.
6. Mount the custom Express routes from source/cloud/customRoute/customApp.js
   onto my existing Express app at the /opensign prefix.
7. Show me how to call replaceMailVaribles() from source/Utils.js in my
   existing email-sending module.
8. Do not invent any new exports; only use symbols documented in USAGE.md.

License and credit

OpenSign is released under the AGPL-3.0 license (see source/LICENSE if present, or the upstream repository). Source: OpenSignLabs/OpenSign on GitHub. Upstream npm package: user@example.com.

This product’s unique contribution is clean room implementation of valuable code block into AVCP compatible standard.

The full install guide and integration prompts unlock after purchase.

Documenso Open Source Document Signing Platform

CRM, ERP, Admin & Internal Tools

Free