
How to Configure Doconut for Distributed Server Deployments
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 viewer that works behind a load balancer without sticky sessions, because every node verifies the same signed access tickets.
Why Distributed Mode Matters
- Scalability – Each node can publish pages to a UNC share or a cloud location; any other node can serve them.
- Security – Requests carry signed access tickets that every node verifies with a shared Data Protection key ring.
- Conversion option – The optional Converter plugin provides supported format-conversion workflows.
These traits let applications keep document rendering inside customer-managed .NET infrastructure and deploy it across supported web-farm configurations.
Shared Storage for Distributed Mode
In distributed mode Doconut publishes the page artifacts to a storage location that every node in the farm can reach – a network (UNC) share or a cloud location served through the Doconut.Clouds handlers (Azure, Amazon S3, Google Cloud and others).
Tip: Use the same UNC path (e.g.,
\\fileserver\doconut) or cloud URL in every instance’s configuration and keep the folder permissions consistent. TheUsePerTokenSubfoldersbehavior 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 it to the number of supported Windows or glibc-based Linux x64 nodes covered by your architecture and license. 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
- Expose the same base URL (e.g., ` on every node.
- Disable sticky sessions – Doconut’s distributed mode removes the need for session affinity.
- Ensure health monitoring checks a basic endpoint of your application (e.g.,
/health) so the balancer only routes traffic to live nodes. - Monitor the shared folder for growth; the default TTL of 30 minutes keeps storage bounded, but you can adjust it per compliance needs.
Benchmark the deployment with your expected concurrency and document set. Doconut’s shared widget store is encrypted at rest with AES-256, but security and capacity depend on the complete application infrastructure.
Ready to try it? Request a 30-day temporary license, start two nodes, point them at a shared UNC path, and test the viewer behind a load balancer without sticky sessions.