<?xml version="1.0" encoding="utf-8" standalone="yes"?><rss version="2.0" xmlns:atom="http://www.w3.org/2005/Atom"><channel><title>mac mini | mutschler.dev</title><link>https://mutschler.dev/tag/mac-mini/</link><atom:link href="https://mutschler.dev/tag/mac-mini/index.xml" rel="self" type="application/rss+xml"/><description>mac mini</description><generator>Wowchemy (https://wowchemy.com)</generator><language>en-us</language><lastBuildDate>Fri, 20 Nov 2026 00:00:00 +0000</lastBuildDate><image><url>https://mutschler.dev/media/icon_hu589851f325050e29bd29c51f9d799271_45964_512x512_fill_lanczos_center_3.png</url><title>mac mini</title><link>https://mutschler.dev/tag/mac-mini/</link></image><item><title>Mac mini M4 Pro: Gitea with Actions CI and modCraft in OrbStack behind Tailscale sidecars</title><link>https://mutschler.dev/apple/mac-mini-gitea-modcraft/</link><pubDate>Fri, 20 Nov 2026 00:00:00 +0000</pubDate><guid>https://mutschler.dev/apple/mac-mini-gitea-modcraft/</guid><description>&lt;p>&lt;em>&lt;strong>Please feel free to raise any comments or issues on the &lt;a href="https://github.com/wmutschl/mutschler.dev" target="_blank" rel="noopener">website&amp;rsquo;s Github repository&lt;/a>.
Pull requests are very much appreciated.&lt;/strong>&lt;/em>
&lt;a href="https://www.buymeacoffee.com/mutschler" target="_blank">&lt;img src="https://cdn.buymeacoffee.com/buttons/v2/default-red.png" alt="Buy Me A Coffee" style="height: 60px !important;width: 217px !important;" >&lt;/a>&lt;/p>
&lt;details class="toc-inpage d-print-none d-xl-none " open>
&lt;summary class="font-weight-bold">Table of Contents&lt;/summary>
&lt;nav id="TableOfContents">
&lt;ul>
&lt;li>&lt;a href="#overview">Overview&lt;/a>&lt;/li>
&lt;li>&lt;a href="#1-the-intended-layout">1 The intended layout&lt;/a>&lt;/li>
&lt;li>&lt;a href="#2-prepare-macos-for-unattended-operation">2 Prepare macOS for unattended operation&lt;/a>
&lt;ul>
&lt;li>&lt;a href="#21-energy-settings">2.1 Energy settings&lt;/a>&lt;/li>
&lt;li>&lt;a href="#22-filevault-restarts-and-remote-access">2.2 FileVault, restarts and remote access&lt;/a>&lt;/li>
&lt;li>&lt;a href="#23-tailscale-on-the-mac-and-the-scripts-repository">2.3 Tailscale on the Mac and the scripts repository&lt;/a>&lt;/li>
&lt;/ul>
&lt;/li>
&lt;li>&lt;a href="#3-orbstack">3 OrbStack&lt;/a>&lt;/li>
&lt;li>&lt;a href="#4-tailscale-tags-oauth-client-and-node-names">4 Tailscale: tags, OAuth client and node names&lt;/a>&lt;/li>
&lt;li>&lt;a href="#5-configure-the-deployment">5 Configure the deployment&lt;/a>&lt;/li>
&lt;li>&lt;a href="#6-gitea">6 Gitea&lt;/a>
&lt;ul>
&lt;li>&lt;a href="#61-start-gitea-and-its-sidecar">6.1 Start Gitea and its sidecar&lt;/a>&lt;/li>
&lt;li>&lt;a href="#62-admin-account-and-two-factor-authentication">6.2 Admin account and two-factor authentication&lt;/a>&lt;/li>
&lt;li>&lt;a href="#63-git-over-ssh-and-https">6.3 Git over SSH and HTTPS&lt;/a>&lt;/li>
&lt;/ul>
&lt;/li>
&lt;li>&lt;a href="#7-mirrors-of-github-and-gitlab">7 Mirrors of GitHub and GitLab&lt;/a>
&lt;ul>
&lt;li>&lt;a href="#71-tokens">7.1 Tokens&lt;/a>&lt;/li>
&lt;li>&lt;a href="#72-create-the-organizations">7.2 Create the organizations&lt;/a>&lt;/li>
&lt;li>&lt;a href="#73-mirror-everything-with-gitea-mirror">7.3 Mirror everything with gitea-mirror&lt;/a>&lt;/li>
&lt;li>&lt;a href="#74-a-single-mirror-in-the-web-interface">7.4 A single mirror in the web interface&lt;/a>&lt;/li>
&lt;li>&lt;a href="#75-how-the-mirrors-behave">7.5 How the mirrors behave&lt;/a>&lt;/li>
&lt;li>&lt;a href="#76-personal-projects">7.6 Personal projects&lt;/a>&lt;/li>
&lt;/ul>
&lt;/li>
&lt;li>&lt;a href="#8-gitea-actions-on-the-mac-mini">8 Gitea Actions on the Mac mini&lt;/a>
&lt;ul>
&lt;li>&lt;a href="#81-register-the-container-runner">8.1 Register the container runner&lt;/a>&lt;/li>
&lt;li>&lt;a href="#82-a-first-workflow">8.2 A first workflow&lt;/a>&lt;/li>
&lt;li>&lt;a href="#83-what-jobs-can-and-cannot-do">8.3 What jobs can and cannot do&lt;/a>&lt;/li>
&lt;li>&lt;a href="#84-optional-a-runner-directly-on-macos">8.4 Optional: a runner directly on macOS&lt;/a>&lt;/li>
&lt;/ul>
&lt;/li>
&lt;li>&lt;a href="#9-modcraft">9 modCraft&lt;/a>
&lt;ul>
&lt;li>&lt;a href="#91-clone-and-configure-modcraft">9.1 Clone and configure modCraft&lt;/a>&lt;/li>
&lt;li>&lt;a href="#92-build-and-start-modcraft-and-its-sidecar">9.2 Build and start modCraft and its sidecar&lt;/a>&lt;/li>
&lt;li>&lt;a href="#93-smoke-test-statistics-backup-and-model-check">9.3 Smoke test, statistics backup and model check&lt;/a>&lt;/li>
&lt;li>&lt;a href="#94-updates">9.4 Updates&lt;/a>&lt;/li>
&lt;li>&lt;a href="#95-serve-instead-of-funnel">9.5 Serve instead of Funnel&lt;/a>&lt;/li>
&lt;li>&lt;a href="#96-moving-modcraft-to-its-vps-later">9.6 Moving modCraft to its VPS later&lt;/a>&lt;/li>
&lt;/ul>
&lt;/li>
&lt;li>&lt;a href="#10-backups-monitoring-and-ongoing-care">10 Backups, monitoring and ongoing care&lt;/a>
&lt;ul>
&lt;li>&lt;a href="#101-healthchecksio-and-the-hosts-settings">10.1 healthchecks.io and the host&amp;rsquo;s settings&lt;/a>&lt;/li>
&lt;li>&lt;a href="#102-install-the-launchd-jobs">10.2 Install the launchd jobs&lt;/a>&lt;/li>
&lt;li>&lt;a href="#103-what-the-backup-contains">10.3 What the backup contains&lt;/a>&lt;/li>
&lt;li>&lt;a href="#104-restore-drills">10.4 Restore drills&lt;/a>&lt;/li>
&lt;li>&lt;a href="#105-recovery-material">10.5 Recovery material&lt;/a>&lt;/li>
&lt;li>&lt;a href="#106-updates">10.6 Updates&lt;/a>&lt;/li>
&lt;li>&lt;a href="#107-regular-checks">10.7 Regular checks&lt;/a>&lt;/li>
&lt;/ul>
&lt;/li>
&lt;/ul>
&lt;/nav>
&lt;/details>
&lt;h2 id="overview">Overview&lt;/h2>
&lt;figure id="figure-mac-mini-workstation">
&lt;div class="d-flex justify-content-center">
&lt;div class="w-100" >&lt;img alt="A Mac mini surrounded by icons for Gitea, Claude, espresso, MATLAB, Dynare, data science, YouTube, writing papers, research and Linux" srcset="
/media/mac-mini-workstation_hub10f5d8bed67042b5f7c7b6bce8b01a1_169206_fac7398c65dd0804858aad592a436bb2.webp 400w,
/media/mac-mini-workstation_hub10f5d8bed67042b5f7c7b6bce8b01a1_169206_0fa29b009edd5aba1edfa0e62b8d1a7a.webp 760w,
/media/mac-mini-workstation_hub10f5d8bed67042b5f7c7b6bce8b01a1_169206_1200x1200_fit_q75_h2_lanczos.webp 1200w"
src="https://mutschler.dev/media/mac-mini-workstation_hub10f5d8bed67042b5f7c7b6bce8b01a1_169206_fac7398c65dd0804858aad592a436bb2.webp"
width="760"
height="760"
loading="lazy" data-zoomable />&lt;/div>
&lt;/div>&lt;figcaption>
My Mac mini M4 Pro and what it is used for.
&lt;/figcaption>&lt;/figure>
&lt;p>My Mac mini M4 Pro is my research workstation, and it runs two services in &lt;a href="https://orbstack.dev" target="_blank" rel="noopener">OrbStack&lt;/a>, a lightweight Docker engine for macOS:&lt;/p>
&lt;ul>
&lt;li>&lt;strong>Gitea&lt;/strong>, set up from scratch.
Mostly it mirrors my repositories from GitHub and GitLab.
It also hosts a few personal projects that need more room than GitHub&amp;rsquo;s or GitLab&amp;rsquo;s free plans give me, or that should run their CI on the Mac itself, with Gitea Actions.
Gitea is reachable only from devices in my tailnet: a &lt;strong>Tailscale sidecar container&lt;/strong> publishes it with Tailscale Serve, over HTTPS and for Git over SSH.&lt;/li>
&lt;li>&lt;strong>modCraft&lt;/strong>, my web app that generates &lt;a href="https://www.dynare.org" target="_blank" rel="noopener">Dynare&lt;/a> models, the &lt;code>.mod&lt;/code> file and its derivation, from a selection of model features.
It runs here until it moves to a VPS of its own.
It keeps its own Compose stack in its repository, and a second Tailscale sidecar publishes it on the internet with Tailscale Funnel.&lt;/li>
&lt;/ul>
&lt;p>No container port is published on the Mac&amp;rsquo;s LAN interface, and nothing is forwarded on the router, a FRITZ!Box in my case, which could not forward IPv4 anyway because my line is DS-Lite.
The FRITZ!Box reserves a fixed IP address for the Mac, &lt;code>192.168.178.65&lt;/code>.
Gitea&amp;rsquo;s data, including its PostgreSQL database, lives in OrbStack&amp;rsquo;s named volumes, which Time Machine does not back up, so every night a launchd job writes a consistent backup into a folder that Time Machine does back up.
healthchecks.io raises an alarm when that backup or an uptime check fails.&lt;/p>
&lt;p>This is my hardware:&lt;/p>
&lt;ul>
&lt;li>&lt;strong>Apple Mac mini M4 Pro&lt;/strong> with a 12-core CPU, 64 GB of unified memory and the 512 GB internal SSD, which holds macOS, OrbStack&amp;rsquo;s data and the backups.&lt;/li>
&lt;li>&lt;strong>Samsung T7 Portable SSD 2 TB&lt;/strong> as the Time Machine disk.&lt;/li>
&lt;li>&lt;strong>Ethernet cable&lt;/strong> to the FRITZ!Box.
Wake for network access and the SSH unlock after a restart are most reliable on a wired connection.&lt;/li>
&lt;li>&lt;strong>A MacBook&lt;/strong> for the SSH sessions; any computer with SSH works just as well.&lt;/li>
&lt;/ul>
&lt;p>I previously ran Gitea on a university server behind a &lt;a href="https://docs.linuxserver.io/general/swag/" target="_blank" rel="noopener">SWAG&lt;/a> reverse proxy with Let&amp;rsquo;s Encrypt certificates.
This time I start with an empty instance: a script creates the mirrors again in minutes, and my personal projects get pushed from their local clones.
My guide &lt;a href="https://mutschler.dev/linux/wyse-ubuntu-nextcloud-aio/">Dell Wyse 5070 Thin Client: Ubuntu Server 26.04 LTS, BTRFS and Nextcloud AIO with a Tailscale sidecar&lt;/a> uses the same sidecar pattern for Nextcloud.
The compose file, the configuration and the scripts are in the &lt;a href="https://github.com/wmutschl/scripts/tree/main/Apple-Mac-mini-M4-Pro" target="_blank" rel="noopener">Apple-Mac-mini-M4-Pro folder of my scripts repository&lt;/a>, next to the shared &lt;a href="https://github.com/wmutschl/scripts/tree/main/Tailscale" target="_blank" rel="noopener">Tailscale folder&lt;/a> with the serve configurations.
The &lt;a href="https://github.com/wmutschl/scripts#apple-mac-mini-m4-pro" target="_blank" rel="noopener">scripts README&lt;/a> lists every file and its purpose.
Every command works in fish, my login shell, as well as in zsh and bash.&lt;/p>
&lt;div class="alert alert-note">
&lt;div>
&lt;p>I wrote this guide for macOS 27, OrbStack 2.2.5, Gitea 28.4.0, the Gitea runner 6.0.0, PostgreSQL 18 and Tailscale 1.104.7.
Two changes make older guides and forum posts misleading:&lt;/p>
&lt;ul>
&lt;li>&lt;strong>Gitea dropped the &lt;code>1.&lt;/code> from its version numbers&lt;/strong> after 1.27.3: 28.0.0 is what would have been 1.28.
The Docker tags &lt;code>1-rootless&lt;/code> and &lt;code>1.27-rootless&lt;/code> stay frozen at 1.27.3.
Gitea 28 also removed &lt;code>[server] DOMAIN&lt;/code>; the domain is now simply the host of &lt;code>ROOT_URL&lt;/code>.&lt;/li>
&lt;li>&lt;strong>act_runner is now called the Gitea runner&lt;/strong>: binary &lt;code>gitea-runner&lt;/code>, image &lt;code>docker.gitea.com/runner&lt;/code>, Homebrew formula &lt;code>gitea-runner&lt;/code>.
The Docker Hub image &lt;code>gitea/act_runner&lt;/code> stopped at 0.6.1.
Configuration keys and &lt;code>GITEA_*&lt;/code> variables kept their names.&lt;/li>
&lt;/ul>
&lt;/div>
&lt;/div>
&lt;div class="alert alert-warning">
&lt;div>
&lt;strong>OrbStack is free only for personal use.&lt;/strong>
Using it for a company, a university or a non-profit organization needs a paid license; see &lt;a href="https://orbstack.dev/pricing" target="_blank" rel="noopener">OrbStack&amp;rsquo;s pricing&lt;/a>.
Check which applies to your Mac before you build on it.
&lt;/div>
&lt;/div>
&lt;h2 id="1-the-intended-layout">1 The intended layout&lt;/h2>
&lt;table>
&lt;thead>
&lt;tr>
&lt;th>Component&lt;/th>
&lt;th>Location / decision&lt;/th>
&lt;/tr>
&lt;/thead>
&lt;tbody>
&lt;tr>
&lt;td>macOS&lt;/td>
&lt;td>FileVault on; after a restart I unlock the disk over SSH and log in through Screen Sharing (&lt;a href="#22-filevault-restarts-and-remote-access">section 2.2&lt;/a>). OrbStack and the launchd jobs run in my logged-in session&lt;/td>
&lt;/tr>
&lt;tr>
&lt;td>Scripts repository&lt;/td>
&lt;td>Cloned to &lt;code>~/scripts&lt;/code>, not under &lt;code>~/Documents&lt;/code>: macOS keeps launchd jobs out of &lt;code>~/Documents&lt;/code>, &lt;code>~/Desktop&lt;/code> and &lt;code>~/Downloads&lt;/code>. The compose file and &lt;code>.env&lt;/code> are in &lt;code>Apple-Mac-mini-M4-Pro/&lt;/code>, the serve configurations in &lt;code>Tailscale/&lt;/code>&lt;/td>
&lt;/tr>
&lt;tr>
&lt;td>Docker engine&lt;/td>
&lt;td>OrbStack, started at login. Named volumes live in its disk image, which Time Machine excludes&lt;/td>
&lt;/tr>
&lt;tr>
&lt;td>Gitea&lt;/td>
&lt;td>&lt;code>gitea&lt;/code> (rootless image 28.4.0) with &lt;code>gitea-db&lt;/code> (PostgreSQL 18); volumes &lt;code>gitea-data&lt;/code> (repositories, LFS, attachments, packages, Actions logs, SSH host keys), &lt;code>gitea-config&lt;/code> (&lt;code>app.ini&lt;/code>) and &lt;code>gitea-db-data&lt;/code>&lt;/td>
&lt;/tr>
&lt;tr>
&lt;td>CI&lt;/td>
&lt;td>&lt;code>gitea-runner&lt;/code> registered for my user only. Its jobs run in containers on the network &lt;code>gitea-ci&lt;/code>, without a Docker socket. Optional: a runner directly on macOS (&lt;a href="#84-optional-a-runner-directly-on-macos">section 8.4&lt;/a>)&lt;/td>
&lt;/tr>
&lt;tr>
&lt;td>Tailnet access to Gitea&lt;/td>
&lt;td>&lt;code>https://gitea.tailnet-name.ts.net&lt;/code> (443) and &lt;code>git@gitea.tailnet-name.ts.net&lt;/code> (SSH on 22) → sidecar &lt;code>gitea-tailscale&lt;/code>, tag &lt;code>tag:gitea&lt;/code>, tailnet only&lt;/td>
&lt;/tr>
&lt;tr>
&lt;td>modCraft&lt;/td>
&lt;td>Its own stack in &lt;code>~/modCraft/website&lt;/code>, Caddy on &lt;code>127.0.0.1:8080&lt;/code> only. Public through Funnel: &lt;code>https://modcraft.tailnet-name.ts.net&lt;/code> → sidecar &lt;code>modcraft-tailscale&lt;/code> (tag &lt;code>tag:container&lt;/code>) → &lt;code>host.docker.internal:8080&lt;/code>&lt;/td>
&lt;/tr>
&lt;tr>
&lt;td>Backups&lt;/td>
&lt;td>Daily at 02:30: &lt;code>pg_dump&lt;/code> plus &lt;code>gitea dump&lt;/code> into &lt;code>~/Backups/gitea&lt;/code>, which Time Machine copies to the T7. modCraft exports its statistics daily at 03:30&lt;/td>
&lt;/tr>
&lt;tr>
&lt;td>Monitoring&lt;/td>
&lt;td>healthchecks.io: the backup and a five-minute uptime check through the tailnet&lt;/td>
&lt;/tr>
&lt;tr>
&lt;td>Tailnet nodes&lt;/td>
&lt;td>The Mac itself, &lt;code>mac-mini&lt;/code> (Tailscale app, my user); the nodes &lt;code>gitea&lt;/code> (&lt;code>tag:gitea&lt;/code>) and &lt;code>modcraft&lt;/code> (&lt;code>tag:container&lt;/code>) of the sidecar containers &lt;code>gitea-tailscale&lt;/code> and &lt;code>modcraft-tailscale&lt;/code>&lt;/td>
&lt;/tr>
&lt;tr>
&lt;td>Listening on the LAN&lt;/td>
&lt;td>SSH and Screen Sharing of macOS. No container port&lt;/td>
&lt;/tr>
&lt;/tbody>
&lt;/table>
&lt;p>&lt;code>tailnet-name.ts.net&lt;/code> stands for the DNS name of your tailnet throughout this guide (&lt;a href="#4-tailscale-tags-oauth-client-and-node-names">section 4&lt;/a>).
Each sidecar is a node of its own with its own name and certificate, so Gitea and modCraft keep their addresses no matter what happens to the Mac&amp;rsquo;s own Tailscale client.
Gitea does not share its sidecar&amp;rsquo;s network namespace: the sidecar reaches it over a Docker network, so only the ports in the serve configuration answer on the tailnet.&lt;/p>
&lt;h2 id="2-prepare-macos-for-unattended-operation">2 Prepare macOS for unattended operation&lt;/h2>
&lt;h3 id="21-energy-settings">2.1 Energy settings&lt;/h3>
&lt;p>The Mac must never sleep, and it should start again after a power failure.
In &lt;strong>System Settings → Energy&lt;/strong>, switch on &lt;strong>Prevent automatic sleeping when the display is off&lt;/strong>, &lt;strong>Wake for network access&lt;/strong> and &lt;strong>Start up automatically after a power failure&lt;/strong>, and switch off &lt;strong>Enable Power Nap&lt;/strong>.
Depending on the model, &lt;strong>Start up automatically after a power failure&lt;/strong> is called &lt;strong>Start up when power is connected: After power failure&lt;/strong>.
On the command line, &lt;code>pmset&lt;/code> changes the same settings:&lt;/p>
&lt;div class="highlight">&lt;pre tabindex="0" class="chroma">&lt;code class="language-sh" data-lang="sh">&lt;span class="line">&lt;span class="cl">sudo pmset -a sleep &lt;span class="m">0&lt;/span> disksleep &lt;span class="m">0&lt;/span> womp &lt;span class="m">1&lt;/span> autorestart &lt;span class="m">1&lt;/span> powernap &lt;span class="m">0&lt;/span>
&lt;/span>&lt;/span>&lt;span class="line">&lt;span class="cl">pmset -g custom
&lt;/span>&lt;/span>&lt;/code>&lt;/pre>&lt;/div>&lt;p>In the output, &lt;code>sleep&lt;/code>, &lt;code>disksleep&lt;/code> and &lt;code>powernap&lt;/code> must show 0, &lt;code>womp&lt;/code> and &lt;code>autorestart&lt;/code> 1.
The display may still turn off; that does not matter.&lt;/p>
&lt;div class="alert alert-note">
&lt;div>
&lt;strong>Lock the screen, never log out.&lt;/strong>
OrbStack, the Tailscale app and my launchd jobs belong to my login session.
Logging out stops all of them, while a locked screen keeps everything running.
&lt;/div>
&lt;/div>
&lt;h3 id="22-filevault-restarts-and-remote-access">2.2 FileVault, restarts and remote access&lt;/h3>
&lt;p>FileVault stays on: the Mac&amp;rsquo;s SSD holds the Gitea backups, SSH keys and access tokens.
The price is that macOS cannot log in automatically while FileVault is on, and none of my services runs before somebody logs in.
OrbStack in particular is an ordinary app that starts at login; it cannot run as a system service.
So after every restart, whether a power failure, a crash or a macOS update, two things have to happen before Gitea and modCraft are back:&lt;/p>
&lt;ol>
&lt;li>&lt;strong>Unlock the disk over SSH.&lt;/strong>
Since macOS 26 Tahoe, a Mac with Apple silicon accepts an SSH connection at the FileVault screen when &lt;strong>Remote Login&lt;/strong> is on, and unlocks the disk with an account&amp;rsquo;s password; see Apple&amp;rsquo;s &lt;a href="https://support.apple.com/guide/security/sec8447f5049/web" target="_blank" rel="noopener">Managing FileVault in macOS&lt;/a> and &lt;code>man 7 apple_ssh_and_filevault&lt;/code>.
This is the macOS counterpart of the SSH unlock in the initrd of my &lt;a href="https://mutschler.dev/linux/wyse-ubuntu-nextcloud-aio/#57-unlocking-the-system-disk-over-ssh">Wyse&lt;/a>.&lt;/li>
&lt;li>&lt;strong>Log in through Screen Sharing.&lt;/strong>
The unlock does not log anybody in; the Mac goes on to the login window.
OrbStack, the Tailscale app and the launchd jobs start only with a real login.&lt;/li>
&lt;/ol>
&lt;p>Turn on &lt;strong>System Settings → General → Sharing → Remote Login&lt;/strong> and &lt;strong>Screen Sharing&lt;/strong>.
Note the details of the unlock phase:&lt;/p>
&lt;ul>
&lt;li>&lt;strong>Password only.&lt;/strong>
The keys in &lt;code>~/.ssh/authorized_keys&lt;/code> and the system&amp;rsquo;s host keys are still encrypted, so the pre-boot SSH server presents a host key of its own and accepts only the password of an account that can unlock FileVault (&lt;code>sudo fdesetup list&lt;/code>).&lt;/li>
&lt;li>&lt;strong>LAN only.&lt;/strong>
The Mac&amp;rsquo;s own Tailscale app is not running yet, so the Mac is reachable only on &lt;code>192.168.178.65&lt;/code>.
From outside I hop through the Wyse, which is at home and on my tailnet.&lt;/li>
&lt;li>&lt;strong>Ethernet.&lt;/strong>
The unlock over Wi-Fi works only from macOS 26.5 on, and Ethernet is the safer bet anyway.&lt;/li>
&lt;/ul>
&lt;p>On the &lt;strong>MacBook&lt;/strong>, four host aliases in &lt;code>~/.ssh/config&lt;/code> cover this.
&lt;code>dell-wyse&lt;/code> is the Wyse&amp;rsquo;s tailnet name (&lt;a href="https://mutschler.dev/linux/wyse-ubuntu-nextcloud-aio/#82-on-the-wyse">section 8.2 of its guide&lt;/a>); at home, the hop through it costs nothing:&lt;/p>
&lt;div class="highlight">&lt;pre tabindex="0" class="chroma">&lt;code class="language-fallback" data-lang="fallback">&lt;span class="line">&lt;span class="cl">Host dell-wyse
&lt;/span>&lt;/span>&lt;span class="line">&lt;span class="cl"> HostName dell-wyse
&lt;/span>&lt;/span>&lt;span class="line">&lt;span class="cl"> User wmutschl
&lt;/span>&lt;/span>&lt;span class="line">&lt;span class="cl"> IdentityFile ~/.ssh/id_ed25519
&lt;/span>&lt;/span>&lt;span class="line">&lt;span class="cl"> IdentitiesOnly yes
&lt;/span>&lt;/span>&lt;span class="line">&lt;span class="cl">
&lt;/span>&lt;/span>&lt;span class="line">&lt;span class="cl">Host mac-mini
&lt;/span>&lt;/span>&lt;span class="line">&lt;span class="cl"> HostName mac-mini
&lt;/span>&lt;/span>&lt;span class="line">&lt;span class="cl"> User wmutschl
&lt;/span>&lt;/span>&lt;span class="line">&lt;span class="cl"> IdentityFile ~/.ssh/id_ed25519
&lt;/span>&lt;/span>&lt;span class="line">&lt;span class="cl"> IdentitiesOnly yes
&lt;/span>&lt;/span>&lt;span class="line">&lt;span class="cl">
&lt;/span>&lt;/span>&lt;span class="line">&lt;span class="cl">Host mac-mini-lan
&lt;/span>&lt;/span>&lt;span class="line">&lt;span class="cl"> HostName 192.168.178.65
&lt;/span>&lt;/span>&lt;span class="line">&lt;span class="cl"> User wmutschl
&lt;/span>&lt;/span>&lt;span class="line">&lt;span class="cl"> ProxyJump dell-wyse
&lt;/span>&lt;/span>&lt;span class="line">&lt;span class="cl"> IdentityFile ~/.ssh/id_ed25519
&lt;/span>&lt;/span>&lt;span class="line">&lt;span class="cl"> IdentitiesOnly yes
&lt;/span>&lt;/span>&lt;span class="line">&lt;span class="cl">
&lt;/span>&lt;/span>&lt;span class="line">&lt;span class="cl"># FileVault unlock after a restart: its own host key, password only
&lt;/span>&lt;/span>&lt;span class="line">&lt;span class="cl">Host mac-mini-unlock
&lt;/span>&lt;/span>&lt;span class="line">&lt;span class="cl"> HostName 192.168.178.65
&lt;/span>&lt;/span>&lt;span class="line">&lt;span class="cl"> User wmutschl
&lt;/span>&lt;/span>&lt;span class="line">&lt;span class="cl"> ProxyJump dell-wyse
&lt;/span>&lt;/span>&lt;span class="line">&lt;span class="cl"> HostKeyAlias mac-mini-unlock
&lt;/span>&lt;/span>&lt;span class="line">&lt;span class="cl"> PubkeyAuthentication no
&lt;/span>&lt;/span>&lt;/code>&lt;/pre>&lt;/div>&lt;p>Copy your key to the Mac once.
At the first connection, compare the host key&amp;rsquo;s fingerprint with the one that &lt;code>ssh-keygen -lf /etc/ssh/ssh_host_ed25519_key.pub&lt;/code> prints on the Mac mini itself:&lt;/p>
&lt;div class="highlight">&lt;pre tabindex="0" class="chroma">&lt;code class="language-sh" data-lang="sh">&lt;span class="line">&lt;span class="cl">ssh-copy-id mac-mini-lan
&lt;/span>&lt;/span>&lt;span class="line">&lt;span class="cl">ssh mac-mini-lan
&lt;/span>&lt;/span>&lt;/code>&lt;/pre>&lt;/div>&lt;p>If you turn off password logins for the normal SSH server in &lt;code>/etc/ssh/sshd_config.d/&lt;/code>, the unlock still accepts the password: the pre-boot SSH server does not read the configuration on the encrypted volume (&lt;code>man 7 apple_ssh_and_filevault&lt;/code>).
Test it once before you rely on it.&lt;/p>
&lt;p>After a restart, unlock, wait a minute, then open Screen Sharing through an SSH tunnel and log in at the login window:&lt;/p>
&lt;div class="highlight">&lt;pre tabindex="0" class="chroma">&lt;code class="language-sh" data-lang="sh">&lt;span class="line">&lt;span class="cl">ssh mac-mini-unlock
&lt;/span>&lt;/span>&lt;span class="line">&lt;span class="cl">&lt;span class="c1"># asks for the macOS password of wmutschl, unlocks the disk and drops the connection&lt;/span>
&lt;/span>&lt;/span>&lt;span class="line">&lt;span class="cl">
&lt;/span>&lt;/span>&lt;span class="line">&lt;span class="cl">ssh -N -L 5901:localhost:5900 mac-mini-lan &lt;span class="p">&amp;amp;&lt;/span>
&lt;/span>&lt;/span>&lt;span class="line">&lt;span class="cl">open vnc://localhost:5901
&lt;/span>&lt;/span>&lt;/code>&lt;/pre>&lt;/div>&lt;p>The first unlock asks you to accept the pre-boot host key, which differs from the normal one; &lt;code>HostKeyAlias&lt;/code> keeps the two apart in &lt;code>known_hosts&lt;/code>.
The tunnel uses local port 5901, because macOS&amp;rsquo;s Screen Sharing refuses to connect to port 5900 of the computer it runs on.
At home, &lt;code>open vnc://192.168.178.65&lt;/code> does the same without a tunnel.
After the login, lock the screen, and run &lt;code>kill %1&lt;/code> in the MacBook&amp;rsquo;s terminal to close the tunnel.&lt;/p>
&lt;div class="alert alert-note">
&lt;div>
&lt;strong>Planned restarts.&lt;/strong>
&lt;code>sudo fdesetup authrestart&lt;/code> restarts without the FileVault unlock, but the Mac still waits at the login window afterwards.
Updates of macOS sometimes log the user back in by themselves; otherwise the Screen Sharing login above is all it takes.
The uptime check in &lt;a href="#101-healthchecksio-and-the-hosts-settings">section 10.1&lt;/a> tells you when the Mac is waiting for one of the two steps.
&lt;/div>
&lt;/div>
&lt;h3 id="23-tailscale-on-the-mac-and-the-scripts-repository">2.3 Tailscale on the Mac and the scripts repository&lt;/h3>
&lt;p>The Mac itself is in my tailnet as &lt;code>mac-mini&lt;/code>, through the &lt;a href="https://tailscale.com/kb/1065/macos-variants" target="_blank" rel="noopener">standalone Tailscale app&lt;/a> and with &lt;strong>Use Tailscale DNS settings&lt;/strong> on.
The sidecars do not need it, as they are tailnet nodes of their own.
But the uptime check, the optional macOS runner and SSH from outside go through it.
Three things matter for a server:&lt;/p>
&lt;ul>
&lt;li>In the Tailscale admin console, open the Mac&amp;rsquo;s machine, choose &lt;strong>Edit machine name&lt;/strong>, and set it to &lt;code>mac-mini&lt;/code> with &lt;strong>Auto-generate from OS hostname&lt;/strong> unticked, unless it already has that name.
The SSH aliases above use that name.
In the same menu, choose &lt;strong>Disable key expiry&lt;/strong>.
Otherwise the Mac&amp;rsquo;s key expires after 180 days and the Mac silently drops out of the tailnet; tagged nodes like the sidecars never expire.&lt;/li>
&lt;li>Run Tailscale &lt;strong>1.104.6 or later&lt;/strong> on the Mac: it fixes MagicDNS resolver selection during network changes.&lt;/li>
&lt;li>Do not use an exit node on this Mac: its routes break OrbStack&amp;rsquo;s networks.&lt;/li>
&lt;/ul>
&lt;p>Install &lt;a href="https://brew.sh" target="_blank" rel="noopener">Homebrew&lt;/a> if it is not there yet, and clone the scripts repository to &lt;code>~/scripts&lt;/code>:&lt;/p>
&lt;div class="highlight">&lt;pre tabindex="0" class="chroma">&lt;code class="language-sh" data-lang="sh">&lt;span class="line">&lt;span class="cl">git clone https://github.com/wmutschl/scripts.git ~/scripts
&lt;/span>&lt;/span>&lt;/code>&lt;/pre>&lt;/div>&lt;p>&lt;code>~/scripts&lt;/code> is not a privacy-protected folder, so the launchd jobs in &lt;a href="#102-install-the-launchd-jobs">section 10.2&lt;/a> may run scripts from it.
Under &lt;code>~/Documents&lt;/code> they would be blocked silently.&lt;/p>
&lt;h2 id="3-orbstack">3 OrbStack&lt;/h2>
&lt;p>Install Rosetta 2 first, which OrbStack uses to run &lt;code>linux/amd64&lt;/code> images.
Without it, a later start of OrbStack over SSH hangs, because the Rosetta prompt cannot appear there.
Then install OrbStack and start it once:&lt;/p>
&lt;div class="highlight">&lt;pre tabindex="0" class="chroma">&lt;code class="language-sh" data-lang="sh">&lt;span class="line">&lt;span class="cl">sudo softwareupdate --install-rosetta --agree-to-license
&lt;/span>&lt;/span>&lt;span class="line">&lt;span class="cl">brew install --cask orbstack
&lt;/span>&lt;/span>&lt;span class="line">&lt;span class="cl">open -a OrbStack
&lt;/span>&lt;/span>&lt;/code>&lt;/pre>&lt;/div>&lt;p>Go through OrbStack&amp;rsquo;s welcome screens: choose &lt;strong>Docker&lt;/strong>, and allow the admin privileges it asks for, so it can link &lt;code>/var/run/docker.sock&lt;/code> and the &lt;code>docker&lt;/code> command.
Answer &lt;strong>Allow&lt;/strong> when macOS asks whether OrbStack may find devices on the local network.
Without that permission, containers cannot reach &lt;code>host.docker.internal&lt;/code>, which modCraft&amp;rsquo;s sidecar needs.
In OrbStack&amp;rsquo;s settings:&lt;/p>
&lt;ul>
&lt;li>&lt;strong>Start at login:&lt;/strong> on.&lt;/li>
&lt;li>&lt;strong>Keep running when app is quit:&lt;/strong> on.&lt;/li>
&lt;li>&lt;strong>Pause containers while Mac is sleeping:&lt;/strong> off.
The Mac never sleeps, but this keeps the services running if it ever does.&lt;/li>
&lt;li>&lt;strong>Automatically download updates:&lt;/strong> off.
An update restarts OrbStack&amp;rsquo;s VM, and with it every container, and in a reported case a stack stayed down afterwards (&lt;a href="https://github.com/orbstack/orbstack/issues/2481" target="_blank" rel="noopener">#2481&lt;/a>).
I update by hand in a quiet moment (&lt;a href="#106-updates">section 10.6&lt;/a>).&lt;/li>
&lt;li>&lt;strong>Memory limit:&lt;/strong> OrbStack lets its VM use up to a quarter of the RAM by default, 16 GiB here.
I raise it to 24 GiB for CI jobs; it is a limit, not a reservation, and unused memory goes back to macOS.&lt;/li>
&lt;/ul>
&lt;p>Under &lt;strong>System Settings → General → Login Items &amp;amp; Extensions&lt;/strong>, allow OrbStack to run in the background.
Set the memory limit, and check that OrbStack keeps its data out of Time Machine:&lt;/p>
&lt;div class="highlight">&lt;pre tabindex="0" class="chroma">&lt;code class="language-sh" data-lang="sh">&lt;span class="line">&lt;span class="cl">orb config &lt;span class="nb">set&lt;/span> memory_mib &lt;span class="m">24576&lt;/span>
&lt;/span>&lt;/span>&lt;span class="line">&lt;span class="cl">orb config get data_allow_backup
&lt;/span>&lt;/span>&lt;span class="line">&lt;span class="cl">&lt;span class="c1"># false&lt;/span>
&lt;/span>&lt;/span>&lt;/code>&lt;/pre>&lt;/div>&lt;p>&lt;code>data_allow_backup&lt;/code> false means that OrbStack&amp;rsquo;s disk image, and with it every named volume, stays out of Time Machine.
Leave it like that: a copy of one huge, constantly changing image file is no backup, and restores of it are reported to fail.
The application-level backup in &lt;a href="#10-backups-monitoring-and-ongoing-care">section 10&lt;/a> is the backup.&lt;/p>
&lt;p>Docker&amp;rsquo;s default log driver in OrbStack is &lt;code>json-file&lt;/code> without rotation, and the logs live inside the same disk image.
Switch the default to the &lt;code>local&lt;/code> driver, which rotates by itself, as on the Wyse.
Add this key to &lt;code>~/.orbstack/config/docker.json&lt;/code>, next to any keys that are already there:&lt;/p>
&lt;div class="highlight">&lt;pre tabindex="0" class="chroma">&lt;code class="language-json" data-lang="json">&lt;span class="line">&lt;span class="cl">&lt;span class="p">{&lt;/span>
&lt;/span>&lt;/span>&lt;span class="line">&lt;span class="cl"> &lt;span class="nt">&amp;#34;log-driver&amp;#34;&lt;/span>&lt;span class="p">:&lt;/span> &lt;span class="s2">&amp;#34;local&amp;#34;&lt;/span>
&lt;/span>&lt;/span>&lt;span class="line">&lt;span class="cl">&lt;span class="p">}&lt;/span>
&lt;/span>&lt;/span>&lt;/code>&lt;/pre>&lt;/div>&lt;p>Then restart OrbStack as a whole, which also applies the memory limit, and check the driver:&lt;/p>
&lt;div class="highlight">&lt;pre tabindex="0" class="chroma">&lt;code class="language-sh" data-lang="sh">&lt;span class="line">&lt;span class="cl">nano ~/.orbstack/config/docker.json
&lt;/span>&lt;/span>&lt;span class="line">&lt;span class="cl">orb stop &lt;span class="o">&amp;amp;&amp;amp;&lt;/span> orb start
&lt;/span>&lt;/span>&lt;span class="line">&lt;span class="cl">docker info --format &lt;span class="s1">&amp;#39;{{.LoggingDriver}}&amp;#39;&lt;/span>
&lt;/span>&lt;/span>&lt;span class="line">&lt;span class="cl">&lt;span class="c1"># local&lt;/span>
&lt;/span>&lt;/span>&lt;/code>&lt;/pre>&lt;/div>&lt;p>Only containers created afterwards use it; the stacks in this guide are all created later.&lt;/p>
&lt;div class="alert alert-note">
&lt;div>
&lt;strong>OrbStack sometimes stays stopped after a login.&lt;/strong>
On macOS 27, OrbStack 2.2.4 and 2.2.5 sometimes fail at the automatic start after a login and then stay stopped (&lt;a href="https://github.com/orbstack/orbstack/issues/2752" target="_blank" rel="noopener">#2752&lt;/a>, &lt;a href="https://github.com/orbstack/orbstack/issues/2773" target="_blank" rel="noopener">#2773&lt;/a>).
The uptime check (&lt;code>mac-mini-alive&lt;/code>, &lt;a href="#101-healthchecksio-and-the-hosts-settings">section 10.1&lt;/a>) runs &lt;code>orb start&lt;/code> when it finds OrbStack stopped, and reports it; &lt;a href="#106-updates">section 10.6&lt;/a> shows how to keep it from doing that during maintenance.
If OrbStack keeps failing to start, the reported workaround is &lt;code>orb config set network_bridge false&lt;/code>, followed by &lt;code>orb stop &amp;amp;&amp;amp; orb start&lt;/code>.
It costs the direct access from macOS to container IPs and &lt;code>*.orb.local&lt;/code> names, which nothing here needs, but &lt;code>host.docker.internal&lt;/code> can then stall, and modCraft&amp;rsquo;s sidecar relies on it.
&lt;/div>
&lt;/div>
&lt;h2 id="4-tailscale-tags-oauth-client-and-node-names">4 Tailscale: tags, OAuth client and node names&lt;/h2>
&lt;p>Gitea&amp;rsquo;s sidecar gets a tag of its own, &lt;code>tag:gitea&lt;/code>, without the Funnel attribute.
Tailscale then refuses to publish Gitea on the internet, even if a serve configuration asked for it.
modCraft&amp;rsquo;s sidecar uses &lt;code>tag:container&lt;/code>, which has the Funnel attribute and which modCraft&amp;rsquo;s earlier sidecar on this Mac already carried.
Tagged nodes have no key expiry.
See &lt;a href="https://tailscale.com/docs/features/containers/docker" target="_blank" rel="noopener">Tailscale in Docker&lt;/a> for more on the sidecar pattern, and its &lt;a href="https://tailscale.com/docs/features/containers/docker/docker-params" target="_blank" rel="noopener">parameters&lt;/a> for the environment variables that the compose file uses.&lt;/p>
&lt;ol>
&lt;li>
&lt;p>&lt;strong>DNS:&lt;/strong> in the &lt;a href="https://console.tailscale.com" target="_blank" rel="noopener">admin console&lt;/a>, note the DNS name of your tailnet, &lt;code>tailnet-name.ts.net&lt;/code> in this guide, and check that MagicDNS and HTTPS Certificates are enabled.
Without HTTPS certificates, the sidecar skips its whole serve configuration, including the SSH forward.
The certificates are public in the Certificate Transparency logs, so the names &lt;code>gitea.tailnet-name.ts.net&lt;/code> and &lt;code>modcraft.tailnet-name.ts.net&lt;/code> become public, although only modCraft answers from the internet.&lt;/p>
&lt;/li>
&lt;li>
&lt;p>&lt;strong>Access controls:&lt;/strong> add the tags and the Funnel attribute next to any existing entries that other machines depend on:&lt;/p>
&lt;div class="highlight">&lt;pre tabindex="0" class="chroma">&lt;code class="language-json" data-lang="json">&lt;span class="line">&lt;span class="cl">&lt;span class="s2">&amp;#34;tagOwners&amp;#34;&lt;/span>&lt;span class="err">:&lt;/span> &lt;span class="p">{&lt;/span>
&lt;/span>&lt;/span>&lt;span class="line">&lt;span class="cl"> &lt;span class="nt">&amp;#34;tag:container&amp;#34;&lt;/span>&lt;span class="p">:&lt;/span> &lt;span class="p">[&lt;/span>&lt;span class="s2">&amp;#34;autogroup:admin&amp;#34;&lt;/span>&lt;span class="p">],&lt;/span>
&lt;/span>&lt;/span>&lt;span class="line">&lt;span class="cl"> &lt;span class="nt">&amp;#34;tag:gitea&amp;#34;&lt;/span>&lt;span class="p">:&lt;/span> &lt;span class="p">[&lt;/span>&lt;span class="s2">&amp;#34;autogroup:admin&amp;#34;&lt;/span>&lt;span class="p">],&lt;/span>
&lt;/span>&lt;/span>&lt;span class="line">&lt;span class="cl">&lt;span class="p">}&lt;/span>&lt;span class="err">,&lt;/span>
&lt;/span>&lt;/span>&lt;span class="line">&lt;span class="cl">&lt;span class="s2">&amp;#34;nodeAttrs&amp;#34;&lt;/span>&lt;span class="err">:&lt;/span> &lt;span class="p">[&lt;/span>
&lt;/span>&lt;/span>&lt;span class="line">&lt;span class="cl"> &lt;span class="p">{&lt;/span>&lt;span class="nt">&amp;#34;target&amp;#34;&lt;/span>&lt;span class="p">:&lt;/span> &lt;span class="p">[&lt;/span>&lt;span class="s2">&amp;#34;tag:container&amp;#34;&lt;/span>&lt;span class="p">],&lt;/span> &lt;span class="nt">&amp;#34;attr&amp;#34;&lt;/span>&lt;span class="p">:&lt;/span> &lt;span class="p">[&lt;/span>&lt;span class="s2">&amp;#34;funnel&amp;#34;&lt;/span>&lt;span class="p">]},&lt;/span>
&lt;/span>&lt;/span>&lt;span class="line">&lt;span class="cl">&lt;span class="p">]&lt;/span>&lt;span class="err">,&lt;/span>
&lt;/span>&lt;/span>&lt;/code>&lt;/pre>&lt;/div>&lt;/li>
&lt;li>
&lt;p>&lt;strong>Optional, narrower access:&lt;/strong> with the default allow-all policy, every device in the tailnet reaches every port of both sidecars, and the sidecars themselves reach every device.
Gitea&amp;rsquo;s login and modCraft&amp;rsquo;s password still protect them.
These grants allow only HTTPS and SSH to Gitea, and only HTTPS to modCraft:&lt;/p>
&lt;div class="highlight">&lt;pre tabindex="0" class="chroma">&lt;code class="language-json" data-lang="json">&lt;span class="line">&lt;span class="cl">&lt;span class="s2">&amp;#34;grants&amp;#34;&lt;/span>&lt;span class="err">:&lt;/span> &lt;span class="p">[&lt;/span>
&lt;/span>&lt;/span>&lt;span class="line">&lt;span class="cl"> &lt;span class="p">{&lt;/span>&lt;span class="nt">&amp;#34;src&amp;#34;&lt;/span>&lt;span class="p">:&lt;/span> &lt;span class="p">[&lt;/span>&lt;span class="s2">&amp;#34;autogroup:member&amp;#34;&lt;/span>&lt;span class="p">],&lt;/span> &lt;span class="nt">&amp;#34;dst&amp;#34;&lt;/span>&lt;span class="p">:&lt;/span> &lt;span class="p">[&lt;/span>&lt;span class="s2">&amp;#34;tag:gitea&amp;#34;&lt;/span>&lt;span class="p">],&lt;/span> &lt;span class="nt">&amp;#34;ip&amp;#34;&lt;/span>&lt;span class="p">:&lt;/span> &lt;span class="p">[&lt;/span>&lt;span class="s2">&amp;#34;tcp:443&amp;#34;&lt;/span>&lt;span class="p">,&lt;/span> &lt;span class="s2">&amp;#34;tcp:22&amp;#34;&lt;/span>&lt;span class="p">]},&lt;/span>
&lt;/span>&lt;/span>&lt;span class="line">&lt;span class="cl"> &lt;span class="p">{&lt;/span>&lt;span class="nt">&amp;#34;src&amp;#34;&lt;/span>&lt;span class="p">:&lt;/span> &lt;span class="p">[&lt;/span>&lt;span class="s2">&amp;#34;autogroup:member&amp;#34;&lt;/span>&lt;span class="p">],&lt;/span> &lt;span class="nt">&amp;#34;dst&amp;#34;&lt;/span>&lt;span class="p">:&lt;/span> &lt;span class="p">[&lt;/span>&lt;span class="s2">&amp;#34;tag:container&amp;#34;&lt;/span>&lt;span class="p">],&lt;/span> &lt;span class="nt">&amp;#34;ip&amp;#34;&lt;/span>&lt;span class="p">:&lt;/span> &lt;span class="p">[&lt;/span>&lt;span class="s2">&amp;#34;tcp:443&amp;#34;&lt;/span>&lt;span class="p">]},&lt;/span>
&lt;/span>&lt;/span>&lt;span class="line">&lt;span class="cl">&lt;span class="p">]&lt;/span>&lt;span class="err">,&lt;/span>
&lt;/span>&lt;/span>&lt;/code>&lt;/pre>&lt;/div>&lt;p>As on the Wyse, they narrow anything only once the broad default rule that allows &lt;code>*&lt;/code> to reach &lt;code>*:*&lt;/code> is replaced by explicit rules for the rest of the tailnet.
Funnel traffic is not governed by grants.
Keep in mind that containers in OrbStack reach the tailnet through the Mac&amp;rsquo;s own Tailscale app, under my user&amp;rsquo;s identity: a CI job or modCraft&amp;rsquo;s Caddy reaches whatever my user may reach.&lt;/p>
&lt;/li>
&lt;li>
&lt;p>&lt;strong>OAuth client&lt;/strong> (under &lt;strong>Settings → Trust credentials&lt;/strong>): create a client for the Mac mini with only the scope &lt;strong>Auth Keys&lt;/strong> with write access, and the two tags &lt;code>tag:gitea&lt;/code> and &lt;code>tag:container&lt;/code>.
If device approval is enabled, append &lt;code>&amp;amp;preauthorized=true&lt;/code> to both &lt;code>TS_AUTHKEY&lt;/code> lines in the compose file; see &lt;a href="https://tailscale.com/docs/features/oauth-clients" target="_blank" rel="noopener">OAuth clients&lt;/a>.
Store the secret in your password manager.
The sidecars use it only for their first login: &lt;code>TS_AUTH_ONCE=true&lt;/code> keeps them from minting a new key at every restart.&lt;/p>
&lt;/li>
&lt;/ol>
&lt;p>&lt;strong>Node names.&lt;/strong> Each sidecar&amp;rsquo;s MagicDNS name is also its certificate&amp;rsquo;s name and, for Gitea, part of every clone URL.
If a node with the same name already exists in the admin console, even offline, Tailscale gives the new node a suffixed name such as &lt;code>gitea-1&lt;/code>, and the suffix stays even if the other node is renamed later.
That earlier &lt;code>modcraft&lt;/code> node is still listed, offline:&lt;/p>
&lt;ul>
&lt;li>If OrbStack on the Mac still has the volume &lt;code>modcraft-tailscale-data&lt;/code> (&lt;code>docker volume ls&lt;/code>), the new sidecar continues as that same node, and nothing needs to be done.&lt;/li>
&lt;li>If not, delete the old &lt;code>modcraft&lt;/code> machine in the admin console &lt;strong>before&lt;/strong> the sidecar first starts.
The same applies to &lt;code>gitea&lt;/code> if an old node of that name exists.&lt;/li>
&lt;/ul>
&lt;h2 id="5-configure-the-deployment">5 Configure the deployment&lt;/h2>
&lt;p>On the &lt;strong>Mac mini&lt;/strong>, create &lt;code>.env&lt;/code> from the template and generate Gitea&amp;rsquo;s secrets.
Generate them without &lt;code>docker run -t&lt;/code>, so they end without a carriage return:&lt;/p>
&lt;div class="highlight">&lt;pre tabindex="0" class="chroma">&lt;code class="language-sh" data-lang="sh">&lt;span class="line">&lt;span class="cl">&lt;span class="nb">cd&lt;/span> ~/scripts/Apple-Mac-mini-M4-Pro
&lt;/span>&lt;/span>&lt;span class="line">&lt;span class="cl">git pull
&lt;/span>&lt;/span>&lt;span class="line">&lt;span class="cl">cp mac-mini.env .env
&lt;/span>&lt;/span>&lt;span class="line">&lt;span class="cl">chmod &lt;span class="m">600&lt;/span> .env
&lt;/span>&lt;/span>&lt;span class="line">&lt;span class="cl">
&lt;/span>&lt;/span>&lt;span class="line">&lt;span class="cl">docker run --rm docker.gitea.com/gitea:28.4.0-rootless gitea generate secret SECRET_KEY
&lt;/span>&lt;/span>&lt;span class="line">&lt;span class="cl">docker run --rm docker.gitea.com/gitea:28.4.0-rootless gitea generate secret INTERNAL_TOKEN
&lt;/span>&lt;/span>&lt;span class="line">&lt;span class="cl">openssl rand -hex &lt;span class="m">24&lt;/span>
&lt;/span>&lt;/span>&lt;span class="line">&lt;span class="cl">nano .env
&lt;/span>&lt;/span>&lt;/code>&lt;/pre>&lt;/div>&lt;p>Fill in:&lt;/p>
&lt;ul>
&lt;li>&lt;code>TAILSCALE_OAUTH_KEY&lt;/code>: the OAuth secret from &lt;a href="#4-tailscale-tags-oauth-client-and-node-names">section 4&lt;/a>.&lt;/li>
&lt;li>&lt;code>GITEA_TAILSCALE_HOSTNAME&lt;/code> and &lt;code>MODCRAFT_TAILSCALE_HOSTNAME&lt;/code>: the node names the sidecars ask for, &lt;code>gitea&lt;/code> and &lt;code>modcraft&lt;/code>; keep them unless those names are taken (&lt;a href="#4-tailscale-tags-oauth-client-and-node-names">section 4&lt;/a>).&lt;/li>
&lt;li>&lt;code>GITEA_DOMAIN&lt;/code>: &lt;code>gitea.&lt;/code> followed by your tailnet&amp;rsquo;s DNS name.
It becomes Gitea&amp;rsquo;s &lt;code>ROOT_URL&lt;/code> and the host of every clone URL, so it must match the sidecar&amp;rsquo;s actual MagicDNS name (&lt;a href="#61-start-gitea-and-its-sidecar">section 6.1&lt;/a>).&lt;/li>
&lt;li>&lt;code>GITEA_DB_PASSWORD&lt;/code>: the output of &lt;code>openssl rand -hex 24&lt;/code>.&lt;/li>
&lt;li>&lt;code>GITEA_SECRET_KEY&lt;/code> and &lt;code>GITEA_INTERNAL_TOKEN&lt;/code>: the two generated secrets.
&lt;code>SECRET_KEY&lt;/code> encrypts Gitea&amp;rsquo;s 2FA seeds, Actions secrets and the credentials of pending migrations; it must never change afterwards.&lt;/li>
&lt;li>Leave &lt;code>GITEA_RUNNER_REGISTRATION_TOKEN&lt;/code> empty for now (&lt;a href="#81-register-the-container-runner">section 8.1&lt;/a>).&lt;/li>
&lt;li>&lt;code>MODCRAFT_SERVE_CONFIG=modcraft-funnel.json&lt;/code> publishes modCraft through Funnel; &lt;a href="#95-serve-instead-of-funnel">section 9.5&lt;/a> covers the tailnet-only alternative.&lt;/li>
&lt;/ul>
&lt;p>Copy all secrets into your password manager.
Git ignores &lt;code>.env&lt;/code>.
Review the compose file, the runner&amp;rsquo;s configuration and the serve configuration (press &lt;code>q&lt;/code> to quit &lt;code>less&lt;/code>):&lt;/p>
&lt;div class="highlight">&lt;pre tabindex="0" class="chroma">&lt;code class="language-sh" data-lang="sh">&lt;span class="line">&lt;span class="cl">less docker-compose.yml
&lt;/span>&lt;/span>&lt;span class="line">&lt;span class="cl">less gitea-runner.yaml
&lt;/span>&lt;/span>&lt;span class="line">&lt;span class="cl">less ../Tailscale/gitea-serve.json
&lt;/span>&lt;/span>&lt;/code>&lt;/pre>&lt;/div>&lt;p>What they configure:&lt;/p>
&lt;ul>
&lt;li>&lt;strong>Sidecars:&lt;/strong> both run Tailscale in userspace mode without extra privileges, log in with the OAuth secret only while they have no state (&lt;code>TS_AUTH_ONCE=true&lt;/code>) and upload no client logs (&lt;code>TS_NO_LOGS_NO_SUPPORT=true&lt;/code>).
They load their serve configuration from the repository&amp;rsquo;s &lt;code>Tailscale/&lt;/code> folder, with &lt;code>${TS_CERT_DOMAIN}&lt;/code> replaced by the node&amp;rsquo;s own name, and re-apply it when it changes.
Whether OrbStack passes edits made on macOS on to the container is undocumented, so restart the sidecar after editing a serve file (&lt;code>docker compose restart gitea-tailscale&lt;/code>).&lt;/li>
&lt;li>&lt;strong>Gitea&amp;rsquo;s serve configuration:&lt;/strong> 443 terminates HTTPS with the tailnet certificate and proxies to &lt;code>http://gitea:3000&lt;/code>; 22 is forwarded to Gitea&amp;rsquo;s built-in SSH server on &lt;code>gitea:2222&lt;/code>.
There is no &lt;code>AllowFunnel&lt;/code>, and &lt;code>tag:gitea&lt;/code> lacks the Funnel attribute anyway.&lt;/li>
&lt;li>&lt;strong>Gitea:&lt;/strong> the rootless image writes every &lt;code>GITEA__section__KEY&lt;/code> variable into &lt;code>/etc/gitea/app.ini&lt;/code> at every start, overriding manual edits to those keys.
&lt;code>INSTALL_LOCK&lt;/code> skips the web installer, which is why &lt;code>SECRET_KEY&lt;/code> must come from &lt;code>.env&lt;/code>: without it, Gitea silently falls back to a public built-in key.
Registration is closed, and nothing is visible without signing in.
New repositories are private by default.
Gitea restarts with &lt;code>restart: always&lt;/code>, so it comes back when OrbStack starts, even after a backup was cut off while Gitea was stopped.&lt;/li>
&lt;li>&lt;strong>Gitea&amp;rsquo;s networks:&lt;/strong> the network &lt;code>gitea&lt;/code> connects Gitea with its sidecar, &lt;code>gitea-ci&lt;/code> with the runner and its jobs, and &lt;code>gitea-db&lt;/code> with PostgreSQL; the network &lt;code>gitea-db&lt;/code> is internal, without a route out.
Gitea trusts &lt;code>X-Forwarded-For&lt;/code> from all of them, as only the sidecar, the runner and its jobs can reach port 3000.&lt;/li>
&lt;li>&lt;strong>Mirrors and Actions:&lt;/strong> new mirrors get no Actions unit (&lt;code>DEFAULT_MIRROR_REPO_UNITS&lt;/code>, Gitea&amp;rsquo;s default, set explicitly), and Gitea reads workflows from &lt;code>.gitea/workflows&lt;/code> only, never from &lt;code>.github/workflows&lt;/code> (&lt;a href="#75-how-the-mirrors-behave">section 7.5&lt;/a>).&lt;/li>
&lt;li>&lt;strong>PostgreSQL 18:&lt;/strong> pinned to the major version, as a new major needs a dump and restore.
From 18 on, the volume goes to &lt;code>/var/lib/postgresql&lt;/code>, and PostgreSQL keeps its data in &lt;code>18/docker&lt;/code> below it; a mount at &lt;code>/var/lib/postgresql/data&lt;/code>, as for 17 and older, makes the container refuse to start.&lt;/li>
&lt;li>&lt;strong>Runner:&lt;/strong> registers once against &lt;code>http://gitea:3000&lt;/code>, the address its jobs then use as well (&lt;a href="#8-gitea-actions-on-the-mac-mini">section 8&lt;/a>).&lt;/li>
&lt;li>&lt;strong>Pinned versions:&lt;/strong> Gitea, the runner and PostgreSQL are pinned; the sidecars follow Tailscale&amp;rsquo;s &lt;code>latest&lt;/code>, which is the current stable release.&lt;/li>
&lt;li>&lt;strong>Project name:&lt;/strong> &lt;code>mac-mini&lt;/code>.
Volumes and networks have fixed names, so the stack keeps them across a renamed folder.&lt;/li>
&lt;/ul>
&lt;p>Validate the compose file and pull the images:&lt;/p>
&lt;div class="highlight">&lt;pre tabindex="0" class="chroma">&lt;code class="language-sh" data-lang="sh">&lt;span class="line">&lt;span class="cl">docker compose config --quiet
&lt;/span>&lt;/span>&lt;span class="line">&lt;span class="cl">docker compose pull
&lt;/span>&lt;/span>&lt;/code>&lt;/pre>&lt;/div>&lt;p>Always run compose from &lt;code>~/scripts/Apple-Mac-mini-M4-Pro&lt;/code>, so that &lt;code>.env&lt;/code> and &lt;code>../Tailscale&lt;/code> resolve.&lt;/p>
&lt;h2 id="6-gitea">6 Gitea&lt;/h2>
&lt;h3 id="61-start-gitea-and-its-sidecar">6.1 Start Gitea and its sidecar&lt;/h3>
&lt;p>Start PostgreSQL, Gitea and Gitea&amp;rsquo;s sidecar; &lt;code>--wait&lt;/code> returns once the health checks pass:&lt;/p>
&lt;div class="highlight">&lt;pre tabindex="0" class="chroma">&lt;code class="language-sh" data-lang="sh">&lt;span class="line">&lt;span class="cl">docker compose up -d --wait gitea-db gitea gitea-tailscale
&lt;/span>&lt;/span>&lt;span class="line">&lt;span class="cl">docker compose ps --format &lt;span class="s1">&amp;#39;{{.Name}} {{.Status}}&amp;#39;&lt;/span>
&lt;/span>&lt;/span>&lt;span class="line">&lt;span class="cl">&lt;span class="c1"># gitea Up 20 seconds (healthy)&lt;/span>
&lt;/span>&lt;/span>&lt;span class="line">&lt;span class="cl">&lt;span class="c1"># gitea-db Up 26 seconds (healthy)&lt;/span>
&lt;/span>&lt;/span>&lt;span class="line">&lt;span class="cl">&lt;span class="c1"># gitea-tailscale Up 26 seconds&lt;/span>
&lt;/span>&lt;/span>&lt;span class="line">&lt;span class="cl">docker &lt;span class="nb">exec&lt;/span> gitea-tailscale tailscale status
&lt;/span>&lt;/span>&lt;span class="line">&lt;span class="cl">docker &lt;span class="nb">exec&lt;/span> gitea-tailscale tailscale serve status
&lt;/span>&lt;/span>&lt;span class="line">&lt;span class="cl">&lt;span class="c1"># https://gitea.tailnet-name.ts.net (tailnet only)&lt;/span>
&lt;/span>&lt;/span>&lt;span class="line">&lt;span class="cl">&lt;span class="c1"># |-- / proxy http://gitea:3000&lt;/span>
&lt;/span>&lt;/span>&lt;/code>&lt;/pre>&lt;/div>&lt;p>&lt;code>serve status&lt;/code> also lists the TCP forward of port 22 to &lt;code>gitea:2222&lt;/code>.
In the admin console, check that the new machine is called exactly &lt;code>gitea&lt;/code> and carries &lt;code>tag:gitea&lt;/code>.
If it became &lt;code>gitea-1&lt;/code>, delete the old &lt;code>gitea&lt;/code> machine, rename the new one to &lt;code>gitea&lt;/code> with &lt;strong>Edit machine name&lt;/strong> (&lt;a href="https://tailscale.com/docs/concepts/machine-names" target="_blank" rel="noopener">Machine names&lt;/a>), and restart the sidecar so that its serve configuration picks up the name: &lt;code>docker compose restart gitea-tailscale&lt;/code>.
Alternatively, set &lt;code>GITEA_DOMAIN&lt;/code> to the name it got and run &lt;code>docker compose up -d gitea&lt;/code>, so that Gitea picks up the new &lt;code>ROOT_URL&lt;/code>.
The first HTTPS request makes the sidecar fetch its certificate, which takes a few seconds; then Gitea&amp;rsquo;s sign-in page appears at &lt;code>https://gitea.tailnet-name.ts.net&lt;/code> in a browser on any of your tailnet devices.
Check the health endpoint from the Mac as well:&lt;/p>
&lt;div class="highlight">&lt;pre tabindex="0" class="chroma">&lt;code class="language-sh" data-lang="sh">&lt;span class="line">&lt;span class="cl">curl -fsS https://gitea.tailnet-name.ts.net/api/healthz
&lt;/span>&lt;/span>&lt;/code>&lt;/pre>&lt;/div>&lt;p>It prints &lt;code>&amp;quot;status&amp;quot;: &amp;quot;pass&amp;quot;&lt;/code> with a database and a cache check.&lt;/p>
&lt;h3 id="62-admin-account-and-two-factor-authentication">6.2 Admin account and two-factor authentication&lt;/h3>
&lt;p>Registration is closed, so create the admin account on the command line.
&lt;code>docker exec&lt;/code> runs as the image&amp;rsquo;s user &lt;code>git&lt;/code>, as Gitea requires, and needs no &lt;code>--config&lt;/code>:&lt;/p>
&lt;div class="highlight">&lt;pre tabindex="0" class="chroma">&lt;code class="language-sh" data-lang="sh">&lt;span class="line">&lt;span class="cl">docker &lt;span class="nb">exec&lt;/span> gitea gitea admin user create --admin --username wmutschl --email you@example.org --random-password
&lt;/span>&lt;/span>&lt;span class="line">&lt;span class="cl">&lt;span class="c1"># generated random password is &amp;#39;...&amp;#39;&lt;/span>
&lt;/span>&lt;/span>&lt;span class="line">&lt;span class="cl">&lt;span class="c1"># New user &amp;#39;wmutschl&amp;#39; has been successfully created!&lt;/span>
&lt;/span>&lt;/span>&lt;/code>&lt;/pre>&lt;/div>&lt;p>Sign in with that password and set your own under &lt;strong>Settings → Account&lt;/strong>.
Under &lt;strong>Settings → Security&lt;/strong>, enable two-factor authentication (TOTP or a passkey) and store the recovery codes in your password manager.
Under &lt;strong>Settings → SSH / GPG Keys&lt;/strong>, add the public SSH key of every computer you push from.&lt;/p>
&lt;h3 id="63-git-over-ssh-and-https">6.3 Git over SSH and HTTPS&lt;/h3>
&lt;p>Gitea&amp;rsquo;s built-in SSH server generated RSA, ECDSA and Ed25519 host keys at its first start.
On the &lt;strong>Mac mini&lt;/strong>, print their fingerprints:&lt;/p>
&lt;div class="highlight">&lt;pre tabindex="0" class="chroma">&lt;code class="language-sh" data-lang="sh">&lt;span class="line">&lt;span class="cl">docker &lt;span class="nb">exec&lt;/span> gitea sh -c &lt;span class="s1">&amp;#39;for k in /var/lib/gitea/ssh/*.pub; do ssh-keygen -lf &amp;#34;$k&amp;#34;; done&amp;#39;&lt;/span>
&lt;/span>&lt;/span>&lt;/code>&lt;/pre>&lt;/div>&lt;p>On the &lt;strong>MacBook&lt;/strong>, compare them with the keys that &lt;code>gitea.tailnet-name.ts.net&lt;/code> presents, before you trust it for the first time, and connect once:&lt;/p>
&lt;div class="highlight">&lt;pre tabindex="0" class="chroma">&lt;code class="language-sh" data-lang="sh">&lt;span class="line">&lt;span class="cl">ssh-keyscan gitea.tailnet-name.ts.net 2&amp;gt;/dev/null &lt;span class="p">|&lt;/span> ssh-keygen -lf -
&lt;/span>&lt;/span>&lt;span class="line">&lt;span class="cl">ssh -T git@gitea.tailnet-name.ts.net
&lt;/span>&lt;/span>&lt;/code>&lt;/pre>&lt;/div>&lt;p>The fingerprints must match, and the last command greets you by your Gitea user name and closes the connection, as Gitea offers no shell.
The host keys live on the data volume and come back with every restore, so clients never see a changed host key.
Clone URLs look like &lt;code>git@gitea.tailnet-name.ts.net:wmutschl/project.git&lt;/code>.
Over HTTPS, use an access token from &lt;strong>Settings → Applications&lt;/strong> instead of the password; macOS&amp;rsquo;s keychain stores it for &lt;code>git&lt;/code>.
Neither Tailscale Serve nor Gitea limits the size of a push over either protocol.&lt;/p>
&lt;h2 id="7-mirrors-of-github-and-gitlab">7 Mirrors of GitHub and GitLab&lt;/h2>
&lt;p>A pull mirror is a read-only copy that Gitea fetches every eight hours by default.
I keep the mirrors in two organizations, &lt;code>github&lt;/code> and &lt;code>gitlab&lt;/code>, apart from my own projects.
That avoids name collisions between the two sources, and the CI runner, registered for my user only, never sees a mirror.&lt;/p>
&lt;h3 id="71-tokens">7.1 Tokens&lt;/h3>
&lt;p>The token you give Gitea for a mirror is stored with that mirror, in plain text in the git configuration of its repository inside Gitea, and therefore in every backup.
Use read-only tokens for the sources:&lt;/p>
&lt;ul>
&lt;li>&lt;strong>GitHub:&lt;/strong> a fine-grained personal access token with &lt;strong>Repository access: All repositories&lt;/strong> and the permission &lt;strong>Contents: Read-only&lt;/strong>; GitHub adds &lt;strong>Metadata: Read-only&lt;/strong> by itself.
A fine-grained token covers the repositories of exactly one owner, so organizations need tokens of their own.
Use a token even for public repositories, because GitHub throttles anonymous clones.&lt;/li>
&lt;li>&lt;strong>GitLab:&lt;/strong> a personal access token with the scopes &lt;code>read_api&lt;/code> and &lt;code>read_repository&lt;/code>.
On gitlab.com, tokens expire after at most 365 days.&lt;/li>
&lt;/ul>
&lt;p>The script itself needs a Gitea token of your own user with the scopes &lt;code>write:repository&lt;/code>, &lt;code>read:user&lt;/code> and &lt;code>read:organization&lt;/code>.
Create it in &lt;strong>Settings → Applications&lt;/strong>, or on the command line; &lt;code>--scopes&lt;/code> defaults to everything, so always set it:&lt;/p>
&lt;div class="highlight">&lt;pre tabindex="0" class="chroma">&lt;code class="language-sh" data-lang="sh">&lt;span class="line">&lt;span class="cl">docker &lt;span class="nb">exec&lt;/span> gitea gitea admin user generate-access-token --username wmutschl --token-name gitea-mirror --scopes write:repository,read:user,read:organization --raw
&lt;/span>&lt;/span>&lt;/code>&lt;/pre>&lt;/div>&lt;h3 id="72-create-the-organizations">7.2 Create the organizations&lt;/h3>
&lt;p>In Gitea, create the organizations &lt;code>github&lt;/code> and &lt;code>gitlab&lt;/code> (&lt;strong>+ → New Organization&lt;/strong>) with the visibility &lt;strong>Private&lt;/strong>.
Mirrors of private repositories stay private in Gitea; the script sets that for every mirror, because Gitea does not copy the visibility from the source.&lt;/p>
&lt;h3 id="73-mirror-everything-with-gitea-mirror">7.3 Mirror everything with gitea-mirror&lt;/h3>
&lt;p>&lt;code>gitea-mirror&lt;/code> lists all repositories of a GitHub user or organization, or of a GitLab user or group, and creates a pull mirror in Gitea for each one that does not exist there yet.
Running it again later only adds what is new.
By default it skips forks and leaves out wikis and Git LFS objects.
Every repository is cloned once during its creation, so the first run takes a while.
Run it on the Mac, where it reads Gitea&amp;rsquo;s address from &lt;code>.env&lt;/code>, or on any other tailnet device after &lt;code>export GITEA_URL=https://gitea.tailnet-name.ts.net&lt;/code>.
Read the tokens without echoing them, so they stay out of the shell history:&lt;/p>
&lt;div class="highlight">&lt;pre tabindex="0" class="chroma">&lt;code class="language-sh" data-lang="sh">&lt;span class="line">&lt;span class="cl">&lt;span class="nb">cd&lt;/span> ~/scripts/Apple-Mac-mini-M4-Pro
&lt;/span>&lt;/span>&lt;span class="line">&lt;span class="cl">&lt;span class="nb">read&lt;/span> -s GITEA_TOKEN &lt;span class="o">&amp;amp;&amp;amp;&lt;/span> &lt;span class="nb">export&lt;/span> GITEA_TOKEN
&lt;/span>&lt;/span>&lt;span class="line">&lt;span class="cl">&lt;span class="nb">read&lt;/span> -s GITHUB_TOKEN &lt;span class="o">&amp;amp;&amp;amp;&lt;/span> &lt;span class="nb">export&lt;/span> GITHUB_TOKEN
&lt;/span>&lt;/span>&lt;span class="line">&lt;span class="cl">./gitea-mirror --dry-run github wmutschl
&lt;/span>&lt;/span>&lt;span class="line">&lt;span class="cl">&lt;span class="c1"># fork, skipped: tidyexplain&lt;/span>
&lt;/span>&lt;/span>&lt;span class="line">&lt;span class="cl">&lt;span class="c1"># would mirror: https://github.com/wmutschl/timeshift-autosnap-apt.git -&amp;gt; github/timeshift-autosnap-apt (private: false, wiki: false, lfs: false)&lt;/span>
&lt;/span>&lt;/span>&lt;span class="line">&lt;span class="cl">&lt;span class="c1"># ...&lt;/span>
&lt;/span>&lt;/span>&lt;span class="line">&lt;span class="cl">./gitea-mirror github wmutschl
&lt;/span>&lt;/span>&lt;span class="line">&lt;span class="cl">&lt;span class="c1"># mirroring: https://github.com/wmutschl/timeshift-autosnap-apt.git -&amp;gt; github/timeshift-autosnap-apt ...&lt;/span>
&lt;/span>&lt;/span>&lt;span class="line">&lt;span class="cl">&lt;span class="c1"># done&lt;/span>
&lt;/span>&lt;/span>&lt;span class="line">&lt;span class="cl">&lt;span class="c1"># ...&lt;/span>
&lt;/span>&lt;/span>&lt;span class="line">&lt;span class="cl">
&lt;/span>&lt;/span>&lt;span class="line">&lt;span class="cl">&lt;span class="nb">read&lt;/span> -s GITLAB_TOKEN &lt;span class="o">&amp;amp;&amp;amp;&lt;/span> &lt;span class="nb">export&lt;/span> GITLAB_TOKEN
&lt;/span>&lt;/span>&lt;span class="line">&lt;span class="cl">./gitea-mirror gitlab wmutschl
&lt;/span>&lt;/span>&lt;/code>&lt;/pre>&lt;/div>&lt;p>The options:&lt;/p>
&lt;ul>
&lt;li>&lt;code>--to OWNER&lt;/code>: another Gitea user or organization for the mirrors.&lt;/li>
&lt;li>&lt;code>--include-forks&lt;/code>, &lt;code>--skip-archived&lt;/code>: forks are left out and archived repositories included by default.&lt;/li>
&lt;li>&lt;code>--wiki&lt;/code>: also mirror wikis that exist upstream.
A wiki that disappears upstream later makes every sync of that mirror fail, which is why this is off by default.&lt;/li>
&lt;li>&lt;code>--lfs&lt;/code>: also mirror Git LFS objects.
Every sync then downloads new LFS objects, which counts against the owner&amp;rsquo;s LFS bandwidth on GitHub.&lt;/li>
&lt;li>&lt;code>--interval DUR&lt;/code>: the sync interval as a Go duration, such as &lt;code>8h&lt;/code> or &lt;code>30m&lt;/code>, at least &lt;code>10m&lt;/code>; units like &lt;code>1d&lt;/code> do not exist.
&lt;code>0&lt;/code> stops the periodic syncs after the first one.&lt;/li>
&lt;li>&lt;code>--match REGEX&lt;/code>: only repositories whose name matches.&lt;/li>
&lt;li>For a self-managed GitLab, run &lt;code>export GITLAB_URL=https://gitlab.example.org&lt;/code> first.&lt;/li>
&lt;/ul>
&lt;p>A migration that fails leaves a repository stuck as &amp;ldquo;migration failed&amp;rdquo; in Gitea; the script deletes it right away, so the next run tries again.&lt;/p>
&lt;h3 id="74-a-single-mirror-in-the-web-interface">7.4 A single mirror in the web interface&lt;/h3>
&lt;p>For a single repository, use &lt;strong>+ → New Migration&lt;/strong>, choose &lt;strong>GitHub&lt;/strong>, &lt;strong>GitLab&lt;/strong> or plain &lt;strong>Git&lt;/strong>, paste the clone URL, and tick &lt;strong>This repository will be a mirror&lt;/strong>.
For GitHub and GitLab, the token goes into &lt;strong>Access Token&lt;/strong>; for plain Git, enter any user name, such as &lt;code>oauth2&lt;/code>, and the token as password.
Pick the owner &lt;code>github&lt;/code> or &lt;code>gitlab&lt;/code>, and tick &lt;strong>Private&lt;/strong> for a private source.&lt;/p>
&lt;h3 id="75-how-the-mirrors-behave">7.5 How the mirrors behave&lt;/h3>
&lt;ul>
&lt;li>&lt;strong>Syncs:&lt;/strong> the first sync after the creation comes within ten minutes, whatever the interval says; after that, the interval counts.
&lt;strong>Synchronize Now&lt;/strong> in the repository&amp;rsquo;s settings fetches immediately.
Every sync fetches all branches and tags and deletes those that disappeared upstream, so a mirror does not protect against deletions upstream.&lt;/li>
&lt;li>&lt;strong>Failures:&lt;/strong> a mirror whose token expired or whose source disappeared is retried every ten minutes, and every failure lands in &lt;strong>Site Administration → System Notices&lt;/strong>.
Look there now and then.&lt;/li>
&lt;li>&lt;strong>Rotating a token:&lt;/strong> in the mirror&amp;rsquo;s &lt;strong>Settings → Mirror Settings&lt;/strong>, enter the new token as the password (username &lt;code>oauth2&lt;/code>).
After a rename upstream, change the address there and enter the token again: since Gitea 28.4, a changed address erases the stored credentials.&lt;/li>
&lt;li>&lt;strong>Changes upstream that Gitea does not follow:&lt;/strong> a new default branch and a newly created wiki.&lt;/li>
&lt;li>&lt;strong>Archived upstream:&lt;/strong> Gitea cannot archive a mirror.
Set its interval to &lt;code>0&lt;/code> to stop the syncs, or turn it into a normal repository with &lt;strong>Convert to Regular Repository&lt;/strong>, which also deletes the stored token.&lt;/li>
&lt;li>&lt;strong>Never Actions on a mirror.&lt;/strong>
A mirror sync counts as a push, and a mirror with Actions enabled would run the mirrored project&amp;rsquo;s workflows on my Mac, with access to my user&amp;rsquo;s Actions secrets.
Three things prevent that: new mirrors get no Actions unit, Gitea reads only &lt;code>.gitea/workflows&lt;/code>, and the runner serves only repositories of my user.
So leave &lt;strong>Actions&lt;/strong> unticked in the settings of every mirror.&lt;/li>
&lt;/ul>
&lt;h3 id="76-personal-projects">7.6 Personal projects&lt;/h3>
&lt;p>My own projects live directly under my user and are private by default.
Git LFS is enabled, without a file size limit.
Uploads through the web interface are limited to 50 MB per file, issue attachments to 100 MB and release assets to 2048 MB; raise them in the compose file if needed, for example &lt;code>GITEA__repository_0x2E_upload__FILE_MAX_SIZE: 500&lt;/code>.
&lt;code>_0x2E_&lt;/code> stands for the dot in the section name &lt;code>[repository.upload]&lt;/code>.&lt;/p>
&lt;p>To keep a copy on GitHub as well, add a &lt;strong>push mirror&lt;/strong> in the repository&amp;rsquo;s &lt;strong>Settings → Mirror Settings&lt;/strong>: your GitHub user name as username, a GitHub token that may write to that one repository as password, and &lt;strong>Sync when commits are pushed&lt;/strong> ticked.
Create the GitHub repository first, and keep in mind what a push mirror does: it force-pushes all branches and tags and deletes on GitHub whatever does not exist in Gitea.
Delete a push mirror in the web interface: in Gitea 28.4, deleting one through the API leaves its token behind in the repository&amp;rsquo;s git configuration.&lt;/p>
&lt;h2 id="8-gitea-actions-on-the-mac-mini">8 Gitea Actions on the Mac mini&lt;/h2>
&lt;p>The runner in the container takes jobs only from repositories of my user.
For each job it starts a container from one of Gitea&amp;rsquo;s runner images on the network &lt;code>gitea-ci&lt;/code>, where the job reaches Gitea at &lt;code>http://gitea:3000&lt;/code> and the runner&amp;rsquo;s cache server at &lt;code>gitea-runner:8088&lt;/code>.
The images are multi-arch, so jobs run natively as &lt;code>linux/arm64&lt;/code>.
Checkout, artifacts and the cache do not depend on Tailscale.
The runner downloads the actions from github.com and the job images from docker.gitea.com.&lt;/p>
&lt;h3 id="81-register-the-container-runner">8.1 Register the container runner&lt;/h3>
&lt;p>Create a registration token for your user, put it into &lt;code>.env&lt;/code> and start the runner:&lt;/p>
&lt;div class="highlight">&lt;pre tabindex="0" class="chroma">&lt;code class="language-sh" data-lang="sh">&lt;span class="line">&lt;span class="cl">&lt;span class="nb">cd&lt;/span> ~/scripts/Apple-Mac-mini-M4-Pro
&lt;/span>&lt;/span>&lt;span class="line">&lt;span class="cl">docker &lt;span class="nb">exec&lt;/span> gitea gitea actions generate-runner-token --scope wmutschl
&lt;/span>&lt;/span>&lt;span class="line">&lt;span class="cl">nano .env &lt;span class="c1"># GITEA_RUNNER_REGISTRATION_TOKEN=...&lt;/span>
&lt;/span>&lt;/span>&lt;span class="line">&lt;span class="cl">docker compose up -d gitea-runner
&lt;/span>&lt;/span>&lt;span class="line">&lt;span class="cl">docker logs gitea-runner
&lt;/span>&lt;/span>&lt;span class="line">&lt;span class="cl">&lt;span class="c1"># .runner is missing or not a regular file&lt;/span>
&lt;/span>&lt;/span>&lt;span class="line">&lt;span class="cl">&lt;span class="c1"># level=info msg=&amp;#34;Registering runner, arch=arm64, os=linux, version=v6.0.0.&amp;#34;&lt;/span>
&lt;/span>&lt;/span>&lt;span class="line">&lt;span class="cl">&lt;span class="c1"># level=info msg=&amp;#34;Runner registered successfully.&amp;#34;&lt;/span>
&lt;/span>&lt;/span>&lt;span class="line">&lt;span class="cl">&lt;span class="c1"># ... level=info msg=&amp;#34;runner: mac-mini-docker, with version: v6.0.0, with labels: [ubuntu-latest ubuntu-26.04 ubuntu-24.04 ubuntu-22.04], declare successfully&amp;#34;&lt;/span>
&lt;/span>&lt;/span>&lt;/code>&lt;/pre>&lt;/div>&lt;p>The runner now appears as &lt;strong>online&lt;/strong> in Gitea under &lt;strong>Settings → Actions → Runners&lt;/strong>.
Its credentials are in &lt;code>/data/.runner&lt;/code> on the volume &lt;code>gitea-runner-data&lt;/code>, so the token is no longer needed.
Empty &lt;code>GITEA_RUNNER_REGISTRATION_TOKEN&lt;/code> in &lt;code>.env&lt;/code> and recreate the container without it.
Then click &lt;strong>Reset registration token&lt;/strong> on the same page, because a token registers any number of runners until it is reset:&lt;/p>
&lt;div class="highlight">&lt;pre tabindex="0" class="chroma">&lt;code class="language-sh" data-lang="sh">&lt;span class="line">&lt;span class="cl">nano .env &lt;span class="c1"># GITEA_RUNNER_REGISTRATION_TOKEN=&lt;/span>
&lt;/span>&lt;/span>&lt;span class="line">&lt;span class="cl">docker compose up -d gitea-runner
&lt;/span>&lt;/span>&lt;/code>&lt;/pre>&lt;/div>&lt;h3 id="82-a-first-workflow">8.2 A first workflow&lt;/h3>
&lt;p>Workflows go into &lt;code>.gitea/workflows/&lt;/code> of a repository; Actions is enabled for new repositories.
A minimal one:&lt;/p>
&lt;div class="highlight">&lt;pre tabindex="0" class="chroma">&lt;code class="language-yaml" data-lang="yaml">&lt;span class="line">&lt;span class="cl">&lt;span class="c"># .gitea/workflows/ci.yml&lt;/span>&lt;span class="w">
&lt;/span>&lt;/span>&lt;/span>&lt;span class="line">&lt;span class="cl">&lt;span class="w">&lt;/span>&lt;span class="nt">name&lt;/span>&lt;span class="p">:&lt;/span>&lt;span class="w"> &lt;/span>&lt;span class="l">ci&lt;/span>&lt;span class="w">
&lt;/span>&lt;/span>&lt;/span>&lt;span class="line">&lt;span class="cl">&lt;span class="w">&lt;/span>&lt;span class="nt">on&lt;/span>&lt;span class="p">:&lt;/span>&lt;span class="w"> &lt;/span>&lt;span class="p">[&lt;/span>&lt;span class="l">push, pull_request]&lt;/span>&lt;span class="w">
&lt;/span>&lt;/span>&lt;/span>&lt;span class="line">&lt;span class="cl">&lt;span class="w">&lt;/span>&lt;span class="nt">jobs&lt;/span>&lt;span class="p">:&lt;/span>&lt;span class="w">
&lt;/span>&lt;/span>&lt;/span>&lt;span class="line">&lt;span class="cl">&lt;span class="w"> &lt;/span>&lt;span class="nt">test&lt;/span>&lt;span class="p">:&lt;/span>&lt;span class="w">
&lt;/span>&lt;/span>&lt;/span>&lt;span class="line">&lt;span class="cl">&lt;span class="w"> &lt;/span>&lt;span class="nt">runs-on&lt;/span>&lt;span class="p">:&lt;/span>&lt;span class="w"> &lt;/span>&lt;span class="l">ubuntu-latest&lt;/span>&lt;span class="w">
&lt;/span>&lt;/span>&lt;/span>&lt;span class="line">&lt;span class="cl">&lt;span class="w"> &lt;/span>&lt;span class="nt">steps&lt;/span>&lt;span class="p">:&lt;/span>&lt;span class="w">
&lt;/span>&lt;/span>&lt;/span>&lt;span class="line">&lt;span class="cl">&lt;span class="w"> &lt;/span>- &lt;span class="nt">uses&lt;/span>&lt;span class="p">:&lt;/span>&lt;span class="w"> &lt;/span>&lt;span class="l">actions/checkout@v4&lt;/span>&lt;span class="w">
&lt;/span>&lt;/span>&lt;/span>&lt;span class="line">&lt;span class="cl">&lt;span class="w"> &lt;/span>- &lt;span class="nt">uses&lt;/span>&lt;span class="p">:&lt;/span>&lt;span class="w"> &lt;/span>&lt;span class="l">actions/cache@v4&lt;/span>&lt;span class="w">
&lt;/span>&lt;/span>&lt;/span>&lt;span class="line">&lt;span class="cl">&lt;span class="w"> &lt;/span>&lt;span class="nt">with&lt;/span>&lt;span class="p">:&lt;/span>&lt;span class="w">
&lt;/span>&lt;/span>&lt;/span>&lt;span class="line">&lt;span class="cl">&lt;span class="w"> &lt;/span>&lt;span class="nt">path&lt;/span>&lt;span class="p">:&lt;/span>&lt;span class="w"> &lt;/span>&lt;span class="l">~/.cache/pip&lt;/span>&lt;span class="w">
&lt;/span>&lt;/span>&lt;/span>&lt;span class="line">&lt;span class="cl">&lt;span class="w"> &lt;/span>&lt;span class="nt">key&lt;/span>&lt;span class="p">:&lt;/span>&lt;span class="w"> &lt;/span>&lt;span class="l">pip-${{ hashFiles(&amp;#39;requirements.txt&amp;#39;) }}&lt;/span>&lt;span class="w">
&lt;/span>&lt;/span>&lt;/span>&lt;span class="line">&lt;span class="cl">&lt;span class="w"> &lt;/span>- &lt;span class="nt">run&lt;/span>&lt;span class="p">:&lt;/span>&lt;span class="w"> &lt;/span>&lt;span class="l">make test&lt;/span>&lt;span class="w">
&lt;/span>&lt;/span>&lt;/span>&lt;/code>&lt;/pre>&lt;/div>&lt;p>&lt;code>runs-on&lt;/code> picks the image through the runner&amp;rsquo;s labels in &lt;code>gitea-runner.yaml&lt;/code>: &lt;code>ubuntu-latest&lt;/code> (currently Ubuntu 26.04), &lt;code>ubuntu-26.04&lt;/code>, &lt;code>ubuntu-24.04&lt;/code> and &lt;code>ubuntu-22.04&lt;/code>, each with Node.js 24, Python 3, git, git-lfs and the Docker CLI.
The runner pulls the image again before each job, so &lt;code>ubuntu-latest&lt;/code> stays current.
A job that needs &lt;code>linux/amd64&lt;/code>, for example for x86-only binaries, runs under Rosetta with a container option:&lt;/p>
&lt;div class="highlight">&lt;pre tabindex="0" class="chroma">&lt;code class="language-yaml" data-lang="yaml">&lt;span class="line">&lt;span class="cl">&lt;span class="w"> &lt;/span>&lt;span class="nt">test-amd64&lt;/span>&lt;span class="p">:&lt;/span>&lt;span class="w">
&lt;/span>&lt;/span>&lt;/span>&lt;span class="line">&lt;span class="cl">&lt;span class="w"> &lt;/span>&lt;span class="nt">runs-on&lt;/span>&lt;span class="p">:&lt;/span>&lt;span class="w"> &lt;/span>&lt;span class="l">ubuntu-latest&lt;/span>&lt;span class="w">
&lt;/span>&lt;/span>&lt;/span>&lt;span class="line">&lt;span class="cl">&lt;span class="w"> &lt;/span>&lt;span class="nt">container&lt;/span>&lt;span class="p">:&lt;/span>&lt;span class="w">
&lt;/span>&lt;/span>&lt;/span>&lt;span class="line">&lt;span class="cl">&lt;span class="w"> &lt;/span>&lt;span class="nt">image&lt;/span>&lt;span class="p">:&lt;/span>&lt;span class="w"> &lt;/span>&lt;span class="l">docker.gitea.com/runner-images:ubuntu-24.04&lt;/span>&lt;span class="w">
&lt;/span>&lt;/span>&lt;/span>&lt;span class="line">&lt;span class="cl">&lt;span class="w"> &lt;/span>&lt;span class="nt">options&lt;/span>&lt;span class="p">:&lt;/span>&lt;span class="w"> &lt;/span>--&lt;span class="l">platform linux/amd64&lt;/span>&lt;span class="w">
&lt;/span>&lt;/span>&lt;/span>&lt;/code>&lt;/pre>&lt;/div>&lt;p>The runner sets &lt;code>ACT=true&lt;/code> in every job, so steps guarded with &lt;code>if: ${{ !env.ACT }}&lt;/code> are skipped.
Jobs stop after three hours, the limit of both the runner&amp;rsquo;s &lt;code>timeout&lt;/code> and Gitea&amp;rsquo;s &lt;code>[actions] ENDLESS_TASK_TIMEOUT&lt;/code>; raise both for longer jobs.&lt;/p>
&lt;h3 id="83-what-jobs-can-and-cannot-do">8.3 What jobs can and cannot do&lt;/h3>
&lt;ul>
&lt;li>&lt;strong>No Docker socket:&lt;/strong> &lt;code>docker_host: &amp;quot;-&amp;quot;&lt;/code> keeps OrbStack&amp;rsquo;s Docker socket out of every job and action container.
With the runner&amp;rsquo;s default, every job could start privileged containers, read every volume, including the sidecars&amp;rsquo; Tailscale keys and Gitea&amp;rsquo;s database, and reach the Mac&amp;rsquo;s files.
A workflow that builds Docker images needs a second runner from the runner image&amp;rsquo;s &lt;code>-dind-rootless&lt;/code> variant, with a label of its own; I have no such workflow.&lt;/li>
&lt;li>&lt;strong>No host mounts and no privileges:&lt;/strong> &lt;code>valid_volumes: []&lt;/code> and &lt;code>privileged: false&lt;/code>; the runner also drops dangerous options from workflows, such as &lt;code>--privileged&lt;/code> or &lt;code>--cap-add&lt;/code>.&lt;/li>
&lt;li>&lt;strong>Limits:&lt;/strong> each job container gets at most 8 GiB of memory and 4096 processes, so that a runaway job cannot starve Gitea, PostgreSQL and modCraft in OrbStack&amp;rsquo;s VM.
The limits do not cover &lt;code>services:&lt;/code> containers or &lt;code>docker://&lt;/code> steps, and a workflow&amp;rsquo;s own &lt;code>--memory&lt;/code> option overrides them.&lt;/li>
&lt;li>&lt;strong>Network:&lt;/strong> jobs reach Gitea&amp;rsquo;s port 3000 and the internet, but not PostgreSQL.
Through OrbStack they also reach the Mac&amp;rsquo;s LAN, services bound to the Mac&amp;rsquo;s &lt;code>127.0.0.1&lt;/code> via &lt;code>host.docker.internal&lt;/code>, such as modCraft&amp;rsquo;s Caddy, and every tailnet device my user may reach.
This runner is for my own code only.&lt;/li>
&lt;li>&lt;strong>Two jobs at a time:&lt;/strong> &lt;code>capacity: 2&lt;/code>.
Jobs share the network &lt;code>gitea-ci&lt;/code>, so two concurrent jobs that both start a service container of the same name would collide; set &lt;code>capacity: 1&lt;/code> if your workflows use &lt;code>services:&lt;/code>.&lt;/li>
&lt;/ul>
&lt;p>Changes to &lt;code>gitea-runner.yaml&lt;/code> take effect with &lt;code>docker compose up -d --force-recreate gitea-runner&lt;/code>.&lt;/p>
&lt;h3 id="84-optional-a-runner-directly-on-macos">8.4 Optional: a runner directly on macOS&lt;/h3>
&lt;p>Some jobs need macOS itself, for example MATLAB with my license or Xcode.
For those, a second runner runs directly on the Mac, from Homebrew, with the label &lt;code>macos-arm64&lt;/code>.
Its jobs run as my user, with access to all my files and my keychain, so it registers for my user&amp;rsquo;s repositories only, like the container runner.
It reaches Gitea through the Mac&amp;rsquo;s Tailscale app, under &lt;code>https://gitea.tailnet-name.ts.net&lt;/code>.
The plist assumes the user &lt;code>wmutschl&lt;/code> and Homebrew in &lt;code>/opt/homebrew&lt;/code>; adapt it before you load it:&lt;/p>
&lt;div class="highlight">&lt;pre tabindex="0" class="chroma">&lt;code class="language-sh" data-lang="sh">&lt;span class="line">&lt;span class="cl">brew install gitea-runner node
&lt;/span>&lt;/span>&lt;span class="line">&lt;span class="cl">mkdir -p ~/.config/gitea-runner
&lt;/span>&lt;/span>&lt;span class="line">&lt;span class="cl">cp ~/scripts/Apple-Mac-mini-M4-Pro/gitea-runner-host.yaml ~/.config/gitea-runner/config.yaml
&lt;/span>&lt;/span>&lt;span class="line">&lt;span class="cl">&lt;span class="nb">cd&lt;/span> ~/.config/gitea-runner
&lt;/span>&lt;/span>&lt;span class="line">&lt;span class="cl">docker &lt;span class="nb">exec&lt;/span> gitea gitea actions generate-runner-token --scope wmutschl
&lt;/span>&lt;/span>&lt;span class="line">&lt;span class="cl">&lt;span class="nb">read&lt;/span> -s TOKEN &lt;span class="c1"># paste the token printed above; it is not shown&lt;/span>
&lt;/span>&lt;/span>&lt;span class="line">&lt;span class="cl">gitea-runner register --no-interactive --config config.yaml --instance https://gitea.tailnet-name.ts.net --name mac-mini-host --token &lt;span class="s2">&amp;#34;&lt;/span>&lt;span class="nv">$TOKEN&lt;/span>&lt;span class="s2">&amp;#34;&lt;/span>
&lt;/span>&lt;/span>&lt;span class="line">&lt;span class="cl">cp ~/scripts/Apple-Mac-mini-M4-Pro/Library/LaunchAgents/local.mac-mini-gitea-runner.plist ~/Library/LaunchAgents/
&lt;/span>&lt;/span>&lt;span class="line">&lt;span class="cl">launchctl bootstrap gui/&lt;span class="k">$(&lt;/span>id -u&lt;span class="k">)&lt;/span> ~/Library/LaunchAgents/local.mac-mini-gitea-runner.plist
&lt;/span>&lt;/span>&lt;span class="line">&lt;span class="cl">tail ~/Library/Logs/mac-mini-gitea-runner.log
&lt;/span>&lt;/span>&lt;/code>&lt;/pre>&lt;/div>&lt;p>Reset the registration token in Gitea afterwards, as in &lt;a href="#81-register-the-container-runner">section 8.1&lt;/a>.
A workflow selects this runner with &lt;code>runs-on: macos-arm64&lt;/code>.
The label is deliberately not &lt;code>macos-latest&lt;/code>, so workflows written for GitHub never land on the bare Mac by accident.
I start it with my own launchd job instead of &lt;code>brew services&lt;/code>, whose job stays down after a failed start, for example when the tailnet certificate is not ready yet after a reboot.
Three more things to know:&lt;/p>
&lt;ul>
&lt;li>macOS&amp;rsquo;s Local Network privacy applies to launchd agents such as this one: its CI jobs cannot reach addresses on the LAN, while loopback and tailnet addresses work.&lt;/li>
&lt;li>Like OrbStack, it runs only while I am logged in, and it needs &lt;code>node&lt;/code> from Homebrew and &lt;code>git&lt;/code> from Apple&amp;rsquo;s Command Line Tools on its &lt;code>PATH&lt;/code>, which the launchd job sets.&lt;/li>
&lt;li>Its cache is off in &lt;code>gitea-runner-host.yaml&lt;/code>, because the cache server would listen on all of the Mac&amp;rsquo;s interfaces; turn it on if macOS jobs use &lt;code>actions/cache&lt;/code>.&lt;/li>
&lt;/ul>
&lt;h2 id="9-modcraft">9 modCraft&lt;/h2>
&lt;p>modCraft keeps its own Compose stack in its repository, with Caddy for the shared-password authentication, an API and a generation worker.
Caddy publishes &lt;code>127.0.0.1:8080&lt;/code> only.
Here, only the Tailscale sidecar lives in the scripts repository: it is the &amp;ldquo;existing HTTPS reverse proxy&amp;rdquo; from modCraft&amp;rsquo;s &lt;code>website/deployment/README.md&lt;/code>, with Tailscale Serve as the proxy.
The sidecar reaches Caddy through OrbStack&amp;rsquo;s &lt;code>host.docker.internal&lt;/code>, which leads to the Mac&amp;rsquo;s loopback interface, so neither stack refers to the other, and each can be rebuilt and updated on its own.
If modCraft is down, its URL answers with a 502.&lt;/p>
&lt;h3 id="91-clone-and-configure-modcraft">9.1 Clone and configure modCraft&lt;/h3>
&lt;p>modCraft&amp;rsquo;s launchd jobs expect the repository in &lt;code>~/modCraft&lt;/code>, which is not a privacy-protected folder either.
My repository is private for now:&lt;/p>
&lt;div class="highlight">&lt;pre tabindex="0" class="chroma">&lt;code class="language-sh" data-lang="sh">&lt;span class="line">&lt;span class="cl">git clone git@github.com:wmutschl/modCraft.git ~/modCraft
&lt;/span>&lt;/span>&lt;span class="line">&lt;span class="cl">&lt;span class="nb">cd&lt;/span> ~/modCraft/website
&lt;/span>&lt;/span>&lt;/code>&lt;/pre>&lt;/div>&lt;p>Create modCraft&amp;rsquo;s private &lt;code>.env&lt;/code> next to its &lt;code>compose.yaml&lt;/code> as described in its &lt;code>deployment/README.md&lt;/code>: &lt;code>MODCRAFT_USERNAME&lt;/code> and the bcrypt hash &lt;code>MODCRAFT_PASSWORD_HASH&lt;/code>, in single quotes because the hash contains &lt;code>$&lt;/code>.
Keep the plaintext password in &lt;code>.env.credentials.local&lt;/code> (&lt;code>MODCRAFT_USERNAME&lt;/code> and &lt;code>MODCRAFT_LOCAL_PASSWORD&lt;/code>, &lt;code>chmod 600&lt;/code>); Git ignores both files.
Serve keeps the original &lt;code>Host&lt;/code> header, and Caddy answers only for the host names in &lt;code>MODCRAFT_SITE_ADDRESS&lt;/code>.
So that variable must contain the sidecar&amp;rsquo;s MagicDNS name, as plain &lt;code>http://…:8080&lt;/code>, because HTTPS ends at the sidecar.
The line in modCraft&amp;rsquo;s &lt;code>.env&lt;/code>:&lt;/p>
&lt;div class="highlight">&lt;pre tabindex="0" class="chroma">&lt;code class="language-text" data-lang="text">&lt;span class="line">&lt;span class="cl">MODCRAFT_SITE_ADDRESS=&amp;#39;http://modcraft.tailnet-name.ts.net:8080, http://localhost:8080&amp;#39;
&lt;/span>&lt;/span>&lt;/code>&lt;/pre>&lt;/div>&lt;p>The &lt;code>localhost&lt;/code> entry keeps &lt;code>http://localhost:8080&lt;/code> working on the Mac itself.&lt;/p>
&lt;h3 id="92-build-and-start-modcraft-and-its-sidecar">9.2 Build and start modCraft and its sidecar&lt;/h3>
&lt;p>The first build pulls TeX and compiles the Dynare preprocessor, so it takes a while:&lt;/p>
&lt;div class="highlight">&lt;pre tabindex="0" class="chroma">&lt;code class="language-sh" data-lang="sh">&lt;span class="line">&lt;span class="cl">&lt;span class="nb">cd&lt;/span> ~/modCraft/website
&lt;/span>&lt;/span>&lt;span class="line">&lt;span class="cl">docker compose up --build -d
&lt;/span>&lt;/span>&lt;span class="line">&lt;span class="cl">docker compose ps
&lt;/span>&lt;/span>&lt;span class="line">&lt;span class="cl">
&lt;/span>&lt;/span>&lt;span class="line">&lt;span class="cl">&lt;span class="nb">cd&lt;/span> ~/scripts/Apple-Mac-mini-M4-Pro
&lt;/span>&lt;/span>&lt;span class="line">&lt;span class="cl">docker compose up -d modcraft-tailscale
&lt;/span>&lt;/span>&lt;span class="line">&lt;span class="cl">docker &lt;span class="nb">exec&lt;/span> modcraft-tailscale tailscale funnel status
&lt;/span>&lt;/span>&lt;span class="line">&lt;span class="cl">&lt;span class="c1"># # Funnel on:&lt;/span>
&lt;/span>&lt;/span>&lt;span class="line">&lt;span class="cl">&lt;span class="c1"># # - https://modcraft.tailnet-name.ts.net&lt;/span>
&lt;/span>&lt;/span>&lt;span class="line">&lt;span class="cl">&lt;span class="c1">#&lt;/span>
&lt;/span>&lt;/span>&lt;span class="line">&lt;span class="cl">&lt;span class="c1"># https://modcraft.tailnet-name.ts.net (Funnel on)&lt;/span>
&lt;/span>&lt;/span>&lt;span class="line">&lt;span class="cl">&lt;span class="c1"># |-- / proxy http://host.docker.internal:8080&lt;/span>
&lt;/span>&lt;/span>&lt;/code>&lt;/pre>&lt;/div>&lt;p>Check the machine name &lt;code>modcraft&lt;/code> and the tag &lt;code>tag:container&lt;/code> in the admin console, as for Gitea.
Public DNS for the Funnel name can take up to ten minutes.
Test the public route from a device outside the tailnet, for example a phone on mobile data with Tailscale off: devices in the tailnet resolve the name to the sidecar&amp;rsquo;s tailnet address and bypass Funnel.
The legal notice and privacy policy at &lt;code>/privacy&lt;/code> and the content-hashed built files under &lt;code>/assets/&lt;/code> are public; everything else asks for the shared password.&lt;/p>
&lt;h3 id="93-smoke-test-statistics-backup-and-model-check">9.3 Smoke test, statistics backup and model check&lt;/h3>
&lt;p>The smoke test submits a small model through the tailnet and checks authentication, worker health, all downloads and the PDF and ZIP output:&lt;/p>
&lt;div class="highlight">&lt;pre tabindex="0" class="chroma">&lt;code class="language-sh" data-lang="sh">&lt;span class="line">&lt;span class="cl">&lt;span class="nb">cd&lt;/span> ~/modCraft/website
&lt;/span>&lt;/span>&lt;span class="line">&lt;span class="cl">python3 deployment/smoke_test.py --credentials .env.credentials.local --url https://modcraft.tailnet-name.ts.net
&lt;/span>&lt;/span>&lt;/code>&lt;/pre>&lt;/div>&lt;p>modCraft brings two launchd jobs of its own; install both as described in its &lt;code>deployment/README.md&lt;/code>:&lt;/p>
&lt;ul>
&lt;li>&lt;code>local.modcraft-statistics-backup&lt;/code> exports the statistics log, with model features and outcomes but no titles, authors, IP addresses or job IDs, daily at 03:30 to &lt;code>~/modCraft/website/backups/statistics.jsonl&lt;/code>, which Time Machine backs up.&lt;/li>
&lt;li>&lt;code>local.modcraft-model-check&lt;/code> runs daily at 04:00 and re-runs, in Octave with Dynare, every model requested since its last run, and reports failures as a macOS notification.&lt;/li>
&lt;/ul>
&lt;p>Before deploying a change to the model files or the generator, run the release gate from the same README, which runs a fixed suite of feature combinations in Octave with Dynare.&lt;/p>
&lt;h3 id="94-updates">9.4 Updates&lt;/h3>
&lt;p>Wait until no modCraft job is queued or running, then pull and rebuild.
&lt;code>--force-recreate&lt;/code> also starts every container&amp;rsquo;s log afresh, which modCraft&amp;rsquo;s privacy policy counts on; &lt;code>down&lt;/code> is not needed and the volumes stay:&lt;/p>
&lt;div class="highlight">&lt;pre tabindex="0" class="chroma">&lt;code class="language-sh" data-lang="sh">&lt;span class="line">&lt;span class="cl">&lt;span class="nb">cd&lt;/span> ~/modCraft &lt;span class="o">&amp;amp;&amp;amp;&lt;/span> git pull &lt;span class="o">&amp;amp;&amp;amp;&lt;/span> &lt;span class="nb">cd&lt;/span> website &lt;span class="o">&amp;amp;&amp;amp;&lt;/span> docker compose up --build --force-recreate -d
&lt;/span>&lt;/span>&lt;span class="line">&lt;span class="cl">docker compose -f ~/modCraft/website/compose.yaml logs --tail&lt;span class="o">=&lt;/span>&lt;span class="m">100&lt;/span> api worker web
&lt;/span>&lt;/span>&lt;span class="line">&lt;span class="cl">docker logs modcraft-tailscale
&lt;/span>&lt;/span>&lt;/code>&lt;/pre>&lt;/div>&lt;p>Changing the shared password means a new hash in modCraft&amp;rsquo;s &lt;code>.env&lt;/code>, an updated &lt;code>.env.credentials.local&lt;/code> and &lt;code>docker compose up -d web&lt;/code> in &lt;code>~/modCraft/website&lt;/code>; modCraft&amp;rsquo;s &lt;code>deployment/README.md&lt;/code> has the command for the hash.
modCraft&amp;rsquo;s privacy policy also relies on &lt;code>TS_NO_LOGS_NO_SUPPORT=true&lt;/code>, so check it after recreating the sidecar:&lt;/p>
&lt;div class="highlight">&lt;pre tabindex="0" class="chroma">&lt;code class="language-sh" data-lang="sh">&lt;span class="line">&lt;span class="cl">docker logs modcraft-tailscale 2&amp;gt;&lt;span class="p">&amp;amp;&lt;/span>&lt;span class="m">1&lt;/span> &lt;span class="p">|&lt;/span> grep &lt;span class="s1">&amp;#39;disabled logging&amp;#39;&lt;/span>
&lt;/span>&lt;/span>&lt;/code>&lt;/pre>&lt;/div>&lt;h3 id="95-serve-instead-of-funnel">9.5 Serve instead of Funnel&lt;/h3>
&lt;p>To make modCraft reachable only from the tailnet, set &lt;code>MODCRAFT_SERVE_CONFIG=modcraft-serve.json&lt;/code> in &lt;code>.env&lt;/code> and recreate the sidecar; that file is &lt;code>modcraft-funnel.json&lt;/code> without &lt;code>AllowFunnel&lt;/code>.
Also empty &lt;code>MODCRAFT_CHECK_FUNNEL&lt;/code> in &lt;code>~/.config/mac-mini/host.env&lt;/code> (&lt;a href="#101-healthchecksio-and-the-hosts-settings">section 10.1&lt;/a>), as there is no public route left to check:&lt;/p>
&lt;div class="highlight">&lt;pre tabindex="0" class="chroma">&lt;code class="language-sh" data-lang="sh">&lt;span class="line">&lt;span class="cl">&lt;span class="nb">cd&lt;/span> ~/scripts/Apple-Mac-mini-M4-Pro
&lt;/span>&lt;/span>&lt;span class="line">&lt;span class="cl">docker compose up -d modcraft-tailscale
&lt;/span>&lt;/span>&lt;span class="line">&lt;span class="cl">docker &lt;span class="nb">exec&lt;/span> modcraft-tailscale tailscale serve status
&lt;/span>&lt;/span>&lt;span class="line">&lt;span class="cl">&lt;span class="c1"># https://modcraft.tailnet-name.ts.net (tailnet only)&lt;/span>
&lt;/span>&lt;/span>&lt;span class="line">&lt;span class="cl">&lt;span class="c1"># |-- / proxy http://host.docker.internal:8080&lt;/span>
&lt;/span>&lt;/span>&lt;/code>&lt;/pre>&lt;/div>&lt;p>Removing a serve file alone does not end Funnel: Tailscale stores the last configuration in the sidecar&amp;rsquo;s state.
Point the sidecar at a file without &lt;code>AllowFunnel&lt;/code>, as above.
To take modCraft off the air at once, &lt;code>docker exec modcraft-tailscale tailscale funnel reset&lt;/code> clears the sidecar&amp;rsquo;s whole serve configuration, the tailnet route included.
The sidecar&amp;rsquo;s next start applies the file named in &lt;code>MODCRAFT_SERVE_CONFIG&lt;/code> again, with Funnel if that is still &lt;code>modcraft-funnel.json&lt;/code>.&lt;/p>
&lt;h3 id="96-moving-modcraft-to-its-vps-later">9.6 Moving modCraft to its VPS later&lt;/h3>
&lt;p>On the VPS, modCraft runs with its &lt;code>compose.production.yaml&lt;/code>, and Caddy gets its own Let&amp;rsquo;s Encrypt certificate for a real domain; its README covers that.
Carry over the private &lt;code>.env&lt;/code> (with the new &lt;code>MODCRAFT_SITE_ADDRESS&lt;/code>), the credentials file and the statistics, restored from the latest &lt;code>statistics.jsonl&lt;/code>.
Then, on the Mac:&lt;/p>
&lt;div class="highlight">&lt;pre tabindex="0" class="chroma">&lt;code class="language-sh" data-lang="sh">&lt;span class="line">&lt;span class="cl">&lt;span class="nb">cd&lt;/span> ~/modCraft/website &lt;span class="o">&amp;amp;&amp;amp;&lt;/span> docker compose down
&lt;/span>&lt;/span>&lt;span class="line">&lt;span class="cl">&lt;span class="nb">cd&lt;/span> ~/scripts/Apple-Mac-mini-M4-Pro &lt;span class="o">&amp;amp;&amp;amp;&lt;/span> docker compose rm -sf modcraft-tailscale
&lt;/span>&lt;/span>&lt;span class="line">&lt;span class="cl">docker volume rm modcraft-tailscale-data
&lt;/span>&lt;/span>&lt;span class="line">&lt;span class="cl">launchctl bootout gui/&lt;span class="k">$(&lt;/span>id -u&lt;span class="k">)&lt;/span>/local.modcraft-statistics-backup
&lt;/span>&lt;/span>&lt;span class="line">&lt;span class="cl">rm ~/Library/LaunchAgents/local.modcraft-statistics-backup.plist
&lt;/span>&lt;/span>&lt;/code>&lt;/pre>&lt;/div>&lt;p>Delete the &lt;code>modcraft&lt;/code> machine in the Tailscale admin console, empty &lt;code>MODCRAFT_CHECK_URL&lt;/code> in &lt;code>~/.config/mac-mini/host.env&lt;/code>, and remove the &lt;code>modcraft-tailscale&lt;/code> service and its volume from the compose file.
&lt;code>docker compose down&lt;/code> keeps modCraft&amp;rsquo;s volumes; remove them only once the VPS has everything.
The daily model check skips silently once &lt;code>modcraft-api-1&lt;/code> is gone.
To keep it, add &lt;code>--export&lt;/code> with the path of a &lt;code>statistics.jsonl&lt;/code> fetched from the VPS before 04:00 to the &lt;code>ProgramArguments&lt;/code> of &lt;code>local.modcraft-model-check.plist&lt;/code>, and keep the image &lt;code>modcraft-backend:local&lt;/code> in step with the VPS by running &lt;code>git pull &amp;amp;&amp;amp; docker compose build&lt;/code> in &lt;code>~/modCraft/website&lt;/code> after each deployment, because the checker builds on it.
Otherwise remove that job the same way as the statistics backup.&lt;/p>
&lt;h2 id="10-backups-monitoring-and-ongoing-care">10 Backups, monitoring and ongoing care&lt;/h2>
&lt;h3 id="101-healthchecksio-and-the-hosts-settings">10.1 healthchecks.io and the host&amp;rsquo;s settings&lt;/h3>
&lt;p>The host&amp;rsquo;s jobs read their settings from &lt;code>~/.config/mac-mini/host.env&lt;/code>: the healthchecks.io ping key, the backup folder, the number of backups to keep, and how the uptime check reaches modCraft.
In healthchecks.io, copy the ping key from &lt;strong>Project Settings → API Access&lt;/strong>, and add the integrations that should alert you, such as email or Signal, as for the Wyse.
The checks are created by their first ping, as &lt;code>mac-mini-gitea-backup&lt;/code> and &lt;code>mac-mini-alive&lt;/code>.
Create the settings file from its template:&lt;/p>
&lt;div class="highlight">&lt;pre tabindex="0" class="chroma">&lt;code class="language-sh" data-lang="sh">&lt;span class="line">&lt;span class="cl">mkdir -p ~/.config/mac-mini
&lt;/span>&lt;/span>&lt;span class="line">&lt;span class="cl">cp ~/scripts/Apple-Mac-mini-M4-Pro/host.env.example ~/.config/mac-mini/host.env
&lt;/span>&lt;/span>&lt;span class="line">&lt;span class="cl">chmod &lt;span class="m">600&lt;/span> ~/.config/mac-mini/host.env
&lt;/span>&lt;/span>&lt;span class="line">&lt;span class="cl">nano ~/.config/mac-mini/host.env
&lt;/span>&lt;/span>&lt;/code>&lt;/pre>&lt;/div>&lt;p>Set &lt;code>MODCRAFT_CHECK_URL=https://modcraft.tailnet-name.ts.net/privacy&lt;/code>, the legal notice, which needs no password.
On the Mac, MagicDNS resolves modCraft&amp;rsquo;s name to the sidecar&amp;rsquo;s tailnet address, so a plain request would never touch Funnel.
&lt;code>MODCRAFT_CHECK_FUNNEL=true&lt;/code> therefore resolves the name through public DNS, with Cloudflare&amp;rsquo;s DNS over HTTPS, and the check takes the public route; empty it with the tailnet-only &lt;code>modcraft-serve.json&lt;/code>.&lt;/p>
&lt;table>
&lt;thead>
&lt;tr>
&lt;th>Job&lt;/th>
&lt;th>When&lt;/th>
&lt;th>What&lt;/th>
&lt;th>healthchecks.io check&lt;/th>
&lt;/tr>
&lt;/thead>
&lt;tbody>
&lt;tr>
&lt;td>Gitea backup&lt;/td>
&lt;td>Daily, 02:30&lt;/td>
&lt;td>&lt;code>pg_dump&lt;/code> and &lt;code>gitea dump&lt;/code> → &lt;code>~/Backups/gitea&lt;/code>; Gitea stops for the dump&lt;/td>
&lt;td>&lt;code>mac-mini-gitea-backup&lt;/code>: period 1 day, grace 1 hour&lt;/td>
&lt;/tr>
&lt;tr>
&lt;td>Uptime&lt;/td>
&lt;td>Every five minutes&lt;/td>
&lt;td>Gitea&amp;rsquo;s &lt;code>/api/healthz&lt;/code> through the tailnet, modCraft&amp;rsquo;s &lt;code>/privacy&lt;/code> through Funnel, OrbStack running&lt;/td>
&lt;td>&lt;code>mac-mini-alive&lt;/code>: period 5 minutes, grace 10 minutes&lt;/td>
&lt;/tr>
&lt;tr>
&lt;td>modCraft statistics&lt;/td>
&lt;td>Daily, 03:30&lt;/td>
&lt;td>modCraft&amp;rsquo;s own job → &lt;code>~/modCraft/website/backups&lt;/code>&lt;/td>
&lt;td>None; its log is &lt;code>~/Library/Logs/modcraft-statistics-backup.log&lt;/code>&lt;/td>
&lt;/tr>
&lt;tr>
&lt;td>Time Machine&lt;/td>
&lt;td>Hourly&lt;/td>
&lt;td>The home folder, including &lt;code>~/Backups/gitea&lt;/code> and &lt;code>~/scripts&lt;/code>, to the T7&lt;/td>
&lt;td>macOS warns after days without a backup&lt;/td>
&lt;/tr>
&lt;/tbody>
&lt;/table>
&lt;p>The uptime check goes down when the Mac is off or waits for its FileVault unlock or login (&lt;a href="#22-filevault-restarts-and-remote-access">section 2.2&lt;/a>), and when the Mac&amp;rsquo;s Tailscale app, OrbStack, a sidecar, Gitea, PostgreSQL, modCraft&amp;rsquo;s Caddy or Funnel fails.
Its failure message names what failed.
While the backup holds Gitea stopped, the check skips Gitea.&lt;/p>
&lt;h3 id="102-install-the-launchd-jobs">10.2 Install the launchd jobs&lt;/h3>
&lt;p>The plists contain the absolute paths &lt;code>/Users/wmutschl/...&lt;/code>; adapt them first if your user name differs.
Copy the two plists into place, load them, and run the backup once:&lt;/p>
&lt;div class="highlight">&lt;pre tabindex="0" class="chroma">&lt;code class="language-sh" data-lang="sh">&lt;span class="line">&lt;span class="cl">cp ~/scripts/Apple-Mac-mini-M4-Pro/Library/LaunchAgents/local.mac-mini-gitea-backup.plist ~/Library/LaunchAgents/
&lt;/span>&lt;/span>&lt;span class="line">&lt;span class="cl">cp ~/scripts/Apple-Mac-mini-M4-Pro/Library/LaunchAgents/local.mac-mini-alive.plist ~/Library/LaunchAgents/
&lt;/span>&lt;/span>&lt;span class="line">&lt;span class="cl">launchctl bootstrap gui/&lt;span class="k">$(&lt;/span>id -u&lt;span class="k">)&lt;/span> ~/Library/LaunchAgents/local.mac-mini-gitea-backup.plist
&lt;/span>&lt;/span>&lt;span class="line">&lt;span class="cl">launchctl bootstrap gui/&lt;span class="k">$(&lt;/span>id -u&lt;span class="k">)&lt;/span> ~/Library/LaunchAgents/local.mac-mini-alive.plist
&lt;/span>&lt;/span>&lt;span class="line">&lt;span class="cl">launchctl kickstart gui/&lt;span class="k">$(&lt;/span>id -u&lt;span class="k">)&lt;/span>/local.mac-mini-gitea-backup
&lt;/span>&lt;/span>&lt;span class="line">&lt;span class="cl">tail -f ~/Library/Logs/mac-mini-gitea-backup.log
&lt;/span>&lt;/span>&lt;span class="line">&lt;span class="cl">&lt;span class="c1"># 2026-11-20 10:27:34 stopping gitea&lt;/span>
&lt;/span>&lt;/span>&lt;span class="line">&lt;span class="cl">&lt;span class="c1"># 2026-11-20 10:27:34 pg_dump&lt;/span>
&lt;/span>&lt;/span>&lt;span class="line">&lt;span class="cl">&lt;span class="c1"># 2026-11-20 10:27:34 gitea dump&lt;/span>
&lt;/span>&lt;/span>&lt;span class="line">&lt;span class="cl">&lt;span class="c1"># 2026-11-20 10:27:34 starting gitea&lt;/span>
&lt;/span>&lt;/span>&lt;span class="line">&lt;span class="cl">&lt;span class="c1"># 2026-11-20 10:27:37 backup complete: /Users/wmutschl/Backups/gitea/gitea-20261120-102734 (584K)&lt;/span>
&lt;/span>&lt;/span>&lt;/code>&lt;/pre>&lt;/div>&lt;p>Press Ctrl-C once the log says &lt;code>backup complete&lt;/code>.
The run creates its check in healthchecks.io; set the periods from the table above there.
Check that Time Machine includes the folder:&lt;/p>
&lt;div class="highlight">&lt;pre tabindex="0" class="chroma">&lt;code class="language-sh" data-lang="sh">&lt;span class="line">&lt;span class="cl">tmutil isexcluded ~/Backups/gitea
&lt;/span>&lt;/span>&lt;span class="line">&lt;span class="cl">&lt;span class="c1"># [Included] /Users/wmutschl/Backups/gitea&lt;/span>
&lt;/span>&lt;/span>&lt;/code>&lt;/pre>&lt;/div>&lt;p>macOS announces the new jobs as background items under &lt;strong>System Settings → General → Login Items &amp;amp; Extensions&lt;/strong>; leave them allowed.
A daily job missed while the Mac slept runs when it wakes up; one missed while it was off does not, and the missing ping reports that.
Finally, test the alert path once and check that the alert reached you; the next uptime run, within five minutes, sets the check back to up:&lt;/p>
&lt;div class="highlight">&lt;pre tabindex="0" class="chroma">&lt;code class="language-sh" data-lang="sh">&lt;span class="line">&lt;span class="cl">~/scripts/Apple-Mac-mini-M4-Pro/mac-mini-hc-ping alive fail &lt;span class="s1">&amp;#39;Test alert from the Mac mini&amp;#39;&lt;/span>
&lt;/span>&lt;/span>&lt;/code>&lt;/pre>&lt;/div>&lt;h3 id="103-what-the-backup-contains">10.3 What the backup contains&lt;/h3>
&lt;p>&lt;code>mac-mini-gitea-backup&lt;/code> stops Gitea while it dumps, because Gitea&amp;rsquo;s documentation requires that for a consistent copy; that takes seconds for a small instance and longer with large repositories.
PostgreSQL keeps running.
A Gitea that is running but not healthy, for example while it migrates its database after an update, is not stopped; the run fails instead.
The dump runs with the image the &lt;code>gitea&lt;/code> container was created from, so a changed image tag in the compose file cannot affect it.
Each run writes a folder &lt;code>gitea-YYYYMMDD-HHMMSS&lt;/code> with two files:&lt;/p>
&lt;ul>
&lt;li>&lt;code>gitea-db.pgdump&lt;/code>: the database as a &lt;code>pg_dump&lt;/code> in PostgreSQL&amp;rsquo;s custom format.&lt;/li>
&lt;li>&lt;code>gitea-dump.tar&lt;/code>: Gitea&amp;rsquo;s own &lt;code>gitea dump&lt;/code>, with the repositories, LFS objects, attachments, packages, Actions logs and artifacts, the SSH host keys, &lt;code>app.ini&lt;/code> and the database once more, as SQL.
It is uncompressed: Git&amp;rsquo;s objects are compressed already, and that keeps Gitea&amp;rsquo;s downtime short.&lt;/li>
&lt;/ul>
&lt;p>Then Gitea starts again, also after an error, if it was running before, and the run waits until Gitea answers again before it reports success.
The script keeps the two newest runs.
Time Machine keeps the older ones, hourly for a day, daily for a month and weekly after that, as space allows.
Neither file contains the search indexes, which Gitea rebuilds, or the sessions, so everyone signs in again after a restore.&lt;/p>
&lt;div class="alert alert-warning">
&lt;div>
&lt;strong>The backups hold every secret of the instance.&lt;/strong>
&lt;code>app.ini&lt;/code> contains &lt;code>SECRET_KEY&lt;/code> and the database password, the repositories&amp;rsquo; git configuration contains the mirror tokens in plain text, and the database holds the hashed passwords and the encrypted 2FA seeds.
&lt;code>~/Backups/gitea&lt;/code> is readable only for my user, and the Time Machine disk must be encrypted: choose &lt;strong>Encrypt Backup&lt;/strong> when you select the disk in &lt;strong>System Settings → General → Time Machine&lt;/strong>.
&lt;/div>
&lt;/div>
&lt;p>Both copies are at home, on the Mac and on the T7.
A fire or theft would take both; an off-site copy of &lt;code>~/Backups/gitea&lt;/code>, for example on the Wyse&amp;rsquo;s Storage Box, would close that gap, but is not part of this guide.
The mirrors, by contrast, come back from GitHub and GitLab at any time.&lt;/p>
&lt;h3 id="104-restore-drills">10.4 Restore drills&lt;/h3>
&lt;p>A backup counts only once a restore from it has worked.
&lt;code>mac-mini-gitea-restore&lt;/code> restores a run into a fresh installation: it loads the database with &lt;code>pg_restore&lt;/code>, unpacks the archive into Gitea&amp;rsquo;s two volumes, starts Gitea and runs &lt;code>gitea admin regenerate hooks&lt;/code> and &lt;code>gitea doctor check --all&lt;/code>.
It refuses to touch a database with tables or volumes with data, so it cannot overwrite a running instance.
It also refuses a &lt;code>.env&lt;/code> whose &lt;code>GITEA_SECRET_KEY&lt;/code> differs from the one in the backup&amp;rsquo;s &lt;code>app.ini&lt;/code>, because Gitea could not decrypt the 2FA seeds and Actions secrets with another key.
I tested it by deleting all three volumes and restoring: repositories, mirrors, attachments, packages, LFS objects, access tokens, the SSH host keys and the runner&amp;rsquo;s registration all came back, and CI jobs ran again once the runner was started.&lt;/p>
&lt;p>For a drill, restore onto &lt;strong>another Mac&lt;/strong> with OrbStack, my MacBook, because the volume names are fixed and the Mac mini&amp;rsquo;s volumes are in use.
The drill instance must not sync mirrors: it would fetch with the stored tokens, and its push mirrors would force-push the backup&amp;rsquo;s older state to GitHub.
A &lt;code>docker-compose.override.yml&lt;/code> next to the compose file, which compose reads by itself, turns mirroring off:&lt;/p>
&lt;div class="highlight">&lt;pre tabindex="0" class="chroma">&lt;code class="language-yaml" data-lang="yaml">&lt;span class="line">&lt;span class="cl">&lt;span class="nt">services&lt;/span>&lt;span class="p">:&lt;/span>&lt;span class="w">
&lt;/span>&lt;/span>&lt;/span>&lt;span class="line">&lt;span class="cl">&lt;span class="w"> &lt;/span>&lt;span class="nt">gitea&lt;/span>&lt;span class="p">:&lt;/span>&lt;span class="w">
&lt;/span>&lt;/span>&lt;/span>&lt;span class="line">&lt;span class="cl">&lt;span class="w"> &lt;/span>&lt;span class="nt">environment&lt;/span>&lt;span class="p">:&lt;/span>&lt;span class="w">
&lt;/span>&lt;/span>&lt;/span>&lt;span class="line">&lt;span class="cl">&lt;span class="w"> &lt;/span>&lt;span class="nt">GITEA__mirror__ENABLED&lt;/span>&lt;span class="p">:&lt;/span>&lt;span class="w"> &lt;/span>&lt;span class="s2">&amp;#34;false&amp;#34;&lt;/span>&lt;span class="w">
&lt;/span>&lt;/span>&lt;/span>&lt;/code>&lt;/pre>&lt;/div>&lt;p>&lt;code>.env&lt;/code> needs the Mac mini&amp;rsquo;s &lt;code>GITEA_SECRET_KEY&lt;/code> from the password manager; the other values may differ, and &lt;code>TAILSCALE_OAUTH_KEY&lt;/code> stays empty, as the drill starts no sidecar.
The backup goes into the drill&amp;rsquo;s folder, so that removing the drill removes it too:&lt;/p>
&lt;div class="highlight">&lt;pre tabindex="0" class="chroma">&lt;code class="language-sh" data-lang="sh">&lt;span class="line">&lt;span class="cl">git clone https://github.com/wmutschl/scripts.git ~/scripts-drill
&lt;/span>&lt;/span>&lt;span class="line">&lt;span class="cl">&lt;span class="nb">cd&lt;/span> ~/scripts-drill/Apple-Mac-mini-M4-Pro
&lt;/span>&lt;/span>&lt;span class="line">&lt;span class="cl">scp -r mac-mini:Backups/gitea/gitea-YYYYMMDD-HHMMSS .
&lt;/span>&lt;/span>&lt;span class="line">&lt;span class="cl">cp mac-mini.env .env
&lt;/span>&lt;/span>&lt;span class="line">&lt;span class="cl">chmod &lt;span class="m">600&lt;/span> .env
&lt;/span>&lt;/span>&lt;span class="line">&lt;span class="cl">nano .env &lt;span class="c1"># GITEA_SECRET_KEY from the password manager; any GITEA_DOMAIN, GITEA_DB_PASSWORD, GITEA_INTERNAL_TOKEN&lt;/span>
&lt;/span>&lt;/span>&lt;span class="line">&lt;span class="cl">nano docker-compose.override.yml &lt;span class="c1"># the override above&lt;/span>
&lt;/span>&lt;/span>&lt;span class="line">&lt;span class="cl">./mac-mini-gitea-restore gitea-YYYYMMDD-HHMMSS
&lt;/span>&lt;/span>&lt;span class="line">&lt;span class="cl">docker &lt;span class="nb">exec&lt;/span> gitea curl -fsS http://localhost:3000/api/healthz
&lt;/span>&lt;/span>&lt;span class="line">&lt;span class="cl">docker &lt;span class="nb">exec&lt;/span> gitea ls /var/lib/gitea/git/repositories
&lt;/span>&lt;/span>&lt;/code>&lt;/pre>&lt;/div>&lt;p>&lt;code>SECRET_KEY&lt;/code> is also in the archive&amp;rsquo;s &lt;code>app.ini&lt;/code>, if the password manager ever fails: &lt;code>tar -xOf gitea-dump.tar app.ini | grep SECRET_KEY&lt;/code>.
Afterwards, remove the drill on the MacBook, and only there:&lt;/p>
&lt;div class="highlight">&lt;pre tabindex="0" class="chroma">&lt;code class="language-sh" data-lang="sh">&lt;span class="line">&lt;span class="cl">&lt;span class="nb">cd&lt;/span> ~/scripts-drill/Apple-Mac-mini-M4-Pro
&lt;/span>&lt;/span>&lt;span class="line">&lt;span class="cl">docker compose down -v
&lt;/span>&lt;/span>&lt;span class="line">&lt;span class="cl">&lt;span class="nb">cd&lt;/span> ~ &lt;span class="o">&amp;amp;&amp;amp;&lt;/span> rm -rf ~/scripts-drill
&lt;/span>&lt;/span>&lt;/code>&lt;/pre>&lt;/div>&lt;p>If the MacBook&amp;rsquo;s Time Machine ran in between, its disk holds a copy of the backup as well, so it must be encrypted too.&lt;/p>
&lt;p>To restore on the Mac mini itself after a broken database, remove the three Gitea containers and volumes, restore the newest backup and start the runner again.
After a lost disk, first set up the Mac again and get &lt;code>~/Backups/gitea&lt;/code> back from Time Machine:&lt;/p>
&lt;div class="highlight">&lt;pre tabindex="0" class="chroma">&lt;code class="language-sh" data-lang="sh">&lt;span class="line">&lt;span class="cl">&lt;span class="nb">cd&lt;/span> ~/scripts/Apple-Mac-mini-M4-Pro
&lt;/span>&lt;/span>&lt;span class="line">&lt;span class="cl">docker compose stop gitea-runner gitea gitea-db &lt;span class="o">&amp;amp;&amp;amp;&lt;/span> docker compose rm -f gitea-runner gitea gitea-db
&lt;/span>&lt;/span>&lt;span class="line">&lt;span class="cl">docker volume rm gitea-db-data gitea-data gitea-config
&lt;/span>&lt;/span>&lt;span class="line">&lt;span class="cl">./mac-mini-gitea-restore ~/Backups/gitea/gitea-YYYYMMDD-HHMMSS
&lt;/span>&lt;/span>&lt;span class="line">&lt;span class="cl">docker compose up -d gitea-runner
&lt;/span>&lt;/span>&lt;/code>&lt;/pre>&lt;/div>&lt;p>The runner reconnects without a new registration if its volume &lt;code>gitea-runner-data&lt;/code> survived; otherwise register it again (&lt;a href="#81-register-the-container-runner">section 8.1&lt;/a>) and delete the old, offline runner in Gitea.
With push mirrors, the restored Gitea force-pushes the backup&amp;rsquo;s state at its next sync.
If GitHub has commits that the backup lacks, put the drill&amp;rsquo;s override in place before the restore, push those commits to Gitea from a local clone, then delete the override and run &lt;code>docker compose up -d gitea&lt;/code>.&lt;/p>
&lt;table>
&lt;thead>
&lt;tr>
&lt;th>When&lt;/th>
&lt;th>Drill&lt;/th>
&lt;th>Passing result&lt;/th>
&lt;/tr>
&lt;/thead>
&lt;tbody>
&lt;tr>
&lt;td>Quarterly&lt;/td>
&lt;td>Restore the newest backup on the MacBook (above)&lt;/td>
&lt;td>Gitea is healthy and lists every repository&lt;/td>
&lt;/tr>
&lt;tr>
&lt;td>Quarterly&lt;/td>
&lt;td>Look at the System Notices in Gitea&amp;rsquo;s site administration&lt;/td>
&lt;td>No mirror keeps failing&lt;/td>
&lt;/tr>
&lt;tr>
&lt;td>Yearly&lt;/td>
&lt;td>Unlock the Mac over SSH and log in through Screen Sharing, from outside home (&lt;a href="#22-filevault-restarts-and-remote-access">section 2.2&lt;/a>)&lt;/td>
&lt;td>Everything comes back, and the uptime check turns green&lt;/td>
&lt;/tr>
&lt;tr>
&lt;td>Yearly&lt;/td>
&lt;td>Go through the recovery material below&lt;/td>
&lt;td>Every secret is there and works&lt;/td>
&lt;/tr>
&lt;/tbody>
&lt;/table>
&lt;h3 id="105-recovery-material">10.5 Recovery material&lt;/h3>
&lt;p>Most of the configuration is in the scripts repository, under &lt;code>Apple-Mac-mini-M4-Pro/&lt;/code> and &lt;code>Tailscale/&lt;/code>.
Keep the rest in your password manager:&lt;/p>
&lt;ul>
&lt;li>The values in &lt;code>~/scripts/Apple-Mac-mini-M4-Pro/.env&lt;/code>: the OAuth secret, &lt;code>GITEA_SECRET_KEY&lt;/code>, &lt;code>GITEA_INTERNAL_TOKEN&lt;/code> and the database password.&lt;/li>
&lt;li>Gitea: the admin password and its 2FA recovery codes, and the access tokens you use.&lt;/li>
&lt;li>GitHub&amp;rsquo;s and GitLab&amp;rsquo;s read-only tokens for the mirrors, with their expiry dates.&lt;/li>
&lt;li>The healthchecks.io ping key from &lt;code>~/.config/mac-mini/host.env&lt;/code>.&lt;/li>
&lt;li>modCraft&amp;rsquo;s &lt;code>.env&lt;/code> and &lt;code>.env.credentials.local&lt;/code>.&lt;/li>
&lt;li>The Mac&amp;rsquo;s FileVault recovery key, and your Tailscale policy file.&lt;/li>
&lt;/ul>
&lt;p>The sidecars&amp;rsquo; state volumes need no backup: a rebuilt sidecar registers again with the OAuth secret, under the same name if the old node was deleted first.&lt;/p>
&lt;h3 id="106-updates">10.6 Updates&lt;/h3>
&lt;ul>
&lt;li>
&lt;p>&lt;strong>macOS:&lt;/strong> install updates in a quiet moment; the restart needs the unlock and the login from &lt;a href="#22-filevault-restarts-and-remote-access">section 2.2&lt;/a>.&lt;/p>
&lt;/li>
&lt;li>
&lt;p>&lt;strong>OrbStack:&lt;/strong> &lt;code>orb update --check&lt;/code>, then update in the app, or with &lt;code>brew upgrade --greedy orbstack&lt;/code>, since a plain &lt;code>brew upgrade&lt;/code> skips apps that update themselves.
It restarts every container.
Before you quit OrbStack for maintenance, run &lt;code>touch ~/.config/mac-mini/maintenance&lt;/code>, so that the uptime check does not start it again; the check still reports OrbStack as down.
Remove the file afterwards.&lt;/p>
&lt;/li>
&lt;li>
&lt;p>&lt;strong>Gitea:&lt;/strong> read the release notes, especially for a new major version.
Run the backup first, in the foreground and before you touch the image tag: newer images can migrate the database, and there is no way back.&lt;/p>
&lt;div class="highlight">&lt;pre tabindex="0" class="chroma">&lt;code class="language-sh" data-lang="sh">&lt;span class="line">&lt;span class="cl">&lt;span class="nb">cd&lt;/span> ~/scripts/Apple-Mac-mini-M4-Pro
&lt;/span>&lt;/span>&lt;span class="line">&lt;span class="cl">./mac-mini-gitea-backup
&lt;/span>&lt;/span>&lt;span class="line">&lt;span class="cl">&lt;span class="c1"># ... backup complete: /Users/wmutschl/Backups/gitea/gitea-YYYYMMDD-HHMMSS (...)&lt;/span>
&lt;/span>&lt;/span>&lt;/code>&lt;/pre>&lt;/div>&lt;p>Continue only if it ends with &lt;code>backup complete&lt;/code>.
Then change the image tag in &lt;code>docker-compose.yml&lt;/code> and run:&lt;/p>
&lt;div class="highlight">&lt;pre tabindex="0" class="chroma">&lt;code class="language-sh" data-lang="sh">&lt;span class="line">&lt;span class="cl">docker compose pull gitea
&lt;/span>&lt;/span>&lt;span class="line">&lt;span class="cl">docker compose up -d gitea
&lt;/span>&lt;/span>&lt;span class="line">&lt;span class="cl">docker logs -f gitea
&lt;/span>&lt;/span>&lt;/code>&lt;/pre>&lt;/div>&lt;p>Gitea&amp;rsquo;s web interface tells administrators when a new version is out.&lt;/p>
&lt;/li>
&lt;li>
&lt;p>&lt;strong>PostgreSQL:&lt;/strong> &lt;code>docker compose pull gitea-db &amp;amp;&amp;amp; docker compose up -d gitea-db&lt;/code> brings new minor versions of 18.
A new major version needs the database moved with a dump and a restore.
Gitea&amp;rsquo;s container is removed, not only stopped, so that an OrbStack restart in between cannot start it against the new, empty database:&lt;/p>
&lt;div class="highlight">&lt;pre tabindex="0" class="chroma">&lt;code class="language-sh" data-lang="sh">&lt;span class="line">&lt;span class="cl">&lt;span class="nb">cd&lt;/span> ~/scripts/Apple-Mac-mini-M4-Pro
&lt;/span>&lt;/span>&lt;span class="line">&lt;span class="cl">./mac-mini-gitea-backup
&lt;/span>&lt;/span>&lt;span class="line">&lt;span class="cl">docker compose stop gitea-runner
&lt;/span>&lt;/span>&lt;span class="line">&lt;span class="cl">docker compose rm -sf gitea gitea-db
&lt;/span>&lt;/span>&lt;span class="line">&lt;span class="cl">docker volume rm gitea-db-data
&lt;/span>&lt;/span>&lt;span class="line">&lt;span class="cl">nano docker-compose.yml &lt;span class="c1"># the new major version for gitea-db&lt;/span>
&lt;/span>&lt;/span>&lt;span class="line">&lt;span class="cl">docker compose up -d --wait gitea-db
&lt;/span>&lt;/span>&lt;span class="line">&lt;span class="cl">docker compose &lt;span class="nb">exec&lt;/span> -T gitea-db pg_restore -U gitea -d gitea --no-owner --exit-on-error &amp;lt; ~/Backups/gitea/gitea-YYYYMMDD-HHMMSS/gitea-db.pgdump
&lt;/span>&lt;/span>&lt;span class="line">&lt;span class="cl">docker compose up -d gitea gitea-runner
&lt;/span>&lt;/span>&lt;/code>&lt;/pre>&lt;/div>&lt;/li>
&lt;li>
&lt;p>&lt;strong>Gitea runner:&lt;/strong> read the release notes before a new major version, as each of them broke something in 2026; then change the tag and run &lt;code>docker compose up -d gitea-runner&lt;/code>.
The job images update by themselves.
The optional macOS runner updates with &lt;code>brew upgrade gitea-runner&lt;/code>, followed by &lt;code>launchctl kickstart -k gui/$(id -u)/local.mac-mini-gitea-runner&lt;/code>.&lt;/p>
&lt;/li>
&lt;li>
&lt;p>&lt;strong>Tailscale sidecars:&lt;/strong> &lt;code>docker compose pull gitea-tailscale modcraft-tailscale &amp;amp;&amp;amp; docker compose up -d gitea-tailscale modcraft-tailscale&lt;/code>.
The Tailscale app on the Mac updates itself.&lt;/p>
&lt;/li>
&lt;li>
&lt;p>&lt;strong>Scripts repository:&lt;/strong> after &lt;code>git pull&lt;/code> in &lt;code>~/scripts&lt;/code>, carry new settings from &lt;code>mac-mini.env&lt;/code> and &lt;code>host.env.example&lt;/code> into &lt;code>.env&lt;/code> and &lt;code>~/.config/mac-mini/host.env&lt;/code> first, then run &lt;code>docker compose up -d&lt;/code> in &lt;code>~/scripts/Apple-Mac-mini-M4-Pro&lt;/code>, so that the containers pick up changes to the compose file or &lt;code>.env&lt;/code>.
If the pull changes Gitea&amp;rsquo;s image tag, run the backup before that, as in the Gitea item above; a new major version of PostgreSQL needs the dump and restore from the PostgreSQL item first.
After a change to a serve file in &lt;code>Tailscale/&lt;/code>, restart only its sidecar: &lt;code>docker compose restart gitea-tailscale&lt;/code> for &lt;code>gitea-serve.json&lt;/code>, or &lt;code>docker compose restart modcraft-tailscale&lt;/code> for the file named in &lt;code>MODCRAFT_SERVE_CONFIG&lt;/code>; the &lt;code>nextcloud-*.json&lt;/code> files are not used here.
A changed &lt;code>gitea-runner.yaml&lt;/code> needs &lt;code>docker compose up -d --force-recreate gitea-runner&lt;/code>.
Copy changed plists again, followed by &lt;code>launchctl bootout&lt;/code> and &lt;code>launchctl bootstrap&lt;/code>.
The &lt;a href="https://github.com/wmutschl/scripts#apple-mac-mini-m4-pro" target="_blank" rel="noopener">scripts README&lt;/a> lists what each kind of change needs.&lt;/p>
&lt;/li>
&lt;/ul>
&lt;h3 id="107-regular-checks">10.7 Regular checks&lt;/h3>
&lt;p>healthchecks.io reports failed and missed jobs by itself.
Look at these now and then anyway, especially after updates:&lt;/p>
&lt;div class="highlight">&lt;pre tabindex="0" class="chroma">&lt;code class="language-sh" data-lang="sh">&lt;span class="line">&lt;span class="cl">&lt;span class="nb">cd&lt;/span> ~/scripts/Apple-Mac-mini-M4-Pro
&lt;/span>&lt;/span>&lt;span class="line">&lt;span class="cl">docker compose ps
&lt;/span>&lt;/span>&lt;span class="line">&lt;span class="cl">docker &lt;span class="nb">exec&lt;/span> gitea-tailscale tailscale serve status
&lt;/span>&lt;/span>&lt;span class="line">&lt;span class="cl">docker &lt;span class="nb">exec&lt;/span> modcraft-tailscale tailscale funnel status
&lt;/span>&lt;/span>&lt;span class="line">&lt;span class="cl">docker system df
&lt;/span>&lt;/span>&lt;span class="line">&lt;span class="cl">ls -l ~/Backups/gitea
&lt;/span>&lt;/span>&lt;span class="line">&lt;span class="cl">tail -n &lt;span class="m">5&lt;/span> ~/Library/Logs/mac-mini-gitea-backup.log ~/Library/Logs/mac-mini-alive.log
&lt;/span>&lt;/span>&lt;span class="line">&lt;span class="cl">launchctl list &lt;span class="p">|&lt;/span> grep local.
&lt;/span>&lt;/span>&lt;/code>&lt;/pre>&lt;/div>&lt;p>In Gitea&amp;rsquo;s &lt;strong>Site Administration&lt;/strong>, glance at &lt;strong>System Notices&lt;/strong> for failing mirrors and at &lt;strong>Actions → Runners&lt;/strong> for runners that went offline.&lt;/p></description></item></channel></rss>