# Stack matrix

This project was built for one server. This page tells you which parts you need, which you can skip, and which you can replace with your own choice.

Status key:

- **Required**: setup does not work without it.
- **Optional**: you can leave it out. The table says how.
- **Replaceable**: the project uses one product, but you can change it. Expect to edit scripts, not only config.

## How setup handles a part you skip

Read this before the table.

`app-setup/run-app-setup.sh` runs every `*-setup.sh` script in `app-setup/`. It does not read config to decide which ones to run. Most optional scripts exit with an error when their config keys are empty, and the run stops at the first error.

To skip a part, choose one:

1. Run only the scripts you want: `./run-app-setup.sh --only plex-setup.sh`.
2. Run everything with `--continue-on-error`, and ignore the failures of the parts you skipped.

A config switch per part does not exist yet.

## Base system

`prep-airdrop.sh` runs on your dev Mac. `scripts/server/first-boot.sh` runs on the new Mac Mini.

| Part | Status | Config keys | Notes | Docs |
| --- | --- | --- | --- | --- |
| Apple Silicon Mac Mini | Required | `SERVER_NAME`, `OPERATOR_USERNAME`, `HOSTNAME_OVERRIDE` | Another Mac can work, but only the Mac Mini is tested. | [Prerequisites](<https://smartwatermelon.github.io/mac-server-setup/get-started/02-prerequisites/index.md>) |
| 1Password CLI | Replaceable, with work | `ONEPASSWORD_VAULT`, `ONEPASSWORD_*_ITEM` | `prep-airdrop.sh` reads every credential from 1Password with `op`. It creates the operator item if it is missing. To use another password manager, edit `prep-airdrop.sh`. | [Credential chain](<https://smartwatermelon.github.io/mac-server-setup/explanation/credential-chain/index.md>) |
| Operator account | Required | `OPERATOR_USERNAME`, `ONEPASSWORD_OPERATOR_ITEM` | The service account that runs the media apps. | [Log in as operator](<https://smartwatermelon.github.io/mac-server-setup/get-started/07-operator-login/index.md>) |
| Time Machine backup | Optional | `ONEPASSWORD_TIMEMACHINE_ITEM` | If the 1Password item is missing, prep prints a warning and skips it. | [Configure](<https://smartwatermelon.github.io/mac-server-setup/get-started/03-configure/index.md>) |
| Apple ID | Optional | `ONEPASSWORD_APPLEID_ITEM` | Prep looks for the item among 1Password favorites. | [Configure](<https://smartwatermelon.github.io/mac-server-setup/get-started/03-configure/index.md>) |
| Terminal profile, iTerm2 | Optional | `TERMINAL_PROFILE_FILE`, `USE_ITERM2` | Leave both empty or `false` to skip. | No doc yet |
| Homebrew packages | Required | `config/formulae.txt`, `config/casks.txt` | Edit the lists to add or remove packages. | [Configure](<https://smartwatermelon.github.io/mac-server-setup/get-started/03-configure/index.md>) |

## Media apps

Scripts are listed in the order `run-app-setup.sh` runs them.

| Part | Status | Config keys | Notes | Docs |
| --- | --- | --- | --- | --- |
| NAS with an NFS share | Required | `NAS_HOSTNAME`, `NAS_USERNAME`, `NAS_SHARE_NAME`, `NAS_VOLUME`, `ONEPASSWORD_PLEX_NAS_ITEM` | Plex and Transmission both use the share. The mount path is `<NAS_HOSTNAME>:/<NAS_VOLUME>/<NAS_SHARE_NAME>`, which is how Synology exports a share. Another NAS works if its export path fits that shape. | [Plex setup](<https://smartwatermelon.github.io/mac-server-setup/components/plex/index.md>) |
| rclone + Dropbox | Optional | `DROPBOX_SYNC_FOLDER`, `DROPBOX_LOCAL_PATH`, `DROPBOX_SYNC_INTERVAL` | Syncs `.torrent` files to the watch folder. Not needed when Catch uses magnet links (`CATCH_USE_MAGNETS="true"`). `rclone-setup.sh` exits with an error when `DROPBOX_SYNC_FOLDER` is empty. | [rclone setup](<https://smartwatermelon.github.io/mac-server-setup/components/rclone/index.md>) |
| Transmission in Podman | Required for downloads | `LAN_SUBNET`, `TRANSMISSION_HOST_PORT` | Runs the `haugene/transmission-openvpn` container in a Podman VM. | [Transmission + FileBot](<https://smartwatermelon.github.io/mac-server-setup/components/transmission-filebot/index.md>) |
| PIA VPN | Replaceable, with work | `ONEPASSWORD_PIA_ITEM`, `PIA_VPN_REGION` | `OPENVPN_PROVIDER=PIA` is fixed in `podman-transmission-setup.sh`. The port-forwarding probe, guard and watchdog work with PIA only. The container supports other providers, but this project does not set them up. | [PIA VPN](<https://smartwatermelon.github.io/mac-server-setup/components/pia-vpn/index.md>) |
| FileBot | Required for library sorting | `FILEBOT_LICENSE_FILE`, `ONEPASSWORD_OPENSUBTITLES_ITEM` | Renames finished downloads and moves them into the Plex library. FileBot needs a paid license. If the license file is missing, setup only warns. OpenSubtitles login is skipped when its credentials are missing. | [Transmission + FileBot](<https://smartwatermelon.github.io/mac-server-setup/components/transmission-filebot/index.md>) |
| Catch (RSS) | Optional | `CATCH_FEEDS_URL`, `CATCH_HISTORY_CUTOFF_DAYS`, `CATCH_USE_MAGNETS` | Gets new episodes from a feed such as ShowRSS. With no feed URL, Catch installs and starts with no feeds. | No doc yet |
| Plex Media Server | Required | `NAS_*`, `PLEX_MIGRATE_FROM` | `PLEX_MIGRATE_FROM` is optional. It copies an existing Plex server's data. | [Plex setup](<https://smartwatermelon.github.io/mac-server-setup/components/plex/index.md>) |

## Remote access

| Part | Status | Config keys | Notes | Docs |
| --- | --- | --- | --- | --- |
| Caddy reverse proxy | Optional | `EXTERNAL_HOSTNAME`, `SERVER_LAN_IP`, `BASICAUTH_USERNAME`, `BASICAUTH_HASH` | Gives HTTPS on the LAN and a dashboard. `caddy-setup.sh` exits with an error when any of these four keys is empty. It also needs a Cloudflare API token in the keychain for DNS-01 certificates. | [Caddy](<https://smartwatermelon.github.io/mac-server-setup/components/caddy/index.md>) |
| Cloudflare domain | Required by Caddy, DDNS and Tunnel | `EXTERNAL_HOSTNAME`, `CLOUDFLARE_ZONE_ID` | A domain whose DNS is on Cloudflare. | [Caddy](<https://smartwatermelon.github.io/mac-server-setup/components/caddy/index.md>) |
| Cloudflare DDNS | Optional | `CLOUDFLARE_ZONE_ID`, `CLOUDFLARE_RECORD_ID`, `DDNS_RECORD_NAME` | Keeps one DNS record on your home IP. Needed only for the home VPN. | [Cloudflare DDNS](<https://smartwatermelon.github.io/mac-server-setup/components/cloudflare-ddns/index.md>) |
| Cloudflare Tunnel + Access | Optional | `CLOUDFLARE_ACCOUNT_ID`, `CLOUDFLARE_TUNNEL_ID`, `CLOUDFLARE_ACCESS_*`, `ACCESS_ALLOWED_EMAIL`, `TUNNEL_METRICS_PORT` | Lets you reach the server from outside without opening a port. Its watchdogs need msmtp. | [Cloudflare Tunnel](<https://smartwatermelon.github.io/mac-server-setup/components/cloudflare-tunnel/index.md>) |
| Home VPN | Optional | (none in this repo) | Runs on the NAS (Synology VPN Server), not on the Mac Mini. It needs Cloudflare DDNS to keep its hostname on your home IP. | [Home VPN](<https://smartwatermelon.github.io/mac-server-setup/components/home-vpn/index.md>) |
| Home Assistant through the tunnel | Optional | `HOME_ASSISTANT_HOSTNAME`, `HOME_ASSISTANT_UPSTREAM` | Gives Home Assistant its own hostname behind the same Access application. Browser only. Needs Cloudflare Tunnel + Access. | [Cloudflare Tunnel](<https://smartwatermelon.github.io/mac-server-setup/components/cloudflare-tunnel/index.md#home-assistant>) |
| Dashboard links | Optional | `HOME_LINKS_TITLE`, `HOME_LINK1_*`, `HOME_LINK2_*` | Up to two optional links on the dashboard, such as your NAS admin pages. A link with an empty URL is left out. | [Caddy](<https://smartwatermelon.github.io/mac-server-setup/components/caddy/index.md#dashboard-links>) |

## Monitoring and extras

| Part | Status | Config keys | Notes | Docs |
| --- | --- | --- | --- | --- |
| msmtp alert email | Optional, but the watchdogs need it | `MONITORING_EMAIL` | Sends through Gmail (`smtp.gmail.com`) with a Gmail App Password. For another mail provider, edit `msmtp-setup.sh`. | [Monitoring](<https://smartwatermelon.github.io/mac-server-setup/components/monitoring/index.md>) |
| Plex watchdog | Optional | `MONITORING_EMAIL` | Needs msmtp. | [Plex watchdog](<https://smartwatermelon.github.io/mac-server-setup/components/plex-watchdog/index.md>) |
| Transmission watchdogs | Installed with Transmission | (none) | The PIA port watchdog and the stall watchdog. They need msmtp to send email. | [Monitoring](<https://smartwatermelon.github.io/mac-server-setup/components/monitoring/index.md>) |
| Stable signing | Installed with auto-updates | (none) | Keeps macOS privacy grants for Homebrew binaries after each upgrade. | [Stable signing](<https://smartwatermelon.github.io/mac-server-setup/components/stable-signing/index.md>) |
| TVmaze scrobble | Optional | `TVMAZE_USERNAME`, `PLEX_ACCOUNT_TITLE`, `PLEX_ACCOUNT_ID`, `TVMAZE_SCROBBLE_PORT` | Marks Plex plays as watched on TVmaze. `tvmaze-scrobble-setup.sh` exits with an error when the username keys are empty. | [TVmaze scrobble](<https://smartwatermelon.github.io/mac-server-setup/components/tvmaze-scrobble/index.md>) |
| Backblaze | Optional | (none) | Installed as a Homebrew cask. You sign in by hand. | No doc yet |

## Values to change in the template

`config/config.conf.template` has some values from the original server. Change these before your first run:

- `OP_VAULT_ID`: a placeholder. Set your own vault ID or vault name. `prep-airdrop.sh` stops when the vault is empty.
- `PIA_VPN_REGION`: picked for a server in the Pacific Northwest. Choose a region near you that supports port forwarding.
