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: rename examples/ to deploy/ and document deploying on Miabi

Jonas Kanindaa4959a1ab04b
diff --git a/README.md b/README.md
index 1ef0276..88a06ab 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/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, attachments
and raw inbound messages stay in the database; point it at `s3` or `fs` to move them out.
diff --git a/compose.yml b/compose.yml
index 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.md
new file mode 100644
index 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.example
similarity index 100%
rename from examples/compose/.env.example
rename to deploy/compose/.env.example
diff --git a/examples/compose/compose.yml b/deploy/compose/compose.yml
similarity index 100%
rename from examples/compose/compose.yml
rename to deploy/compose/compose.yml
diff --git a/examples/compose/docker-compose-full.yml b/deploy/compose/docker-compose-full.yml
similarity index 100%
rename from examples/compose/docker-compose-full.yml
rename to deploy/compose/docker-compose-full.yml
diff --git a/examples/miabi/posta-replicated.yaml b/deploy/miabi/posta-replicated.yaml
similarity index 90%
rename from examples/miabi/posta-replicated.yaml
rename to deploy/miabi/posta-replicated.yaml
index 1231ed6..e5498f5 100644
--- a/examples/miabi/posta-replicated.yaml
+++ b/deploy/miabi/posta-replicated.yaml
@@ -134,9 +134,14 @@ spec:
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"
+ # 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:port
POSTA_REDIS_URL: "{{ .databases.posta-redis.uri }}"
@@ -169,7 +174,7 @@ spec:
# POSTA_SYSTEM_SMTP_FROM: [email protected]
# POSTA_SYSTEM_SMTP_ENCRYPTION: starttls
secretEnv:
- - POSTA_DB_URL
+ - POSTA_DB_PASSWORD
- POSTA_REDIS_URL
- POSTA_JWT_SECRET
- POSTA_ENCRYPTION_KEY
@@ -217,9 +222,14 @@ spec:
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"
+ # 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:port
POSTA_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_KEY
diff --git a/examples/miabi/posta.yaml b/deploy/miabi/posta.yaml
similarity index 92%
rename from examples/miabi/posta.yaml
rename to deploy/miabi/posta.yaml
index 1c03c1d..e42b577 100644
--- a/examples/miabi/posta.yaml
+++ b/deploy/miabi/posta.yaml
@@ -98,9 +98,14 @@ spec:
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"
+ # 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:port
POSTA_REDIS_URL: "{{ .databases.posta-redis.uri }}"
@@ -133,7 +138,7 @@ spec:
# POSTA_SYSTEM_SMTP_FROM: [email protected]
# POSTA_SYSTEM_SMTP_ENCRYPTION: starttls
secretEnv:
- - POSTA_DB_URL
+ - POSTA_DB_PASSWORD
- POSTA_REDIS_URL
- POSTA_JWT_SECRET
- POSTA_ENCRYPTION_KEY
diff --git a/docs/docs/getting-started/architecture.md b/docs/docs/getting-started/architecture.md
index 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 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/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.
:::warning
diff --git a/docs/docs/getting-started/configuration.md b/docs/docs/getting-started/configuration.md
index 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: 2
title: Configuration
description: Environment variables and configuration options
---
diff --git a/docs/docs/getting-started/installation.md b/docs/docs/getting-started/installation.md
index 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)
```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/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)
```yaml
services:
diff --git a/docs/docs/getting-started/managed-posta.md b/docs/docs/getting-started/managed-posta.md
index 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: 3
title: Managed Posta
description: 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.md
new file mode 100644
index 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.md
index 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.