Deployment Architecture Overview

This page describes the recommended production hosting architecture for SmallBlock CMS. It focuses on the infrastructure and operational components required to run SmallBlock reliably, securely, and at scale.

This page is intended for:

• System administrators

• DevOps and SRE engineers

• Cloud architects

• Anyone preparing a production deployment

It does not cover internal application architecture. For that, see the Conceptual Architecture page.

—

Overview

A production SmallBlock deployment is typically composed of:

• A reverse proxy (Nginx or Traefik) handling TLS termination and static assets

• One or more SmallBlock application server instances (Python WSGI/ASGI)

• A database server (PostgreSQL or MariaDB)

• Optional Redis for caching or session storage

• Optional object storage (S3, MinIO) for uploaded media

• Optional load balancer for multi-node deployments

SmallBlock runs well on bare metal, VPS hosting, Docker, Kubernetes, and managed cloud platforms.

—

High-Level Deployment Diagram

—

Reverse Proxy Layer (Nginx or Traefik)

The reverse proxy handles:

• TLS termination (including Let’s Encrypt automation)

• Delivery of static files (CSS, JS, images)

• Optional delivery of media files

• Compression (gzip or brotli)

• Request buffering and connection reuse

• Optional load balancing across app servers

• Security headers (CSP, HSTS, X-Frame-Options, X-Content-Type-Options)

For most deployments, Nginx is preferred. Traefik excels in containerized setups.

—

Application Server Layer

SmallBlock runs behind the reverse proxy using a Python WSGI or ASGI server.

Recommended servers:

• Gunicorn (WSGI)

• Uvicorn or Hypercorn (ASGI)

Responsibilities:

• Routing

• Middleware

• Template rendering

• Plugin execution

• Authentication

• Admin interface

• Database session management

Recommended configuration:

• 2–4 workers for small sites

• 1 worker per CPU core for larger workloads

• systemd or supervisor to ensure automatic restarts

—

Database Layer

Supported databases:

• PostgreSQL (recommended)

• MariaDB (supported)

The database stores:

• Pages

• Users and permissions

• Translations

• Plugin metadata

• Version history

• Drafts and publishing state

Recommended settings:

• UTF-8 encoding

• Automated nightly backups

• WAL archiving (PostgreSQL) for point-in-time recovery

• Use pgBouncer for high-traffic sites

• Dedicated host or a managed DB service for multi-node deployments

—

Static and Media Files

SmallBlock separates static assets from user-uploaded media.

Static files: - Served by Nginx or a CDN - Rarely change and can be cached aggressively

Media files: - Served from /media/ on disk for small deployments - Served from object storage (S3, MinIO) in multi-node setups

Object storage is recommended for scalability and redundancy.

—

Caching Layer (Optional)

Redis may be used for:

• Fragment or page caching

• Session storage

• Rate limiting

• Caching expensive template tag computations

Caching is recommended for:

• Authenticated sites

• High-traffic deployments

• Multilingual content

• Sites with many plugins

—

Deployment Models

Single-Server Deployment

Appropriate for low-traffic sites, personal projects, and small organizations.

Architecture:

Nginx → SmallBlock (Gunicorn/Uvicorn) → PostgreSQL

Pros: - Simple - Low cost - Fast setup

Cons: - No redundancy - Limited scaling

—

Multi-Server Deployment

Recommended for production and business-critical sites.

Architecture:

Browser → CDN → Load Balancer → Nginx nodes → App servers → Database → Object storage

Pros: - High availability - Horizontal scaling - Rolling deployments possible

Cons: - More expensive - More complex infrastructure

—

Container Deployment (Docker)

Suitable for teams using CI/CD or orchestrated hosting.

Typical stack includes:

• Traefik or Nginx proxy container

• One or more SmallBlock containers

• PostgreSQL container

• Optional Redis container

• S3/MinIO back-end for media

Docker Compose or Podman Compose works well for development and small production deployments.

—

Kubernetes Deployment

Recommended for enterprise environments.

Components include:

• Ingress controller (Nginx/Traefik)

• Deployments with autoscaling

• Managed or containerized PostgreSQL

• ConfigMaps and Secrets for environment settings

• Persistent storage (or S3 for media)

Pros: - Elastic scaling - Zero-downtime updates - Strong operational tooling

Cons: - Significant infrastructure overhead

—

Security Boundaries

A secure SmallBlock deployment should include:

• HTTPS enforced at the reverse proxy

• Application server not exposed to the public internet

• Firewall rules: * Only Nginx may reach the application server * Only the application server may reach the DB

• Hardened Linux environment

• Dedicated system user for the SmallBlock service

• Database roles with least-privilege restrictions

• Strict CSP and security headers

See the Security Hardening section for a full checklist.

—

Backups and Disaster Recovery

Recommended practices:

• Daily full database backups

• Hourly WAL archiving (PostgreSQL)

• Nightly media file backups

• Offsite retention (S3/Glacier)

• Regular restoration tests

• Monitoring of backup success/failure

—

Choosing a Deployment Architecture

—

Next Steps

• Production Deployment Guide

• Security Hardening

• Scaling SmallBlock

• Database Configuration