Pare down Deployment instructions
All checks were successful
CI / checks (pull_request) Successful in 1m2s
All checks were successful
CI / checks (pull_request) Successful in 1m2s
This commit is contained in:
parent
0f1e568009
commit
e6b48796ff
1 changed files with 2 additions and 96 deletions
98
README.md
98
README.md
|
|
@ -148,48 +148,10 @@ pnpm run preview:digest
|
|||
open digest-preview.html
|
||||
```
|
||||
|
||||
## Docker
|
||||
|
||||
### Quick start
|
||||
|
||||
```sh
|
||||
cp .env.template .env
|
||||
# Fill in your secrets in .env
|
||||
docker compose up -d
|
||||
```
|
||||
|
||||
### Build and run manually
|
||||
|
||||
```sh
|
||||
docker build -t mailship .
|
||||
docker run -d \
|
||||
-p 4738:4738 \
|
||||
-v mailship-data:/data \
|
||||
--env-file .env \
|
||||
mailship
|
||||
```
|
||||
|
||||
## Tests
|
||||
|
||||
```sh
|
||||
pnpm test:unit # Run unit tests (vitest)
|
||||
pnpm test # Run integration tests (bash E2E)
|
||||
pnpm test:server # Start server for manual testing
|
||||
```
|
||||
|
||||
## Deployment
|
||||
|
||||
### Production Image Build
|
||||
|
||||
Mailship uses a **multi-stage Docker build** to produce a minimal production image.
|
||||
|
||||
| Stage | Base Image | Purpose |
|
||||
|---|---|---|
|
||||
| `build` | `node:22-alpine` | Compile TypeScript, install all dependencies |
|
||||
| `production` | `node:22-alpine` | Runtime — only production deps, compiled JS, static assets |
|
||||
|
||||
The Dockerfile is structured to keep the final image small by discarding build tooling
|
||||
(`python3`, `make`, `g++`, `git`) and development dependencies after compilation.
|
||||
The recommended deployment method for mailship is using Docker. You can build the docker image from the repo root with:
|
||||
|
||||
```sh
|
||||
docker build -t mailship .
|
||||
|
|
@ -204,7 +166,7 @@ Copy the environment template, fill in your secrets, and start:
|
|||
|
||||
```sh
|
||||
cp .env.template .env
|
||||
# Edit .env with your production values (see Required Environment Variables below)
|
||||
# Edit .env with your production values (see Configuration section in README)
|
||||
docker compose up -d
|
||||
```
|
||||
|
||||
|
|
@ -225,59 +187,3 @@ docker compose build --pull
|
|||
docker compose pull
|
||||
docker compose up -d
|
||||
```
|
||||
|
||||
### Required Environment Variables
|
||||
|
||||
The table below marks variables that are especially important in **production**.
|
||||
Defaults are safe for development but may leak information or misroute mail in a
|
||||
production deployment.
|
||||
|
||||
| Variable | Required in production | Notes |
|
||||
|---|---|---|
|
||||
| `MAILSHIP_SECRET` | ✓ | Must be a **private key in hex** — never share or commit this value |
|
||||
| `MAILSHIP_URL` | ✓ | Set to the **public-facing URL** of your instance (e.g. `https://mail.example.com`) |
|
||||
| `BASE_URL` | ✓ | Same as `MAILSHIP_URL` in most setups; used for callback URLs in email |
|
||||
| `SMTP_HOST` | ✓ | Production SMTP server (e.g. `smtp.sendgrid.net`, `email-smtp.us-east-1.amazonaws.com`) |
|
||||
| `SMTP_PORT` | ✓ | 587 (STARTTLS) or 465 (TLS); verify with your provider |
|
||||
| `SMTP_USER` | ✓ | SMTP authentication username |
|
||||
| `SMTP_PASSWORD` | ✓ | SMTP authentication password — use a secret manager or env injection, not a file |
|
||||
| `SMTP_FROM` | ✓ | The `From:` address recipients will see (e.g. `"Mailship" <notifications@example.com>`) |
|
||||
| `DEFAULT_RELAYS` | | Comma-separated relay list; production should tune these to reliable relays |
|
||||
| `INDEXER_RELAYS` | | Same — use relays you trust for discovery |
|
||||
| `SEARCH_RELAYS` | | Same — use a relay that supports NIP-50 search |
|
||||
| `CORS_ORIGIN` | ✓ | **Must** be set to the exact origin your browser client runs on (e.g. `https://app.example.com`). The server refuses to start without it. |
|
||||
| `DATA_DIR` | | Default `/data` in the Docker image; change only if you mount a different volume path |
|
||||
| `BRAND_NAME`, `BRAND_ACCENT`, `BRAND_LOGO` | | Branding overrides — safe to leave at defaults |
|
||||
| `EVENT_VIEWER_URL` | | Controls where event links in emails point; defaults to Flotilla, set to your app's URL |
|
||||
| `PORT` | | Internal port (default `4738`) — no need to change unless remapping in compose |
|
||||
|
||||
> **Secrets in production:** Never commit `.env` or embed secrets in the compose
|
||||
> file. Use your infrastructure's secret store (e.g. Docker secrets, HashiCorp Vault,
|
||||
> Ansible Vault, 1Password CLI) and inject variables at deploy time.
|
||||
|
||||
### Persistent Data Volume
|
||||
|
||||
Mailship stores its data in a **SQLite database** located at `$DATA_DIR/mailship.db`
|
||||
(`/data/mailship.db` by default in the Docker image).
|
||||
|
||||
- **The database is the single source of truth** for subscriptions, events, and
|
||||
delivery state. Losing it means losing all subscriptions and digest history.
|
||||
- **Backup regularly** — a simple `sqlite3 /data/mailship.db .dump` or file-level
|
||||
copy (while the service is idle) is sufficient. For zero-downtime backups, use
|
||||
SQLite's `.backup` command or VACUUM INTO.
|
||||
- **Do not share the volume** across multiple Mailship instances — the in-process
|
||||
cron scheduler assumes a single writer.
|
||||
- **Volume location** when using Docker Compose:
|
||||
|
||||
```sh
|
||||
docker volume inspect mailship_mailship-data # inspect mount point
|
||||
docker run --rm -v mailship_mailship-data:/data alpine ls -la /data # browse contents
|
||||
```
|
||||
|
||||
To migrate or snapshot, stop the container and copy the database file:
|
||||
|
||||
```sh
|
||||
docker compose down
|
||||
docker run --rm -v mailship_mailship-data:/data -v $(pwd):/backup alpine cp /data/mailship.db /backup/mailship-$(date +%F).db
|
||||
docker compose up -d
|
||||
```
|
||||
|
|
|
|||
Loading…
Reference in a new issue