READ ME FIRST · MAC EDITION

Your Plex newsletter.Native to your Mac workflow.

A Mac-specific Docker Desktop package for installing, testing, scheduling, and safely operating TautWeekly for Plex without QNAP, Unraid, Windows BAT files, or host-installed PowerShell.

Start the walkthrough →See all six email states Open complete reference

Terminal — TautWeekly for Plex

$ ./tautweekly.sh verify

[OK] Docker Desktop connected
[OK] Tautulli API connected
[OK] Animated GIF assets valid
[OK] Preview web assets served
[OK] Six email states supported

NEXT: ./tautweekly.sh preview-all
No real Plex user email will be sent.

$ |

2Mac architectures supported

6deterministic preview states

3real delivery types

0credentials included

No guide sections matched that search. Try “Tautulli,” “sleep,” “SMTP,” “backup,” or “Apple silicon.”

Before installation

ZIP versus TAR.GZ

Both archives contain the same Mac package. Choose based on how you prefer to extract it.

ZIP

Finder-friendly ZIP

Best when downloading and extracting through Finder. Run the documented chmod command afterward.

TGZ

Terminal-native TAR.GZ

Better at preserving Unix executable permissions when extracted from Terminal.

Install only one archive.

Keeping both as backups is fine, but extracting both into the same folder is unnecessary.

Preflight

What your Mac needs

All runtime dependencies stay inside Docker. macOS only needs Docker Desktop and network access.

Apple silicon

arm64 Macs are detected automatically.

Intel

x86_64 Macs use the same package.

◫

Docker Desktop

The Docker engine and Compose must be running.

✉

STARTTLS SMTP

Use a provider port such as 587, not implicit SMTPS 465.

No native PowerShell installation.

PowerShell 7, ImageMagick, Python, and the scheduler run entirely inside the Linux container.

Launch sequence

Install step by step

The installer creates Mac-specific environment settings, starts the container, opens setup, and verifies the result.

Extract into a permanent folder

Example: ~/Applications/TautWeekly.

Open Terminal in the folder

Permissions

chmod +x INSTALL-MAC.command mac-install.sh tautweekly.sh

Run the Mac installer

Guided install

./mac-install.sh

It detects Apple silicon or Intel, uses your macOS UID/GID, and binds previews to localhost.

Complete TautWeekly for Plex setup

Enter Tautulli, choose any users to exclude from weekly delivery, then finish SMTP, branding, and schedule values. The direct Plex token remains optional.

Run acceptance tests

Safe acceptance

./tautweekly.sh verify
./tautweekly.sh list-users
./tautweekly.sh exclude-users
./tautweekly.sh preview-all
./tautweekly.sh send-test-all
./tautweekly.sh schedule-status

Enable automatic delivery last

Explicit authorization

./tautweekly.sh schedule-enable

Container networking

Point TautWeekly for Plex at the right host

Inside the container, localhost points back to TautWeekly for Plex—not to macOS or Tautulli.

Tautulli native on Mac

Recommended

http://host.docker.internal:8181

Tautulli container

Shared network

http://tautulli:8181

Remote server or NAS

LAN address

http://media.example.test:8181

Direct Plex on this Mac.

Use http://host.docker.internal:32400. The Plex token is optional and may be left blank.

Command center

Know what every command does

Safe actions, TestEmail-only actions, and real-recipient actions are separated clearly.

Command	Purpose	Risk
`verify`	Checks config, Tautulli, assets, SMTP reachability, preview web root, and schedule syntax.	SAFE
`list-users`	Lists users and recipient addresses exposed by Tautulli.	SAFE
`exclude-users`	Revises stable user exclusions without rerunning SMTP or schedule setup.	CONFIG
`preview / preview-all`	Creates one branch or all six HTML states.	NO EMAIL
`send-test / send-test-all`	Sends one or six messages exclusively to TestEmail.	TESTEMAIL
`welcome`	Sends a real welcome to the selected Plex user.	REAL USER
`send-all`	Sends separate newsletters to all eligible users.	BULK SEND
`schedule-enable`	Authorizes automatic weekly SendAll.	AUTOMATION
`backup / update`	Backs up data or rebuilds the service while preserving data.	SYSTEM
`open-preview`	Opens the local preview service in the default Mac browser.	SAFE

Use stable IDs for recipient policy.

Run ./tautweekly.sh exclude-users, select rows or ranges, press Enter to keep the current list, or type none to clear it. The roster contains private names and email addresses.

Visual acceptance

Six deterministic email states

All states share the production renderer and actual MIME/CID test pipeline.

Manual welcome

One-off onboarding without weekly stats.

WELCOMEONLY

New user, no history

First-Friday onboarding replaces empty stats.

RECENTACCESS + ZERO

New user, with history

First-Friday layout with populated personal stats.

RECENTACCESS + ACTIVITY

Established normal

Normal active-user weekly newsletter.

ACTIVITY

Established quiet

Zero activity after the initial warm-up period.

QUIET IN THIS SECTOR

Established warm-up

Zero activity during TautWeekly for Plex’s initial data window.

STATS ARE WARMING UP

Automatic delivery

Scheduling and Mac sleep

The scheduler lives inside the container, so launchd is unnecessary—but the Mac still has to be awake.

◷

Internal scheduler

Day, time, timezone, and grace window come from config and .env.

☾

Sleep matters

A sleeping or powered-off Mac cannot send.

↻

Duplicate guard

The attempt is recorded before sending to suppress unsafe retries.

▶

Docker startup

Docker Desktop should start when you sign in if this Mac is the permanent host.

Grace window behavior.

A short interruption may still be handled after wake if the configured grace period remains open. Do not rely on this for long sleep periods.

Persistence

Data, backup, and updates

The container is disposable. The project’s data folder carries configuration, state, output, and history.

data/ ├── config.json ├── state.json ├── access-state.json ├── scheduler-state.json ├── assets/ ├── output/ └── logs/

Update safely

Never replace or delete the data folder
Run backup before major updates
Rebuild with ./tautweekly.sh update
Run verify and preview-all afterward

Backup and update

./tautweekly.sh backup
./tautweekly.sh update
./tautweekly.sh repair-assets
./tautweekly.sh verify
./tautweekly.sh preview-all

Existing installation

Migrate from NAS Portable v1.0.4

The underlying data schema is compatible, so history and access state can move with you.

Stop both services

Avoid copying state while either scheduler or sender is active.

Copy the complete data folder

Preserve config, state, access-state, scheduler-state, assets, logs, and output.

Review host URLs

Native Mac services normally change to host.docker.internal.

Verify before enabling scheduling

Run the full preview and TestEmail acceptance sequence.

Diagnostics

Common Mac issues

Most failures are Docker startup, file permissions, host addressing, or SMTP settings.

Docker command cannot connect

Open Docker Desktop and wait until the engine reports that it is running. Then rerun docker info and ./tautweekly.sh status.

INSTALL-MAC.command will not open

Right-click the file and choose Open, or use Terminal: chmod +x INSTALL-MAC.command mac-install.sh tautweekly.sh followed by ./mac-install.sh.

Tautulli connection fails

Use host.docker.internal for Tautulli running natively on the Mac. Do not use 127.0.0.1 from inside the container.

Preview page is unavailable

Run ./tautweekly.sh status, ./tautweekly.sh logs, and ./tautweekly.sh verify. The default URL is http://localhost:8787.

Scheduled send did not run

Confirm Docker Desktop was running and the Mac was awake. Check schedule-status, timezone, day/time, grace window, and scheduler logs.

SMTP authentication fails

Verify STARTTLS, port 587, username, and app password/provider credentials. Port 465 implicit SMTPS is unsupported.

Complete reference

Recommended operating sequence

The shortest safe path from extraction to automatic weekly delivery.

Full Mac workflow

cd ~/Applications/TautWeekly
chmod +x INSTALL-MAC.command mac-install.sh tautweekly.sh
./mac-install.sh

./tautweekly.sh verify
./tautweekly.sh list-users
./tautweekly.sh exclude-users
./tautweekly.sh preview-all
./tautweekly.sh send-test-all
./tautweekly.sh schedule-status
./tautweekly.sh open-preview

# Enable only after all six TestEmail messages are approved:
./tautweekly.sh schedule-enable

Final acceptance gate.

Review the browser preview index and all six TestEmail messages on desktop and mobile before enabling the scheduler.

Current email behavior

Adaptive stats and the Binge Champion award

Light viewing weeks reveal more detail without making heavy viewing weeks excessively tall.

1–3

Itemized movies

Mini poster, movie title, Rotten Tomatoes critic score, and audience score.

1–3

Itemized episodes

Mini show poster, show title, Sxx EPxx episode title, and IMDb score.

Compact counts

At four or more, the card returns to the large-number format to protect email length.

Binge Champion is a privacy-preserving server-wide award.

The user with the most qualifying watch time wins; total plays break an exact-time tie. Every scheduled weekly email shows the same anonymous movie-play, TV-play, and total-time aggregate. Only the winner’s card receives the gold border, larger trophy, and “YOU WON” treatment.

Trending is not duplicated.

Trending ranks a media title and displays its server-wide play count once. Binge Champion ranks a person by qualifying watch time, but never reveals that person’s name, user ID, or watched titles.

Global movie formatting

Genre now appears in watched-movie statistics

The compact 1–3 movie recap now matches the rest of the newsletter’s movie hierarchy.

1–3

Adaptive movie rows

Each row includes a mini poster, title, genre, and Rotten Tomatoes critic and audience scores.

ALL

One genre rule

Show the first two genres and append “, and more” when additional genres exist.

✓

No empty genre row

When metadata has no genre, the rating line moves up automatically with no blank space.

Applied everywhere the adaptive movie-stat card can render.

This includes production and portable previews, individual tests, six-state test suites, scheduled weekly newsletters, and all applicable recipient states.

PowerShell 5.1 hotfix

Single-item adaptive cards now retain array semantics

Exactly one watched movie or one streamed episode no longer becomes a scalar under strict mode.

Resolved: “The property ‘Count’ cannot be found on this object.”

MovieItems and EpisodeItems are initialized and assigned explicitly as arrays before the adaptive renderer checks their counts.

Empty collection

Retains a valid zero-length array.

Single item

Remains an array instead of being unwrapped into a scalar.

2–3

Multiple items

Continues to render the adaptive poster rows normally.