Email (SMTP) & file storage (S3)

PurrOS sends email through any SMTP server, and stores files either on local disk or in any S3-compatible object storage. Both are set with environment variables (see Configuration) and can be tested with the CLI.

Email (SMTP)Copy Anchor Link

What PurrOS sends by emailCopy Anchor Link

Once notifications ship, everyone will choose which ones they get by email. Security emails and sign-in links will always be sent.

SettingsCopy Anchor Link

Emails are sent by the worker from a queue, so a slow or unavailable SMTP server never slows the app down. Failed sends are retried with growing delays for up to 24 hours. Once sent, the email body is deleted; only the recipient, subject, kind and status are kept.

Example config/purros.envCopy Anchor Link

SMTP_HOST=smtp.your-provider.example
SMTP_PORT=587
SMTP_USER=apikey
SMTP_PASSWORD=your-smtp-password-or-api-key
SMTP_FROM="Acme Operations <[email protected]>"
SMTP_REPLY_TO=[email protected]

Any SMTP service works: a transactional email provider, Microsoft 365 or Google Workspace SMTP relay, Amazon SES, or your own mail server.

Make sure email gets deliveredCopy Anchor Link

To keep PurrOS email out of spam folders, set these DNS records for the domain in SMTP_FROM, following your email provider's instructions:

• SPF: authorizes your provider to send for your domain.
• DKIM: signs messages so receivers can verify them.
• DMARC: tells receivers what to do with unauthenticated mail.

Test itCopy Anchor Link

docker compose exec api purros email test --to [email protected]

It shows the exact SMTP error if sending fails.

Delivery logCopy Anchor Link

purros email log [--limit 30] lists recent emails with their status (queued, sent, failed) and the reason for failures. Email content is not kept once sent, only the recipient, subject and type.

Branding and languageCopy Anchor Link

Emails use the company name. (Planned: the company logo, each recipient's language, and editable templates.)

Without SMTPCopy Anchor Link

PurrOS works without email, but:

• invitation and sign-in links are printed instead (purros users invite, purros users sign-in-link) and have to be shared by hand
• magic-link sign-in and password reset by email are unavailable

File storage (S3)Copy Anchor Link

What PurrOS stores as filesCopy Anchor Link

Anything uploaded through attachments: employee documents (contracts, IDs, certificates), photos (checklist, audit, repair ticket and waste photos), receipts and supplier invoices, and payslip PDFs. (Planned: kiosk photos, the shared files library, imports and full company exports, and branding images. "Export my data" ZIPs and invoice PDFs are generated on request and not stored.)

The database only keeps each file's metadata (name, type, size, checksum, owner, who can see it). The file itself lives in storage.

DriversCopy Anchor Link

S3-compatible services include AWS S3, Cloudflare R2, Backblaze B2, Wasabi, DigitalOcean Spaces, Google Cloud Storage (interoperability mode), and self-hosted MinIO, Garage or Ceph.

S3 settingsCopy Anchor Link

Example: AWS S3Copy Anchor Link

STORAGE_DRIVER=s3
STORAGE_S3_BUCKET=acme-purros-files
STORAGE_S3_REGION=eu-central-1
STORAGE_S3_ACCESS_KEY_ID=AKIA...
STORAGE_S3_SECRET_ACCESS_KEY=...
STORAGE_S3_SSE=AES256

Example: self-hosted MinIO next to PurrOSCopy Anchor Link

Add to docker-compose.yml:

  minio:
    image: minio/minio
    command: server /data --console-address ":9001"
    environment:
      MINIO_ROOT_USER: purros
      MINIO_ROOT_PASSWORD: change-me-long-password
    volumes:
      - minio-data:/data
    restart: unless-stopped

volumes:
  minio-data:

STORAGE_DRIVER=s3
STORAGE_S3_ENDPOINT=http://minio:9000
STORAGE_S3_REGION=us-east-1
STORAGE_S3_BUCKET=purros
STORAGE_S3_FORCE_PATH_STYLE=true
STORAGE_S3_ACCESS_KEY_ID=purros
STORAGE_S3_SECRET_ACCESS_KEY=change-me-long-password

Create the bucket once in the MinIO console (port 9001) or with purros storage init.

Bucket setupCopy Anchor Link

• Keep the bucket private. PurrOS never makes files public. Downloads use short-lived signed URLs created only after checking that the person may see the file.
• Turn on versioning, so deleted or overwritten files can be recovered.
• Encryption at rest: use STORAGE_S3_SSE, or the provider's default bucket encryption.
• Lifecycle rules are optional. Don't set rules that delete files PurrOS still references. (Retention settings that let PurrOS delete old files itself, e.g. kiosk photos after 90 days, are planned.)
• Minimum permissions for the access key, on the bucket and prefix only: s3:GetObject, s3:PutObject, s3:DeleteObject, s3:ListBucket, s3:AbortMultipartUpload.

Example IAM policy for AWS:

{
  "Version": "2012-10-17",
  "Statement": [
    { "Effect": "Allow", "Action": ["s3:ListBucket"], "Resource": "arn:aws:s3:::acme-purros-files" },
    { "Effect": "Allow",
      "Action": ["s3:GetObject", "s3:PutObject", "s3:DeleteObject", "s3:AbortMultipartUpload"],
      "Resource": "arn:aws:s3:::acme-purros-files/*" }
  ]
}

How uploads and downloads workCopy Anchor Link

• Uploads go through the API (POST /api/v1/attachments). They are streamed straight to storage without being held in memory. PurrOS checks the file type from its content, enforces STORAGE_MAX_UPLOAD_MB, and records the SHA-256 checksum. See Attachments.
• Downloads go through a permission check. With S3, the response is a redirect to a signed URL that expires after STORAGE_SIGNED_URL_TTL seconds, so the file comes straight from the bucket. With local storage, PurrOS streams the file itself.
• Direct browser-to-bucket uploads (signed upload URLs) are planned. Until then, the bucket needs no CORS settings.

Test itCopy Anchor Link

• purros storage test writes, reads and deletes a test file (--backups tests the backup bucket)
• purros storage verify [--checksums] checks that every attachment's file is in storage
• purros doctor includes the same write/read test

Moving from local disk to S3Copy Anchor Link

# 1. Add the S3 settings to config/purros.env, but keep STORAGE_DRIVER=local for now
docker compose exec api purros storage migrate --to s3
# 2. When it reports "0 remaining", switch the driver
#    STORAGE_DRIVER=s3
docker compose up -d
docker compose exec api purros storage verify

storage migrate copies every file and checks its checksum. It can be stopped and run again: files already copied are skipped. Run it once more right before switching STORAGE_DRIVER to catch files uploaded in the meantime. The local volume isn't deleted, so remove it yourself once you've confirmed everything works.

Database backups to S3 (optional)Copy Anchor Link

PurrOS can upload every backup (scheduled and manual) to an S3-compatible bucket, and keeps a set number there. Use a different bucket from file storage, ideally with another provider or in another region.

With S3 enabled, PURROS_BACKUP_DIR becomes optional:

• With a directory, backups are kept locally and uploaded.
• Without one, backups are only uploaded; the local copy is deleted once the upload succeeds.

A failed upload is recorded, shown by purros backup list and purros doctor, and retried with the next backup.

purros backup list --remote                 # backups in the bucket
purros backup restore s3:<name> --replace   # restore straight from the bucket
purros backup download <name>               # or download first
purros storage init --backups               # create the bucket if needed

Encrypt backups before they leave the server with PURROS_BACKUP_PASSPHRASE. See Backups & upgrades.

With S3 file storage, the files themselves are backed up through bucket versioning and replication or your own tools, unless you set PURROS_BACKUP_FILES=true to include them in backups. With local storage they're included by default.