Native Linux · no Docker required

A quiet service.
A deliberate send.

Run a fully headless, Docker-free service with no server desktop. Open the same authenticated Manager and newsletter workflow from an administrator workstation through an SSH tunnel or optional password-gated public Tailscale Funnel while systemd isolates private state.

headlessPowerShell 7.2+systemdloopback Manager

Start installation Download release

linux — controlled launch

$ sudo ./install-linux.sh
✓ protected service account
✓ application separated from data

$ sudo tautweekly manager-bootstrap
✓ one-time token, terminal only

$ ssh -L 8788:127.0.0.1:8788 HOST
→ GUI setup · verify · TestEmail

0default passwords

0700private data directory mode

127.0.0.1default Manager bind

opt-inautomatic production delivery

Before installation

Use a supported runtime.

The package requires PowerShell 7.2+, systemd, Python 3, ImageMagick, tar, and util-linux. PowerShell comes from Microsoft's supported distribution repository; TautWeekly does not add repositories as root.

Choose the native track

Use a current 64-bit Ubuntu, Debian, or RHEL release with systemd for a Docker-free install. A Linux server that runs Docker uses the NAS/Docker package; the name does not require NAS hardware.

PowerShell 7

Install pwsh 7.2 or newer. A current LTS is recommended. Confirm with pwsh --version.

Host tools

Provide Python 3, tar, and util-linux tools including runuser and flock.

GUI-first installation

Verify, install, pair.

The application is replaceable and fully headless. Your Manager credentials, newsletter configuration, scheduler guard, logs, previews, and custom assets live outside it; use a separate administrator workstation for browser access.

1. Verify and extract the release

sha256sum --check SHA256SUMS.txt --ignore-missing tar -xzf TautWeekly-linux.tar.gz cd TautWeekly-linux

2. Install and open guided GUI setup

sudo ./install-linux.sh ssh -L 8788:127.0.0.1:8788 YOUR_ADMIN@YOUR_HOST sudo tautweekly manager-bootstrap # on the workstation, open http://127.0.0.1:8788, pair, and complete Config

The one-time token is returned only by the explicit bootstrap command and never appears in installer or service logs. Choose a unique administrator password; there is no insecure default. No desktop or browser is required on the Linux server itself.

PMS

Direct Plex is recommended for full newsletter fidelity

Tautulli supplies core activity and selected/flattened rating fallbacks. During setup, enter a Plex URL and administrator token reachable from the service runtime for complete movie RT critic/audience ratings, exact-episode IMDb/RT ratings, backgrounds, and selected logos. Verification checks Plex identity and authenticated library access without printing the token; a resolved but unusable connection fails before preview or TestEmail.

Before acceptance

Refresh Plex, then Tautulli.

Use this after first setup, after a Plex agent/source change, or after a ratings/artwork recovery update when data may be stale.

01 Plex source

Confirm Edit → Advanced → Ratings Source for each included Plex Movie library.

02 Plex refresh

Run Manage Library → Refresh All Metadata for every included movie/TV library and wait.

03 Tautulli refresh

Open each same Library → Media Info tab, select Refresh media info, and wait. Repeat per library.

Full refreshes can be slow and can update metadata or artwork.

Do not refresh unrelated libraries. Tautulli's table refresh does not replace Plex's refresh. Routine TautWeekly updates do not require this when current output is correct.

Main features and acceptance

Shape it, inspect it, then deliver.

The Manager exposes the everyday newsletter controls without requiring JSON edits. Use the full reference for 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 releases, Trending, and personal statistics. Unselected sections do not contribute.

User exclusions

Save who is excluded from personalized use. The 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.

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 sudo tautweekly cache-refresh explicitly and sudo tautweekly cache-status for a share-safe aggregate summary. 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 under /var/lib/tautweekly.

01 Config

Use the Manager to enter Tautulli, recommended direct Plex, SMTP, branding, libraries, exclusions, schedule, and the optional custom text card. Its body is required when enabled.

02 Verify

Run the GUI checks for Tautulli, direct Plex identity/authenticated library access, files, SMTP reachability, and time zone.

03 Preview

Render six deterministic browser states without email.

04 TestEmail

Validate SMTP authentication, sender permission, MIME, and mail-client rendering.

05 Schedule

Enable in the GUI only after roster and exclusions are reviewed.

# In the Manager at http://127.0.0.1:8788: Config → Validate, save, and verify Previews → Generate six previews Operations → Send TestEmail Schedule → Enable schedule

LIB

One upstream content scope

manage-libraries saves stable Tautulli section IDs and backs up private configuration. The renderer queries selected sections independently, rejects mismatched rows, and applies the resulting scope before quiet mode, Trending, Binge Champion, and personal statistics are calculated.

MAIL

Current newsletter presentation

The inherited payload lists every qualifying personal movie and TV show in separate full-width cards. Both use two title columns on desktop; on mobile, movies stack one per row while TV retains two columns. Empty media cards stay omitted; compact personal total watch time and Binge Champion cards remain distinct. HOT NEW RELEASE is movie-only; a movie-empty week uses an authentic Trending hero when server history supplies one and retains new TV cards.

Optional public remote access

Public HTTPS Funnel, fixed to loopback.

A unique Manager password and exact public DNS/TLS verification are required before Active.

1. Prepare Tailscale

Install the official Linux client, start it, and sign in on this host. Confirm MagicDNS, HTTPS certificates, and a Funnel node attribute that targets this node; tagged service nodes need an explicit tag target. TautWeekly never installs, authenticates, or edits tailnet policy.

2. Authorize the fixed adapter

sudo tautweekly remote-access-authorize

The root-owned one-shot helper accepts only Inspect, Enable, or Disable for the fixed port 8788 target; Manager remains unprivileged.

3. Enable and verify

Create the Manager password, open Settings > Tailscale Funnel, complete any provider approval, and Verify. Local Funnel on and gold Publication pending are not green Active; independent public DNS and trusted TLS must pass. Never open a firewall/router port or create a DNS record.

Manager authentication remains required

Funnel is public ingress, so the Manager password is the authentication boundary. Every remote session still has full Manager administration. Disable in Settings before running sudo tautweekly remote-access-revoke; local access remains the recovery path.

Use the loopback access path.

Native Linux does not publish Manager directly to the LAN. Keep the SSH tunnel open while using http://127.0.0.1:8788/, or enable the documented password-gated public Funnel. A local server desktop is neither required nor expected.

Keep `/var/lib/tautweekly` private.

config.json contains an SMTP credential and Tautulli API key and may contain a Plex token. Logs, previews, and backups can reveal recipients and viewing activity. Never upload them to an issue or release.

Path	Role	Boundary
`/opt/tautweekly`	Application and defaults	Root-owned, read-only to service
`/var/lib/tautweekly`	All private runtime material	Service-owned, mode 0700
`/etc/tautweekly/tautweekly.env`	Timezone, paths, Manager listener, and renderer preview URL	Root-owned, mode 0600

ssh -L 8788:127.0.0.1:8788 admin@example.com # open http://127.0.0.1:8788 locally

Local recovery stays on loopback.

Use the SSH local forward for setup/recovery. Optional public access uses only the independently verified Funnel hostname, which the backend admits with its Secure-cookie boundary automatically. Do not publish either loopback listener directly.

Forgot the Manager password?

Run sudo tautweekly manager-reset-access, then sudo tautweekly manager-bootstrap. This resets only Manager authentication and browser sessions; configuration, schedules, output, history, and backups remain intact.

Settings status, host-owned update

Check, back up, verify, upgrade.

Settings > Updates is the primary status source for the running application, native package, stable release, check history, sanitized failures, and release notes. Authenticated entry renders cached status first, then performs one bounded background refresh only when the last success is missing or at least 24 hours old and backoff permits. The main header Refresh reloads local status first and then starts that check only when the new typed status recommends it; it never waits for GitHub, while scoped refresh controls stay isolated. Successful results are reused for five minutes; Check now then explicitly refreshes the same endpoint. Current remains green, every non-current status gives the update card an attention glow, and the purple header SVG appears only after a successful check validates a newer running application. Normal health stays offline-capable. The GUI never invokes sudo or systemd and instead provides sudo tautweekly update. The host wrapper verifies the matching archive, checksum, and internal manifest, waits for an active delivery, preserves private data, and verifies service recovery.

Check and upgrade

tautweekly check-update sudo tautweekly backup sudo tautweekly update # sign back into the GUI, verify, preview, and TestEmail

Observe

sudo systemctl status tautweekly sudo journalctl -u tautweekly -n 200 --no-pager

Private backup

sudo tautweekly backup # briefly stops an active service for consistency

Unattended upgrades are not enabled.

If acceptance fails, reinstall the previous verified archive or restore the timestamped program backup; private state remains under /var/lib/tautweekly. Reinstall preserves that directory. Uninstall removes the service and replaceable application but should retain private data until its backup is verified and deletion is explicitly intended.

Individual backup deletion is explicit.

Manager Config > Configuration backups requires Confirm delete before permanently deleting one backup. It does not modify the live configuration.

Basic troubleshooting

Check the boundary that failed.

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

Manager does not open

Run sudo systemctl status tautweekly, confirm the service is active, and use tautweekly open-manager. From another device, keep loopback and use the documented SSH tunnel. For public Funnel, confirm tautweekly remote-access-status reports authorized and use Settings > Tailscale Funnel > Verify; gold Publication pending is not Active.

Verify cannot reach a service

Test the saved Tautulli or Plex URL from the Linux host and service network. Confirm the target listening address, firewall, and that loopback is used only for a service on this host.

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 Manager history or recent sanitized journal output.

Full troubleshooting Configuration reference