Agent 31deaf3aa5 Add Dockerfile, docker-compose.yml, .dockerignore

Multi-stage Dockerfile:
- Stage 1: install deps, build TS, build web UI
- Stage 2: minimal production image with sqlite, only prod deps
- Exposes port 4738, uses /data volume for SQLite

docker-compose.yml for easy local deployment with .env support.
.dockerignore to keep the build context lean.
README updated with Docker usage.
.env.template adds DATA_DIR.

2026-08-18 12:40:42 -04:00

2.9 KiB

Raw Blame History

Mailship

A Nostr email notification server. Receives events pushed from relays via NIP-9a, stores them, and sends daily or weekly digest emails.

Architecture

Flotilla ──HTTP──▶ Mailship (POST /subscription/email)
  │                   NIP-98 auth
  │                   returns {key, callback}
  │
  └──kind 30390──▶ relay or NPB
                         │
                    event matches filter
                         │
                         ▼
                    POST /notify/:subId ──▶ Mailship
                         {id, relay}         │
                           UUID in path      ├── fetch event from relay
                           is the auth       ├── store in SQLite (dedup)
                                             │
                                        cron fires ──▶ render digest ──▶ Postmark ──▶ email

Configuration

Variable	Required	Description
`MAILSHIP_SECRET`	✓	A nostr private key hex string for the server's identity
`MAILSHIP_NAME`	✓	Name of this Mailship instance
`MAILSHIP_URL`	✓	Public URL of this instance
`BASE_URL`	✓	Base URL for callback URLs (same as MAILSHIP_URL typically)
`POSTMARK_API_KEY`	✓	Postmark API key for sending emails
`POSTMARK_SENDER_ADDRESS`	✓	Verified sender email in Postmark
`DEFAULT_RELAYS`	✓	Comma-separated list of default relays
`INDEXER_RELAYS`	✓	Comma-separated list of indexer relays
`SEARCH_RELAYS`	✓	Comma-separated list of search relays
`PORT`		Port to run on (default: 3000)

API

POST /subscription/email

Body: { email, frequency, pubkey }
Auth: NIP-98 (planned)
Response: { key, callback }

DELETE /subscription/:key

Unsubscribe.

Auth: NIP-98 (planned)
Response: { ok: true }

POST /notify/:id

NIP-9a relay push callback. Called by relays or NPB when matching events are found.

Body: { id, relay }
Response: { ok: true, stored: boolean }
Returns 404 if subscription not found or inactive.

GET /confirm?token=...

Confirm email address via link from confirmation email.

GET /unsubscribe?token=...

Unsubscribe via link from digest email.

Development

pnpm install
pnpm run build
pnpm run start

Docker

Quick start

cp .env.template .env
# Fill in your secrets in .env
docker compose up -d

Build and run manually

docker build -t mailship .
docker run -d \
  -p 4738:4738 \
  -v mailship-data:/data \
  --env-file .env \
  mailship

Tests

pnpm test          # Run integration tests
pnpm test:server   # Start server for manual testing

Forked from Anchor

Mailship is a fork of Anchor, stripped of push notification support and adapted for NIP-9a relay push event intake.

2.9 KiB Raw Blame History