🚀 Deployment

Local Build

Docker Build

Quick Deployment (Docker Compose)

Manual Deployment (no CI/CD)

You can run the full production stack (MongoDB, Redis, Application Service, Background Worker, and Web) on a single host without a pipeline. Build the images, render the secrets file, then bring the stack up — the same steps the pipeline automates.

Production Considerations

• Persistent Storage: Docker volumes preserve data across deployments
• Environment Variables: Configure production settings via environment
• SSL/TLS: Add reverse proxy (nginx/Apache) for HTTPS
• Monitoring: Use built-in health checks and infrastructure monitor
• Backups: Regular database backups, configuration backups, and the Data Protection key ring — losing the ring makes every encrypted field permanently unreadable
• Scaling: single-node by default; run multiple instances behind a load balancer with a shared data tier, sticky sessions, and a single worker
• Background Processing: .NET Worker Service handles background tasks including push notifications, data cleanup, and AI workflows

How the pipeline works

One multi-stage pipeline builds, tests, and deploys — no separate release step. The flow is identical on Azure DevOps and GitHub Actions, and the container registry is a setting you choose:

• Test — unit + relational integration tests and migration guards.
• Build — builds the four images (Web, InternalApi, BackgroundWorker, DbMigrator) and pushes them to your registry with a readable version tag from the repo-root VERSION file plus the CI build number — e.g. 1.0.0.2517 (immutable, what Deploy pins), alongside floating 1.0.0 and latest tags. Bump VERSION for a release.
• Deploy — renders secrets into a git-ignored deploy.env, pulls the exact image tag, runs the DbMigrator as a gated one-shot (a failure blocks the deploy before the app is touched), then docker compose up and a /health check. Rollback = re-deploy a prior image tag.

Where the stages run: the pipeline ships with Test + Build on a self-hosted Default agent pool and Deploy on your server (an Environment VM resource). To run Test/Build on free Microsoft-hosted Linux agents instead, set their pool: to vmImage: 'ubuntu-latest'. The shell steps are cross-platform (a Git-Bash guard handles Windows), so a Windows or Linux self-hosted agent works either way — each just needs Docker, and its account authorised for Docker (LocalSystem or the docker-users group on Windows; the docker group on Linux).

Secrets — one variable set, both platforms

Deploy-time secrets live in an Azure DevOps variable group (or GitHub Actions secrets), never in the pipeline files. The Deploy stage maps them into scripts/render-deploy-env.sh, which writes the git-ignored deploy.env that docker compose reads. Required (fail-closed) keys:

Plus one non-secret variable: DATABASE_USERNAME. It is required on MongoDB and PostgreSQL and has no default; SQL Server does not take one, because the image cannot rename sa.

The datastore credentials are checked by a Validate deploy configuration job that runs alongside the tests, before anything is built or pushed — so a missing or unusable value costs seconds rather than a full test pass and four image builds, and every problem is named at once. It checks more than presence: the character rules above, whitespace, a minimum length, values that look like the placeholders this repository ships, and SQL Server's own complexity rule. It is a separate job rather than a step in the build precisely so it can run that early: the deploy secrets stay out of the jobs that run restore, the test suites and third-party analysers, and it skips itself on a pull request, where a fork can read no secrets at all.

The app secrets are checked one step later, by scripts/render-deploy-env.sh, which fails closed on its own required list. The split is by kind, not importance: one checks what docker compose interpolates to configure the database and Redis containers, the other checks what the app itself reads from configuration.

The two database names — set once, at the first deploy

Both are optional pipeline variables (not secrets), and both default to what the stack has always used. Leave them unset unless you have a reason:

You need them when one Postgres or SQL Server instance carries more than one deployment, or when a house naming convention has to be honoured. Every compose file feeds both to all four services from the one variable, which is the point: the name the model qualifies its tables into and the name the repository routes reads to have to be the same string, and one service left on a different value is an empty database rather than an error.

Most other keys (OAuth, email, OpenAI, OpenRouter, N8N) fall back to appsettings.json when omitted. Site identity does not — it ships blank so a copy of this repository carries none, so set these to your own values:

Lite mode — the single-process shape

The banner at the top of this page says "run the pieces you need". Lite mode is how: docker-compose.lite.yml at the repo root declares two services — the Web app and its database — and nothing else. No Redis, no separate API service, no separate worker. The same job handlers run inside the web process, and the recurring sweeps run there too. Same code, one container to operate — and one product feature turned off, below.

You do not set Messaging:Transport by hand. The compose file sets ASPNETCORE_ENVIRONMENT=Lite, and appsettings.Lite.json supplies InProcess along with the rest of the single-process configuration — one source of truth, so the transport cannot disagree with the containers actually running.

Move to the full stack when you want background work isolated from request serving, want to scale the two independently, or want more than one app instance. Lite is a single-instance profile in a stronger sense than just "one container is enough": with no Redis there is no shared cache-eviction bus, no SignalR backplane, no shared rate-limit counter and no shared key ring, so a second replica would not see the first one's writes. Multi-instance also needs the separate worker, so that timer sweeps fire once rather than once per instance.

Pick your database backend

The stack runs on MongoDB (default), PostgreSQL, or SQL Server. Set DATABASE_TYPE in the variable group / Actions variables to postgresql or sqlserver and the Deploy stage picks the matching compose file (all three are equally pipeline-ready: gated migrator, secrets, pinned volumes). Every backend needs the same two secrets — DATABASE_PASSWORD and REDIS_PASSWORD — plus DATABASE_USERNAME on MongoDB and PostgreSQL. Switching backend changes the VALUES, never the variable names. The app images are backend-agnostic (the backend is chosen at runtime), so switching needs no rebuild — but switching a live deployment is a data migration, not just a setting change.

Choosing your container registry

The registry is a setting, not baked into the pipeline. Create the matching service connection (Azure DevOps) or set the REGISTRY_* variables (GitHub Actions), then point REGISTRY_BASE at the image prefix — the pipeline appends /<image-name>:<tag> to it:

• ACR takes no owner segment — the registry itself is the namespace. GHCR and Docker Hub both need the org/username segment.
• No trailing slash, and GHCR must be lowercase — ghcr.io/myorg, never ghcr.io/MyOrg, or the push fails.
• Azure DevOps → GHCR uses a service connection of type Others: URL https://ghcr.io, your GitHub username, and a PAT with write:packages + read:packages.
• You don't pre-create repositories — the four images appear on first push. GHCR packages default to private; on Docker Hub check the visibility yourself, since its free tier allows only one private repository and this pipeline pushes four.

Azure DevOps setup

1. Service connection: Project Settings → Service connections → New → Docker Registry, choosing your registry type — Docker Hub, Azure Container Registry, or Others (for GHCR and anything else). Name it exactly registry-connection — the pipeline references that literal name, because Azure DevOps resolves service connections at compile time and a $(variable) there fails validation. The name is just a label: re-point this one connection to switch registries.
2. Environment — not a Deployment Group: Pipelines → Environments → New → BlazorBlueprint-Production → Add resource → Virtual machines, then run the generated script on your server (a few minutes, mostly downloading the agent). YAML pipelines cannot target a classic deployment group — if you are migrating from a classic Release, leave the old deployment group in place; this installs its own agent alongside it. Add an approval check here for a manual gate.
3. Variable group: Pipelines → Library → BlazorBlueprint-Production with REGISTRY_BASE (the image prefix, e.g. docker.io/<user> or myacr.azurecr.io), plus the secrets above (lock the secret ones).
4. Authorize the connection: on the first run Azure DevOps asks you to permit the pipeline to use registry-connection — approve it, or pre-grant access from the connection's Security tab.
5. Pipeline: New pipeline → Existing Azure Pipelines YAML → .azure/devops/build-pipeline.yml. Push to main to build + deploy.

GitHub Actions setup

1. No registry setup needed — images push to ghcr.io/<your-org> using the built-in GITHUB_TOKEN. To use Docker Hub or ACR instead, set the REGISTRY_SERVER, REGISTRY_USERNAME and REGISTRY_BASE variables plus a REGISTRY_PASSWORD secret.
2. Self-hosted runner: Settings → Actions → Runners → New self-hosted runner, installed on your server (with Docker + Git Bash). Open port 8080 (Web) — and only that: the API, worker, database and Redis publish no host port at all.
3. Environment: Settings → Environments → production (add a required reviewer for a manual gate).
4. Secrets & variables: Settings → Secrets and variables → Actions — add the secret keys above; put the non-secret config (client IDs, email/OpenAI toggles) under Variables.
5. Deploy: push to main, or use "Run workflow" with an image_tag to roll back to a prior build.

What gets deployed

• Web Application: Blazor Server app on port 8080
• API Service: the internal API, on port 8081 inside the compose network only — it publishes no host port in either compose file, so it is unreachable from outside the deployment. A public or partner API belongs in the Web application, which is the only service that publishes one
• Background Worker: .NET Worker for async tasks and queue processing
• DbMigrator: one-shot schema/index runner, gated ahead of the app
• Database: MongoDB, PostgreSQL or SQL Server with persistent storage — internal to the compose network, never published to the host
• Redis: cache, SignalR backplane, Data Protection key ring, and the job streams that carry background work. Persistent storage, internal-only — it holds the key ring, so it is never exposed to the host
• Networking: isolated Docker network; data preserved in pinned named volumes across deploys

Infrastructure Requirements

• Server: 4+ CPU cores, 8GB+ RAM, 20GB+ storage
• Docker: Docker Engine 20.10+ or Docker Desktop, with Docker Compose v2.24+ (required for the env_file handling the deploy relies on)
• Network: port 8080 (Web) plus 80/443 on your reverse proxy — that is the whole list. 8080 is the only published port in any compose file: the API, the worker, the database and Redis are reachable on the compose network only. Do not open 8081 on the firewall; nothing listens on it from the host, and Redis in particular holds the Data Protection key ring. Lite is the same, with fewer services behind it
• SSL Certificate: For HTTPS (Let's Encrypt recommended)

Security Configuration

• Environment Variables: Store secrets in environment, not appsettings.json
• Database Security: Enable authentication and encryption-at-rest on whichever backend you run
• Redis Security: Configure Redis AUTH and disable dangerous commands. The instance carrying the job streams must run maxmemory-policy noeviction — any allkeys-* policy evicts queued jobs under memory pressure and loses the work silently. Not applicable to Lite, which runs no Redis
• HTTPS Only: Force HTTPS redirects and secure cookies
• CORS: Configure appropriate CORS policies

First run in a container

A fresh deployment redirects to /initial-setup, and that page is gated: on a container the request never looks like loopback, because the port is published and the app sees the Docker bridge gateway. The compose files therefore name that network on the web service, which keeps first run a single click:

- "Security__Setup__TrustedNetworks__0=172.16.0.0/12"

Understand what you are keeping: the app cannot tell the operator from anyone else — both arrive from the gateway — so this trusts every caller that can reach the published port for as long as no organisation exists. That is the right trade when the port is firewalled or private, and the wrong one for a fresh instance sitting on a public address unattended. Delete the line and setup falls back to a token the app logs at Warning the first time an attempt is refused:

docker compose -f .azure/devops/docker-compose.yml logs blazorblueprint-web | grep setupToken

Open the /initial-setup?setupToken=… URL from that line. Set Security:Setup:Token to pin a value instead — necessary if you run more than one web replica, since a generated token lives in one process. Full detail on the security page.

Reverse proxy & forwarded headers

Behind a reverse proxy the app only sees the proxy's address unless you tell it which proxies to trust. It honours X-Forwarded-For, -Proto and -Host, and trust is additive: loopback (127.0.0.0/8, ::1) is trusted out of the box — enough for a proxy sidecar on localhost — and you widen it yourself:

"Security": {
  "ForwardedHeaders": {
    "KnownProxies": [ "172.18.0.5" ],
    "KnownNetworks": [ "172.18.0.0/16" ]
  }
}

A proxy on a separate host or container — a cloudflared container on a Docker bridge, for instance — must be listed here. Miss it and the client IP is never rewritten, so every visitor shares one rate-limit bucket under the proxy's address. The headers cannot be spoofed from an untrusted address: the rewrite only happens when the immediate connecting peer is on the trust list.

Monitoring & Maintenance

• Health Checks: Monitor /health endpoint
• Infrastructure Monitor: Use the built-in dashboard at /Platform/Infrastructure (platform administrators only). Full stack only — it keeps its cross-replica status cache and leader lock in Redis, so under Lite the page reports that it is not available in this deployment mode and probes nothing. Lite's equivalent is the /health endpoint plus the container logs
• Logging: Configure structured logging and log aggregation
• Backups: Automated database backups and disaster recovery
• Updates: Regular security updates and dependency updates

Performance Optimization

• Caching: Redis distributed caching is enabled by default. Lite turns it off (Caching:UseRedisDistributedCache=false) and uses an in-memory tier instead, which is correct on a single instance and wrong on more than one
• CDN: Use CDN for static assets and images
• Database: Indexes are provisioned for you — the DbMigrator reconciles them on every deploy
• Scaling: Compose-based single-node by default; Kubernetes-ready if you supply your own manifests (none ship in the box)
• Background Processing: Queue-based background processing enables horizontal scaling of worker services
• Compression: Enable gzip compression in reverse proxy

Scaling out to multiple instances

The shipped compose files are single-node: one server runs Web, the API and the worker alongside its database and Redis, with data in local named volumes. That scales vertically a long way, and it is the right default. When you outgrow one box, the single architectural change is to separate the app from its data — several stateless app instances behind a load balancer, all pointing at one shared data tier.

These are the rules that bite if you get them wrong:

• Redis must be shared. It holds the Data Protection key ring, so every instance has to be able to decrypt the others' auth cookies and encrypted fields, and it carries the SignalR backplane. A per-instance Redis breaks logins across instances.
• Sticky sessions for the Web host. Blazor Server keeps each user's circuit in memory on one instance, so the load balancer must pin a user to theirs. The API is stateless and needs no affinity.
• Run one background worker. Its recurring sweeps are timer-driven, so two workers double-fire them — duplicate emails and reminders. Queue consumers are already distributed by consumer group and the stream janitor takes its own leader lock; the timer sweeps are the catch. Add leader election before running more than one.
• Identical Messaging:MessageSigningKey and Caching:RedisKeyPrefix on every instance. A mismatch produces no error at all — just jobs that are never processed.
• Migrate once per deploy, as a single pre-rollout step against the shared database, not once per app instance.
• The database needs redundancy too — a MongoDB replica set, or one Postgres / SQL Server primary with read replicas as you grow. A standalone node is a single point of failure once the app tier is redundant.

On a self-hosted hypervisor such as Proxmox this maps straight onto VMs: one per app instance, one for the load balancer, and the data tier on its own private network with no published ports. Your VM snapshots then become the key-ring and database safety net.