fetch2gmail 1.0.2__tar.gz → 1.0.4__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.2/src/fetch2gmail.egg-info → fetch2gmail-1.0.4}/PKG-INFO +59 -47
  2. {fetch2gmail-1.0.2 → fetch2gmail-1.0.4}/README.md +58 -46
  3. {fetch2gmail-1.0.2 → fetch2gmail-1.0.4}/pyproject.toml +1 -1
  4. {fetch2gmail-1.0.2 → fetch2gmail-1.0.4/src/fetch2gmail.egg-info}/PKG-INFO +59 -47
  5. {fetch2gmail-1.0.2 → fetch2gmail-1.0.4}/src/fetcher/cli.py +67 -1
  6. {fetch2gmail-1.0.2 → fetch2gmail-1.0.4}/src/fetcher/web_ui.py +50 -4
  7. {fetch2gmail-1.0.2 → fetch2gmail-1.0.4}/LICENSE +0 -0
  8. {fetch2gmail-1.0.2 → fetch2gmail-1.0.4}/setup.cfg +0 -0
  9. {fetch2gmail-1.0.2 → fetch2gmail-1.0.4}/src/fetch2gmail.egg-info/SOURCES.txt +0 -0
  10. {fetch2gmail-1.0.2 → fetch2gmail-1.0.4}/src/fetch2gmail.egg-info/dependency_links.txt +0 -0
  11. {fetch2gmail-1.0.2 → fetch2gmail-1.0.4}/src/fetch2gmail.egg-info/entry_points.txt +0 -0
  12. {fetch2gmail-1.0.2 → fetch2gmail-1.0.4}/src/fetch2gmail.egg-info/requires.txt +0 -0
  13. {fetch2gmail-1.0.2 → fetch2gmail-1.0.4}/src/fetch2gmail.egg-info/top_level.txt +0 -0
  14. {fetch2gmail-1.0.2 → fetch2gmail-1.0.4}/src/fetcher/__init__.py +0 -0
  15. {fetch2gmail-1.0.2 → fetch2gmail-1.0.4}/src/fetcher/auth_server.py +0 -0
  16. {fetch2gmail-1.0.2 → fetch2gmail-1.0.4}/src/fetcher/auth_ui.py +0 -0
  17. {fetch2gmail-1.0.2 → fetch2gmail-1.0.4}/src/fetcher/config.py +0 -0
  18. {fetch2gmail-1.0.2 → fetch2gmail-1.0.4}/src/fetcher/env_file.py +0 -0
  19. {fetch2gmail-1.0.2 → fetch2gmail-1.0.4}/src/fetcher/gmail_client.py +0 -0
  20. {fetch2gmail-1.0.2 → fetch2gmail-1.0.4}/src/fetcher/imap_client.py +0 -0
  21. {fetch2gmail-1.0.2 → fetch2gmail-1.0.4}/src/fetcher/log_buffer.py +0 -0
  22. {fetch2gmail-1.0.2 → fetch2gmail-1.0.4}/src/fetcher/run.py +0 -0
  23. {fetch2gmail-1.0.2 → fetch2gmail-1.0.4}/src/fetcher/state.py +0 -0
  24. {fetch2gmail-1.0.2 → fetch2gmail-1.0.4}/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.2
3
+ Version: 1.0.4
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
@@ -99,6 +99,8 @@ Use the same path in the steps below (replace `/opt/fetch2gmail` and the usernam
99
99
 
100
100
  **Step 7. Install pipx and fetch2gmail on the server**
101
101
 
102
+ Run these from **any directory** (you do not need to be in `/opt/fetch2gmail`):
103
+
102
104
  ```bash
103
105
  sudo apt install pipx
104
106
  pipx ensurepath
@@ -106,7 +108,7 @@ pipx ensurepath
106
108
  pipx install fetch2gmail
107
109
  ```
108
110
 
109
- The command is at **`~/.local/bin/fetch2gmail`**. Use that path in systemd (step 9).
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.
110
112
 
111
113
  **Step 8. Set the UI username and password**
112
114
 
@@ -119,52 +121,34 @@ fetch2gmail set-ui-password
119
121
 
120
122
  Enter a username and password when prompted.
121
123
 
122
- **Step 9. Install and enable the systemd services**
123
-
124
- Copy the three unit files into systemd (get them from the repo, e.g. clone or download):
125
-
126
- ```bash
127
- sudo cp /path/to/fetch2gmail/systemd/fetch2gmail.service /path/to/fetch2gmail/systemd/fetch2gmail.timer /path/to/fetch2gmail/systemd/fetch2gmail-ui.service /etc/systemd/system/
128
- ```
129
-
130
- Edit the **fetch** service:
131
-
132
- ```bash
133
- sudo systemctl edit --full fetch2gmail.service
134
- ```
135
-
136
- Set:
137
-
138
- - **User=** and **Group=** — the user that owns the data directory (e.g. `odroid`).
139
- - **WorkingDirectory=** — your data directory (e.g. `/opt/fetch2gmail`).
140
- - **Environment=FETCH2GMAIL_CONFIG=** — full path to config (e.g. `/opt/fetch2gmail/config.json`).
141
- - **ExecStart=** — path to `fetch2gmail run` (e.g. `/home/odroid/.local/bin/fetch2gmail run`).
142
-
143
- Save and exit.
124
+ **Step 9. Install and enable the systemd service (one service: web UI + background fetch)**
144
125
 
145
- Edit the **UI** service:
126
+ One service runs the web UI and polls your ISP mailbox on a schedule (every 5 minutes by default). Generate the unit file and install it:
146
127
 
147
128
  ```bash
148
- sudo systemctl edit --full fetch2gmail-ui.service
129
+ fetch2gmail install-service --user YOUR_USER --dir /opt/fetch2gmail -o /tmp/fetch2gmail.service
130
+ sudo mv /tmp/fetch2gmail.service /etc/systemd/system/fetch2gmail.service
131
+ sudo systemctl daemon-reload
132
+ sudo systemctl enable fetch2gmail
133
+ sudo systemctl start fetch2gmail
149
134
  ```
150
135
 
151
- Set the same **User**, **Group**, **WorkingDirectory**, **FETCH2GMAIL_CONFIG**. Set **ExecStart=** to the same path but with **`serve --host 0.0.0.0`** (e.g. `/home/odroid/.local/bin/fetch2gmail serve --host 0.0.0.0`). Save and exit.
136
+ Replace **YOUR_USER** with the user that owns `/opt/fetch2gmail` (e.g. `odroid`). Replace **/opt/fetch2gmail** if you used a different data directory. The command finds `fetch2gmail` on your PATH; if it is elsewhere, add `--exec /path/to/fetch2gmail`.
152
137
 
153
- Enable and start both the UI service and the timer:
138
+ Alternatively, print the unit file and pipe it into place:
154
139
 
155
140
  ```bash
141
+ fetch2gmail install-service --user YOUR_USER --dir /opt/fetch2gmail | sudo tee /etc/systemd/system/fetch2gmail.service > /dev/null
156
142
  sudo systemctl daemon-reload
157
- sudo systemctl enable fetch2gmail-ui.service
158
- sudo systemctl start fetch2gmail-ui.service
159
- sudo systemctl enable fetch2gmail.timer
160
- sudo systemctl start fetch2gmail.timer
143
+ sudo systemctl enable fetch2gmail
144
+ sudo systemctl start fetch2gmail
161
145
  ```
162
146
 
163
147
  **Step 10. Configure ISP mail in the web UI**
164
148
 
165
149
  Open **http://\<server-ip\>:8765** in your browser (e.g. http://192.168.1.10:8765). Log in with the UI username and password from step 8. You will see the **initial setup** form. Enter your IMAP host, username, password, mailbox, and Gmail label, then click **Create config**. The app stores your password securely and will poll your ISP mailbox on a schedule (every 5 minutes by default). You do not need to edit any config file by hand.
166
150
 
167
- **Done.** To watch logs: `journalctl -u fetch2gmail.service -f` or `journalctl -u fetch2gmail-ui.service -f`. See **systemd/README.md** for more.
151
+ **Done.** To watch logs: `journalctl -u fetch2gmail -f`.
168
152
 
169
153
  ---
170
154
 
@@ -197,23 +181,15 @@ mkdir -p ~/fetch2gmail
197
181
 
198
182
  Use the same path in the steps below (replace `~/fetch2gmail` if you use something else).
199
183
 
200
- **Step 5. Install and enable the systemd services**
201
-
202
- Copy the three unit files from the repo to `/etc/systemd/system/` (same as Use case 1, step 9). Edit **fetch2gmail.service** and **fetch2gmail-ui.service** with:
184
+ **Step 5. Install and enable the systemd service**
203
185
 
204
- - **User** and **Group** — your user.
205
- - **WorkingDirectory** — your data directory (e.g. `/home/you/fetch2gmail`).
206
- - **Environment=FETCH2GMAIL_CONFIG=** — e.g. `/home/you/fetch2gmail/config.json`.
207
- - **ExecStart** — e.g. `/home/you/.local/bin/fetch2gmail run` and `/home/you/.local/bin/fetch2gmail serve --host 0.0.0.0`.
208
-
209
- Then:
186
+ Same as Use case 1, step 9: one service (web UI + background fetch). Replace **YOUR_USER** and the path with yours:
210
187
 
211
188
  ```bash
189
+ fetch2gmail install-service --user YOUR_USER --dir /home/YOUR_USER/fetch2gmail | sudo tee /etc/systemd/system/fetch2gmail.service > /dev/null
212
190
  sudo systemctl daemon-reload
213
- sudo systemctl enable fetch2gmail-ui.service
214
- sudo systemctl start fetch2gmail-ui.service
215
- sudo systemctl enable fetch2gmail.timer
216
- sudo systemctl start fetch2gmail.timer
191
+ sudo systemctl enable fetch2gmail
192
+ sudo systemctl start fetch2gmail
217
193
  ```
218
194
 
219
195
  **Step 6. Sign in with Google in the web UI**
@@ -241,7 +217,7 @@ Google does not allow redirect URIs that use an IP address. That is why the toke
241
217
 
242
218
  ### Poll interval
243
219
 
244
- The timer runs the fetch every 5 minutes by default. You can change the interval in the web UI (Config) or in **config.json** (`poll_interval_minutes`).
220
+ The app runs the fetch every 5 minutes by default (background poller in the same process as the web UI). You can change the interval in the web UI (Config) or in **config.json** (`poll_interval_minutes`).
245
221
 
246
222
  ### Data directory
247
223
 
@@ -259,6 +235,7 @@ All app files live in **one directory**: **config.json**, **credentials.json**,
259
235
  |--------|---------|
260
236
  | `fetch2gmail auth` | Get **token.json** on a machine with a browser (opens http://127.0.0.1:8765). |
261
237
  | `fetch2gmail set-ui-password` | Set UI username and password (hash in **.ui_auth**). |
238
+ | `fetch2gmail install-service` | Generate systemd unit file (one service: web UI + background fetch). Use `--user`, `--dir`, and optionally `--output` or pipe to `sudo tee`. |
262
239
  | `fetch2gmail serve` | Run the web UI (default: localhost only; use `--host 0.0.0.0` to bind to all interfaces). |
263
240
  | `fetch2gmail run` | Run one fetch cycle. |
264
241
  | `fetch2gmail run --dry-run` | Connect to ISP and show what would be imported; no Gmail import, no delete. |
@@ -269,6 +246,41 @@ After copying **credentials.json** and **token.json** to the server, you can rem
269
246
 
270
247
  ---
271
248
 
249
+ ## Development / testing from source
250
+
251
+ To run from a git clone (e.g. to test changes before pushing):
252
+
253
+ 1. **Clone and go into the repo:**
254
+ ```bash
255
+ git clone https://github.com/yourusername/fetch2gmail.git
256
+ cd fetch2gmail
257
+ ```
258
+
259
+ 2. **Create and activate a virtual environment:**
260
+ - **Linux / macOS:** `python3 -m venv .venv` then `source .venv/bin/activate`
261
+ - **Windows (PowerShell):** `python -m venv .venv` then `.venv\Scripts\Activate.ps1`
262
+ - **Windows (Command Prompt):** `python -m venv .venv` then `.venv\Scripts\activate.bat`
263
+
264
+ 3. **Install the package in editable mode** (so changes in the repo are used when you run the app):
265
+ ```bash
266
+ pip install -e .
267
+ ```
268
+ Optional, for tests: `pip install -e ".[dev]"`
269
+
270
+ 4. **Run and test** (use the same terminal with the venv active):
271
+ - `fetch2gmail serve` — web UI at http://127.0.0.1:8765
272
+ - `fetch2gmail auth` — get token (put **credentials.json** in the current directory first)
273
+ - `fetch2gmail run` or `fetch2gmail run --dry-run` — if you have **config.json** and secrets set up
274
+
275
+ 5. **Before pushing: test the build** so the package still builds and you catch errors:
276
+ ```bash
277
+ pip install build
278
+ python -m build
279
+ ```
280
+ This creates `dist/` with the sdist and wheel. See **docs/PUBLISHING.md** for Test PyPI and release steps.
281
+
282
+ ---
283
+
272
284
  ## License
273
285
 
274
286
  MIT. See **LICENSE**.
@@ -68,6 +68,8 @@ Use the same path in the steps below (replace `/opt/fetch2gmail` and the usernam
68
68
 
69
69
  **Step 7. Install pipx and fetch2gmail on the server**
70
70
 
71
+ Run these from **any directory** (you do not need to be in `/opt/fetch2gmail`):
72
+
71
73
  ```bash
72
74
  sudo apt install pipx
73
75
  pipx ensurepath
@@ -75,7 +77,7 @@ pipx ensurepath
75
77
  pipx install fetch2gmail
76
78
  ```
77
79
 
78
- The command is at **`~/.local/bin/fetch2gmail`**. Use that path in systemd (step 9).
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.
79
81
 
80
82
  **Step 8. Set the UI username and password**
81
83
 
@@ -88,52 +90,34 @@ fetch2gmail set-ui-password
88
90
 
89
91
  Enter a username and password when prompted.
90
92
 
91
- **Step 9. Install and enable the systemd services**
92
-
93
- Copy the three unit files into systemd (get them from the repo, e.g. clone or download):
94
-
95
- ```bash
96
- sudo cp /path/to/fetch2gmail/systemd/fetch2gmail.service /path/to/fetch2gmail/systemd/fetch2gmail.timer /path/to/fetch2gmail/systemd/fetch2gmail-ui.service /etc/systemd/system/
97
- ```
98
-
99
- Edit the **fetch** service:
100
-
101
- ```bash
102
- sudo systemctl edit --full fetch2gmail.service
103
- ```
104
-
105
- Set:
106
-
107
- - **User=** and **Group=** — the user that owns the data directory (e.g. `odroid`).
108
- - **WorkingDirectory=** — your data directory (e.g. `/opt/fetch2gmail`).
109
- - **Environment=FETCH2GMAIL_CONFIG=** — full path to config (e.g. `/opt/fetch2gmail/config.json`).
110
- - **ExecStart=** — path to `fetch2gmail run` (e.g. `/home/odroid/.local/bin/fetch2gmail run`).
111
-
112
- Save and exit.
93
+ **Step 9. Install and enable the systemd service (one service: web UI + background fetch)**
113
94
 
114
- Edit the **UI** service:
95
+ One service runs the web UI and polls your ISP mailbox on a schedule (every 5 minutes by default). Generate the unit file and install it:
115
96
 
116
97
  ```bash
117
- sudo systemctl edit --full fetch2gmail-ui.service
98
+ fetch2gmail install-service --user YOUR_USER --dir /opt/fetch2gmail -o /tmp/fetch2gmail.service
99
+ sudo mv /tmp/fetch2gmail.service /etc/systemd/system/fetch2gmail.service
100
+ sudo systemctl daemon-reload
101
+ sudo systemctl enable fetch2gmail
102
+ sudo systemctl start fetch2gmail
118
103
  ```
119
104
 
120
- Set the same **User**, **Group**, **WorkingDirectory**, **FETCH2GMAIL_CONFIG**. Set **ExecStart=** to the same path but with **`serve --host 0.0.0.0`** (e.g. `/home/odroid/.local/bin/fetch2gmail serve --host 0.0.0.0`). Save and exit.
105
+ Replace **YOUR_USER** with the user that owns `/opt/fetch2gmail` (e.g. `odroid`). Replace **/opt/fetch2gmail** if you used a different data directory. The command finds `fetch2gmail` on your PATH; if it is elsewhere, add `--exec /path/to/fetch2gmail`.
121
106
 
122
- Enable and start both the UI service and the timer:
107
+ Alternatively, print the unit file and pipe it into place:
123
108
 
124
109
  ```bash
110
+ fetch2gmail install-service --user YOUR_USER --dir /opt/fetch2gmail | sudo tee /etc/systemd/system/fetch2gmail.service > /dev/null
125
111
  sudo systemctl daemon-reload
126
- sudo systemctl enable fetch2gmail-ui.service
127
- sudo systemctl start fetch2gmail-ui.service
128
- sudo systemctl enable fetch2gmail.timer
129
- sudo systemctl start fetch2gmail.timer
112
+ sudo systemctl enable fetch2gmail
113
+ sudo systemctl start fetch2gmail
130
114
  ```
131
115
 
132
116
  **Step 10. Configure ISP mail in the web UI**
133
117
 
134
118
  Open **http://\<server-ip\>:8765** in your browser (e.g. http://192.168.1.10:8765). Log in with the UI username and password from step 8. You will see the **initial setup** form. Enter your IMAP host, username, password, mailbox, and Gmail label, then click **Create config**. The app stores your password securely and will poll your ISP mailbox on a schedule (every 5 minutes by default). You do not need to edit any config file by hand.
135
119
 
136
- **Done.** To watch logs: `journalctl -u fetch2gmail.service -f` or `journalctl -u fetch2gmail-ui.service -f`. See **systemd/README.md** for more.
120
+ **Done.** To watch logs: `journalctl -u fetch2gmail -f`.
137
121
 
138
122
  ---
139
123
 
@@ -166,23 +150,15 @@ mkdir -p ~/fetch2gmail
166
150
 
167
151
  Use the same path in the steps below (replace `~/fetch2gmail` if you use something else).
168
152
 
169
- **Step 5. Install and enable the systemd services**
170
-
171
- Copy the three unit files from the repo to `/etc/systemd/system/` (same as Use case 1, step 9). Edit **fetch2gmail.service** and **fetch2gmail-ui.service** with:
153
+ **Step 5. Install and enable the systemd service**
172
154
 
173
- - **User** and **Group** — your user.
174
- - **WorkingDirectory** — your data directory (e.g. `/home/you/fetch2gmail`).
175
- - **Environment=FETCH2GMAIL_CONFIG=** — e.g. `/home/you/fetch2gmail/config.json`.
176
- - **ExecStart** — e.g. `/home/you/.local/bin/fetch2gmail run` and `/home/you/.local/bin/fetch2gmail serve --host 0.0.0.0`.
177
-
178
- Then:
155
+ Same as Use case 1, step 9: one service (web UI + background fetch). Replace **YOUR_USER** and the path with yours:
179
156
 
180
157
  ```bash
158
+ fetch2gmail install-service --user YOUR_USER --dir /home/YOUR_USER/fetch2gmail | sudo tee /etc/systemd/system/fetch2gmail.service > /dev/null
181
159
  sudo systemctl daemon-reload
182
- sudo systemctl enable fetch2gmail-ui.service
183
- sudo systemctl start fetch2gmail-ui.service
184
- sudo systemctl enable fetch2gmail.timer
185
- sudo systemctl start fetch2gmail.timer
160
+ sudo systemctl enable fetch2gmail
161
+ sudo systemctl start fetch2gmail
186
162
  ```
187
163
 
188
164
  **Step 6. Sign in with Google in the web UI**
@@ -210,7 +186,7 @@ Google does not allow redirect URIs that use an IP address. That is why the toke
210
186
 
211
187
  ### Poll interval
212
188
 
213
- The timer runs the fetch every 5 minutes by default. You can change the interval in the web UI (Config) or in **config.json** (`poll_interval_minutes`).
189
+ The app runs the fetch every 5 minutes by default (background poller in the same process as the web UI). You can change the interval in the web UI (Config) or in **config.json** (`poll_interval_minutes`).
214
190
 
215
191
  ### Data directory
216
192
 
@@ -228,6 +204,7 @@ All app files live in **one directory**: **config.json**, **credentials.json**,
228
204
  |--------|---------|
229
205
  | `fetch2gmail auth` | Get **token.json** on a machine with a browser (opens http://127.0.0.1:8765). |
230
206
  | `fetch2gmail set-ui-password` | Set UI username and password (hash in **.ui_auth**). |
207
+ | `fetch2gmail install-service` | Generate systemd unit file (one service: web UI + background fetch). Use `--user`, `--dir`, and optionally `--output` or pipe to `sudo tee`. |
231
208
  | `fetch2gmail serve` | Run the web UI (default: localhost only; use `--host 0.0.0.0` to bind to all interfaces). |
232
209
  | `fetch2gmail run` | Run one fetch cycle. |
233
210
  | `fetch2gmail run --dry-run` | Connect to ISP and show what would be imported; no Gmail import, no delete. |
@@ -238,6 +215,41 @@ After copying **credentials.json** and **token.json** to the server, you can rem
238
215
 
239
216
  ---
240
217
 
218
+ ## Development / testing from source
219
+
220
+ To run from a git clone (e.g. to test changes before pushing):
221
+
222
+ 1. **Clone and go into the repo:**
223
+ ```bash
224
+ git clone https://github.com/yourusername/fetch2gmail.git
225
+ cd fetch2gmail
226
+ ```
227
+
228
+ 2. **Create and activate a virtual environment:**
229
+ - **Linux / macOS:** `python3 -m venv .venv` then `source .venv/bin/activate`
230
+ - **Windows (PowerShell):** `python -m venv .venv` then `.venv\Scripts\Activate.ps1`
231
+ - **Windows (Command Prompt):** `python -m venv .venv` then `.venv\Scripts\activate.bat`
232
+
233
+ 3. **Install the package in editable mode** (so changes in the repo are used when you run the app):
234
+ ```bash
235
+ pip install -e .
236
+ ```
237
+ Optional, for tests: `pip install -e ".[dev]"`
238
+
239
+ 4. **Run and test** (use the same terminal with the venv active):
240
+ - `fetch2gmail serve` — web UI at http://127.0.0.1:8765
241
+ - `fetch2gmail auth` — get token (put **credentials.json** in the current directory first)
242
+ - `fetch2gmail run` or `fetch2gmail run --dry-run` — if you have **config.json** and secrets set up
243
+
244
+ 5. **Before pushing: test the build** so the package still builds and you catch errors:
245
+ ```bash
246
+ pip install build
247
+ python -m build
248
+ ```
249
+ This creates `dist/` with the sdist and wheel. See **docs/PUBLISHING.md** for Test PyPI and release steps.
250
+
251
+ ---
252
+
241
253
  ## License
242
254
 
243
255
  MIT. See **LICENSE**.
@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
4
4
 
5
5
  [project]
6
6
  name = "fetch2gmail"
7
- version = "1.0.2"
7
+ version = "1.0.4"
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.2
3
+ Version: 1.0.4
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
@@ -99,6 +99,8 @@ Use the same path in the steps below (replace `/opt/fetch2gmail` and the usernam
99
99
 
100
100
  **Step 7. Install pipx and fetch2gmail on the server**
101
101
 
102
+ Run these from **any directory** (you do not need to be in `/opt/fetch2gmail`):
103
+
102
104
  ```bash
103
105
  sudo apt install pipx
104
106
  pipx ensurepath
@@ -106,7 +108,7 @@ pipx ensurepath
106
108
  pipx install fetch2gmail
107
109
  ```
108
110
 
109
- The command is at **`~/.local/bin/fetch2gmail`**. Use that path in systemd (step 9).
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.
110
112
 
111
113
  **Step 8. Set the UI username and password**
112
114
 
@@ -119,52 +121,34 @@ fetch2gmail set-ui-password
119
121
 
120
122
  Enter a username and password when prompted.
121
123
 
122
- **Step 9. Install and enable the systemd services**
123
-
124
- Copy the three unit files into systemd (get them from the repo, e.g. clone or download):
125
-
126
- ```bash
127
- sudo cp /path/to/fetch2gmail/systemd/fetch2gmail.service /path/to/fetch2gmail/systemd/fetch2gmail.timer /path/to/fetch2gmail/systemd/fetch2gmail-ui.service /etc/systemd/system/
128
- ```
129
-
130
- Edit the **fetch** service:
131
-
132
- ```bash
133
- sudo systemctl edit --full fetch2gmail.service
134
- ```
135
-
136
- Set:
137
-
138
- - **User=** and **Group=** — the user that owns the data directory (e.g. `odroid`).
139
- - **WorkingDirectory=** — your data directory (e.g. `/opt/fetch2gmail`).
140
- - **Environment=FETCH2GMAIL_CONFIG=** — full path to config (e.g. `/opt/fetch2gmail/config.json`).
141
- - **ExecStart=** — path to `fetch2gmail run` (e.g. `/home/odroid/.local/bin/fetch2gmail run`).
142
-
143
- Save and exit.
124
+ **Step 9. Install and enable the systemd service (one service: web UI + background fetch)**
144
125
 
145
- Edit the **UI** service:
126
+ One service runs the web UI and polls your ISP mailbox on a schedule (every 5 minutes by default). Generate the unit file and install it:
146
127
 
147
128
  ```bash
148
- sudo systemctl edit --full fetch2gmail-ui.service
129
+ fetch2gmail install-service --user YOUR_USER --dir /opt/fetch2gmail -o /tmp/fetch2gmail.service
130
+ sudo mv /tmp/fetch2gmail.service /etc/systemd/system/fetch2gmail.service
131
+ sudo systemctl daemon-reload
132
+ sudo systemctl enable fetch2gmail
133
+ sudo systemctl start fetch2gmail
149
134
  ```
150
135
 
151
- Set the same **User**, **Group**, **WorkingDirectory**, **FETCH2GMAIL_CONFIG**. Set **ExecStart=** to the same path but with **`serve --host 0.0.0.0`** (e.g. `/home/odroid/.local/bin/fetch2gmail serve --host 0.0.0.0`). Save and exit.
136
+ Replace **YOUR_USER** with the user that owns `/opt/fetch2gmail` (e.g. `odroid`). Replace **/opt/fetch2gmail** if you used a different data directory. The command finds `fetch2gmail` on your PATH; if it is elsewhere, add `--exec /path/to/fetch2gmail`.
152
137
 
153
- Enable and start both the UI service and the timer:
138
+ Alternatively, print the unit file and pipe it into place:
154
139
 
155
140
  ```bash
141
+ fetch2gmail install-service --user YOUR_USER --dir /opt/fetch2gmail | sudo tee /etc/systemd/system/fetch2gmail.service > /dev/null
156
142
  sudo systemctl daemon-reload
157
- sudo systemctl enable fetch2gmail-ui.service
158
- sudo systemctl start fetch2gmail-ui.service
159
- sudo systemctl enable fetch2gmail.timer
160
- sudo systemctl start fetch2gmail.timer
143
+ sudo systemctl enable fetch2gmail
144
+ sudo systemctl start fetch2gmail
161
145
  ```
162
146
 
163
147
  **Step 10. Configure ISP mail in the web UI**
164
148
 
165
149
  Open **http://\<server-ip\>:8765** in your browser (e.g. http://192.168.1.10:8765). Log in with the UI username and password from step 8. You will see the **initial setup** form. Enter your IMAP host, username, password, mailbox, and Gmail label, then click **Create config**. The app stores your password securely and will poll your ISP mailbox on a schedule (every 5 minutes by default). You do not need to edit any config file by hand.
166
150
 
167
- **Done.** To watch logs: `journalctl -u fetch2gmail.service -f` or `journalctl -u fetch2gmail-ui.service -f`. See **systemd/README.md** for more.
151
+ **Done.** To watch logs: `journalctl -u fetch2gmail -f`.
168
152
 
169
153
  ---
170
154
 
@@ -197,23 +181,15 @@ mkdir -p ~/fetch2gmail
197
181
 
198
182
  Use the same path in the steps below (replace `~/fetch2gmail` if you use something else).
199
183
 
200
- **Step 5. Install and enable the systemd services**
201
-
202
- Copy the three unit files from the repo to `/etc/systemd/system/` (same as Use case 1, step 9). Edit **fetch2gmail.service** and **fetch2gmail-ui.service** with:
184
+ **Step 5. Install and enable the systemd service**
203
185
 
204
- - **User** and **Group** — your user.
205
- - **WorkingDirectory** — your data directory (e.g. `/home/you/fetch2gmail`).
206
- - **Environment=FETCH2GMAIL_CONFIG=** — e.g. `/home/you/fetch2gmail/config.json`.
207
- - **ExecStart** — e.g. `/home/you/.local/bin/fetch2gmail run` and `/home/you/.local/bin/fetch2gmail serve --host 0.0.0.0`.
208
-
209
- Then:
186
+ Same as Use case 1, step 9: one service (web UI + background fetch). Replace **YOUR_USER** and the path with yours:
210
187
 
211
188
  ```bash
189
+ fetch2gmail install-service --user YOUR_USER --dir /home/YOUR_USER/fetch2gmail | sudo tee /etc/systemd/system/fetch2gmail.service > /dev/null
212
190
  sudo systemctl daemon-reload
213
- sudo systemctl enable fetch2gmail-ui.service
214
- sudo systemctl start fetch2gmail-ui.service
215
- sudo systemctl enable fetch2gmail.timer
216
- sudo systemctl start fetch2gmail.timer
191
+ sudo systemctl enable fetch2gmail
192
+ sudo systemctl start fetch2gmail
217
193
  ```
218
194
 
219
195
  **Step 6. Sign in with Google in the web UI**
@@ -241,7 +217,7 @@ Google does not allow redirect URIs that use an IP address. That is why the toke
241
217
 
242
218
  ### Poll interval
243
219
 
244
- The timer runs the fetch every 5 minutes by default. You can change the interval in the web UI (Config) or in **config.json** (`poll_interval_minutes`).
220
+ The app runs the fetch every 5 minutes by default (background poller in the same process as the web UI). You can change the interval in the web UI (Config) or in **config.json** (`poll_interval_minutes`).
245
221
 
246
222
  ### Data directory
247
223
 
@@ -259,6 +235,7 @@ All app files live in **one directory**: **config.json**, **credentials.json**,
259
235
  |--------|---------|
260
236
  | `fetch2gmail auth` | Get **token.json** on a machine with a browser (opens http://127.0.0.1:8765). |
261
237
  | `fetch2gmail set-ui-password` | Set UI username and password (hash in **.ui_auth**). |
238
+ | `fetch2gmail install-service` | Generate systemd unit file (one service: web UI + background fetch). Use `--user`, `--dir`, and optionally `--output` or pipe to `sudo tee`. |
262
239
  | `fetch2gmail serve` | Run the web UI (default: localhost only; use `--host 0.0.0.0` to bind to all interfaces). |
263
240
  | `fetch2gmail run` | Run one fetch cycle. |
264
241
  | `fetch2gmail run --dry-run` | Connect to ISP and show what would be imported; no Gmail import, no delete. |
@@ -269,6 +246,41 @@ After copying **credentials.json** and **token.json** to the server, you can rem
269
246
 
270
247
  ---
271
248
 
249
+ ## Development / testing from source
250
+
251
+ To run from a git clone (e.g. to test changes before pushing):
252
+
253
+ 1. **Clone and go into the repo:**
254
+ ```bash
255
+ git clone https://github.com/yourusername/fetch2gmail.git
256
+ cd fetch2gmail
257
+ ```
258
+
259
+ 2. **Create and activate a virtual environment:**
260
+ - **Linux / macOS:** `python3 -m venv .venv` then `source .venv/bin/activate`
261
+ - **Windows (PowerShell):** `python -m venv .venv` then `.venv\Scripts\Activate.ps1`
262
+ - **Windows (Command Prompt):** `python -m venv .venv` then `.venv\Scripts\activate.bat`
263
+
264
+ 3. **Install the package in editable mode** (so changes in the repo are used when you run the app):
265
+ ```bash
266
+ pip install -e .
267
+ ```
268
+ Optional, for tests: `pip install -e ".[dev]"`
269
+
270
+ 4. **Run and test** (use the same terminal with the venv active):
271
+ - `fetch2gmail serve` — web UI at http://127.0.0.1:8765
272
+ - `fetch2gmail auth` — get token (put **credentials.json** in the current directory first)
273
+ - `fetch2gmail run` or `fetch2gmail run --dry-run` — if you have **config.json** and secrets set up
274
+
275
+ 5. **Before pushing: test the build** so the package still builds and you catch errors:
276
+ ```bash
277
+ pip install build
278
+ python -m build
279
+ ```
280
+ This creates `dist/` with the sdist and wheel. See **docs/PUBLISHING.md** for Test PyPI and release steps.
281
+
282
+ ---
283
+
272
284
  ## License
273
285
 
274
286
  MIT. See **LICENSE**.
@@ -5,6 +5,7 @@ Interactive CLI for Fetch2Gmail: config wizard and one-shot / dry-run.
5
5
  import argparse
6
6
  import json
7
7
  import os
8
+ import shutil
8
9
  import sys
9
10
  from pathlib import Path
10
11
 
@@ -69,6 +70,20 @@ def main() -> None:
69
70
  )
70
71
  p_set_ui_password.set_defaults(func=_cmd_set_ui_password)
71
72
 
73
+ p_install_service = sub.add_parser(
74
+ "install-service",
75
+ help="Generate a systemd unit file for Fetch2Gmail (one service: web UI + background fetch). Write to --output or stdout.",
76
+ )
77
+ p_install_service.add_argument("--user", required=True, help="User and group to run the service (e.g. odroid)")
78
+ p_install_service.add_argument("--dir", required=True, help="Data directory (config, credentials, token; e.g. /opt/fetch2gmail)")
79
+ p_install_service.add_argument("--output", "-o", default=None, help="Write unit file here (default: print to stdout)")
80
+ p_install_service.add_argument(
81
+ "--exec",
82
+ default=None,
83
+ help="Path to fetch2gmail binary (default: detect from PATH)",
84
+ )
85
+ p_install_service.set_defaults(func=_cmd_install_service)
86
+
72
87
  args = parser.parse_args()
73
88
  if not args.command:
74
89
  parser.print_help()
@@ -136,6 +151,57 @@ def _cmd_serve(args: argparse.Namespace) -> None:
136
151
  serve(host=args.host, port=args.port, config_path=args.config)
137
152
 
138
153
 
154
+ # Single systemd service: web UI + built-in poller (no separate timer/oneshot)
155
+ _SYSTEMD_UNIT_TEMPLATE = """[Unit]
156
+ Description=Fetch2Gmail - web UI and background fetch
157
+ Documentation=https://github.com/yourusername/fetch2gmail
158
+ After=network-online.target
159
+ Wants=network-online.target
160
+
161
+ [Service]
162
+ Type=simple
163
+ User={user}
164
+ Group={group}
165
+ Environment=FETCH2GMAIL_CONFIG={config_path}
166
+ WorkingDirectory={working_dir}
167
+ StandardOutput=journal
168
+ StandardError=journal
169
+ SyslogIdentifier=fetch2gmail
170
+ ExecStart={exec_start}
171
+ Restart=on-failure
172
+ RestartSec=5
173
+
174
+ [Install]
175
+ WantedBy=multi-user.target
176
+ """
177
+
178
+
179
+ def _cmd_install_service(args: argparse.Namespace) -> None:
180
+ """Generate systemd unit file and write to --output or stdout."""
181
+ user = args.user
182
+ data_dir = Path(args.dir).resolve()
183
+ config_path = data_dir / "config.json"
184
+ exec_path = args.exec or shutil.which("fetch2gmail")
185
+ if not exec_path:
186
+ print("Could not find fetch2gmail on PATH. Use --exec /path/to/fetch2gmail", file=sys.stderr)
187
+ sys.exit(1)
188
+ exec_path = str(Path(exec_path).resolve())
189
+ content = _SYSTEMD_UNIT_TEMPLATE.format(
190
+ user=user,
191
+ group=user,
192
+ config_path=config_path,
193
+ working_dir=data_dir,
194
+ exec_start=f"{exec_path} serve --host 0.0.0.0",
195
+ )
196
+ if args.output:
197
+ out = Path(args.output)
198
+ out.parent.mkdir(parents=True, exist_ok=True)
199
+ out.write_text(content, encoding="utf-8")
200
+ print(f"Wrote {out}. Then: sudo systemctl daemon-reload && sudo systemctl enable fetch2gmail && sudo systemctl start fetch2gmail", file=sys.stderr)
201
+ else:
202
+ print(content)
203
+
204
+
139
205
  def _cmd_set_ui_password(args: argparse.Namespace) -> None:
140
206
  """Prompt for username and password; store bcrypt hash in .ui_auth in config directory."""
141
207
  import getpass
@@ -154,7 +220,7 @@ def _cmd_set_ui_password(args: argparse.Namespace) -> None:
154
220
  print("Password cannot be empty.", file=sys.stderr)
155
221
  sys.exit(1)
156
222
  create_ui_auth(config_dir, username, password)
157
- print("Done. The web UI will now require this username and password when you run it (e.g. with --host 0.0.0.0).")
223
+ print("Done. The web UI will now require this username and password when you run it")
158
224
 
159
225
 
160
226
  def _cmd_auth(args: argparse.Namespace) -> None:
@@ -186,6 +186,7 @@ class ConfigResponse(BaseModel):
186
186
  state_db_path: str
187
187
  gmail_connected: bool
188
188
  imap_password_set: bool
189
+ config_exists: bool = True # False when config.json not created yet (show setup wizard)
189
190
 
190
191
 
191
192
  @app.get("/static/app.js", response_model=None)
@@ -236,7 +237,12 @@ def api_auth_session(request: Request) -> dict[str, bool]:
236
237
 
237
238
  @app.post("/api/logout")
238
239
  def api_logout():
239
- resp = RedirectResponse(url="/login", status_code=302)
240
+ """Clear session and redirect. With Basic Auth, browser may still re-send credentials; redirect to / with hint."""
241
+ cfg_dir = _config_dir_safe()
242
+ if load_ui_auth(cfg_dir):
243
+ resp = RedirectResponse(url="/?logged_out=1", status_code=302)
244
+ else:
245
+ resp = RedirectResponse(url="/login", status_code=302)
240
246
  clear_session_cookie(resp)
241
247
  return resp
242
248
 
@@ -305,15 +311,42 @@ def api_gmail_email(request: Request) -> dict[str, str | None]:
305
311
  return {"email": _gmail_email()}
306
312
 
307
313
 
314
+ def _default_config_response() -> ConfigResponse:
315
+ """Return empty config when config.json does not exist yet (avoids 404, show setup wizard)."""
316
+ return ConfigResponse(
317
+ imap=ImapConfigSafe(
318
+ host="",
319
+ port=993,
320
+ username="",
321
+ mailbox="INBOX",
322
+ use_ssl=True,
323
+ delete_after_import=True,
324
+ ),
325
+ gmail=GmailConfigSafe(
326
+ use_label=False,
327
+ label="ISP Mail",
328
+ credentials_path="credentials.json",
329
+ token_path="token.json",
330
+ ),
331
+ ui=UIConfigSafe(host="127.0.0.1", port=8765),
332
+ poll_interval_minutes=5,
333
+ state_db_path="state.db",
334
+ gmail_connected=_gmail_connected(),
335
+ imap_password_set=False,
336
+ config_exists=False,
337
+ )
338
+
339
+
308
340
  @app.get("/api/config", response_model=ConfigResponse)
309
341
  def api_config(request: Request) -> ConfigResponse:
310
342
  """Return non-sensitive config for display/editing (no password resolution)."""
311
343
  if not _require_auth(request):
312
344
  raise HTTPException(status_code=401, detail="Not authenticated")
345
+ path = _get_config_path()
346
+ if not path.exists():
347
+ return _default_config_response()
313
348
  try:
314
- cfg = load_config(_get_config_path(), resolve_password=False)
315
- except FileNotFoundError:
316
- raise HTTPException(status_code=404, detail="config.json not found")
349
+ cfg = load_config(path, resolve_password=False)
317
350
  except ValueError as e:
318
351
  raise HTTPException(status_code=400, detail=str(e))
319
352
  imap = cfg.get("imap") or {}
@@ -345,6 +378,7 @@ def api_config(request: Request) -> ConfigResponse:
345
378
  state_db_path=str(state.get("db_path", "state.db")),
346
379
  gmail_connected=_gmail_connected(),
347
380
  imap_password_set=_imap_password_set(),
381
+ config_exists=True,
348
382
  )
349
383
 
350
384
 
@@ -592,6 +626,7 @@ _HTML_PAGE = """
592
626
  <body>
593
627
  <h1>Fetch2Gmail <span class="logout" id="logoutSpan" style="display:none"><form method="post" action="/api/logout" style="display:inline"><button type="submit">Log out</button></form></span></h1>
594
628
  <p id="subtitle">IMAP to Gmail import. Configure below.</p>
629
+ <p id="loggedOutMsg" style="display:none" class="status"></p>
595
630
  <p id="loadingMsg">Loading...</p>
596
631
 
597
632
  <div id="credentialsFirst" style="display:none">
@@ -701,12 +736,23 @@ _APP_JS = r"""
701
736
  document.getElementById('subtitle').textContent = 'Gmail connected. You can run a fetch now.';
702
737
  history.replaceState({}, '', '/');
703
738
  }
739
+ if (params.get('logged_out') === '1') {
740
+ var el = document.getElementById('loggedOutMsg');
741
+ el.style.display = 'block';
742
+ el.textContent = 'You clicked Log out. When using password protection, the browser may still send your password. To fully log out, close this tab or use a private window.';
743
+ history.replaceState({}, '', '/');
744
+ }
704
745
  if (params.get('error') === 'no_credentials') document.getElementById('subtitle').innerHTML = '<span class="error">Put credentials.json in the app folder and try Connect Gmail again.</span>';
705
746
 
706
747
  function hideLoading() { var el = document.getElementById('loadingMsg'); if (el) el.style.display = 'none'; }
707
748
  function loadConfig() {
708
749
  return api('/api/config').then(function(c) {
709
750
  hideLoading();
751
+ if (!c.config_exists) {
752
+ document.getElementById('dashboard').style.display = 'none';
753
+ document.getElementById('setupWizard').style.display = 'block';
754
+ return null;
755
+ }
710
756
  document.getElementById('setupWizard').style.display = 'none';
711
757
  document.getElementById('dashboard').style.display = 'block';
712
758
  document.getElementById('imap_host').value = c.imap.host;
File without changes
File without changes