Purpose:
This guide explains how to deploy a Digital Slide Archive (DSA) instance, from a quick container-based startup to production-scale deployment considerations.
It is intended for both:
This section gets a DSA instance running on your local machine in minutes. This is not yet a production deployment it is a way to verify the software works and to begin exploring configuration before making infrastructure decisions.
Before starting, ensure you have:
apt install docker-compose-plugin on Ubuntu). The Docker Compose V2 plugin is invoked as docker compose (with a space), not docker-compose (with a hyphen).Why these requirements? DSA runs as a multi-container stack: a MongoDB database, a RabbitMQ message broker, one or more Celery worker processes for background tasks (like tile generation), and the Girder-based web application itself. Each of these consumes memory and disk. The 4 GB minimum keeps the stack responsive even during initial data import.
# 1. Clone the official repository
git clone https://github.com/DigitalSlideArchive/digital_slide_archive
cd digital_slide_archive/devops/dsa
# 2. Pull the latest container images
docker compose pull
# 3. Launch the stack
# IMPORTANT: Do NOT run this as root/sudo/admin.
# Running as root causes file ownership problems inside containers
# and creates security risks on the host.
DSA_USER=$(id -u):$(id -g) docker compose upWhy
DSA_USER=$(id -u):$(id -g)? This passes your host user and group IDs into the container environment. DSA’s worker processes write files (uploaded slides, generated tiles, logs) to mounted volumes. Without this, those files would be owned by root inside the container, making them unmanageable from the host. By matching the container user to your host user, files written by the container are naturally owned by you.
After the containers start (this may take a minute on first launch), you need to access the DSA web interface. How you do this depends on where you are running the containers:
If you launched the containers on the same machine where your browser is running, open a browser and navigate to:
http://localhost:8080What is localhost? localhost is a special network name that always refers to the machine you are currently using. It maps to the IP address 127.0.0.1. When you access http://localhost:8080, your browser connects to port 8080 on your own machine, which is where the DSA container is listening.
If you launched the containers on a separate server (e.g., a lab server or a VM in your institution’s data center), you need the server’s IP address instead of localhost. Open a browser on your own machine and navigate to:
http://<SERVER_IP>:8080Replace <SERVER_IP> with the actual IP address of the server.
How to find the server’s IP address:
hostname -I or ip addr show on the server. Look for the inet address on the primary network interface (not the 127.0.0.1 loopback address).ipconfig on the server. Look for the IPv4 Address under the active network adapter.Note: If the server is on an internal network, you must be on that network (or connected via VPN) to reach it. If you cannot connect, check with your IT department about network access to the server.
You should see the DSA web interface. At this point:
The remaining sections of this guide address how to move from this local instance to a production-ready deployment. For details on securing the deployment, see Security and SSL Deep Dive. For details on the tunnel-based access model, see Secure Tunnel Deep Dive.
Before configuring anything else, you must answer one fundamental question: How will users reach the DSA server?
This decision shapes every subsequent configuration step: DNS, SSL, firewall rules, and even storage layout all depend on the network topology you choose.
There are two primary models:
In this model, the DSA server (or its reverse proxy) is directly reachable from the internet. Users navigate to a public URL like https://bdsa.institution.edu, and traffic flows directly to your server.
graph TD
A[User Browser] -->|HTTPS| B[Public DNS<br>bdsa.institution.edu]
B -->|Resolve IP| C[Reverse Proxy<br>NGINX/Apache]
C -->|HTTP :8080| D[DSA Containers<br>Girder + Workers]
D -->|Read/Write| E[Slide Storage<br>Local/NFS/S3]
style A fill:#4A90D9,color:#fff
style B fill:#7B68EE,color:#fff
style C fill:#F5A623,color:#fff
style D fill:#D0021B,color:#fff
style E fill:#9B9B9B,color:#fffThe reverse proxy is the single entry point, handling SSL termination and forwarding to the DSA containers.
bdsa.institution.edu, that maps to an IP address): Your server must be reachable on the internet. This typically means your institution’s IT department must assign you a public IP and configure routing. Submit an IT ticket to request a public IP and DNS record for your chosen hostname.Choose public deployment when your institution allows inbound internet traffic to research servers and you have IT support to manage firewall rules and DNS. This is the simpler path and is recommended unless institutional policy forbids it.
In this model, the DSA server lives on an internal network behind a firewall that blocks all inbound connections. Instead of opening the firewall, a secure tunnel carries traffic from a public-facing Hub node to the internal DSA server.
The key insight is that the tunnel is established outbound from the internal server: the internal server connects out to the Hub node, and the Hub node bridges incoming user traffic through that connection. Since the firewall allows outbound connections, no inbound rules need to be opened.
graph TD
A[User Browser] -->|HTTPS| B[Hub Node<br>NGINX + SSL]
C[Internal DSA Server] -->|Outbound Tunnel<br>Initiated from inside| B
B -->|Forward via Tunnel| C
C -->|Read/Write| D[Slide Storage]
style A fill:#4A90D9,color:#fff
style B fill:#F5A623,color:#fff
style C fill:#D0021B,color:#fff
style D fill:#9B9B9B,color:#fffNote that the tunnel connection originates from the internal server (outbound), which is why no inbound firewall rules are needed.
Choose tunnel deployment when your institution’s IT policy prohibits inbound internet traffic to internal servers, or when your slide data is subject to compliance requirements that mandate network isolation. Be aware that this adds operational complexity: the tunnel is an additional service that must be monitored and maintained. For a detailed walkthrough, see Secure Tunnel Deep Dive.
Before proceeding to detailed configuration, work through these decisions with your team and IT department. Each decision affects the others, so it helps to address them in order.
A hostname is a human-readable name that identifies your server on the network (for example, bdsa.institution.edu). Instead of typing a numeric IP address like 203.0.113.50, users type the hostname, and DNS (the Domain Name System, which acts as a phonebook for the internet) translates it to the correct IP address.
Choose a stable, memorable hostname. This hostname will be used for:
Changing the hostname later is disruptive. It requires new SSL certificates, DNS updates, and notifying all users. Choose carefully at the outset.
How to set up a hostname: Submit an IT ticket to your institution’s networking team requesting a DNS A record (or CNAME) for your chosen hostname pointing to your server’s IP address. Your IT department will handle the DNS configuration.
If the server has a public IP and can accept inbound connections, use Option A (public deployment). If the server is on an internal network with no inbound access, use Option B (tunnel deployment).
This is determined by the previous question. If the server is not public, you need a tunnel. Plan for:
At minimum, the public-facing server (whether it is the DSA server itself or the Hub node) must accept:
All other ports should be closed at the firewall level. Submit an IT ticket to request that the appropriate ports be opened on the firewall.
Determine whether your institution’s IT department manages certificates or whether you will manage them yourself. This affects:
Institutional CA is the most common choice. Most universities and research institutions have their own certificate authority or a contract with a commercial CA provider. Check with your IT department first before exploring other options.
Automated renewal is strongly recommended. Let’s Encrypt with Certbot can renew certificates automatically via cron or systemd timer. Sectigo, a widely used certificate management service, also provides automated renewal tools for institutional deployments. If your institution uses a different CA, ensure there is a documented renewal process.
What does it mean to renew a certificate? SSL certificates have an expiration date (typically 90 days for Let’s Encrypt, 1 year for most commercial CAs). After expiration, browsers will refuse to connect to your site. Renewal means obtaining a new certificate from the certificate authority before the old one expires, and installing it on your server. With automated renewal, this process runs on a schedule without manual intervention. Without it, someone must remember to request and install a new certificate before the old one expires, which is easy to forget and can cause unexpected outages.
An expired certificate will make the DSA instance inaccessible: browsers will refuse to connect.
DSA supports several authentication methods:
Choose authentication before going live. Changing authentication methods after users have created data and annotations is possible but requires careful migration.
CILogon allows users to authenticate using their existing institutional credentials. Here is the high-level setup process:
Register a CILogon client: Navigate to https://cilogon.org/oauth2/register and fill out the registration form. Set the client name to your BDSA site name, the Home URL to your site’s public domain (e.g., https://bdsa.institution.edu), and the callback URL to https://bdsa.institution.edu/api/v1/oauth/cilogon/callback. Set the Client Type to Confidential and request the scopes: email, org.cilogon.userinfo, and profile. After registration, save the client ID and client secret (you cannot retrieve the secret later).
Configure the OAuth plugin in BDSA: Log in to your BDSA server with an admin account. Go to Admin Console > Plugins, locate the "OAuth2 Login" plugin, and select the gear icon. Open CILogon from the list, enter your client ID and client secret, and save.
Set the server root: From the footer of the page, select "Web API". Find the "system" section and add the key core.server_root with the value set to your site URL (e.g., `https://bdsa.institution.edu)
For detailed, step-by-step instructions with screenshots, refer to the [BDSA CILogon Documentation](<link here>).
Whole-slide images (WSIs) are large: typically 500 MB to 5 GB per slide, and some modalities (e.g., multi-frame fluorescence) can exceed 10 GB per slide. A collection of 1,000 slides can easily require 2-5 TB of storage.
Estimate your storage needs based on:
Always over-provision storage by at least 50%. Slide collections grow faster than expected, and running out of disk space during an import can corrupt data.
Plan for growth from the start. Options include:
Backups must be stored separately from the primary storage. If the primary storage fails, the backup must still be accessible. Consider:
Someone must be responsible for noticing when the DSA instance is down. Options include:
DSA releases updates periodically. Someone must:
Backups must be:
See the expanded backup operations section under Scaling Considerations for details on what taking backups looks like in practice.
Use the GitHub-provided Docker deployment to start the full DSA stack:
git clone https://github.com/DigitalSlideArchive/digital_slide_archive
cd digital_slide_archive/devops/dsa
docker compose pull
DSA_USER=$(id -u):$(id -g) docker compose up -dWhy
-d? The-dflag runs containers in the background (detached mode). For initial testing, you may want to omit-dto see logs in the terminal. For production, use-dand manage logs through Docker’s logging driver.
This provides the application runtime environment but does not expose a secure public service. The containers listen on localhost only, without encryption.
The reverse proxy sits between users and the DSA containers. It serves several critical functions. For a deeper explanation of why the reverse proxy handles SSL termination, see Security and SSL Deep Dive.
You might wonder: why not expose the DSA container directly? Several reasons:
The two most common choices for DSA deployments are:
Which should you choose? If you do not have an existing preference, NGINX is recommended for its simpler configuration syntax and strong performance. If your institution’s IT team is more familiar with Apache, use Apache.
Regardless of which proxy you choose, you must configure:
Note on upload size limits: In a typical BDSA deployment, users do not directly upload slide files through the browser. Instead, slides are stored in assetstores (configured storage locations that DSA manages). The assetstore configuration handles file size limits, so the reverse proxy’s client body size limit is less critical than it would be for direct browser uploads. However, if you do allow direct browser uploads, set the client body size limit to at least the size of your largest expected slide (e.g.,
client_max_body_size 10Gin NGINX).
DNS (the Domain Name System) maps your chosen hostname to the server’s IP address:
bdsa.institution.edu → 203.0.113.50Without DNS, users must access DSA via IP address (e.g., https://203.0.113.50). This causes several problems:
bdsa.institution.edu will not validate when users connect via IP. Browsers will show security warnings.Submit an IT ticket to your institution’s networking team requesting a DNS A record (or CNAME) pointing your chosen hostname to the server’s public IP. If using a tunnel deployment, the DNS record should point to the Hub node’s IP, not the internal DSA server.
SSL (Secure Sockets Layer), now more accurately called TLS (Transport Layer Security), is the protocol that encrypts data sent between a user’s browser and the server. When you see https:// in a URL, the "s" means the connection is using SSL/TLS. SSL certificates are digital files that enable this encrypted connection and verify the server’s identity.
SSL/TLS certificates provide three essential functions:
| Option | Cost | Renewal | Best For |
|---|---|---|---|
| Institutional CA | Varies (often free) | Varies (often automated) | Most deployments; check with your IT department first |
| Let’s Encrypt | Free | Automated (90-day) | When institutional CA is not available |
| Sectigo | Varies (institutional licensing) | Automated tools available | Institutions that use Sectigo’s certificate management platform |
| Commercial CA | Paid | Manual or semi-automated (1-year) | When institutional policy requires a specific commercial CA |
Start with your institution’s IT department. Most institutions have an established process for provisioning SSL certificates. They may use an internal CA, a contract with a provider like Sectigo, or Let’s Encrypt. Using the institutional process is almost always the easiest path.
The DSA container must be able to access:
Test with a real slide early. Before committing to a storage architecture, upload a full-size WSI and verify that tile generation completes successfully. Some network storage configurations have latency or locking characteristics that cause issues with DSA’s tile generation process.
Storage is often the largest and most consequential deployment decision for a DSA instance. Whole-slide images are among the largest files commonly served over the web, and the storage architecture you choose affects performance, cost, reliability, and scalability.
graph TD
subgraph Local Storage
A1[DSA Server] -->|Direct I/O| A2[Local Disk<br>Simple, Fast, Limited Scale]
end
subgraph Network Storage
A1[DSA Server] -->|NFS/SMB Mount| B2[Network Appliance<br>Centralized, Expandable]
end
subgraph Object Storage
A1[DSA Server] -->|S3 API| C2[Object Store<br>Scalable, Durable, Complex]
end
style A1 fill:#4A90D9,color:#fff
style A2 fill:#9B9B9B,color:#fff
style B2 fill:#7B68EE,color:#fff
style C2 fill:#50C878,color:#fffThis diagram helps stakeholders understand the tradeoffs between storage options at a glance.
Slides are stored on disks directly attached to the DSA server (e.g., internal SSDs or HDDs, or directly attached RAID arrays).
Local storage is ideal for single-server deployments with a known, bounded collection size. If you expect fewer than a few thousand slides and do not plan to scale to multiple web nodes, local storage is the simplest and fastest option.
Slides are stored on mounted network storage (NFS, SMB/CIFS, or similar). The DSA server accesses files through a network mount point.
Network storage is a good middle ground for medium deployments (hundreds to low thousands of slides) where you need centralized management or plan to run multiple DSA nodes. Ensure your network infrastructure can handle the bandwidth.
Slides are stored in S3-compatible object storage (AWS S3, MinIO, Azure Blob Storage, etc.). DSA accesses files through the S3 API.
Object storage is the best choice for large or growing collections (thousands of slides and beyond), multi-node deployments, and cloud-hosted DSA instances. The upfront complexity pays off in scalability and durability.
A small DSA deployment (a few dozen users, a few hundred slides) runs comfortably on a single server. As usage grows, you may need to scale individual components. The key principle is to scale components independently: do not add more web servers if the bottleneck is the database.
graph TD
A[User Browser] -->|HTTPS| B[Load Balancer]
B -->|HTTP| C[DSA Web Node 1]
B -->|HTTP| D[DSA Web Node 2]
C -->|Tasks| E[RabbitMQ]
D -->|Tasks| E
E -->|Dispatch| F[Worker Node 1]
E -->|Dispatch| G[Worker Node 2]
C -->|Read/Write| H[Shared Storage<br>NFS or S3]
D -->|Read/Write| H
C -->|Metadata| I[MongoDB<br>Dedicated Server]
D -->|Metadata| I
style A fill:#4A90D9,color:#fff
style B fill:#F5A623,color:#fff
style C fill:#D0021B,color:#fff
style D fill:#D0021B,color:#fff
style E fill:#FFD700,color:#333
style F fill:#50C878,color:#fff
style G fill:#50C878,color:#fff
style H fill:#9B9B9B,color:#fff
style I fill:#7B68EE,color:#fffThis diagram illustrates an enterprise-scale deployment with independent scaling of web nodes, workers, storage, and database.
As user count grows, separate the DSA stack into independent components that can be scaled individually:
Start by scaling workers first. In most DSA deployments, the limiting factor is tile generation throughput, not web request capacity. Adding worker processes (or worker nodes) gives the most immediate performance improvement.
As your slide collection grows, consider the tradeoffs of cloud-based object storage:
If you started with local or network storage and are running into capacity limits, migrating to object storage (cloud or on-premises MinIO) eliminates the capacity planning problem entirely.
Large deployments may need:
mongodump or filesystem snapshots on a regular schedule. For production deployments, automate this and store backups off-server.Taking backups is not just about running a command once. It is an ongoing operational process. Here is what it looks like in practice:
The MongoDB database contains all metadata: user accounts, collection structures, annotations, and permissions. Losing this data means losing the organizational structure of your entire slide archive, even if the slide files themselves are preserved.
mongodump daily (or more frequently for active deployments). Automate this with a cron job or systemd timer.Slide files (the WSI data) are much larger than the database. Your backup strategy depends on whether the original source files are still available:
You cannot manage what you cannot see. Implement observability from the start:
Observability is generally managed by the development team. The team responsible for the DSA deployment should set up monitoring and alerting, and make dashboards and status pages easily available to users so they can check system health without needing technical access.
SSL/TLS is not optional for a production DSA deployment. This section explains why and how it works.
SSL (Secure Sockets Layer), more accurately called TLS (Transport Layer Security) in modern usage, is the standard technology for encrypting data sent between a web browser and a web server. When you visit a URL that starts with https://, the "s" stands for "secure" and means the connection is encrypted using SSL/TLS.
Without SSL/TLS encryption, everything sent between the browser and the server, including usernames, passwords, and slide data, travels across the network in plain text. Anyone who can intercept the network traffic (which is trivial on shared Wi-Fi networks and possible on institutional networks) can read everything. SSL/TLS prevents this by encrypting the data so that only the intended recipient can read it.
Without SSL:
Browser requests https://bdsa.institution.edu
↓
Server presents SSL certificate
↓
Browser validates certificate (checks CA signature, expiration, domain match)
↓
Encrypted session established (TLS handshake complete)
↓
All traffic between browser and server is encrypted
↓
Reverse proxy decrypts and forwards to DSA containers over internal HTTPYou might wonder why the reverse proxy handles SSL instead of the DSA application itself. There are several important reasons:
graph LR
A[User Browser] -->|Encrypted HTTPS| B[Reverse Proxy<br>SSL Certificate Here]
B -->|Decrypted HTTP| C[DSA Container<br>No Certificate Needed]
style A fill:#4A90D9,color:#fff
style B fill:#F5A623,color:#fff
style C fill:#D0021B,color:#fffThis diagram highlights where encryption ends and internal forwarding begins. The DSA container never handles certificates; the proxy centralizes this responsibility.
For environments where the DSA server cannot be directly exposed to the internet, a secure tunnel provides access without compromising network isolation. This is the architecture used in Option B: Secure Tunnel Deployment Behind Firewall.
User Browser
↓ HTTPS
Hub Node (NGINX + SSL)
↓ Tunnel (encrypted)
Internal DSA Server
↓
Slide StorageThe tunnel architecture provides a critical security property: the internal server never accepts inbound connections from the internet. The firewall can block all incoming traffic, and the DSA instance is still accessible because the tunnel connection originates from inside the network.
This is often required for:
When implementing a tunnel, document the following:
The container deployment is only the first step. A production DSA deployment also requires:
The most important early decisions are:
These three decisions are foundational: they determine the rest of the deployment design and are expensive to change later. Invest the time to make them correctly at the outset.
Imported from gh:Kentucky-Open-Science/BDSA_Setup_Documentation. Source last updated 2026-04-28. Synced 2026-07-27.
Source code on GitHub.
apt install docker-compose-plugin on Ubuntu). The Docker Compose V2 plugin is invoked as docker compose (with a space), not docker-compose (with a hyphen).