Run Document Processing on Your Own Infrastructure

⚡ Quick Start

Choose the setup that fits your workflow. Both options take only a few steps.

.NET 9 (fastest way)

If you already have .NET installed, this is the quickest way to get started.

1. Download the self-host package
2. Extract the archive
3. Run:

dotnet Documentize.SelfHost.dll

Then open http://localhost in your browser.

Docker

Prefer containers? Use the included Dockerfile to run Documentize anywhere.

1. Download the Docker package
2. Build the image:

docker build -t documentize .

Run the container:

docker run -p 80:80 documentize

Then open http://localhost.

🧩 Requirements

Minimal requirements depending on your setup:

• .NET 9 Runtime for direct execution
• Docker for containerized setup

⚙️ More Details

The self-host version is built as a standard ASP.NET Core application, so it behaves exactly like any modern .NET web API.

• Runs locally or on any server
• Default Docker port: 80
• No external services required
• Suitable for internal tools or production use

🔑 Licensing & Subscription

Without a license the API runs in Trial Mode — output files may contain evaluation watermarks. Apply a license to enable full, watermark-free processing.

Free vs. paid tier

Every request — with a key or without one — runs under one of two allowances. A paid subscription is what lifts both the daily quota and, if the key is an active paid subscription, the Aspose watermark.

A paid subscription is proven to the instance by a signed key — either fetched automatically for you (Option 3) or issued manually (Option 4) — never by an environment variable you set yourself: those numbers are compiled into the binary and cannot be raised any other way.

Option 1 — Environment variable

Base64-encode your .lic file and pass it as an environment variable before starting:

# Linux / macOS
export ASPOSE_PDF_LICENSE=$(base64 -w 0 Aspose.Pdf.lic)
dotnet Documentize.SelfHost.dll

# Docker
docker run -p 80:80 \
  -e ASPOSE_PDF_LICENSE=$(base64 -w 0 Aspose.Pdf.lic) \
  documentize

Option 2 — Upload via API

POST the .lic file to your running instance at any time.

curl -X POST http://localhost/webapi/license \
  -F "license=@Aspose.Pdf.lic"

Check the current license status at any time:

GET http://localhost/webapi/license
# { "licensed": true }

Option 3 — Activate with your Documentize account (recommended)

If you already have a Documentize account with an active subscription, you don't need an Aspose .lic file at all. Create a SelfHost activation key below (requires signing in), then set it as an environment variable on your instance. The instance uses the key to call the Documentize API roughly every 6 hours and fetch a short-lived signed entitlement — whatever plan is active on your account is reflected automatically, with no further action from you when you upgrade, downgrade, or renew.

# Linux / macOS / Docker
export DOCUMENTIZE_API_TOKEN=dmk_your_activation_key

This API token is not the same as the "Copy API token" button in the sidebar — that one is a short-lived login token for the hosted Documentize web app. The activation key created below is a separate, long-lived, single-purpose credential: it can only be used to refresh a SelfHost instance's entitlement, and it can be revoked here at any time, which stops the next refresh from renewing that instance — the instance simply keeps running on its last-known entitlement until that grant's own short expiry, then falls back to the free tier.

Independent of Options 1, 2 and 4 — use whichever fits your deployment; an instance is free to run more than one method side by side (a per-request key always wins if you send one — see below).

Option 4 — Manually issue a subscription key (advanced)

Options 1–3 are for the plans sold through the Documentize website. If you are distributing your own long-lived (monthly, yearly, or perpetual) subscription keys — for example as a vendor bundling SelfHost for your own customers — the Documentize.SelfHost binary can mint them itself, offline, from the command line. Neither command touches the network or starts the web server.

First, generate a signing key pair once (keep the private half secret):

dotnet Documentize.SelfHost.dll --new-signing-key
# PUBLIC  (ship this — DOCUMENTIZE_SUBSCRIPTION_PUBLIC_KEY):
# MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA...
#
# PRIVATE (keep secret — needed only to issue keys):
# MIIEvQIBADANBgkqhkiG9w0BAQEFAASCBKcwggSjAgEA...

Set the public half as DOCUMENTIZE_SUBSCRIPTION_PUBLIC_KEY on every instance that should trust keys you issue (a Release build can also have it baked in at compile time). Then issue a key for a customer:

dotnet Documentize.SelfHost.dll --issue-key "<privateKeyBase64>" \
  '{"sub":"customer-123","email":"buyer@example.com","plan":"Pro Yearly","tier":"paid","period":"year","exp":1798761600}'
# DMZ1.eyJzdWIiOiJjdXN0b21lci0xMjMiLCJ0aWVyIjoicGFpZCIsLi4ufQ.MEUCIQD...

Give the printed DMZ1.… value to the customer to set as:

# Linux / macOS / Docker
export DOCUMENTIZE_KEY=DMZ1.eyJzdWIiOiJjdXN0b21lci0xMjMiLC4uLn0.MEUCIQD...
# or, for a docker secret / k8s mount:
export DOCUMENTIZE_KEY_FILE=/run/secrets/documentize_key

Payload fields: sub/email/plan are freeform, shown back on /webapi/usage. tier is "free" or "paid". period is "month", "year", or "perpetual". exp is a Unix timestamp (seconds) the key stops working at — omit it (or set 0) for a perpetual key that never expires. You can optionally cap dailyOps, maxFileMb, or maxConcurrent per key for a bespoke plan; leave them out to use the standard paid-tier numbers above.

This key never expires from your side and never phones home — the instance verifies it completely offline, forever, unless you also set DOCUMENTIZE_KEY_REFRESH_URL to let it check for revocation periodically. This is the right tool for a key you are selling or handing out yourself; Option 3 above is the right tool for a customer with a Documentize account who just wants their own subscription reflected automatically.

Presenting a key on a single request

Whichever option you use, a DOCUMENTIZE_KEY/DOCUMENTIZE_API_TOKEN set on the instance is the default for every request. You can also override it per request, e.g. to test a different key without restarting the instance — any one of these three works, and a per-request key always wins over whatever the instance is configured with:

# Dedicated header
curl http://localhost/webapi/usage -H "X-Documentize-Key: DMZ1...."

# Standard bearer auth (what Swagger UI's Authorize button sends)
curl http://localhost/webapi/usage -H "Authorization: Bearer DMZ1...."

# Query string, for clients that can't set headers
curl "http://localhost/webapi/usage?key=DMZ1...."

Checking your current status

Free, no key required:

GET http://localhost/limits        # human-readable
GET http://localhost/limits.json   # machine-readable
GET http://localhost/webapi/usage  # your own tier, plan, usage today, and licensing status

/webapi/usage reports the same tier/plan a browser sees on the Documentize account page (email, plan name, days left in a term key), plus licensed/licensing fields explaining exactly why the Aspose watermark is or isn't applied right now — the first place to check if paid processing doesn't look the way you expect.