Mac-tailored authenticated Manager

Set up on Mac.Stay in the GUI.

Pull the public Mac-specific image with one standalone Compose file—no repository clone and no local application build. The secure Manager, scheduler, health check, persistent /data, and graceful lifecycle stay Mac-specific.

Install Update safely Full Mac guide

Mac Terminal · first run

$ docker compose pull tautweekly
$ docker compose up -d tautweekly
✓ public amd64/arm64 image healthy

$ docker compose exec -T tautweekly /opt/tautweekly/bin/run-as-user.sh \
  /opt/tautweekly/bin/tautweekly-manager access-bootstrap --data-dir /data/manager
✓ token returned only here

$ open http://localhost:8787/
✓ Config → Verify → Previews → TestEmail

Registry-first · no clone

Pull once, configure in Manager

Download the release's standalone Compose asset and SHA256SUMS.txt, verify them together, then let Docker Desktop select amd64 or arm64 from the unified image. The file pins full semver, selects desktop, stores private state in a named volume, and publishes only to Mac loopback.

1. Verify one file

TAUTWEEKLY_VERSION=0.25.0
grep '  TautWeekly-mac-compose.yaml$' SHA256SUMS.txt | shasum -a 256 -c -

Download both files from the same v0.25.0 release, then rename the verified asset to compose.yaml.

2. Pull and start

docker compose pull tautweekly
docker compose up -d tautweekly
docker compose ps

No repository clone, source tree, compiler, or local image build is involved.

3. Pin automation

Use ghcr.io/sparkmoxie/tautweekly:0.25.0 or the same tag plus its manifest digest. Never use mutable latest, 0.25, or edge as a CI/CD promotion pin.

No default password

Run the documented manager-bootstrap command through docker compose exec, open http://localhost:8787/, enter the one-time token, and create the administrator password. The token is absent from Docker logs and invalid after pairing.

Main features

Shape the newsletter in Manager Config

Normal configuration no longer uses the terminal wizard. These are the everyday controls; the full reference covers advanced renderer fields.

Connections and delivery

Add Tautulli, recommended direct Plex, SMTP, sender identity, and a controlled TestEmail. Saved secrets remain write-only.

Library selection

Choose the movie and TV libraries that define release, Trending, and personal-stat content. Unselected sections do not contribute.

User exclusions

Review the discovered roster and save who is excluded. The saved policy blocks those users from previews, TestEmail, welcome, and production delivery while keeping them visible for policy review.

Managed-user addresses

A separate card appears only for active Tautulli users without native email. Private fallback assignments may share an inbox, never override native email, and remain subject to existing exclusions; TestEmail stays isolated.

Newsletter and custom text

Set lookback, card limits, branding, and the optional custom text card. Its body is required when enabled; title, six-choice local title GIF, subheading, and border are optional.

Verify and PreviewAll

Select Validate, save, and verify, confirm library/user discovery and non-sending connectivity checks, then inspect all six previews.

TestEmail and Schedule

Send the six controlled messages only to TestEmail. Enable future starts after content, recipients, timezone, and inbox rendering are correct.

Deleted-item cache

When the cache is enabled or its coverage changes, validation starts a separate no-email refresh for every production-eligible included user and selected movie/TV library. It captures only qualifying live newsletter-window items by exact stable GUID and usable poster; it does not crawl the whole library or depend on PreviewAll. Run ./tautweekly.sh cache-refresh explicitly; for a share-safe summary, run docker compose exec tautweekly /opt/tautweekly/bin/run-script.sh Cache-Diagnostics.ps1 -DataRoot /data. Unseeded means no qualifying live refresh or render has written an entry. Disabling the cache stops reads and writes but does not erase retained entries in the persistent volume.

Prepare Plex and Tautulli metadata

Connection checks cannot prove upstream metadata freshness. Use this sequence after first setup, agent or Ratings Source changes, or a ratings/artwork recovery update.

Confirm Plex Movie Edit > Advanced > Ratings Source for each included library.
Run Plex Manage Library > Refresh All Metadata for every included movie/TV library and wait.
In Tautulli, open each same Library > Media Info tab, choose Refresh media info, and wait. The current control is per-library.
Return to Manager Verify, PreviewAll, and TestEmail.

Routine TautWeekly updates do not require a full refresh when current output already renders correctly.

Loopback recovery, verified Funnel remote access

Mac-hosted services

Use host.docker.internal for Plex or Tautulli running directly on the Mac. Container localhost refers to TautWeekly itself.

Manager access

PREVIEW_BIND and PREVIEW_PORT retain the fixed 127.0.0.1:8787 recovery mapping. Do not bind a LAN or all-interface address.

Browser boundary

Exact Host/origin admission, CSRF, HttpOnly/SameSite sessions, and Secure cookies remain backend-owned. The independently verified Funnel hostname is admitted automatically; /health/live exposes liveness only.

Public Tailscale Funnel

TAUTWEEKLY_FUNNEL_ADAPTER=enabled
./tautweekly.sh restart
./tautweekly.sh remote-access-login

Complete the official interactive sign-in, enable the Manager password lock, then enable and verify Funnel in Settings. The isolated userspace adapter owns separate state and only the fixed Manager target. Manager has no Docker socket, host executable, TUN device, network privilege, auth key, token, or arbitrary CLI input. Remote viewers need an ordinary browser, not Tailscale or a VPN.

Registry pull, host-owned recreate

Update without replacing private data

Settings > Updates reports the running image, unified repository, active desktop profile, recommended semver reference, digest policy, migration state, host-adapter compatibility, stable release, check history, sanitized failure, and release notes. The browser cannot invoke Docker Desktop; release publication is gated on the shared amd64/arm64 manifest and checksummed Compose assets.

1. Back up and pin

docker compose exec -T tautweekly tar -C /data -czf - . > private-backup.tar.gz

Record the previous semver/digest and keep the backup private.

2. Pull and recreate

docker compose pull tautweekly
docker compose up -d --force-recreate tautweekly

Advance TAUTWEEKLY_VERSION and optional digest-pinned TAUTWEEKLY_IMAGE together in .env. The named or bind-mounted data/ remains attached.

3. Accept in Manager

open http://localhost:8787/

Rollback and interruption

Rerun an interrupted pull or recreate. If health fails, restore the previous exact image reference and recreate against the same /data. Never run docker compose down -v. Graceful stop allows up to 30 minutes for an active newsletter.

Migrate the v0.22.0 Mac image without moving data

ghcr.io/sparkmoxie/tautweekly-mac:0.22.0 remains pullable for rollback but receives no new release tags. Preserve the exact named volume or bind mount, PUID/PGID/UMASK, ports, networks, and private .env; switch to the unified repository with desktop, pull, recreate, wait for health, then sign in with the existing password. An unexpected pairing page means the old /data is not attached. Rerun interrupted pulls/recreates against the same mount and never use docker compose down -v. The complete migration and rollback contract covers backup, host.docker.internal, loopback recovery, credentials, permissions, and interrupted recovery.

Archive/local-build fallback stays supported

The verified Mac archive, private .env plus data/ bind mount, ./mac-install.sh, and rollback-capable ./tautweekly.sh update remain available for break-fix use and existing installations. The transitional Mac Compose asset remains through v0.24.x and may retire no earlier than v0.25.0 with release-note notice.

Recovery and data ownership

Password recovery

docker compose exec -T tautweekly /opt/tautweekly/bin/run-as-user.sh \
  /opt/tautweekly/bin/tautweekly-manager access-recover --data-dir /data/manager --confirm
docker compose restart tautweekly
docker compose exec -T tautweekly /opt/tautweekly/bin/run-as-user.sh \
  /opt/tautweekly/bin/tautweekly-manager access-bootstrap --data-dir /data/manager

Only Manager credentials and sessions reset; configuration, schedules, history, output, and delivery state remain.

Named volume or bind mount

The no-clone default stores /data in a named volume. For ./data:/data, set non-root Mac PUID/PGID in a mode-0600 .env. The image stays read-only.

Uninstall

Run docker compose down without -v to retain private state. Delete the volume or bind-mounted data/ only when configuration, credentials, schedules, output, and cache should be erased.

Truthful limitation

This is a Docker Desktop Manager, not a native notarized .app, menu-bar item, Login Item, or macOS background agent. A physical Intel/Apple-silicon Mac and Docker Desktop remain final hardware acceptance gaps when CI cannot provide them.

In Manager Config > Configuration backups, Delete requires a second confirmation and permanently removes only that backup; it does not alter the current configuration.

Basic troubleshooting

Check the boundary that failed

Start with Manager status and Docker Desktop; keep private credentials, generated output, and raw logs out of public support reports.

Manager does not open

Confirm Docker Desktop is running, docker info succeeds, and docker compose ps reports the TautWeekly container healthy. Reopen http://localhost:8787/.

Verify cannot reach a service

For Plex or Tautulli on the Mac, use host.docker.internal; container localhost points back to TautWeekly. Confirm LAN firewalls and the saved URL.

Preview is skipped or incomplete

Confirm one owner/admin sample, selected libraries, and metadata readiness. Save and verify again before regenerating all six previews.

TestEmail or schedule fails

Keep production disabled. Recheck SMTP, sender permission, TestEmail, exclusions, timezone, and the saved revision, then inspect the sanitized operation result.

Full troubleshooting Configuration reference

Terminal commands are expert fallbacks

setup, verify, preview-all USER_ID, and send-test-all USER_ID remain for recovery and automation. They do not replace the normal Manager setup and acceptance workflow.

./tautweekly.sh status and logs inspect Docker Desktop lifecycle.
./tautweekly.sh check-update checks only; it never applies or schedules an update.
Real-recipient welcome and bulk delivery retain explicit confirmation.