wiki: add SELinux vmail and gitea-runner articles; update indexes

- New: SELinux Fixing Dovecot Mail Spool Context (/var/vmail)
  Corrected fix — mail_spool_t only, no dovecot_tmp_t on tmp/ dirs.
  Includes warning and recovery steps for the Postfix delivery outage.
- New: Gitea Actions Runner Boot Race Condition Fix
  network-online.target dependency, RestartSec=10, /etc/hosts workaround.
- Updated SUMMARY.md, index.md, README.md, 05-troubleshooting/index.md
- Article count: 37 → 39; MajorWiki-Deploy-Status updated

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
2026-03-14 22:49:01 -04:00
parent 58cb5e7b2a
commit 21988a2fa9
7 changed files with 206 additions and 5 deletions

View File

@@ -0,0 +1,84 @@
# Gitea Actions Runner: Boot Race Condition Fix
If your `gitea-runner` (act_runner) service fails to start on boot — crash-looping and eventually hitting systemd's restart rate limit — the service is likely starting before DNS is available.
## Symptoms
- `gitea-runner.service` enters a crash loop on boot
- `journalctl -u gitea-runner` shows connection/DNS errors on startup:
```
dial tcp: lookup git.example.com: no such host
```
or similar resolution failures
- Service eventually stops retrying (systemd restart rate limit reached)
- `systemctl status gitea-runner` shows `(Result: start-limit-hit)` after reboot
- Service works fine if started manually after boot completes
## Why It Happens
`After=network.target` only guarantees that the network **interfaces are configured** — not that DNS resolution is functional. systemd-resolved (or your local resolver) starts slightly later. `act_runner` tries to connect to the Gitea instance by hostname on startup, the DNS lookup fails, and the process exits.
With the default `Restart=always` and no `RestartSec`, systemd restarts the service immediately. After 5 rapid failures within the default burst window (10 attempts in 2 minutes), systemd hits the rate limit and stops restarting.
## Fix
### 1. Update the Service File
Edit `/etc/systemd/system/gitea-runner.service`:
```ini
[Unit]
Description=Gitea Actions Runner
After=network-online.target
Wants=network-online.target
[Service]
User=deploy
WorkingDirectory=/opt/gitea-runner
ExecStart=/opt/gitea-runner/act_runner daemon
Restart=always
RestartSec=10
[Install]
WantedBy=multi-user.target
```
Key changes:
- `After=network-online.target` + `Wants=network-online.target` — waits for full network stack including DNS
- `RestartSec=10` — adds a 10-second delay between restart attempts, preventing rapid failure bursts from hitting the rate limit
### 2. Add a Local /etc/hosts Entry (Optional but Recommended)
If your Gitea instance is on the same local network or reachable via Tailscale, add an entry to `/etc/hosts` so act_runner can resolve it without depending on external DNS:
```
127.0.0.1 git.example.com
```
Replace `git.example.com` with your Gitea hostname and the IP with the correct local address. This makes resolution instantaneous and eliminates the DNS dependency entirely for startup.
### 3. Reload and Restart
```bash
sudo systemctl daemon-reload
sudo systemctl restart gitea-runner
sudo systemctl status gitea-runner
```
Verify it shows `active (running)` and stays that way. Then reboot and confirm it comes up automatically.
## Why `network-online.target` and Not `network.target`
| Target | What it guarantees |
|---|---|
| `network.target` | Network interfaces are configured (IP assigned) |
| `network-online.target` | Network is fully operational (DNS resolvers reachable) |
Services that need to make outbound network connections (especially DNS lookups) on startup should always use `network-online.target`. This includes: mail servers, monitoring agents, CI runners, anything that connects to an external host by name.
> [!note] `network-online.target` can add a few seconds to boot time since systemd waits for the network stack to fully initialize. For server contexts this is always the right tradeoff.
## Related
- [Managing Linux Services with systemd](../01-linux/process-management/managing-linux-services-systemd-ansible.md)
- [MajorWiki Setup & Publishing Pipeline](majwiki-setup-and-pipeline.md)