A minimal email TUI where you read with Markdown and write in Neovim.
neomd.ssp.sh/docs
email
markdown
neovim
tui
update headless docs
+187
-23
+187
-23
docs/content/docs/configurations/headless.md
+187
-23
docs/content/docs/configurations/headless.md
···
71
71
72
72
## Syncthing Setup
73
73
74
-
### Files to Sync
74
+
### What Gets Synced
75
+
76
+
**Screener list directory**: `~/.config/neomd/lists/` - you can also sync the entire `neomd` folder, if you don't have passwords stored in there, only ENVs:
77
+
- `screened_in.txt`
78
+
- `screened_out.txt`
79
+
- `feed.txt`
80
+
- `papertrail.txt`
81
+
- `spam.txt`
82
+
83
+
### Step-by-Step Setup
84
+
85
+
#### 1. Install Syncthing
86
+
87
+
**On Arch Linux / Server:**
88
+
```sh
89
+
sudo pacman -S syncthing
90
+
systemctl --user enable syncthing
91
+
systemctl --user start syncthing
92
+
```
93
+
94
+
**On other systems**: See [Syncthing installation docs](https://docs.syncthing.net/intro/getting-started.html)
95
+
96
+
> **Note**: Use `systemctl --user` instead of adding to window manager autostart scripts. This ensures Syncthing runs on login, works across different environments, and continues running independently of your desktop session.
97
+
98
+
#### 2. Access Web UI
99
+
100
+
Open http://localhost:8384 on each device
101
+
102
+
#### 3. Connect Devices
103
+
104
+
**On Device A (e.g., your laptop):**
105
+
1. Go to **Actions** → **Show ID** to get your Device ID
106
+
2. Copy the long alphanumeric Device ID
107
+
108
+
**On Device B (e.g., your server):**
109
+
1. Click **Add Remote Device**
110
+
2. Paste Device A's Device ID
111
+
3. Name it (e.g., "laptop")
112
+
4. Click **Save**
113
+
114
+
**Back on Device A:**
115
+
1. Accept the connection notification
116
+
2. Name Device B (e.g., "server")
117
+
3. Click **Save**
118
+
119
+
Repeat for all devices (laptop, server, Android).
120
+
121
+
#### 4. Create Shared Folder
122
+
123
+
**On one device (e.g., server):**
124
+
1. Click **Add Folder**
125
+
2. Set **Folder Label**: `neomd-lists`
126
+
3. Set **Folder ID**: `neomd-lists` (same on all devices)
127
+
4. Set **Folder Path**: `/home/user/.config/neomd/lists/` (or `~/.config/neomd/` if syncing entire folder)
128
+
5. Go to **Sharing** tab → check all other devices
129
+
6. Go to **File Versioning** tab:
130
+
- Select **Simple File Versioning**
131
+
- Keep Versions: `5`
132
+
7. Click **Save**
75
133
76
-
Configure Syncthing to sync the following files across all your devices:
134
+
**On other devices:**
135
+
1. Accept the folder share notification
136
+
2. Verify/set the correct path for that device
137
+
3. Enable **File Versioning** (same as above)
138
+
4. Click **Save**
77
139
78
-
1. **Screener list directory**: `~/.config/neomd/lists/`
79
-
- `screened_in.txt`
80
-
- `screened_out.txt`
81
-
- `feed.txt`
82
-
- `papertrail.txt`
83
-
- `spam.txt`
140
+
#### 5. Backup First (Important!)
84
141
85
-
2. **Config file** (optional): `~/.config/neomd/config.toml`
86
-
- Useful for keeping settings consistent across devices
87
-
- Be careful with account-specific settings (passwords, paths)
142
+
Before syncing existing data, **backup your lists**:
88
143
89
-
### Syncthing Folder Setup
144
+
```sh
145
+
cp -r ~/.config/neomd/lists ~/.config/neomd/lists.backup-$(date +%Y%m%d)
146
+
```
90
147
91
-
1. **Install Syncthing** on all devices (NAS, laptop, Android)
92
-
2. **Create a shared folder** named "neomd-lists"
93
-
3. **Set folder path** to `~/.config/neomd/lists/` on each device
94
-
4. **Connect devices** and wait for initial sync
148
+
#### 6. Wait for Initial Sync
95
149
96
-
Example Syncthing folder configuration:
97
-
- **Folder ID**: `neomd-lists`
98
-
- **Folder Path**: `/home/user/.config/neomd/lists/`
99
-
- **Folder Type**: Send & Receive
100
-
- **File Versioning**: Simple File Versioning (keep 5 versions)
150
+
Watch the folder status in the web UI. It will show "Syncing" with progress, then "Up to Date" when complete.
151
+
152
+
### Server Setup (FreeBSD / No GUI)
153
+
154
+
If running neomd headless on a FreeBSD server without a desktop environment, use SSH port forwarding to access the Syncthing web UI:
155
+
156
+
#### 1. Start Syncthing on FreeBSD
157
+
158
+
```sh
159
+
# Enable and start as system service
160
+
sudo sysrc syncthing_enable="YES"
161
+
sudo sysrc syncthing_user="sspaeti"
162
+
sudo service syncthing start
163
+
164
+
# Or run as user service (no sudo)
165
+
syncthing &
166
+
167
+
# Or with nohup for persistent operation
168
+
nohup syncthing > ~/syncthing.log 2>&1 &
169
+
```
170
+
171
+
Check it's running:
172
+
```sh
173
+
ps aux | grep syncthing
174
+
```
175
+
176
+
#### 2. SSH Port Forwarding
177
+
178
+
From your **local machine** (laptop/desktop with browser), create an SSH tunnel:
179
+
180
+
```sh
181
+
ssh -L 8385:localhost:8384 your-server
182
+
```
183
+
184
+
This forwards `localhost:8385` on your local machine to `localhost:8384` on the server.
185
+
186
+
Now open in your **local browser**: http://localhost:8385
187
+
188
+
You'll see the server's Syncthing web UI!
189
+
190
+
#### 3. Get Server Device ID
191
+
192
+
In the web UI at http://localhost:8385:
193
+
1. Go to **Actions** → **Show ID**
194
+
2. Copy the Device ID
195
+
196
+
#### 4. Connect Your Devices
197
+
198
+
**On your local machine's Syncthing** (http://localhost:8384):
199
+
1. Click **Add Remote Device**
200
+
2. Paste the server's Device ID
201
+
3. Name it (e.g., "freebsd-server")
202
+
4. Click **Save**
203
+
204
+
**On the server's UI** (http://localhost:8385 via SSH tunnel):
205
+
1. Accept the connection notification
206
+
2. Name your local device (e.g., "laptop")
207
+
3. Click **Save**
208
+
209
+
#### 5. Share the Folder
210
+
211
+
**On your local machine** (http://localhost:8384):
212
+
1. Find your existing `neomd-lists` folder
213
+
2. Click **Edit**
214
+
3. Go to **Sharing** tab
215
+
4. Check the box next to your server device
216
+
5. Click **Save**
217
+
218
+
**On the server** (http://localhost:8385):
219
+
1. Accept the folder share notification
220
+
2. Set **Folder Path**: `/home/user/.config/neomd/lists/` (or `~/.config/neomd/` if syncing entire folder)
221
+
3. Go to **File Versioning** tab:
222
+
- Select **Simple File Versioning**
223
+
- Keep Versions: `5`
224
+
4. Click **Save**
225
+
226
+
#### 6. Handle Existing Files
227
+
228
+
Before syncing, **backup the server's existing lists**:
229
+
230
+
```sh
231
+
# On server
232
+
cp -r ~/.config/neomd/lists ~/.config/neomd/lists.backup-$(date +%Y%m%d)
233
+
```
234
+
235
+
Syncthing will merge files from both sides. To **start fresh from your local machine's data**:
236
+
237
+
```sh
238
+
# On server - remove existing files (after backup!)
239
+
rm -rf ~/.config/neomd/lists/*
240
+
```
241
+
242
+
#### 7. Close SSH Tunnel
243
+
244
+
Once setup is complete, you can close the SSH tunnel (Ctrl+C in the SSH session). Devices will continue syncing in the background.
245
+
246
+
For future configuration changes, create the SSH tunnel again when needed:
247
+
```sh
248
+
ssh -L 8385:localhost:8384 your-server
249
+
```
250
+
251
+
### Verify Sync is Working
252
+
253
+
```sh
254
+
# Check files exist
255
+
ls -la ~/.config/neomd/lists/
256
+
257
+
# Watch real-time sync in logs
258
+
journalctl --user -u syncthing -f
259
+
```
260
+
261
+
The daemon watches for file changes and reloads screener lists automatically when Syncthing updates them.
101
262
102
263
### Conflict Handling
103
264
104
-
- **File-level conflicts**: Syncthing creates `.sync-conflict` files if two devices modify the same file simultaneously
265
+
- **File-level conflicts**: Syncthing creates `.sync-conflict-*` files if two devices modify the same file simultaneously
105
266
- **Email-level**: IMAP is the source of truth; no local email state to conflict
106
267
- **Screener lists**: Append-only operations are safe; duplicates are harmless (normalized automatically)
107
268
108
-
The daemon watches for file changes and reloads screener lists automatically when Syncthing updates them.
269
+
Check for conflicts periodically:
270
+
```sh
271
+
find ~/.config/neomd/lists -name "*.sync-conflict-*"
272
+
```
109
273
110
274
## Systemd Service (Optional)
111
275