Use Doconut in Distributed Server Configuration

When you need to serve PDFs, Office files, CAD drawings, or images from a cluster of ASP.NET Core nodes, Doconut’s distributed mode lets every node read the same page artifacts from a shared location. The result is a horizontally‑scalable, secure viewer that works behind a load balancer without sticky sessions.

Why Distributed Mode Matters

• Scalability – Each node can publish pages to a UNC or cloud share; any other node can serve them instantly.
• Security – Artifacts are stored encrypted on the shared folder; the viewer validates every request against the ASP.NET session token.
• Zero Office dependency – The Converter plugin runs server‑side, converting Word, Excel, PowerPoint, CAD, and images to PDF or images without installing Microsoft Office.

These traits let enterprise DMS, CRM, or e‑learning portals keep document processing inside the .NET back‑end while scaling to dozens of containers.

Shared Storage for Distributed Mode

In distributed mode Doconut expects the page artifacts (PDF pages, image tiles, etc.) to be written to a storage location that is reachable by every node in the farm – a network share, Azure Blob container, S3 bucket, or any other shared storage supported by the Progressive Cloud Publishing feature. The viewer automatically looks for the artifact folder that matches the per‑document security token, so no additional code is required beyond ensuring that all nodes have the same read‑write access to the chosen storage.

Tip: Use the same UNC path (e.g., \\fileserver\doconut) or cloud URL in every instance’s configuration and keep the folder permissions consistent. The UsePerTokenSubfolders behavior is enabled by default and isolates each document’s pages.

Registering Doconut and Session Middleware

Doconut relies on ASP.NET Core session state for per‑document security. A distributed cache is required only when you use a minimal‑API project; MVC or Razor Pages already add one.

builder.Services.AddDoconut(options =>
{
    options.LicensePath = "Doconut.Viewer.lic";
});

builder.Services.AddDistributedMemoryCache(); // session needs a cache
builder.Services.AddSession();                 // Doconut validates against session

app.UseSession();               // Must run before UseDoconut()
app.UseDoconutResources();      // Registers static viewer assets
app.Map("/doconut", branch => branch.UseDoconut());

Custom Paths (optional)

If another route conflicts with /doconut, change the paths once and keep the client BasePath in sync:

builder.Services.AddDoconut(options =>
{
    options.MiddlewarePath = "/docs-engine";
    options.ResourcesPath  = "/docs-assets";
});
app.UseDoconutResources();
app.Map("/docs-engine", branch => branch.UseDoconut());

Never prepend a leading slash to MiddlewarePath or ResourcesPath; the viewer adds the slash automatically.

Putting It All Together: Minimal‑API Example

Below is a compact, production‑ready setup that combines the shared‑storage requirement, session handling, and Doconut registration.

var builder = WebApplication.CreateBuilder(args);

// 1️⃣ Core Doconut registration
builder.Services.AddDoconut(options =>
{
    options.LicensePath = Path.Combine(
        AppContext.BaseDirectory, "wwwroot", "Doconut.Viewer.lic");
    options.MiddlewarePath = "/doconut";
    options.ResourcesPath  = "/doconut-res";
});

// 2️⃣ Session and cache (required for security)
builder.Services.AddDistributedMemoryCache();
builder.Services.AddSession();

var app = builder.Build();

app.UseRouting();
app.UseSession();
app.UseDoconutResources();                     // static viewer bundle
app.Map("/doconut", branch => branch.UseDoconut());

app.Run();

Deploy this binary to any number of Docker containers or Windows services behind a load balancer. As long as each instance can reach the shared storage location you configured for page artifacts, the viewer will fetch pages from any node, and uploads/conversions will survive node hops.

Deploying Behind a Load Balancer

1. Expose the same base URL (e.g., ` on every node.
2. Disable sticky sessions – Doconut’s distributed mode removes the need for session affinity.
3. Ensure health monitoring checks a basic endpoint of your application (e.g., /health) so the balancer only routes traffic to live nodes.
4. Monitor the shared folder for growth; the default TTL of 30 minutes keeps storage bounded, but you can adjust it per compliance needs.

With these steps, your document‑intensive .NET application can serve thousands of concurrent viewers, keep every page encrypted at rest, and avoid the overhead of installing Office on each server.

Ready to try it? Grab a free trial of Doconut, spin up a couple of containers, point them at a shared UNC path, and watch the viewer scale without a single sticky‑session cookie.