fetch2gmail 1.0.7__tar.gz → 1.0.8__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (24) hide show
  1. {fetch2gmail-1.0.7/src/fetch2gmail.egg-info → fetch2gmail-1.0.8}/PKG-INFO +83 -33
  2. {fetch2gmail-1.0.7 → fetch2gmail-1.0.8}/README.md +82 -32
  3. {fetch2gmail-1.0.7 → fetch2gmail-1.0.8}/pyproject.toml +1 -1
  4. {fetch2gmail-1.0.7 → fetch2gmail-1.0.8/src/fetch2gmail.egg-info}/PKG-INFO +83 -33
  5. {fetch2gmail-1.0.7 → fetch2gmail-1.0.8}/src/fetcher/env_file.py +9 -3
  6. {fetch2gmail-1.0.7 → fetch2gmail-1.0.8}/src/fetcher/gmail_client.py +1 -1
  7. {fetch2gmail-1.0.7 → fetch2gmail-1.0.8}/src/fetcher/web_ui.py +341 -190
  8. {fetch2gmail-1.0.7 → fetch2gmail-1.0.8}/LICENSE +0 -0
  9. {fetch2gmail-1.0.7 → fetch2gmail-1.0.8}/setup.cfg +0 -0
  10. {fetch2gmail-1.0.7 → fetch2gmail-1.0.8}/src/fetch2gmail.egg-info/SOURCES.txt +0 -0
  11. {fetch2gmail-1.0.7 → fetch2gmail-1.0.8}/src/fetch2gmail.egg-info/dependency_links.txt +0 -0
  12. {fetch2gmail-1.0.7 → fetch2gmail-1.0.8}/src/fetch2gmail.egg-info/entry_points.txt +0 -0
  13. {fetch2gmail-1.0.7 → fetch2gmail-1.0.8}/src/fetch2gmail.egg-info/requires.txt +0 -0
  14. {fetch2gmail-1.0.7 → fetch2gmail-1.0.8}/src/fetch2gmail.egg-info/top_level.txt +0 -0
  15. {fetch2gmail-1.0.7 → fetch2gmail-1.0.8}/src/fetcher/__init__.py +0 -0
  16. {fetch2gmail-1.0.7 → fetch2gmail-1.0.8}/src/fetcher/auth_server.py +0 -0
  17. {fetch2gmail-1.0.7 → fetch2gmail-1.0.8}/src/fetcher/auth_ui.py +0 -0
  18. {fetch2gmail-1.0.7 → fetch2gmail-1.0.8}/src/fetcher/cli.py +0 -0
  19. {fetch2gmail-1.0.7 → fetch2gmail-1.0.8}/src/fetcher/config.py +0 -0
  20. {fetch2gmail-1.0.7 → fetch2gmail-1.0.8}/src/fetcher/imap_client.py +0 -0
  21. {fetch2gmail-1.0.7 → fetch2gmail-1.0.8}/src/fetcher/log_buffer.py +0 -0
  22. {fetch2gmail-1.0.7 → fetch2gmail-1.0.8}/src/fetcher/run.py +0 -0
  23. {fetch2gmail-1.0.7 → fetch2gmail-1.0.8}/src/fetcher/state.py +0 -0
  24. {fetch2gmail-1.0.7 → fetch2gmail-1.0.8}/src/fetcher/ui_auth.py +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: fetch2gmail
3
- Version: 1.0.7
3
+ Version: 1.0.8
4
4
  Summary: Self-hosted email fetcher: IMAP to Gmail API import with idempotent state tracking
5
5
  Author: Fetch2Gmail Contributors
6
6
  License-Expression: MIT
@@ -108,18 +108,14 @@ pipx ensurepath
108
108
  pipx install fetch2gmail
109
109
  ```
110
110
 
111
- The app will find your token and files in `/opt/fetch2gmail` because in step 9 you install a single systemd service that sets **WorkingDirectory** and **FETCH2GMAIL_CONFIG** to that directory. For step 8 you **cd** into `/opt/fetch2gmail` before running `set-ui-password` so the password file is stored there.
111
+ The app will find your token and files in `/opt/fetch2gmail` because in step 9 you install a single systemd service that sets **WorkingDirectory** and **FETCH2GMAIL_CONFIG** to that directory. If you set the UI password from the CLI (step 8), **cd** into `/opt/fetch2gmail` first so **.ui_auth** is created there.
112
112
 
113
113
  **Step 8. Set the UI username and password**
114
114
 
115
- Run once so only you can access the web UI (username and hashed password are stored in **.ui_auth**):
115
+ The web UI is protected by a username and password (stored as a hash in **.ui_auth**). You can set it from the CLI or from the UI:
116
116
 
117
- ```bash
118
- cd /opt/fetch2gmail
119
- fetch2gmail set-ui-password
120
- ```
121
-
122
- Enter a username and password when prompted.
117
+ - **From the CLI:** Run `cd /opt/fetch2gmail` then `fetch2gmail set-ui-password` and enter username and password when prompted.
118
+ - **From the UI:** If **.ui_auth** does not exist yet, open the web UI and you will see the Set UI password wizard. Set a username and password there; after that, the UI will require them (HTTP Basic Auth). You cannot create config or use the app until a UI password is set.
123
119
 
124
120
  **Step 9. Install and enable the systemd service (one service: web UI + background fetch)**
125
121
 
@@ -154,7 +150,7 @@ Open **http://\<server-ip\>:8765** in your browser (e.g. http://192.168.1.10:876
154
150
 
155
151
  ## Use case 2: Device with a browser (one machine)
156
152
 
157
- Everything runs on **one machine** (laptop or desktop) that has a browser. You sign in with Google in the web UI — the redirect works because you open the UI on localhost. You do **not** need to run `fetch2gmail auth` or set a UI password. Follow the steps in order.
153
+ Everything runs on **one machine** (laptop or desktop) that has a browser. You get **token.json** via **`fetch2gmail auth`** (CLI); the web UI does not have "Sign in with Google". Then set a UI password and configure ISP mail in the UI. Follow the steps in order.
158
154
 
159
155
  **Step 1. Get credentials.json from Google Cloud**
160
156
 
@@ -181,7 +177,11 @@ mkdir -p ~/fetch2gmail
181
177
 
182
178
  Use the same path in the steps below (replace `~/fetch2gmail` if you use something else).
183
179
 
184
- **Step 5. Install and enable the systemd service**
180
+ **Step 5. Get token.json (CLI)**
181
+
182
+ **cd** into your data directory and run **`fetch2gmail auth`**. A browser opens; sign in with the Gmail account that will receive the imported mail and click Allow. **token.json** is saved in that folder. Press **Ctrl+C** to stop the auth server.
183
+
184
+ **Step 6. Install and enable the systemd service**
185
185
 
186
186
  Same as Use case 1, step 9: one service (web UI + background fetch). Replace **YOUR_USER** and the path with yours:
187
187
 
@@ -192,13 +192,9 @@ sudo systemctl enable fetch2gmail
192
192
  sudo systemctl start fetch2gmail
193
193
  ```
194
194
 
195
- **Step 6. Sign in with Google in the web UI**
196
-
197
- Open **http://127.0.0.1:8765** in your browser (**use localhost** so the Google OAuth redirect works). You will see **Sign in with Google** — click it, sign in with the Gmail account that will receive the imported mail, and click Allow. The app saves **token.json** in your data directory. You are now signed in.
195
+ **Step 7. Set UI password and configure ISP mail**
198
196
 
199
- **Step 7. Configure ISP mail in the web UI**
200
-
201
- Use the **initial setup** form to enter your IMAP host, username, password, mailbox, and Gmail label, then click **Create config**. The app stores your password securely and the timer runs the fetch on the schedule you set (every 5 minutes by default).
197
+ Open **http://127.0.0.1:8765** in your browser. If **.ui_auth** does not exist yet, you will see the Set UI password wizard; set a username and password there (or run `fetch2gmail set-ui-password` from the CLI). Then use the **initial setup** form to enter your IMAP host, username, password, mailbox, and Gmail label, and click **Create config**. The app stores your password securely and the timer runs the fetch on the schedule you set (every 5 minutes by default).
202
198
 
203
199
  **Done.**
204
200
 
@@ -226,9 +222,48 @@ All app files live in **one directory**: **config.json**, **credentials.json**,
226
222
  ### Security
227
223
 
228
224
  - Do not commit **credentials.json**, **token.json**, or **config.json** with secrets. Restrict file permissions to the user running the service.
229
- - On the server, the UI is protected by the username and password you set with **`fetch2gmail set-ui-password`** (stored as a hash in **.ui_auth**). There is no Google sign-in on the server when **token.json** is already there.
225
+ - The UI is protected by a username and password in **.ui_auth** (when set). Get **token.json** via **`fetch2gmail auth`** (CLI only; there is no "Sign in with Google" in the UI).
230
226
  - The Gmail scope requested is **gmail.modify** (read and modify labels/messages only).
231
227
 
228
+ ### Multiple accounts (multiple instances)
229
+
230
+ One instance = one IMAP mailbox → one Gmail account. To run **multiple accounts** (e.g. two ISP mailboxes forwarding to two Gmail addresses), run **multiple instances**, each with its own data directory and **its own port** so the UIs don’t conflict.
231
+
232
+ **Second instance (example):**
233
+
234
+ 1. Create a second data directory and put config and credentials there (e.g. `/opt/fetch2gmail2` with its own **config.json**, **credentials.json**, **token.json**, **.env**). Use the same GCP **credentials.json** if you like; get a separate **token.json** for the second Gmail account (run `fetch2gmail auth` and sign in with the second Gmail, then copy that **token.json** into the second directory).
235
+
236
+ 2. Generate a second systemd unit with a **different port** and unit name:
237
+ ```bash
238
+ fetch2gmail install-service --user YOUR_USER --dir /opt/fetch2gmail2 -o /tmp/fetch2gmail2.service
239
+ ```
240
+ Edit `/tmp/fetch2gmail2.service`: in **ExecStart**, add **`--port 8766`** so this instance uses port 8766 (the first stays on 8765). Set **WorkingDirectory** and **Environment=FETCH2GMAIL_CONFIG** to the second directory (e.g. `/opt/fetch2gmail2`, `/opt/fetch2gmail2/config.json`).
241
+
242
+ 3. Install and enable the second unit under a different name so both can run:
243
+ ```bash
244
+ sudo mv /tmp/fetch2gmail2.service /etc/systemd/system/fetch2gmail2.service
245
+ sudo systemctl daemon-reload
246
+ sudo systemctl enable fetch2gmail2
247
+ sudo systemctl start fetch2gmail2
248
+ ```
249
+ Run **`fetch2gmail set-ui-password`** once from the second directory (or with **FETCH2GMAIL_CONFIG** set to the second config) so the second UI is protected.
250
+
251
+ 4. Open the first UI at **http://server:8765** and the second at **http://server:8766**. Each has its own config, token, and poller.
252
+
253
+ **You need a different port per instance** — each `fetch2gmail serve` binds to one port, so a second instance must use `--port 8766` (or another free port).
254
+
255
+ ### Troubleshooting
256
+
257
+ **"Background fetch skipped: IMAP password could not be decrypted"** — The encrypted IMAP password in **.env** was created with a different encryption key (e.g. different config directory or **.cookie_secret**). Re-enter the IMAP password in the UI (Config section) and Save to re-encrypt it.
258
+
259
+ To see what the service is doing (background poller, fetch results, errors), stream the logs:
260
+
261
+ ```bash
262
+ journalctl -u fetch2gmail -f
263
+ ```
264
+
265
+ You’ll see messages like "Poller: next fetch in Xs", "Poller: running fetch now", and "Background fetch: imported=...". Use **Ctrl+C** to stop following. For a second instance (e.g. **fetch2gmail2**), use `journalctl -u fetch2gmail2 -f`.
266
+
232
267
  ### CLI
233
268
 
234
269
  | Command | Purpose |
@@ -236,10 +271,34 @@ All app files live in **one directory**: **config.json**, **credentials.json**,
236
271
  | `fetch2gmail auth` | Get **token.json** on a machine with a browser (opens http://127.0.0.1:8765). |
237
272
  | `fetch2gmail set-ui-password` | Set UI username and password (hash in **.ui_auth**). |
238
273
  | `fetch2gmail install-service` | Generate systemd unit file (one service: web UI + background fetch). Use `--user`, `--dir`, and optionally `--output` or pipe to `sudo tee`. |
239
- | `fetch2gmail serve` | Run the web UI (default: localhost only; use `--host 0.0.0.0` to bind to all interfaces). |
274
+ | `fetch2gmail serve` | Run the web UI. By default uses the **current directory** for config, credentials, and token; use `--port` and `--host` as needed. See below. |
240
275
  | `fetch2gmail run` | Run one fetch cycle. |
241
276
  | `fetch2gmail run --dry-run` | Connect to ISP and show what would be imported; no Gmail import, no delete. |
242
277
 
278
+ **`fetch2gmail serve` — defaults and options**
279
+
280
+ - **Default:** The app uses the **current working directory** as the data directory: it looks for **config.json**, **credentials.json**, **token.json**, and **.env** in the directory you run the command from. So from a folder that already has those (or at least credentials and token), run `fetch2gmail serve` and open http://127.0.0.1:8765.
281
+ - **Options:**
282
+ - **`--port 8766`** — Use a different port (default 8765). Useful if 8765 is in use or you run multiple instances.
283
+ - **`--host 0.0.0.0`** — Bind to all interfaces (e.g. to reach the UI from another device on the LAN). Default is 127.0.0.1 (localhost only).
284
+ - **`FETCH2GMAIL_CONFIG=/path/to/config.json`** — Use a different data directory. The path must be the **full path to config.json** inside that directory; the app will look for credentials, token, and .env in the same directory. Use this when you run `fetch2gmail serve` from one place (e.g. your git clone) but want to use config and data from another (e.g. `/home/sarah/Desktop/config.json`).
285
+
286
+ ### Updating
287
+
288
+ If you installed with **pipx**, upgrade to the latest release with:
289
+
290
+ ```bash
291
+ pipx upgrade fetch2gmail
292
+ ```
293
+
294
+ You do **not** need to stop the service, remove the systemd unit, or uninstall first. The service will use the new version the next time it runs (e.g. after a reboot), or restart it now to pick up the update:
295
+
296
+ ```bash
297
+ sudo systemctl restart fetch2gmail
298
+ ```
299
+
300
+ Your config, token, and data directory are unchanged.
301
+
243
302
  ### Uninstall
244
303
 
245
304
  **Machine used only to get the token (no system service):** After copying **credentials.json** and **token.json** to the server, remove the app: `pipx uninstall fetch2gmail`. Reinstall with `pipx install fetch2gmail` if you need to run `fetch2gmail auth` again later.
@@ -290,21 +349,12 @@ To run from a git clone (e.g. to test changes before pushing):
290
349
  ```
291
350
  Optional, for tests: `pip install -e ".[dev]"`
292
351
 
293
- 4. **Run and test** (use the same terminal with the venv active):
294
- - `fetch2gmail serve` — web UI at http://127.0.0.1:8765
295
- - `fetch2gmail auth` — get token (put **credentials.json** in the current directory first)
296
- - `fetch2gmail run` or `fetch2gmail run --dry-run` — if you have **config.json** and secrets set up
297
-
298
- **Testing the UI locally (no need to reinstall or touch the service):** To try code changes without stopping the system service or reinstalling, run the UI from your clone on a **different port** so it doesn’t conflict with the service. Point the app at your data directory (where your config, credentials, token, and `.ui_auth` live) so it finds everything:
299
-
300
- ```bash
301
- cd /path/to/your/fetch2gmail # your git clone
302
- source .venv/bin/activate # or .venv\Scripts\activate on Windows
303
- pip install -e . # if you haven’t already (editable = your changes are used)
304
- FETCH2GMAIL_CONFIG=/path/to/your/data/config.json fetch2gmail serve --port 8766
305
- ```
352
+ 4. **Run and test** (use the same terminal with the venv active; no pipx needed—the editable install provides the `fetch2gmail` command):
353
+ - **`fetch2gmail serve`** — Run the web UI. **Default: uses the current directory** for config, credentials, and token. So put **credentials.json** and **token.json** in your project directory (or any folder), **cd** there, run `fetch2gmail serve`, and open http://127.0.0.1:8765. Optionally add **`--port 8766`** to use another port. No need to set `FETCH2GMAIL_CONFIG` when you run from the directory that has your data.
354
+ - **`fetch2gmail auth`** — Get token. **cd** into the directory that has **credentials.json** (or pass `--credentials` and `--token`), then run it; a browser opens for Google sign-in and **token.json** is written there. Use **`--port 8766`** if 8765 is in use.
355
+ - **`fetch2gmail run`** or **`fetch2gmail run --dry-run`** — If you have **config.json** and secrets set up (again, run from the data directory or set `FETCH2GMAIL_CONFIG`).
306
356
 
307
- Replace `/path/to/your/data` with your actual data directory (e.g. `/opt/fetch2gmail` or `~/fetch2gmail`). Then open **http://127.0.0.1:8766** in your browser. The system service (if it’s running) stays on 8765; this process uses your local code. Edit code, restart this command, and refresh the browser to test. If you prefer to use port 8765, stop the service first (`sudo systemctl stop fetch2gmail`), run `fetch2gmail serve` (no `--port`), then start the service again when you’re done.
357
+ **Using a different data directory:** If you want to run `fetch2gmail serve` from your git clone but use config and data from another folder (e.g. **credentials.json** and **token.json** on your Desktop), set **`FETCH2GMAIL_CONFIG`** to the full path to **config.json** in that folder (e.g. `FETCH2GMAIL_CONFIG=/home/sarah/Desktop/config.json`). **config.json** does not need to exist yet—the UI creates it when you complete the setup form.
308
358
 
309
359
  5. **Before pushing: test the build** so the package still builds and you catch errors:
310
360
  ```bash
@@ -77,18 +77,14 @@ pipx ensurepath
77
77
  pipx install fetch2gmail
78
78
  ```
79
79
 
80
- The app will find your token and files in `/opt/fetch2gmail` because in step 9 you install a single systemd service that sets **WorkingDirectory** and **FETCH2GMAIL_CONFIG** to that directory. For step 8 you **cd** into `/opt/fetch2gmail` before running `set-ui-password` so the password file is stored there.
80
+ The app will find your token and files in `/opt/fetch2gmail` because in step 9 you install a single systemd service that sets **WorkingDirectory** and **FETCH2GMAIL_CONFIG** to that directory. If you set the UI password from the CLI (step 8), **cd** into `/opt/fetch2gmail` first so **.ui_auth** is created there.
81
81
 
82
82
  **Step 8. Set the UI username and password**
83
83
 
84
- Run once so only you can access the web UI (username and hashed password are stored in **.ui_auth**):
84
+ The web UI is protected by a username and password (stored as a hash in **.ui_auth**). You can set it from the CLI or from the UI:
85
85
 
86
- ```bash
87
- cd /opt/fetch2gmail
88
- fetch2gmail set-ui-password
89
- ```
90
-
91
- Enter a username and password when prompted.
86
+ - **From the CLI:** Run `cd /opt/fetch2gmail` then `fetch2gmail set-ui-password` and enter username and password when prompted.
87
+ - **From the UI:** If **.ui_auth** does not exist yet, open the web UI and you will see the Set UI password wizard. Set a username and password there; after that, the UI will require them (HTTP Basic Auth). You cannot create config or use the app until a UI password is set.
92
88
 
93
89
  **Step 9. Install and enable the systemd service (one service: web UI + background fetch)**
94
90
 
@@ -123,7 +119,7 @@ Open **http://\<server-ip\>:8765** in your browser (e.g. http://192.168.1.10:876
123
119
 
124
120
  ## Use case 2: Device with a browser (one machine)
125
121
 
126
- Everything runs on **one machine** (laptop or desktop) that has a browser. You sign in with Google in the web UI — the redirect works because you open the UI on localhost. You do **not** need to run `fetch2gmail auth` or set a UI password. Follow the steps in order.
122
+ Everything runs on **one machine** (laptop or desktop) that has a browser. You get **token.json** via **`fetch2gmail auth`** (CLI); the web UI does not have "Sign in with Google". Then set a UI password and configure ISP mail in the UI. Follow the steps in order.
127
123
 
128
124
  **Step 1. Get credentials.json from Google Cloud**
129
125
 
@@ -150,7 +146,11 @@ mkdir -p ~/fetch2gmail
150
146
 
151
147
  Use the same path in the steps below (replace `~/fetch2gmail` if you use something else).
152
148
 
153
- **Step 5. Install and enable the systemd service**
149
+ **Step 5. Get token.json (CLI)**
150
+
151
+ **cd** into your data directory and run **`fetch2gmail auth`**. A browser opens; sign in with the Gmail account that will receive the imported mail and click Allow. **token.json** is saved in that folder. Press **Ctrl+C** to stop the auth server.
152
+
153
+ **Step 6. Install and enable the systemd service**
154
154
 
155
155
  Same as Use case 1, step 9: one service (web UI + background fetch). Replace **YOUR_USER** and the path with yours:
156
156
 
@@ -161,13 +161,9 @@ sudo systemctl enable fetch2gmail
161
161
  sudo systemctl start fetch2gmail
162
162
  ```
163
163
 
164
- **Step 6. Sign in with Google in the web UI**
165
-
166
- Open **http://127.0.0.1:8765** in your browser (**use localhost** so the Google OAuth redirect works). You will see **Sign in with Google** — click it, sign in with the Gmail account that will receive the imported mail, and click Allow. The app saves **token.json** in your data directory. You are now signed in.
164
+ **Step 7. Set UI password and configure ISP mail**
167
165
 
168
- **Step 7. Configure ISP mail in the web UI**
169
-
170
- Use the **initial setup** form to enter your IMAP host, username, password, mailbox, and Gmail label, then click **Create config**. The app stores your password securely and the timer runs the fetch on the schedule you set (every 5 minutes by default).
166
+ Open **http://127.0.0.1:8765** in your browser. If **.ui_auth** does not exist yet, you will see the Set UI password wizard; set a username and password there (or run `fetch2gmail set-ui-password` from the CLI). Then use the **initial setup** form to enter your IMAP host, username, password, mailbox, and Gmail label, and click **Create config**. The app stores your password securely and the timer runs the fetch on the schedule you set (every 5 minutes by default).
171
167
 
172
168
  **Done.**
173
169
 
@@ -195,9 +191,48 @@ All app files live in **one directory**: **config.json**, **credentials.json**,
195
191
  ### Security
196
192
 
197
193
  - Do not commit **credentials.json**, **token.json**, or **config.json** with secrets. Restrict file permissions to the user running the service.
198
- - On the server, the UI is protected by the username and password you set with **`fetch2gmail set-ui-password`** (stored as a hash in **.ui_auth**). There is no Google sign-in on the server when **token.json** is already there.
194
+ - The UI is protected by a username and password in **.ui_auth** (when set). Get **token.json** via **`fetch2gmail auth`** (CLI only; there is no "Sign in with Google" in the UI).
199
195
  - The Gmail scope requested is **gmail.modify** (read and modify labels/messages only).
200
196
 
197
+ ### Multiple accounts (multiple instances)
198
+
199
+ One instance = one IMAP mailbox → one Gmail account. To run **multiple accounts** (e.g. two ISP mailboxes forwarding to two Gmail addresses), run **multiple instances**, each with its own data directory and **its own port** so the UIs don’t conflict.
200
+
201
+ **Second instance (example):**
202
+
203
+ 1. Create a second data directory and put config and credentials there (e.g. `/opt/fetch2gmail2` with its own **config.json**, **credentials.json**, **token.json**, **.env**). Use the same GCP **credentials.json** if you like; get a separate **token.json** for the second Gmail account (run `fetch2gmail auth` and sign in with the second Gmail, then copy that **token.json** into the second directory).
204
+
205
+ 2. Generate a second systemd unit with a **different port** and unit name:
206
+ ```bash
207
+ fetch2gmail install-service --user YOUR_USER --dir /opt/fetch2gmail2 -o /tmp/fetch2gmail2.service
208
+ ```
209
+ Edit `/tmp/fetch2gmail2.service`: in **ExecStart**, add **`--port 8766`** so this instance uses port 8766 (the first stays on 8765). Set **WorkingDirectory** and **Environment=FETCH2GMAIL_CONFIG** to the second directory (e.g. `/opt/fetch2gmail2`, `/opt/fetch2gmail2/config.json`).
210
+
211
+ 3. Install and enable the second unit under a different name so both can run:
212
+ ```bash
213
+ sudo mv /tmp/fetch2gmail2.service /etc/systemd/system/fetch2gmail2.service
214
+ sudo systemctl daemon-reload
215
+ sudo systemctl enable fetch2gmail2
216
+ sudo systemctl start fetch2gmail2
217
+ ```
218
+ Run **`fetch2gmail set-ui-password`** once from the second directory (or with **FETCH2GMAIL_CONFIG** set to the second config) so the second UI is protected.
219
+
220
+ 4. Open the first UI at **http://server:8765** and the second at **http://server:8766**. Each has its own config, token, and poller.
221
+
222
+ **You need a different port per instance** — each `fetch2gmail serve` binds to one port, so a second instance must use `--port 8766` (or another free port).
223
+
224
+ ### Troubleshooting
225
+
226
+ **"Background fetch skipped: IMAP password could not be decrypted"** — The encrypted IMAP password in **.env** was created with a different encryption key (e.g. different config directory or **.cookie_secret**). Re-enter the IMAP password in the UI (Config section) and Save to re-encrypt it.
227
+
228
+ To see what the service is doing (background poller, fetch results, errors), stream the logs:
229
+
230
+ ```bash
231
+ journalctl -u fetch2gmail -f
232
+ ```
233
+
234
+ You’ll see messages like "Poller: next fetch in Xs", "Poller: running fetch now", and "Background fetch: imported=...". Use **Ctrl+C** to stop following. For a second instance (e.g. **fetch2gmail2**), use `journalctl -u fetch2gmail2 -f`.
235
+
201
236
  ### CLI
202
237
 
203
238
  | Command | Purpose |
@@ -205,10 +240,34 @@ All app files live in **one directory**: **config.json**, **credentials.json**,
205
240
  | `fetch2gmail auth` | Get **token.json** on a machine with a browser (opens http://127.0.0.1:8765). |
206
241
  | `fetch2gmail set-ui-password` | Set UI username and password (hash in **.ui_auth**). |
207
242
  | `fetch2gmail install-service` | Generate systemd unit file (one service: web UI + background fetch). Use `--user`, `--dir`, and optionally `--output` or pipe to `sudo tee`. |
208
- | `fetch2gmail serve` | Run the web UI (default: localhost only; use `--host 0.0.0.0` to bind to all interfaces). |
243
+ | `fetch2gmail serve` | Run the web UI. By default uses the **current directory** for config, credentials, and token; use `--port` and `--host` as needed. See below. |
209
244
  | `fetch2gmail run` | Run one fetch cycle. |
210
245
  | `fetch2gmail run --dry-run` | Connect to ISP and show what would be imported; no Gmail import, no delete. |
211
246
 
247
+ **`fetch2gmail serve` — defaults and options**
248
+
249
+ - **Default:** The app uses the **current working directory** as the data directory: it looks for **config.json**, **credentials.json**, **token.json**, and **.env** in the directory you run the command from. So from a folder that already has those (or at least credentials and token), run `fetch2gmail serve` and open http://127.0.0.1:8765.
250
+ - **Options:**
251
+ - **`--port 8766`** — Use a different port (default 8765). Useful if 8765 is in use or you run multiple instances.
252
+ - **`--host 0.0.0.0`** — Bind to all interfaces (e.g. to reach the UI from another device on the LAN). Default is 127.0.0.1 (localhost only).
253
+ - **`FETCH2GMAIL_CONFIG=/path/to/config.json`** — Use a different data directory. The path must be the **full path to config.json** inside that directory; the app will look for credentials, token, and .env in the same directory. Use this when you run `fetch2gmail serve` from one place (e.g. your git clone) but want to use config and data from another (e.g. `/home/sarah/Desktop/config.json`).
254
+
255
+ ### Updating
256
+
257
+ If you installed with **pipx**, upgrade to the latest release with:
258
+
259
+ ```bash
260
+ pipx upgrade fetch2gmail
261
+ ```
262
+
263
+ You do **not** need to stop the service, remove the systemd unit, or uninstall first. The service will use the new version the next time it runs (e.g. after a reboot), or restart it now to pick up the update:
264
+
265
+ ```bash
266
+ sudo systemctl restart fetch2gmail
267
+ ```
268
+
269
+ Your config, token, and data directory are unchanged.
270
+
212
271
  ### Uninstall
213
272
 
214
273
  **Machine used only to get the token (no system service):** After copying **credentials.json** and **token.json** to the server, remove the app: `pipx uninstall fetch2gmail`. Reinstall with `pipx install fetch2gmail` if you need to run `fetch2gmail auth` again later.
@@ -259,21 +318,12 @@ To run from a git clone (e.g. to test changes before pushing):
259
318
  ```
260
319
  Optional, for tests: `pip install -e ".[dev]"`
261
320
 
262
- 4. **Run and test** (use the same terminal with the venv active):
263
- - `fetch2gmail serve` — web UI at http://127.0.0.1:8765
264
- - `fetch2gmail auth` — get token (put **credentials.json** in the current directory first)
265
- - `fetch2gmail run` or `fetch2gmail run --dry-run` — if you have **config.json** and secrets set up
266
-
267
- **Testing the UI locally (no need to reinstall or touch the service):** To try code changes without stopping the system service or reinstalling, run the UI from your clone on a **different port** so it doesn’t conflict with the service. Point the app at your data directory (where your config, credentials, token, and `.ui_auth` live) so it finds everything:
268
-
269
- ```bash
270
- cd /path/to/your/fetch2gmail # your git clone
271
- source .venv/bin/activate # or .venv\Scripts\activate on Windows
272
- pip install -e . # if you haven’t already (editable = your changes are used)
273
- FETCH2GMAIL_CONFIG=/path/to/your/data/config.json fetch2gmail serve --port 8766
274
- ```
321
+ 4. **Run and test** (use the same terminal with the venv active; no pipx needed—the editable install provides the `fetch2gmail` command):
322
+ - **`fetch2gmail serve`** — Run the web UI. **Default: uses the current directory** for config, credentials, and token. So put **credentials.json** and **token.json** in your project directory (or any folder), **cd** there, run `fetch2gmail serve`, and open http://127.0.0.1:8765. Optionally add **`--port 8766`** to use another port. No need to set `FETCH2GMAIL_CONFIG` when you run from the directory that has your data.
323
+ - **`fetch2gmail auth`** — Get token. **cd** into the directory that has **credentials.json** (or pass `--credentials` and `--token`), then run it; a browser opens for Google sign-in and **token.json** is written there. Use **`--port 8766`** if 8765 is in use.
324
+ - **`fetch2gmail run`** or **`fetch2gmail run --dry-run`** — If you have **config.json** and secrets set up (again, run from the data directory or set `FETCH2GMAIL_CONFIG`).
275
325
 
276
- Replace `/path/to/your/data` with your actual data directory (e.g. `/opt/fetch2gmail` or `~/fetch2gmail`). Then open **http://127.0.0.1:8766** in your browser. The system service (if it’s running) stays on 8765; this process uses your local code. Edit code, restart this command, and refresh the browser to test. If you prefer to use port 8765, stop the service first (`sudo systemctl stop fetch2gmail`), run `fetch2gmail serve` (no `--port`), then start the service again when you’re done.
326
+ **Using a different data directory:** If you want to run `fetch2gmail serve` from your git clone but use config and data from another folder (e.g. **credentials.json** and **token.json** on your Desktop), set **`FETCH2GMAIL_CONFIG`** to the full path to **config.json** in that folder (e.g. `FETCH2GMAIL_CONFIG=/home/sarah/Desktop/config.json`). **config.json** does not need to exist yet—the UI creates it when you complete the setup form.
277
327
 
278
328
  5. **Before pushing: test the build** so the package still builds and you catch errors:
279
329
  ```bash
@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
4
4
 
5
5
  [project]
6
6
  name = "fetch2gmail"
7
- version = "1.0.7"
7
+ version = "1.0.8"
8
8
  description = "Self-hosted email fetcher: IMAP to Gmail API import with idempotent state tracking"
9
9
  readme = "README.md"
10
10
  license = "MIT"
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: fetch2gmail
3
- Version: 1.0.7
3
+ Version: 1.0.8
4
4
  Summary: Self-hosted email fetcher: IMAP to Gmail API import with idempotent state tracking
5
5
  Author: Fetch2Gmail Contributors
6
6
  License-Expression: MIT
@@ -108,18 +108,14 @@ pipx ensurepath
108
108
  pipx install fetch2gmail
109
109
  ```
110
110
 
111
- The app will find your token and files in `/opt/fetch2gmail` because in step 9 you install a single systemd service that sets **WorkingDirectory** and **FETCH2GMAIL_CONFIG** to that directory. For step 8 you **cd** into `/opt/fetch2gmail` before running `set-ui-password` so the password file is stored there.
111
+ The app will find your token and files in `/opt/fetch2gmail` because in step 9 you install a single systemd service that sets **WorkingDirectory** and **FETCH2GMAIL_CONFIG** to that directory. If you set the UI password from the CLI (step 8), **cd** into `/opt/fetch2gmail` first so **.ui_auth** is created there.
112
112
 
113
113
  **Step 8. Set the UI username and password**
114
114
 
115
- Run once so only you can access the web UI (username and hashed password are stored in **.ui_auth**):
115
+ The web UI is protected by a username and password (stored as a hash in **.ui_auth**). You can set it from the CLI or from the UI:
116
116
 
117
- ```bash
118
- cd /opt/fetch2gmail
119
- fetch2gmail set-ui-password
120
- ```
121
-
122
- Enter a username and password when prompted.
117
+ - **From the CLI:** Run `cd /opt/fetch2gmail` then `fetch2gmail set-ui-password` and enter username and password when prompted.
118
+ - **From the UI:** If **.ui_auth** does not exist yet, open the web UI and you will see the Set UI password wizard. Set a username and password there; after that, the UI will require them (HTTP Basic Auth). You cannot create config or use the app until a UI password is set.
123
119
 
124
120
  **Step 9. Install and enable the systemd service (one service: web UI + background fetch)**
125
121
 
@@ -154,7 +150,7 @@ Open **http://\<server-ip\>:8765** in your browser (e.g. http://192.168.1.10:876
154
150
 
155
151
  ## Use case 2: Device with a browser (one machine)
156
152
 
157
- Everything runs on **one machine** (laptop or desktop) that has a browser. You sign in with Google in the web UI — the redirect works because you open the UI on localhost. You do **not** need to run `fetch2gmail auth` or set a UI password. Follow the steps in order.
153
+ Everything runs on **one machine** (laptop or desktop) that has a browser. You get **token.json** via **`fetch2gmail auth`** (CLI); the web UI does not have "Sign in with Google". Then set a UI password and configure ISP mail in the UI. Follow the steps in order.
158
154
 
159
155
  **Step 1. Get credentials.json from Google Cloud**
160
156
 
@@ -181,7 +177,11 @@ mkdir -p ~/fetch2gmail
181
177
 
182
178
  Use the same path in the steps below (replace `~/fetch2gmail` if you use something else).
183
179
 
184
- **Step 5. Install and enable the systemd service**
180
+ **Step 5. Get token.json (CLI)**
181
+
182
+ **cd** into your data directory and run **`fetch2gmail auth`**. A browser opens; sign in with the Gmail account that will receive the imported mail and click Allow. **token.json** is saved in that folder. Press **Ctrl+C** to stop the auth server.
183
+
184
+ **Step 6. Install and enable the systemd service**
185
185
 
186
186
  Same as Use case 1, step 9: one service (web UI + background fetch). Replace **YOUR_USER** and the path with yours:
187
187
 
@@ -192,13 +192,9 @@ sudo systemctl enable fetch2gmail
192
192
  sudo systemctl start fetch2gmail
193
193
  ```
194
194
 
195
- **Step 6. Sign in with Google in the web UI**
196
-
197
- Open **http://127.0.0.1:8765** in your browser (**use localhost** so the Google OAuth redirect works). You will see **Sign in with Google** — click it, sign in with the Gmail account that will receive the imported mail, and click Allow. The app saves **token.json** in your data directory. You are now signed in.
195
+ **Step 7. Set UI password and configure ISP mail**
198
196
 
199
- **Step 7. Configure ISP mail in the web UI**
200
-
201
- Use the **initial setup** form to enter your IMAP host, username, password, mailbox, and Gmail label, then click **Create config**. The app stores your password securely and the timer runs the fetch on the schedule you set (every 5 minutes by default).
197
+ Open **http://127.0.0.1:8765** in your browser. If **.ui_auth** does not exist yet, you will see the Set UI password wizard; set a username and password there (or run `fetch2gmail set-ui-password` from the CLI). Then use the **initial setup** form to enter your IMAP host, username, password, mailbox, and Gmail label, and click **Create config**. The app stores your password securely and the timer runs the fetch on the schedule you set (every 5 minutes by default).
202
198
 
203
199
  **Done.**
204
200
 
@@ -226,9 +222,48 @@ All app files live in **one directory**: **config.json**, **credentials.json**,
226
222
  ### Security
227
223
 
228
224
  - Do not commit **credentials.json**, **token.json**, or **config.json** with secrets. Restrict file permissions to the user running the service.
229
- - On the server, the UI is protected by the username and password you set with **`fetch2gmail set-ui-password`** (stored as a hash in **.ui_auth**). There is no Google sign-in on the server when **token.json** is already there.
225
+ - The UI is protected by a username and password in **.ui_auth** (when set). Get **token.json** via **`fetch2gmail auth`** (CLI only; there is no "Sign in with Google" in the UI).
230
226
  - The Gmail scope requested is **gmail.modify** (read and modify labels/messages only).
231
227
 
228
+ ### Multiple accounts (multiple instances)
229
+
230
+ One instance = one IMAP mailbox → one Gmail account. To run **multiple accounts** (e.g. two ISP mailboxes forwarding to two Gmail addresses), run **multiple instances**, each with its own data directory and **its own port** so the UIs don’t conflict.
231
+
232
+ **Second instance (example):**
233
+
234
+ 1. Create a second data directory and put config and credentials there (e.g. `/opt/fetch2gmail2` with its own **config.json**, **credentials.json**, **token.json**, **.env**). Use the same GCP **credentials.json** if you like; get a separate **token.json** for the second Gmail account (run `fetch2gmail auth` and sign in with the second Gmail, then copy that **token.json** into the second directory).
235
+
236
+ 2. Generate a second systemd unit with a **different port** and unit name:
237
+ ```bash
238
+ fetch2gmail install-service --user YOUR_USER --dir /opt/fetch2gmail2 -o /tmp/fetch2gmail2.service
239
+ ```
240
+ Edit `/tmp/fetch2gmail2.service`: in **ExecStart**, add **`--port 8766`** so this instance uses port 8766 (the first stays on 8765). Set **WorkingDirectory** and **Environment=FETCH2GMAIL_CONFIG** to the second directory (e.g. `/opt/fetch2gmail2`, `/opt/fetch2gmail2/config.json`).
241
+
242
+ 3. Install and enable the second unit under a different name so both can run:
243
+ ```bash
244
+ sudo mv /tmp/fetch2gmail2.service /etc/systemd/system/fetch2gmail2.service
245
+ sudo systemctl daemon-reload
246
+ sudo systemctl enable fetch2gmail2
247
+ sudo systemctl start fetch2gmail2
248
+ ```
249
+ Run **`fetch2gmail set-ui-password`** once from the second directory (or with **FETCH2GMAIL_CONFIG** set to the second config) so the second UI is protected.
250
+
251
+ 4. Open the first UI at **http://server:8765** and the second at **http://server:8766**. Each has its own config, token, and poller.
252
+
253
+ **You need a different port per instance** — each `fetch2gmail serve` binds to one port, so a second instance must use `--port 8766` (or another free port).
254
+
255
+ ### Troubleshooting
256
+
257
+ **"Background fetch skipped: IMAP password could not be decrypted"** — The encrypted IMAP password in **.env** was created with a different encryption key (e.g. different config directory or **.cookie_secret**). Re-enter the IMAP password in the UI (Config section) and Save to re-encrypt it.
258
+
259
+ To see what the service is doing (background poller, fetch results, errors), stream the logs:
260
+
261
+ ```bash
262
+ journalctl -u fetch2gmail -f
263
+ ```
264
+
265
+ You’ll see messages like "Poller: next fetch in Xs", "Poller: running fetch now", and "Background fetch: imported=...". Use **Ctrl+C** to stop following. For a second instance (e.g. **fetch2gmail2**), use `journalctl -u fetch2gmail2 -f`.
266
+
232
267
  ### CLI
233
268
 
234
269
  | Command | Purpose |
@@ -236,10 +271,34 @@ All app files live in **one directory**: **config.json**, **credentials.json**,
236
271
  | `fetch2gmail auth` | Get **token.json** on a machine with a browser (opens http://127.0.0.1:8765). |
237
272
  | `fetch2gmail set-ui-password` | Set UI username and password (hash in **.ui_auth**). |
238
273
  | `fetch2gmail install-service` | Generate systemd unit file (one service: web UI + background fetch). Use `--user`, `--dir`, and optionally `--output` or pipe to `sudo tee`. |
239
- | `fetch2gmail serve` | Run the web UI (default: localhost only; use `--host 0.0.0.0` to bind to all interfaces). |
274
+ | `fetch2gmail serve` | Run the web UI. By default uses the **current directory** for config, credentials, and token; use `--port` and `--host` as needed. See below. |
240
275
  | `fetch2gmail run` | Run one fetch cycle. |
241
276
  | `fetch2gmail run --dry-run` | Connect to ISP and show what would be imported; no Gmail import, no delete. |
242
277
 
278
+ **`fetch2gmail serve` — defaults and options**
279
+
280
+ - **Default:** The app uses the **current working directory** as the data directory: it looks for **config.json**, **credentials.json**, **token.json**, and **.env** in the directory you run the command from. So from a folder that already has those (or at least credentials and token), run `fetch2gmail serve` and open http://127.0.0.1:8765.
281
+ - **Options:**
282
+ - **`--port 8766`** — Use a different port (default 8765). Useful if 8765 is in use or you run multiple instances.
283
+ - **`--host 0.0.0.0`** — Bind to all interfaces (e.g. to reach the UI from another device on the LAN). Default is 127.0.0.1 (localhost only).
284
+ - **`FETCH2GMAIL_CONFIG=/path/to/config.json`** — Use a different data directory. The path must be the **full path to config.json** inside that directory; the app will look for credentials, token, and .env in the same directory. Use this when you run `fetch2gmail serve` from one place (e.g. your git clone) but want to use config and data from another (e.g. `/home/sarah/Desktop/config.json`).
285
+
286
+ ### Updating
287
+
288
+ If you installed with **pipx**, upgrade to the latest release with:
289
+
290
+ ```bash
291
+ pipx upgrade fetch2gmail
292
+ ```
293
+
294
+ You do **not** need to stop the service, remove the systemd unit, or uninstall first. The service will use the new version the next time it runs (e.g. after a reboot), or restart it now to pick up the update:
295
+
296
+ ```bash
297
+ sudo systemctl restart fetch2gmail
298
+ ```
299
+
300
+ Your config, token, and data directory are unchanged.
301
+
243
302
  ### Uninstall
244
303
 
245
304
  **Machine used only to get the token (no system service):** After copying **credentials.json** and **token.json** to the server, remove the app: `pipx uninstall fetch2gmail`. Reinstall with `pipx install fetch2gmail` if you need to run `fetch2gmail auth` again later.
@@ -290,21 +349,12 @@ To run from a git clone (e.g. to test changes before pushing):
290
349
  ```
291
350
  Optional, for tests: `pip install -e ".[dev]"`
292
351
 
293
- 4. **Run and test** (use the same terminal with the venv active):
294
- - `fetch2gmail serve` — web UI at http://127.0.0.1:8765
295
- - `fetch2gmail auth` — get token (put **credentials.json** in the current directory first)
296
- - `fetch2gmail run` or `fetch2gmail run --dry-run` — if you have **config.json** and secrets set up
297
-
298
- **Testing the UI locally (no need to reinstall or touch the service):** To try code changes without stopping the system service or reinstalling, run the UI from your clone on a **different port** so it doesn’t conflict with the service. Point the app at your data directory (where your config, credentials, token, and `.ui_auth` live) so it finds everything:
299
-
300
- ```bash
301
- cd /path/to/your/fetch2gmail # your git clone
302
- source .venv/bin/activate # or .venv\Scripts\activate on Windows
303
- pip install -e . # if you haven’t already (editable = your changes are used)
304
- FETCH2GMAIL_CONFIG=/path/to/your/data/config.json fetch2gmail serve --port 8766
305
- ```
352
+ 4. **Run and test** (use the same terminal with the venv active; no pipx needed—the editable install provides the `fetch2gmail` command):
353
+ - **`fetch2gmail serve`** — Run the web UI. **Default: uses the current directory** for config, credentials, and token. So put **credentials.json** and **token.json** in your project directory (or any folder), **cd** there, run `fetch2gmail serve`, and open http://127.0.0.1:8765. Optionally add **`--port 8766`** to use another port. No need to set `FETCH2GMAIL_CONFIG` when you run from the directory that has your data.
354
+ - **`fetch2gmail auth`** — Get token. **cd** into the directory that has **credentials.json** (or pass `--credentials` and `--token`), then run it; a browser opens for Google sign-in and **token.json** is written there. Use **`--port 8766`** if 8765 is in use.
355
+ - **`fetch2gmail run`** or **`fetch2gmail run --dry-run`** — If you have **config.json** and secrets set up (again, run from the data directory or set `FETCH2GMAIL_CONFIG`).
306
356
 
307
- Replace `/path/to/your/data` with your actual data directory (e.g. `/opt/fetch2gmail` or `~/fetch2gmail`). Then open **http://127.0.0.1:8766** in your browser. The system service (if it’s running) stays on 8765; this process uses your local code. Edit code, restart this command, and refresh the browser to test. If you prefer to use port 8765, stop the service first (`sudo systemctl stop fetch2gmail`), run `fetch2gmail serve` (no `--port`), then start the service again when you’re done.
357
+ **Using a different data directory:** If you want to run `fetch2gmail serve` from your git clone but use config and data from another folder (e.g. **credentials.json** and **token.json** on your Desktop), set **`FETCH2GMAIL_CONFIG`** to the full path to **config.json** in that folder (e.g. `FETCH2GMAIL_CONFIG=/home/sarah/Desktop/config.json`). **config.json** does not need to exist yet—the UI creates it when you complete the setup form.
308
358
 
309
359
  5. **Before pushing: test the build** so the package still builds and you catch errors:
310
360
  ```bash
@@ -4,7 +4,7 @@ import base64
4
4
  import re
5
5
  from pathlib import Path
6
6
 
7
- from cryptography.fernet import Fernet
7
+ from cryptography.fernet import Fernet, InvalidToken
8
8
 
9
9
  from .auth_ui import get_or_create_cookie_secret
10
10
 
@@ -45,5 +45,11 @@ def set_encrypted_env(config_dir: Path, key: str, value: str) -> None:
45
45
 
46
46
  def decrypt_env_value(config_dir: Path, encrypted_b64: str) -> str:
47
47
  """Decrypt a value stored with set_encrypted_env."""
48
- fernet = _fernet_for_config_dir(config_dir)
49
- return fernet.decrypt(encrypted_b64.encode("ascii")).decode("utf-8")
48
+ try:
49
+ fernet = _fernet_for_config_dir(config_dir)
50
+ return fernet.decrypt(encrypted_b64.encode("ascii")).decode("utf-8")
51
+ except InvalidToken:
52
+ raise ValueError(
53
+ "IMAP password could not be decrypted (encryption key may have changed, e.g. different config dir or .cookie_secret). "
54
+ "Re-enter the IMAP password in the UI Config section to fix."
55
+ ) from None
@@ -47,7 +47,7 @@ def get_gmail_service(credentials_path: str | Path, token_path: str | Path):
47
47
  creds = flow.run_local_server(port=0)
48
48
  with open(tok_path, "w", encoding="utf-8") as f:
49
49
  f.write(creds.to_json())
50
- return build("gmail", "v1", credentials=creds)
50
+ return build("gmail", "v1", credentials=creds, cache_discovery=False)
51
51
 
52
52
 
53
53
  def _parse_date_from_raw(raw: bytes) -> str | None: