Skip to content

armgit / posta

Public Imported from GitHub
0

Self-hosted email delivery platform that enables applications to send emails via HTTP APIs while handling SMTP delivery, templates, storage, security, and analytics. Fully self-hostable alternative to services like SendGrid or Mailgun.

docs(examples): add Miabi deployments, move compose files to compose/

Jonas Kaninda92edf1dbdd8d
diff --git a/README.md b/README.md
index 8bdcbdf..39bfa8e 100644
--- a/README.md
+++ b/README.md
@@ -275,7 +275,7 @@ flowchart LR
Running the API without a dedicated worker works for evaluation, but production
deployments should split them so sending, retries, campaigns, and scheduled jobs scale
independently of request traffic — see
-[`examples/docker-compose-full.yml`](examples/docker-compose-full.yml).
+[`examples/compose/docker-compose-full.yml`](examples/compose/docker-compose-full.yml).
Object storage is optional (dashed above). With `POSTA_BLOB_PROVIDER` unset, attachments
and raw inbound messages stay in the database; point it at `s3` or `fs` to move them out.
diff --git a/docs/docs/getting-started/architecture.md b/docs/docs/getting-started/architecture.md
index ee28564..5c892f4 100644
--- a/docs/docs/getting-started/architecture.md
+++ b/docs/docs/getting-started/architecture.md
@@ -81,7 +81,7 @@ small installs — one container, nothing else to run. Production deployments
should split them, so sending, retries, campaigns, and scheduled jobs scale
independently of request traffic and a burst of API calls cannot starve delivery.
-See [`examples/docker-compose-full.yml`](https://github.com/goposta/posta/blob/main/examples/docker-compose-full.yml)
+See [`examples/compose/docker-compose-full.yml`](https://github.com/goposta/posta/blob/main/examples/compose/docker-compose-full.yml)
for a two-process deployment.
:::warning
diff --git a/docs/docs/getting-started/installation.md b/docs/docs/getting-started/installation.md
index 91a9ac0..fd309d7 100644
--- a/docs/docs/getting-started/installation.md
+++ b/docs/docs/getting-started/installation.md
@@ -20,7 +20,7 @@ Full Docker Compose examples are available in the [`examples/`](https://github.c
This setup runs Posta with the embedded worker enabled. The email processing worker runs inside the main server process, so no separate worker container is required. Ideal for development and small deployments.
-See [`examples/compose.yml`](https://github.com/goposta/posta/blob/main/examples/compose.yml)
+See [`examples/compose/compose.yml`](https://github.com/goposta/posta/blob/main/examples/compose/compose.yml)
```yaml
services:
@@ -94,7 +94,7 @@ Posta will be available at `http://localhost:9000`.
For production environments, run the worker as a separate container. This allows the API server and background processing to scale independently.
-See [`examples/docker-compose-full.yml`](https://github.com/goposta/posta/blob/main/examples/docker-compose-full.yml)
+See [`examples/compose/docker-compose-full.yml`](https://github.com/goposta/posta/blob/main/examples/compose/docker-compose-full.yml)
```yaml
services:
diff --git a/examples/README.md b/examples/README.md
new file mode 100644
index 0000000..109efff
--- /dev/null
+++ b/examples/README.md
@@ -0,0 +1,40 @@
+# Deployment examples
+
+| Example | Topology | Use it for |
+|---|---|---|
+| [`compose/compose.yml`](compose/compose.yml) | One container, embedded worker | Development, small installs |
+| [`compose/docker-compose-full.yml`](compose/docker-compose-full.yml) | Server + dedicated worker | Production on a single Docker host |
+| [`miabi/posta.yaml`](miabi/posta.yaml) | One app, embedded worker, managed Postgres/Redis, TLS route | Small and medium installs on [Miabi](https://miabi.io) |
+| [`miabi/posta-replicated.yaml`](miabi/posta-replicated.yaml) | Replicated server and workers as Swarm services, S3 attachments | Production on a Miabi cluster |
+
+## Docker Compose
+
+```sh
+cd compose
+export POSTA_JWT_SECRET=$(openssl rand -hex 32)
+export POSTA_ADMIN_PASSWORD='a-strong-password'
+docker compose up -d # embedded worker
+docker compose -f docker-compose-full.yml up -d # dedicated worker
+```
+
+[`compose/.env.example`](compose/.env.example) lists every setting. Copy it to `compose/.env` to keep
+values out of your shell history.
+
+## Miabi
+
+```sh
+cd miabi
+miabi apply -f posta.yaml --dry-run # preview the plan
+miabi apply -f posta.yaml # converge the workspace
+```
+
+Both manifests generate the JWT secret, encryption key and initial admin password into the workspace
+vault. Reveal `posta-admin-password` there after the first apply.
+
+## Scaling
+
+The worker is stateless and scales freely: every instance consumes the same Redis queue.
+
+The API server does not scale freely yet. Each server process runs the scheduled jobs and the
+failed-email retry loop without a lock, so extra server replicas repeat them. Keep the server at one
+replica and add workers. `miabi/posta-replicated.yaml` ships that way.
diff --git a/examples/.env.example b/examples/compose/.env.example
similarity index 100%
rename from examples/.env.example
rename to examples/compose/.env.example
diff --git a/examples/compose.yml b/examples/compose/compose.yml
similarity index 100%
rename from examples/compose.yml
rename to examples/compose/compose.yml
diff --git a/examples/docker-compose-full.yml b/examples/compose/docker-compose-full.yml
similarity index 100%
rename from examples/docker-compose-full.yml
rename to examples/compose/docker-compose-full.yml
diff --git a/examples/miabi/posta-replicated.yaml b/examples/miabi/posta-replicated.yaml
new file mode 100644
index 0000000..371fd1a
--- /dev/null
+++ b/examples/miabi/posta-replicated.yaml
@@ -0,0 +1,268 @@
+# Posta on Miabi (replicated server + dedicated workers)
+# ======================================================
+# The production topology for a Miabi location running in cluster mode
+# (a swarm): the API server and the queue worker run as separate replicated
+# services, so request traffic and email delivery scale independently and a
+# node failure reschedules them elsewhere.
+#
+# posta HTTP API + web UI, 3 replicas behind the gateway
+# posta-worker queue consumer (sending, retries, campaigns), 2 replicas
+# posta-db managed PostgreSQL, shared by both
+# posta-redis queue, sessions, caches and realtime events, shared by both
+#
+# What makes replicas safe:
+# • Shared state lives in Postgres and Redis only. Sessions, the queue and
+# realtime events are all in Redis, so any replica can serve any request.
+# • Every replica gets the same JWT secret and encryption key, from the vault.
+# • Attachments go to S3. A volume is node-local and per-replica, so the
+# filesystem blob provider does not work here.
+# • POSTA_EMBEDDED_WORKER is off: delivery belongs to posta-worker.
+#
+# ⚠ Known limitation: every server replica starts its own scheduler (daily
+# reports, bounce alerts, API key expiry, retention, campaign restarts) and
+# its own failed-email retry loop. Neither takes a lock yet, so with N
+# replicas those jobs run N times, and a failed email can be re-enqueued
+# once per replica. Until the server can elect one scheduler, keep the
+# `posta` service at replicas: 1 and scale posta-worker instead, which
+# is safe at any count.
+#
+# Before applying:
+# 1. Replace posta.example.com (three places) with your hostname.
+# 2. Set the S3 bucket settings below and store the secret key:
+# echo -n "$S3_SECRET" | miabi secrets seal posta-s3-secret-key
+# and paste the output over the SealedSecret value below.
+#
+# Apply:
+# miabi apply -f posta-replicated.yaml --dry-run
+# miabi apply -f posta-replicated.yaml
+#
+# After the first apply, reveal `posta-admin-password` in the workspace vault.
+apiVersion: miabi.io/v1
+kind: Project
+metadata:
+ name: posta
+spec:
+ description: Posta with a replicated API server and dedicated queue workers.
+ resources:
+ - apiVersion: miabi.io/v1
+ kind: Secret
+ metadata: { name: posta-jwt-secret }
+ spec:
+ generate: true
+ length: 64
+
+ # Do not rotate: stored SMTP passwords would no longer decrypt.
+ - apiVersion: miabi.io/v1
+ kind: Secret
+ metadata: { name: posta-encryption-key }
+ spec:
+ generate: true
+ length: 48
+
+ - apiVersion: miabi.io/v1
+ kind: Secret
+ metadata: { name: posta-admin-password }
+ spec:
+ generate: true
+ length: 24
+
+ # Sealed to your workspace's key, so this file is safe to commit.
+ - apiVersion: miabi.io/v1
+ kind: SealedSecret
+ metadata: { name: posta-s3-secret-key }
+ spec:
+ value: sealed:v1:REPLACE-WITH-OUTPUT-OF-miabi-secrets-seal
+
+ - apiVersion: miabi.io/v1
+ kind: Database
+ metadata: { name: posta-db }
+ spec:
+ engine: postgres
+ version: "17-alpine"
+ instance: dedicated
+ resources:
+ memory: 2Gi
+ cpu: "1"
+
+ - apiVersion: miabi.io/v1
+ kind: Database
+ metadata: { name: posta-redis }
+ spec:
+ engine: redis
+ version: "8-alpine"
+ instance: dedicated
+ resources:
+ memory: 512Mi
+ cpu: "0.5"
+
+ # Members share a network and resolve each other by name.
+ - apiVersion: miabi.io/v1
+ kind: Stack
+ metadata: { name: posta }
+ spec:
+ description: Posta server and workers.
+
+ # ── API server ──────────────────────────────────────────────────────────
+ - apiVersion: miabi.io/v1
+ kind: Application
+ metadata: { name: posta }
+ spec:
+ image: jkaninda/posta
+ tag: "latest" # pin a release tag (or digest) in production
+ stack: posta
+ deployment:
+ runtime: service
+ # See the known limitation above before raising this.
+ replicas: 1
+ strategy: rolling
+ update:
+ parallelism: 1 # one replica at a time: migrations run on boot
+ delaySeconds: 15
+ placement:
+ constraints:
+ - node.role==worker
+ healthcheck:
+ type: http
+ path: /healthz
+ port: 9000
+ intervalSeconds: 10
+ startPeriodSeconds: 30
+ ports:
+ - container: 9000
+ scheme: http
+ env:
+ POSTA_ENV: production
+ POSTA_WEB_URL: "https://posta.example.com"
+
+ # Miabi renders postgres://user:pass@host:port/db (no TLS on the
+ # workspace network, hence sslmode=disable).
+ POSTA_DB_URL: "{{ .databases.posta-db.uri }}?sslmode=disable"
+
+ # redis://:password@host:port
+ POSTA_REDIS_URL: "{{ .databases.posta-redis.uri }}"
+
+ POSTA_JWT_SECRET: "{{ .secrets.posta-jwt-secret }}"
+ POSTA_ENCRYPTION_KEY: "{{ .secrets.posta-encryption-key }}"
+ POSTA_ADMIN_EMAIL: [email protected]
+ POSTA_ADMIN_PASSWORD: "{{ .secrets.posta-admin-password }}"
+
+ POSTA_TRUSTED_PROXIES: "10.0.0.0/8,172.16.0.0/12"
+ POSTA_EMBEDDED_WORKER: "false"
+ POSTA_METRICS_ENABLED: "true"
+
+ POSTA_BLOB_PROVIDER: s3
+ POSTA_BLOB_S3_ENDPOINT: s3.eu-central-1.amazonaws.com
+ POSTA_BLOB_S3_REGION: eu-central-1
+ POSTA_BLOB_S3_BUCKET: posta-attachments
+ POSTA_BLOB_S3_ACCESS_KEY: AKIAXXXXXXXXXXXXXXXX
+ POSTA_BLOB_S3_SECRET_KEY: "{{ .secrets.posta-s3-secret-key }}"
+ POSTA_BLOB_S3_USE_SSL: "true"
+ POSTA_BLOB_S3_PATH_STYLE: "false" # true for MinIO and most self-hosted S3
+
+ # System SMTP for invitations, password resets and daily reports.
+ # POSTA_SYSTEM_SMTP_HOST: smtp.example.com
+ # POSTA_SYSTEM_SMTP_PORT: "587"
+ # POSTA_SYSTEM_SMTP_USERNAME: [email protected]
+ # POSTA_SYSTEM_SMTP_PASSWORD: "{{ .secrets.posta-system-smtp-password }}"
+ # POSTA_SYSTEM_SMTP_FROM: [email protected]
+ # POSTA_SYSTEM_SMTP_ENCRYPTION: starttls
+ secretEnv:
+ - POSTA_DB_URL
+ - POSTA_REDIS_URL
+ - POSTA_JWT_SECRET
+ - POSTA_ENCRYPTION_KEY
+ - POSTA_ADMIN_PASSWORD
+ - POSTA_BLOB_S3_SECRET_KEY
+ resources:
+ memory: 512Mi
+ cpu: "1"
+
+ # ── Queue workers ───────────────────────────────────────────────────────
+ # Workers pull from the shared Redis queue, so any count is safe. Scale
+ # this, not the server, when delivery falls behind.
+ - apiVersion: miabi.io/v1
+ kind: Application
+ metadata: { name: posta-worker }
+ spec:
+ image: jkaninda/posta
+ tag: "latest" # keep in lockstep with the server's tag
+ command: ["worker"]
+ stack: posta
+ deployment:
+ runtime: service
+ replicas: 2
+ strategy: rolling
+ update:
+ parallelism: 1
+ delaySeconds: 10
+ placement:
+ constraints:
+ - node.role==worker
+ # The worker serves /healthz, /readyz and /metrics on POSTA_PORT.
+ healthcheck:
+ type: http
+ path: /healthz
+ port: 9000
+ intervalSeconds: 15
+ startPeriodSeconds: 20
+ ports:
+ - container: 9000
+ scheme: http
+ # Same database, Redis, secrets and S3 settings as the server: the worker
+ # signs tracking links with the JWT secret, decrypts SMTP passwords with
+ # the encryption key, and reads attachments from the bucket.
+ env:
+ POSTA_ENV: production
+ POSTA_WEB_URL: "https://posta.example.com" # base for tracking and unsubscribe links
+
+ # Miabi renders postgres://user:pass@host:port/db (no TLS on the
+ # workspace network, hence sslmode=disable).
+ POSTA_DB_URL: "{{ .databases.posta-db.uri }}?sslmode=disable"
+
+ # redis://:password@host:port
+ POSTA_REDIS_URL: "{{ .databases.posta-redis.uri }}"
+
+ POSTA_JWT_SECRET: "{{ .secrets.posta-jwt-secret }}"
+ POSTA_ENCRYPTION_KEY: "{{ .secrets.posta-encryption-key }}"
+
+ POSTA_BLOB_PROVIDER: s3
+ POSTA_BLOB_S3_ENDPOINT: s3.eu-central-1.amazonaws.com
+ POSTA_BLOB_S3_REGION: eu-central-1
+ POSTA_BLOB_S3_BUCKET: posta-attachments
+ POSTA_BLOB_S3_ACCESS_KEY: AKIAXXXXXXXXXXXXXXXX
+ POSTA_BLOB_S3_SECRET_KEY: "{{ .secrets.posta-s3-secret-key }}"
+ POSTA_BLOB_S3_USE_SSL: "true"
+ POSTA_BLOB_S3_PATH_STYLE: "false"
+
+ POSTA_WORKER_CONCURRENCY: "20"
+ POSTA_WORKER_MAX_RETRIES: "5"
+ POSTA_WORKER_HEALTH_ENABLED: "true"
+ POSTA_WORKER_HEALTH_PORT: "9000"
+ POSTA_METRICS_ENABLED: "true"
+ secretEnv:
+ - POSTA_DB_URL
+ - POSTA_REDIS_URL
+ - POSTA_JWT_SECRET
+ - POSTA_ENCRYPTION_KEY
+ - POSTA_BLOB_S3_SECRET_KEY
+ resources:
+ memory: 512Mi
+ cpu: "1"
+
+ # ── Public route ────────────────────────────────────────────────────────
+ - apiVersion: miabi.io/v1
+ kind: Domain
+ metadata: { name: posta.example.com }
+ spec:
+ tls: acme
+
+ - apiVersion: miabi.io/v1
+ kind: Route
+ metadata: { name: posta-web }
+ spec:
+ hosts: [posta.example.com]
+ app: posta
+ port: 9000
+ tls: acme
+ security:
+ exploitProtection: true
diff --git a/examples/miabi/posta.yaml b/examples/miabi/posta.yaml
new file mode 100644
index 0000000..76eb231
--- /dev/null
+++ b/examples/miabi/posta.yaml
@@ -0,0 +1,169 @@
+# Posta on Miabi (single instance, embedded worker)
+# ==================================================
+# A complete Posta deployment as one miabi.io/v1 Project: a managed PostgreSQL
+# database, a dedicated Redis, generated secrets, a volume for attachments, the
+# Posta server (HTTP API + web UI with the worker embedded), and a public HTTPS
+# route with automatic TLS.
+#
+# This is the Miabi equivalent of ../compose/compose.yml. It suits small and
+# medium installations; for replicas and a dedicated worker see
+# posta-replicated.yaml.
+#
+# Before applying, replace posta.example.com (three places) with your hostname.
+#
+# Apply:
+# miabi apply -f posta.yaml --dry-run # preview the plan
+# miabi apply -f posta.yaml # converge the workspace
+#
+# After the first apply, reveal the generated admin password in the workspace
+# vault (secret `posta-admin-password`) and sign in as [email protected].
+apiVersion: miabi.io/v1
+kind: Project
+metadata:
+ name: posta
+spec:
+ description: Posta transactional email platform, with Postgres, Redis, server and route.
+ resources:
+ # Secrets are generated once at create time and never change on re-apply.
+ # POSTA_JWT_SECRET signs sessions: anyone who knows it can forge one.
+ - apiVersion: miabi.io/v1
+ kind: Secret
+ metadata: { name: posta-jwt-secret }
+ spec:
+ generate: true
+ length: 64
+
+ # Encrypts SMTP server passwords at rest (hashed to an AES-256 key, so any
+ # length works). Do not rotate it: stored passwords would no longer decrypt.
+ - apiVersion: miabi.io/v1
+ kind: Secret
+ metadata: { name: posta-encryption-key }
+ spec:
+ generate: true
+ length: 48
+
+ # Used only to create the first admin account on an empty database.
+ - apiVersion: miabi.io/v1
+ kind: Secret
+ metadata: { name: posta-admin-password }
+ spec:
+ generate: true
+ length: 24
+
+ - apiVersion: miabi.io/v1
+ kind: Database
+ metadata: { name: posta-db }
+ spec:
+ engine: postgres
+ version: "17-alpine"
+ instance: auto # auto | dedicated | shared
+
+ # Queue (asynq), sessions, caches and realtime events. Redis is always a
+ # dedicated instance; Miabi sets its password.
+ - apiVersion: miabi.io/v1
+ kind: Database
+ metadata: { name: posta-redis }
+ spec:
+ engine: redis
+ version: "8-alpine"
+ instance: dedicated
+
+ # Attachments and inbound mail bodies. A single instance can keep them on a
+ # volume; replicas need S3 instead (see posta-replicated.yaml).
+ - apiVersion: miabi.io/v1
+ kind: Volume
+ metadata: { name: posta-data }
+ spec:
+ size: 5Gi
+
+ - apiVersion: miabi.io/v1
+ kind: Application
+ metadata: { name: posta }
+ spec:
+ image: jkaninda/posta
+ tag: "latest" # pin a release tag in production
+ ports:
+ - container: 9000
+ scheme: http
+ # The image's `posta` user. Stating it makes Miabi chown the volume
+ # to it, so the server can write attachments.
+ security:
+ runAsUser: "100:101"
+ healthcheck:
+ type: http
+ path: /healthz
+ port: 9000
+ startPeriodSeconds: 20
+ env:
+ POSTA_ENV: production
+ POSTA_WEB_URL: "https://posta.example.com" # must match the route host
+
+ # Miabi renders postgres://user:pass@host:port/db (no TLS on the
+ # workspace network, hence sslmode=disable).
+ POSTA_DB_URL: "{{ .databases.posta-db.uri }}?sslmode=disable"
+
+ # redis://:password@host:port
+ POSTA_REDIS_URL: "{{ .databases.posta-redis.uri }}"
+
+ POSTA_JWT_SECRET: "{{ .secrets.posta-jwt-secret }}"
+ POSTA_ENCRYPTION_KEY: "{{ .secrets.posta-encryption-key }}"
+ POSTA_ADMIN_EMAIL: [email protected]
+ POSTA_ADMIN_PASSWORD: "{{ .secrets.posta-admin-password }}"
+
+ # Requests arrive through the Miabi gateway; trust its forwarded
+ # client IP so rate limits and audit logs see the real address.
+ # Narrow this to your workspace network if you know its subnet.
+ POSTA_TRUSTED_PROXIES: "10.0.0.0/8,172.16.0.0/12"
+
+ POSTA_EMBEDDED_WORKER: "true"
+ POSTA_WORKER_CONCURRENCY: "10"
+ POSTA_WORKER_MAX_RETRIES: "5"
+
+ POSTA_BLOB_PROVIDER: filesystem
+ POSTA_BLOB_FS_PATH: /data/attachments
+
+ # System SMTP for invitations, password resets and daily reports.
+ # Uncomment and set, then add POSTA_SYSTEM_SMTP_PASSWORD to secretEnv.
+ # POSTA_SYSTEM_SMTP_HOST: smtp.example.com
+ # POSTA_SYSTEM_SMTP_PORT: "587"
+ # POSTA_SYSTEM_SMTP_USERNAME: [email protected]
+ # POSTA_SYSTEM_SMTP_PASSWORD: "{{ .secrets.posta-system-smtp-password }}"
+ # POSTA_SYSTEM_SMTP_FROM: [email protected]
+ # POSTA_SYSTEM_SMTP_ENCRYPTION: starttls
+ secretEnv:
+ - POSTA_DB_URL
+ - POSTA_REDIS_URL
+ - POSTA_JWT_SECRET
+ - POSTA_ENCRYPTION_KEY
+ - POSTA_ADMIN_PASSWORD
+ mounts:
+ - volume: posta-data
+ path: /data
+ resources:
+ memory: 512Mi
+ cpu: "1"
+
+ # ── Optional: receive inbound email ──────────────────────────────────
+ # Add to env:
+ # POSTA_INBOUND_ENABLED: "true"
+ # POSTA_INBOUND_HOSTNAME: posta.example.com # must match your MX record
+ # and publish the receiver on the node's port 25:
+ # - container: 2525
+ # protocol: tcp
+ # publish: true
+ # hostPort: 25
+
+ - apiVersion: miabi.io/v1
+ kind: Domain
+ metadata: { name: posta.example.com }
+ spec:
+ tls: acme
+
+ - apiVersion: miabi.io/v1
+ kind: Route
+ metadata: { name: posta-web }
+ spec:
+ hosts: [posta.example.com]
+ app: posta
+ port: 9000
+ tls: acme