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.
Go email-relayemail-routinghttp-to-smtpmail-deliverymailchimp-alternativemailgun-alternativemailsendermailservermailtemplatemailtestpostmark-alternativesend-emailsendgrid-alternativesendmailtransactional-emailtransactional-outbox
docs: rename examples/ to deploy/ and document deploying on Miabi
Jonas Kanindaa4959a1ab04b
diff --git a/README.md b/README.mdindex 1ef0276..88a06ab 100644--- a/README.md+++ b/README.md@@ -275,7 +275,7 @@ flowchart LRRunning the API without a dedicated worker works for evaluation, but productiondeployments should split them so sending, retries, campaigns, and scheduled jobs scaleindependently of request traffic — see-[`examples/compose/docker-compose-full.yml`](examples/compose/docker-compose-full.yml).+[`deploy/compose/docker-compose-full.yml`](deploy/compose/docker-compose-full.yml).Object storage is optional (dashed above). With `POSTA_BLOB_PROVIDER` unset, attachmentsand raw inbound messages stay in the database; point it at `s3` or `fs` to move them out.diff --git a/compose.yml b/compose.ymlindex cfd7a8f..961550f 100644--- a/compose.yml+++ b/compose.yml@@ -9,7 +9,7 @@ services:POSTA_DB_URL: "host=posta-db user=posta password=posta dbname=posta port=5432 sslmode=disable"POSTA_REDIS_ADDR: "posta-redis:6379"# Local quick start only. Production rejects the placeholder credentials- # below, so this file declares itself dev; see examples/ for a deployable+ # below, so this file declares itself dev; see deploy/ for a deployable# template that requires real secrets.POSTA_ENV: "dev"POSTA_JWT_SECRET: "change-me-in-production"diff --git a/deploy/README.md b/deploy/README.mdnew file mode 100644index 0000000..9a51286--- /dev/null+++ b/deploy/README.md@@ -0,0 +1,43 @@+# Deploy++| 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.++To set the same deployment up by hand in the Miabi console instead, follow+[Deploy on Miabi](https://docs.goposta.dev/docs/getting-started/miabi) in the docs.++## 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/compose/.env.example b/deploy/compose/.env.examplesimilarity index 100%rename from examples/compose/.env.examplerename to deploy/compose/.env.examplediff --git a/examples/compose/compose.yml b/deploy/compose/compose.ymlsimilarity index 100%rename from examples/compose/compose.ymlrename to deploy/compose/compose.ymldiff --git a/examples/compose/docker-compose-full.yml b/deploy/compose/docker-compose-full.ymlsimilarity index 100%rename from examples/compose/docker-compose-full.ymlrename to deploy/compose/docker-compose-full.ymldiff --git a/examples/miabi/posta-replicated.yaml b/deploy/miabi/posta-replicated.yamlsimilarity index 90%rename from examples/miabi/posta-replicated.yamlrename to deploy/miabi/posta-replicated.yamlindex 1231ed6..e5498f5 100644--- a/examples/miabi/posta-replicated.yaml+++ b/deploy/miabi/posta-replicated.yaml@@ -134,9 +134,14 @@ spec:POSTA_ENV: productionPOSTA_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"+ # The database's own settings, so nothing has to be appended to a URL.+ # No TLS on the workspace's private network.+ POSTA_DB_HOST: "{{ .databases.posta-db.host }}"+ POSTA_DB_PORT: "{{ .databases.posta-db.port }}"+ POSTA_DB_NAME: "{{ .databases.posta-db.name }}"+ POSTA_DB_USER: "{{ .databases.posta-db.user }}"+ POSTA_DB_PASSWORD: "{{ .databases.posta-db.password }}"+ POSTA_DB_SSL_MODE: disable# redis://:password@host:portPOSTA_REDIS_URL: "{{ .databases.posta-redis.uri }}"@@ -169,7 +174,7 @@ spec:# POSTA_SYSTEM_SMTP_FROM: [email protected]# POSTA_SYSTEM_SMTP_ENCRYPTION: starttlssecretEnv:- - POSTA_DB_URL+ - POSTA_DB_PASSWORD- POSTA_REDIS_URL- POSTA_JWT_SECRET- POSTA_ENCRYPTION_KEY@@ -217,9 +222,14 @@ spec:POSTA_ENV: productionPOSTA_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"+ # The database's own settings, so nothing has to be appended to a URL.+ # No TLS on the workspace's private network.+ POSTA_DB_HOST: "{{ .databases.posta-db.host }}"+ POSTA_DB_PORT: "{{ .databases.posta-db.port }}"+ POSTA_DB_NAME: "{{ .databases.posta-db.name }}"+ POSTA_DB_USER: "{{ .databases.posta-db.user }}"+ POSTA_DB_PASSWORD: "{{ .databases.posta-db.password }}"+ POSTA_DB_SSL_MODE: disable# redis://:password@host:portPOSTA_REDIS_URL: "{{ .databases.posta-redis.uri }}"@@ -242,7 +252,7 @@ spec:POSTA_WORKER_HEALTH_PORT: "9000"POSTA_METRICS_ENABLED: "true"secretEnv:- - POSTA_DB_URL+ - POSTA_DB_PASSWORD- POSTA_REDIS_URL- POSTA_JWT_SECRET- POSTA_ENCRYPTION_KEYdiff --git a/examples/miabi/posta.yaml b/deploy/miabi/posta.yamlsimilarity index 92%rename from examples/miabi/posta.yamlrename to deploy/miabi/posta.yamlindex 1c03c1d..e42b577 100644--- a/examples/miabi/posta.yaml+++ b/deploy/miabi/posta.yaml@@ -98,9 +98,14 @@ spec:POSTA_ENV: productionPOSTA_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"+ # The database's own settings, so nothing has to be appended to a URL.+ # No TLS on the workspace's private network.+ POSTA_DB_HOST: "{{ .databases.posta-db.host }}"+ POSTA_DB_PORT: "{{ .databases.posta-db.port }}"+ POSTA_DB_NAME: "{{ .databases.posta-db.name }}"+ POSTA_DB_USER: "{{ .databases.posta-db.user }}"+ POSTA_DB_PASSWORD: "{{ .databases.posta-db.password }}"+ POSTA_DB_SSL_MODE: disable# redis://:password@host:portPOSTA_REDIS_URL: "{{ .databases.posta-redis.uri }}"@@ -133,7 +138,7 @@ spec:# POSTA_SYSTEM_SMTP_FROM: [email protected]# POSTA_SYSTEM_SMTP_ENCRYPTION: starttlssecretEnv:- - POSTA_DB_URL+ - POSTA_DB_PASSWORD- POSTA_REDIS_URL- POSTA_JWT_SECRET- POSTA_ENCRYPTION_KEYdiff --git a/docs/docs/getting-started/architecture.md b/docs/docs/getting-started/architecture.mdindex 5c892f4..36ebb32 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 deploymentsshould split them, so sending, retries, campaigns, and scheduled jobs scaleindependently of request traffic and a burst of API calls cannot starve delivery.-See [`examples/compose/docker-compose-full.yml`](https://github.com/goposta/posta/blob/main/examples/compose/docker-compose-full.yml)+See [`deploy/compose/docker-compose-full.yml`](https://github.com/goposta/posta/blob/main/deploy/compose/docker-compose-full.yml)for a two-process deployment.:::warningdiff --git a/docs/docs/getting-started/configuration.md b/docs/docs/getting-started/configuration.mdindex 1881496..848c94c 100644--- a/docs/docs/getting-started/configuration.md+++ b/docs/docs/getting-started/configuration.md@@ -1,5 +1,5 @@----sidebar_position: 3+sidebar_position: 2title: Configurationdescription: Environment variables and configuration options---diff --git a/docs/docs/getting-started/installation.md b/docs/docs/getting-started/installation.mdindex fd309d7..6187d50 100644--- a/docs/docs/getting-started/installation.md+++ b/docs/docs/getting-started/installation.md@@ -13,14 +13,14 @@ Deploy the same self-hosted Posta from the [Miabi Marketplace](https://marketpla::::::tip-Full Docker Compose examples are available in the [`examples/`](https://github.com/goposta/posta/tree/main/examples) folder of the repository.+Ready-to-use Docker Compose files and Miabi manifests are in the [`deploy/`](https://github.com/goposta/posta/tree/main/deploy) folder of the repository. To run Posta on Miabi from a manifest or by hand in its console, see [Deploy on Miabi](./miabi).:::## Docker Compose — Embedded Worker (Simple)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/compose.yml`](https://github.com/goposta/posta/blob/main/examples/compose/compose.yml)+See [`deploy/compose/compose.yml`](https://github.com/goposta/posta/blob/main/deploy/compose/compose.yml)```yamlservices:@@ -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/compose/docker-compose-full.yml`](https://github.com/goposta/posta/blob/main/examples/compose/docker-compose-full.yml)+See [`deploy/compose/docker-compose-full.yml`](https://github.com/goposta/posta/blob/main/deploy/compose/docker-compose-full.yml)```yamlservices:diff --git a/docs/docs/getting-started/managed-posta.md b/docs/docs/getting-started/managed-posta.mdindex 584c250..1805de1 100644--- a/docs/docs/getting-started/managed-posta.md+++ b/docs/docs/getting-started/managed-posta.md@@ -1,5 +1,5 @@----sidebar_position: 2+sidebar_position: 3title: Managed Postadescription: Deploy your own Posta from the Miabi Marketplace, without writing Docker Compose---@@ -34,4 +34,6 @@ Same REST API, same dashboard, same [SDKs](/docs/sdks/overview), same [configura## Prefer to wire it up yourself?-Deploy it anywhere Docker or a Go binary runs — see [Installation](./installation) for the Docker Compose examples and build-from-source instructions.+To stay on Miabi but choose every piece yourself, deploy from a manifest or set it up by hand in the console: see [Deploy on Miabi](./miabi).++Or deploy it anywhere Docker or a Go binary runs — see [Installation](./installation) for the Docker Compose examples and build-from-source instructions.diff --git a/docs/docs/getting-started/miabi.md b/docs/docs/getting-started/miabi.mdnew file mode 100644index 0000000..a1e2bd9--- /dev/null+++ b/docs/docs/getting-started/miabi.md@@ -0,0 +1,153 @@+---+sidebar_position: 2.5+title: Deploy on Miabi+description: Run Posta on Miabi from a manifest, or set it up by hand in the Miabi console+---++# Deploy on Miabi++[Miabi](https://miabi.io) runs Posta with a managed PostgreSQL, a dedicated Redis, generated secrets and an HTTPS route with automatic TLS. There are three ways to get there:++| Way | Effort | Choose it when |+|---|---|---|+| [Marketplace template](./managed-posta) | One click | You want Posta running with the least setup |+| [Manifest](#with-a-manifest) | One command | You want the deployment in a file you can review, commit and re-apply |+| [Console, by hand](#by-hand-in-the-console) | About fifteen minutes | You want to see and choose every piece |++All three give you the same self-hosted Posta; everything else in these docs applies unchanged.++## With a manifest++The [`deploy/miabi/`](https://github.com/goposta/posta/tree/main/deploy/miabi) folder holds two `miabi.io/v1` manifests. Each declares the whole deployment as one project, so applying it again converges to the file instead of duplicating anything.++| Manifest | Topology | Use it for |+|---|---|---|+| [`posta.yaml`](https://github.com/goposta/posta/blob/main/deploy/miabi/posta.yaml) | One application with the worker embedded, attachments on a volume | Small and medium installs |+| [`posta-replicated.yaml`](https://github.com/goposta/posta/blob/main/deploy/miabi/posta-replicated.yaml) | Server and dedicated workers as replicated services, attachments on S3 | Production on a Miabi cluster |++1. Replace `posta.example.com` with your hostname (it appears three times) and `[email protected]` with your address.+2. For `posta-replicated.yaml` only, set the S3 bucket settings and seal the secret key:++ ```bash+ echo -n "$S3_SECRET" | miabi secrets seal posta-s3-secret-key+ ```++ Paste the output over the `SealedSecret` value. It is sealed to your workspace's key, so the file is safe to commit.+3. Preview, then apply:++ ```bash+ miabi apply -f posta.yaml --dry-run+ miabi apply -f posta.yaml+ ```++4. Point your hostname's DNS at Miabi. Once the route has its certificate, open `https://posta.example.com`.+5. Reveal the generated `posta-admin-password` in the workspace's **Secrets** and sign in.++The manifests generate the JWT secret, the encryption key and the first admin password into the workspace vault, so no secret is ever written in the file.++:::caution Keep the server at one replica+The worker scales freely, but the API server does not yet: each server replica runs the scheduled jobs and the failed-email retry loop on its own. `posta-replicated.yaml` ships with one server replica; scale `posta-worker` when delivery falls behind.+:::++## By hand in the console++These steps build the same deployment as `posta.yaml`: one application with the worker embedded. Everything happens in your workspace in the Miabi console.++### 1. Create the secrets++Open **Secrets** in the workspace sidebar and create three secrets. Use the **Generator** button on the vault's toolbar, which names and saves the value in one step:++| Name | Generator | Used for |+|---|---|---|+| `posta-jwt-secret` | Token, 32 bytes, hex | Signing sessions. Anyone who has it can forge a login |+| `posta-encryption-key` | Token, 32 bytes, hex | Encrypting stored SMTP passwords |+| `posta-admin-password` | Password, 24 characters | The first admin account |++:::caution+Never rotate `posta-encryption-key` once Posta has stored SMTP servers: their passwords would no longer decrypt.+:::++### 2. Create the database and Redis++From **Data → Databases → New database**, create:++- `posta-db`, engine **PostgreSQL**, version `17-alpine`;+- `posta-redis`, engine **Redis**, version `8-alpine`.++Miabi generates their credentials and keeps them in the vault.++### 3. Create a volume for attachments++From **Data → Volumes → Create volume**, create `posta-data` with a size limit of about 5 GB. Posta stores email attachments and inbound message bodies there.++### 4. Create the application++Click **New application**, choose **Docker image**, and set:++- **Image**: `jkaninda/posta`+- **Tag**: a release tag such as the latest on [Docker Hub](https://hub.docker.com/r/jkaninda/posta), rather than `latest`, so a redeploy never upgrades Posta by surprise+- **Container port**: `9000`++Then, in the application's **Settings**:++- **Run as user**: `100:101`, the image's `posta` user. Miabi then makes the volume writable by it; without this, attachments cannot be saved.+- **Healthcheck**: HTTP, path `/healthz`, port `9000`.++### 5. Link the database and Redis++In the application's **Databases** tab, link `posta-db`. Open **Environment variables** in the link dialog and map the fields to Posta's settings, unticking the rest:++| Field | Variable |+|---|---|+| `host` | `POSTA_DB_HOST` |+| `port` | `POSTA_DB_PORT` |+| `name` | `POSTA_DB_NAME` |+| `user` | `POSTA_DB_USER` |+| `password` | `POSTA_DB_PASSWORD` |+| `url`, `database_url` | unticked |++Then link `posta-redis` and map its `url` field to `POSTA_REDIS_URL`, unticking the others.++Posta connects to PostgreSQL without TLS by default (`POSTA_DB_SSL_MODE=disable`), which is right on the workspace's private network.++### 6. Set the environment++In the **Environment** tab, add:++| Variable | Value |+|---|---|+| `POSTA_ENV` | `production` |+| `POSTA_WEB_URL` | `https://posta.example.com` (your hostname) |+| `POSTA_JWT_SECRET` | `${{ secrets.posta-jwt-secret }}` |+| `POSTA_ENCRYPTION_KEY` | `${{ secrets.posta-encryption-key }}` |+| `POSTA_ADMIN_EMAIL` | your email address |+| `POSTA_ADMIN_PASSWORD` | `${{ secrets.posta-admin-password }}` |+| `POSTA_EMBEDDED_WORKER` | `true` |+| `POSTA_TRUSTED_PROXIES` | `10.63.0.0/16` |+| `POSTA_BLOB_PROVIDER` | `filesystem` |+| `POSTA_BLOB_FS_PATH` | `/data/attachments` |++`POSTA_TRUSTED_PROXIES` lets Posta see visitors' real addresses behind the Miabi gateway, for rate limits and audit logs. `10.63.0.0/16` is the gateway network's default subnet; use your `MIABI_SUBNET` if your Miabi install sets one.++To send invitations and password resets, also set the `POSTA_SYSTEM_SMTP_*` variables (see [Configuration](./configuration)), keeping the password in a secret.++### 7. Attach the volume++In the **Volumes** tab, attach `posta-data` at mount path `/data`.++### 8. Deploy and add the route++Click **Deploy**. When the application is healthy:++1. Add your domain under **Networking → Domains** and complete its DNS verification.+2. In the application's **Routes** tab, create a route for your hostname on port `9000`. Miabi issues the TLS certificate automatically.++### 9. Sign in++Reveal `posta-admin-password` in **Secrets**, open your hostname, and sign in with `POSTA_ADMIN_EMAIL` and that password. The admin account is created only on the first start against an empty database.++### Going further++- **Dedicated workers and replicas.** Moving sending to separate worker services also means moving attachments to S3, since a volume belongs to one node. [`posta-replicated.yaml`](https://github.com/goposta/posta/blob/main/deploy/miabi/posta-replicated.yaml) has that setup ready to apply.+- **Receiving email.** Set `POSTA_INBOUND_ENABLED=true` and `POSTA_INBOUND_HOSTNAME` to the host your MX record names, and publish container port `2525` on the node's port `25`. See [Inbound email](/docs/inbound/overview).+- **Upgrading.** Change the image tag in the application's source settings and redeploy. Posta migrates its database on start.diff --git a/examples/README.md b/examples/README.mdindex 109efff..0a0379e 100644--- a/examples/README.md+++ b/examples/README.md@@ -1,40 +1,5 @@-# Deployment examples+# Moved to deploy/-| 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 |+The Docker Compose files and Miabi manifests are now in [`deploy/`](../deploy/).-## 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.+This note keeps old links working for one release and will then be removed.