Docker Compose Reference Architecture
Highly available reference architecture for running Authgear on virtual machines with Docker Compose or Podman Compose.
This page describes a highly available reference architecture for running Authgear on conventional virtual machines with Docker Compose or Podman Compose. It suits deployments where a Kubernetes cluster is unavailable, or not worth operating for a single application. For the Kubernetes-based architecture, see K8S Cluster Reference Architecture.
For development, see Run locally with Docker Compose.
Components
The system has three parts.
Authgear: the application services and their ingress (a reverse proxy), run under Compose on two Authgear VMs.
Monitoring stack: Prometheus and Grafana, run under Compose on a separate monitor VM. Option 1 can omit this VM, at the cost of monitoring.
Datastores: PostgreSQL, Redis, and S3-compatible object storage.
Choosing a Datastore Option
Option 1: Your Own Datastores. You supply PostgreSQL, Redis, and object storage from services you already operate. Choose this when your platform team already runs them. It is the preferred option, because backup, patching, and failover stay with the team that already handles them. Two VMs, plus an optional monitor VM.
Option 2: Included Datastores. The datastores are installed on dedicated datastore VMs as part of the deployment. Choose this when no managed datastores are available, such as air-gapped sites and bare-metal data centres, or when you want a self-contained environment. Five VMs: two for Authgear, two for the datastores, and a monitor VM.
VM counts exclude the load balancer, which you provide.
Option 1: Your Own Datastores
The deployment adds only the VMs that run Authgear and the monitoring stack, and uses datastores you already operate. Authgear runs on two VMs behind a load balancer, so either can be rebooted or upgraded without an outage. The monitoring stack runs on an optional monitor VM. Without that VM, the setup has no monitoring.
Inventory
In addition to the common inventory, you provide the following.
Load balancer
1
For example HAProxy, Apache, or a managed service.
Must be highly available.
Can terminate TLS or pass it through to the ingress.
Authgear VM
2 CPU / 16 GB / 40 GB Data Disk
4 CPU / 16 GB / 100 GB Data Disk
2
For failover, not capacity.
Monitor VM
1 CPU / 8 GB / 40 GB Data Disk
1 CPU / 8 GB / 40 GB Data Disk
1
Optional.
PostgreSQL
2 CPU / 16 GB / 40 GB Data Disk
4 CPU / 16 GB / 100 GB Data Disk
1
Size the disk for user data and audit logs.
Redis
1 CPU / 4 GB / 10 GB Data Disk
1 CPU / 8 GB / 10 GB Data Disk
1
About 30 kB per session.
Object storage
40 GB Storage
80 GB Storage
1
Holds user profile pictures and other assets.
Option 2: Included Datastores
PostgreSQL, Redis, and S3-compatible object storage (RustFS) are installed on two dedicated datastore VMs, a primary and a replica, as part of the deployment. This is the only option that needs no managed datastore from you, at the cost of more VMs. Authgear runs on two further VMs behind the load balancer. Each Authgear VM runs its own HAProxy, which routes database and Redis connections to the current primary. The monitor VM runs the monitoring stack and the failover controllers: pg_auto_failover (PAF) for PostgreSQL and Sentinel for Redis. Object storage replication copies objects to the second datastore VM, which gives a redundant copy rather than automatic failover.
Inventory
In addition to the common inventory, you provide the following. The datastores are installed on the datastore VMs as part of the deployment.
Load balancer
1
For example HAProxy, Apache, or a managed service.
Must be highly available.
Can terminate TLS or pass it through to the ingress.
Authgear VM
2 CPU / 16 GB / 40 GB Data Disk
4 CPU / 16 GB / 100 GB Data Disk
2
For failover, not capacity. Each runs its own HAProxy for database and Redis routing.
Datastore VM
2 CPU / 16 GB / 100 GB Data Disk
4 CPU / 16 GB / 200 GB Data Disk
2
Primary and replica. Size the disk for user data and audit logs.
Monitor VM
1 CPU / 8 GB / 40 GB Data Disk
1 CPU / 8 GB / 40 GB Data Disk
1
Runs the monitoring stack and the PAF and Sentinel failover controllers.
Requirements
Common Inventory
Both options need the following, in addition to the VMs listed in their inventories.
IP address
1
For the load balancer.
Domain
2 + 1 per project
Two system domains for the Authgear Portal and Portal Login, for example portal.example.com and accounts.example.com, plus one Authgear Endpoint domain per project, for example auth.example.com.
Certificate
1
Wildcard certificate covering the domains above. Install it on the ingress, or on the load balancer if that terminates TLS.
Grafana hostname
1
Internal hostname and certificate. Grafana is not exposed to the internet, so it does not use the public domains or the wildcard certificate. Not needed when Option 1 omits the monitor VM.
Firewall
1
In front of the load balancer.
Mailer
1
Optional. SMTP server or SendGrid.
SMS
1
Optional. Gateway account for SMS delivery.
1
Optional. Business account for WhatsApp delivery.
CAPTCHA
1
Optional. Google reCAPTCHA or Cloudflare Turnstile.
Datastore Requirements
The versions below are the ones Authgear is tested against, on both a cloud-managed service and the included datastores. Option 2 installs exactly these versions. With Option 1, match them where you can. Other releases have not been tested.
PostgreSQL
16.14, with the pg_partman extension 16.5.1.
Redis
6.2.20.
Object storage
Any S3-compatible implementation.
Expected Capacity
With 100 concurrent users logging in, the Minimum and Recommended specifications in the inventories above are expected to sustain:
Minimum
5
Recommended
15
The figures hold for both options, provided the datastores you supply under Option 1 match the specifications in the inventories.
Throughput is bound by the database, not by the number of Authgear VMs, so the second Authgear VM adds availability, not capacity. The architecture therefore fixes Authgear at two VMs, enough for failover and rolling upgrades. A third would add nothing.
Datastore High Availability
With Option 1, datastore availability is your responsibility. With Option 2, the PAF, Sentinel, and HAProxy components described under Option 2 provide it. The High Availability section of the K8S Cluster Reference Architecture describes how they fail over. That page places them in Kubernetes. Here they run on the monitor VM and the Authgear VMs.
Object storage uses bucket replication to keep a copy of every object on the second datastore VM. Replication is asynchronous and provides a redundant copy rather than automatic failover.
Network, Monitoring, and Backups
The firewall rules, hostnames, WAF paths, and backup guidance in K8S Cluster Reference Architecture apply to this architecture too. Where that page says Kubernetes, read the Authgear VMs. Administrators reach Grafana over your internal network, not through the public path that serves users.
Metrics are collected by the Prometheus and Grafana instances that ship with the deployment. Access logs come from the ingress on each Authgear VM. Audit logs are persisted in PostgreSQL, so include the database in your backup policy.
Last updated
Was this helpful?