Fossil SCM
Added the "Email Notification" section to the forum.wiki document.
Commit
6b2752030d391a603a9bab2b899a71cff22496bb35f7fb718f0ceee78f2f3ca0
Parent
0194fb677490c6f…
1 file changed
+188
-8
+188
-8
| --- www/forum.wiki | ||
| +++ www/forum.wiki | ||
| @@ -174,11 +174,11 @@ | ||
| 174 | 174 | capabilities to individual accounts except in atypical cases, such as |
| 175 | 175 | to grant the Moderate Forum capability (5) to an uncommonly |
| 176 | 176 | highly-trusted user. |
| 177 | 177 | |
| 178 | 178 | |
| 179 | -<h3>Skin Setup</h3> | |
| 179 | +<h3 id="skin">Skin Setup</h3> | |
| 180 | 180 | |
| 181 | 181 | If you create a new Fossil repository with version 2.7 or newer, its |
| 182 | 182 | default skin is already set up correctly for typical forum |
| 183 | 183 | configurations. |
| 184 | 184 | |
| @@ -266,18 +266,198 @@ | ||
| 266 | 266 | authorized on a different Fossil repository. |
| 267 | 267 | |
| 268 | 268 | |
| 269 | 269 | <h3>Email Notification</h3> |
| 270 | 270 | |
| 271 | -See [./emaildesign.md | the email notification design document] for now. | |
| 272 | -More administration-oriented documentation TODO. | |
| 271 | +The detailed information for this feature of Fossil is in two other | |
| 272 | +documents: | |
| 273 | + | |
| 274 | + * [./alerts.md | Email Alerts] | |
| 275 | + * [./emaildesign.md | Email Notification Design] | |
| 276 | + | |
| 277 | +You may want to study those in detail, since email is complicated. Some | |
| 278 | +of that complexity necessarily leaks out to the configuration of email | |
| 279 | +notification in Fossil. | |
| 280 | + | |
| 281 | + | |
| 282 | +<h4>Quick Setup</h4> | |
| 283 | + | |
| 284 | +However, if you've already got a working Postfix, Exim, or Sendmail | |
| 285 | +server on the machine running your Fossil instance(s), and you aren't | |
| 286 | +using Fossil's <tt>chroot</tt> feature to wall it off from the rest of | |
| 287 | +the machine, it's fairly simple to set up email notifications: | |
| 288 | + | |
| 289 | +<ol> | |
| 290 | + <li>Go to Admin → Notification and fill out all of the | |
| 291 | + <b>Required</b> fields:</li> | |
| 292 | + | |
| 293 | + <ul> | |
| 294 | + <li><b>Canonical server URL</b> — Use the suggested URL</li> | |
| 295 | + <li><b>"From" email address</b> — <tt>[email protected]</tt> | |
| 296 | + is traditional, but do what you like</li> | |
| 297 | + <li><b>Repository nickname</b> — See the suggested examples on | |
| 298 | + the web page.</li> | |
| 299 | + </ul> | |
| 300 | + | |
| 301 | + <li>Set "Email Send Method" to "Pipe to a command"</li> | |
| 302 | + | |
| 303 | + <li>Set the "Administrator email address" to a suitable email address. | |
| 304 | + It could be the same value you used for the "From" address above, | |
| 305 | + or it could be a different value like | |
| 306 | + <tt>[email protected]</tt>.</li> | |
| 307 | +</ol> | |
| 308 | + | |
| 309 | +Save your changes. | |
| 310 | + | |
| 311 | +<a id="cd"></a>For all of the following <tt>fossil</tt> CLI commands, | |
| 312 | +we're going to assume that you've <tt>cd</tt>'d into a checkout | |
| 313 | +directory for your repository on the central server. Otherwise, we'd | |
| 314 | +need to add <tt>-R /path/to/repo.fossil</tt> to each of them. | |
| 315 | + | |
| 316 | +Give this command: | |
| 317 | + | |
| 318 | +<verbatim> | |
| 319 | + $ fossil set email-send-command | |
| 320 | +</verbatim> | |
| 321 | + | |
| 322 | +If that gives a blank value instead of <tt>sendmail -t</tt>, say | |
| 323 | + | |
| 324 | +<verbatim> | |
| 325 | + $ fossil set email-send-command "sendmail -t" | |
| 326 | +</verbatim> | |
| 327 | + | |
| 328 | +to force the setting. That's a | |
| 329 | +[https://fossil-scm.org/forum/forumpost/840b676410 | known bug] which | |
| 330 | +should be squished soon. | |
| 331 | + | |
| 332 | +This is the correct command even if you're running Postfix or Exim | |
| 333 | +rather than Sendmail. These mail servers (and perhaps others) provide a | |
| 334 | +<tt>sendmail</tt> command for this very sort of reason: it lets programs | |
| 335 | +send email without having to care exactly which server implementation is | |
| 336 | +running at a given site. | |
| 337 | + | |
| 338 | +<a id="status"></a>If you reload the Email Notification Setup page, the | |
| 339 | +Status section at the top should show: | |
| 340 | + | |
| 341 | +<verbatim> | |
| 342 | + Outgoing Email: Piped to command "sendmail -t" | |
| 343 | + Pending Alerts: 0 normal, 0 digest | |
| 344 | + Subscribers: 0 active, 0 total | |
| 345 | +</verbatim> | |
| 346 | + | |
| 347 | + | |
| 348 | +<h4>Subscribe to Alerts</h4> | |
| 349 | + | |
| 350 | +Above, we see that there are no subscribers, so the next step is to add | |
| 351 | +one. | |
| 352 | + | |
| 353 | +Go to the <tt>/subscribe</tt> page on your Fossil instance and sign your | |
| 354 | +regular Fossil user up for email alerts. (Alternate path: click the | |
| 355 | +login/logout link in the upper right corner, then go to "Email Alerts".) | |
| 356 | +You will need "Forum Posts" checked at the least for the testing steps | |
| 357 | +below. | |
| 358 | + | |
| 359 | +If you use the same user name and email address as you used for your | |
| 360 | +normal user login, Fossil will simply tie your alert preferences to your | |
| 361 | +login, and it will be considered already-verified. Otherwise, Fossil | |
| 362 | +will create up an alert-only record, and you will have to verify the | |
| 363 | +email address before Fossil will send notifications to it. | |
| 364 | + | |
| 365 | +This shows a key aspect of the way Fossil's email alerts system works, | |
| 366 | +by the way: a user can be signed up for email alerts without having a | |
| 367 | +full-fledged Fossil user account. Only when both user names are the same | |
| 368 | +are the two records tied together under the hood. | |
| 369 | + | |
| 370 | + | |
| 371 | +<h4>Test the Email Subsystem</h4> | |
| 372 | + | |
| 373 | +If you'd rather not create an inane "testing" post in your Fossil | |
| 374 | +instance just to force out an email alert, we can check whether the | |
| 375 | +email subsystem separate from the rest of the Fossil Email Alerts system | |
| 376 | +is working with the following command: | |
| 377 | + | |
| 378 | +<verbatim> | |
| 379 | + $ fossil alerts test-message [email protected] --body README.md --subject Test | |
| 380 | +</verbatim> | |
| 381 | + | |
| 382 | +That should send you an email with "Test" in the subject line and the | |
| 383 | +contents of your project's <tt>README.md</tt> file in the body. If it | |
| 384 | +works, the file's contents may be truncated. I'm uncertain whether | |
| 385 | +that's due to an intentionally-small buffer size or if it's a bug. | |
| 386 | + | |
| 387 | +That command assumes that your project [./foss-cklist.wiki | contains a | |
| 388 | +readme file]. Of course it does. Why would it not? | |
| 389 | + | |
| 390 | + | |
| 391 | +<h4>Frist Post</h4> | |
| 392 | + | |
| 393 | +Since you've already edited the skin per [#skin | the instructions | |
| 394 | +above], you can click the "Forum" link in the navbar and create a new | |
| 395 | +post. I suggest taking the time to compose a suitable introductory | |
| 396 | +message especially for your project's forum, suitable for pointing new | |
| 397 | +forum users at. | |
| 398 | + | |
| 399 | +Wait a few seconds, and you should receive a notification email with the | |
| 400 | +post's subject and body text in the email. | |
| 401 | + | |
| 402 | + | |
| 403 | +<h4>Troubleshooting</h4> | |
| 404 | + | |
| 405 | +If email alerts aren't working, there are several useful commands you | |
| 406 | +can give to figure out why. | |
| 407 | + | |
| 408 | +(Be sure to [#cd | <tt>cd</tt> into a repo checkout directory] first!) | |
| 409 | + | |
| 410 | +<verbatim> | |
| 411 | + $ fossil alerts status | |
| 412 | +</verbatim> | |
| 413 | + | |
| 414 | +This should give much the same information as you saw [#status | above]. | |
| 415 | +One difference is that, since you've created a forum post, the | |
| 416 | +<tt>pending-alerts</tt> value should only be zero if you did in fact get | |
| 417 | +the requested email alert. If it's zero, check your mailer's spam | |
| 418 | +folder. If it's nonzero, continue with these troubleshooting steps. | |
| 419 | + | |
| 420 | +<verbatim> | |
| 421 | + $ fossil backoffice | |
| 422 | +</verbatim> | |
| 423 | + | |
| 424 | +That forces Fossil to run its [./backoffice.md | "back office" process]. | |
| 425 | +Its only purpose at the time of this writing is to push out alert | |
| 426 | +emails, but it might do other things later. Sometimes it can get stuck | |
| 427 | +and needs to be kicked. For that reason, you might want to set up a | |
| 428 | +crontab entry to make sure it runs occasionally. | |
| 429 | + | |
| 430 | +<verbatim> | |
| 431 | + $ fossil alerts send | |
| 432 | +</verbatim> | |
| 433 | + | |
| 434 | +This should also kick off the backoffice processing, if there are any | |
| 435 | +pending alerts to send out. | |
| 436 | + | |
| 437 | +<verbatim> | |
| 438 | + $ fossil alert pending | |
| 439 | + $ fossil test-add-alerts f5900 | |
| 440 | + $ fossil alert send | |
| 441 | +</verbatim> | |
| 442 | + | |
| 443 | +If the first command gives no output and <tt>pending-alerts</tt> in the | |
| 444 | +earlier command is 0, the second command will add another alert, which | |
| 445 | +should shortly cause another notification email. The <tt>f</tt> in the | |
| 446 | +final parameter means you're scheduling a "forum" alert, and the integer | |
| 447 | +is the ID of a forum post, which you can find by visiting | |
| 448 | +<tt>/timeline?showid</tt> on your Fossil instance. | |
| 449 | + | |
| 450 | +The third command above is necessary because the | |
| 451 | +<tt>test-add-alerts</tt> command doesn't kick off a backoffice run. | |
| 452 | + | |
| 453 | +<verbatim> | |
| 454 | + $ fossil ale send | |
| 455 | +</verbatim> | |
| 273 | 456 | |
| 457 | +This only does the same thing as the final command above, rather than | |
| 458 | +send you an ale, as you might be hoping. Sorry. | |
| 274 | 459 | |
| 275 | 460 | |
| 276 | 461 | <h2>Moderation</h2> |
| 277 | 462 | |
| 278 | -TODO | |
| 279 | - | |
| 280 | - | |
| 281 | -<h2>Troubleshooting</h2> | |
| 282 | - | |
| 283 | 463 | TODO |
| 284 | 464 |
| --- www/forum.wiki | |
| +++ www/forum.wiki | |
| @@ -174,11 +174,11 @@ | |
| 174 | capabilities to individual accounts except in atypical cases, such as |
| 175 | to grant the Moderate Forum capability (5) to an uncommonly |
| 176 | highly-trusted user. |
| 177 | |
| 178 | |
| 179 | <h3>Skin Setup</h3> |
| 180 | |
| 181 | If you create a new Fossil repository with version 2.7 or newer, its |
| 182 | default skin is already set up correctly for typical forum |
| 183 | configurations. |
| 184 | |
| @@ -266,18 +266,198 @@ | |
| 266 | authorized on a different Fossil repository. |
| 267 | |
| 268 | |
| 269 | <h3>Email Notification</h3> |
| 270 | |
| 271 | See [./emaildesign.md | the email notification design document] for now. |
| 272 | More administration-oriented documentation TODO. |
| 273 | |
| 274 | |
| 275 | |
| 276 | <h2>Moderation</h2> |
| 277 | |
| 278 | TODO |
| 279 | |
| 280 | |
| 281 | <h2>Troubleshooting</h2> |
| 282 | |
| 283 | TODO |
| 284 |
| --- www/forum.wiki | |
| +++ www/forum.wiki | |
| @@ -174,11 +174,11 @@ | |
| 174 | capabilities to individual accounts except in atypical cases, such as |
| 175 | to grant the Moderate Forum capability (5) to an uncommonly |
| 176 | highly-trusted user. |
| 177 | |
| 178 | |
| 179 | <h3 id="skin">Skin Setup</h3> |
| 180 | |
| 181 | If you create a new Fossil repository with version 2.7 or newer, its |
| 182 | default skin is already set up correctly for typical forum |
| 183 | configurations. |
| 184 | |
| @@ -266,18 +266,198 @@ | |
| 266 | authorized on a different Fossil repository. |
| 267 | |
| 268 | |
| 269 | <h3>Email Notification</h3> |
| 270 | |
| 271 | The detailed information for this feature of Fossil is in two other |
| 272 | documents: |
| 273 | |
| 274 | * [./alerts.md | Email Alerts] |
| 275 | * [./emaildesign.md | Email Notification Design] |
| 276 | |
| 277 | You may want to study those in detail, since email is complicated. Some |
| 278 | of that complexity necessarily leaks out to the configuration of email |
| 279 | notification in Fossil. |
| 280 | |
| 281 | |
| 282 | <h4>Quick Setup</h4> |
| 283 | |
| 284 | However, if you've already got a working Postfix, Exim, or Sendmail |
| 285 | server on the machine running your Fossil instance(s), and you aren't |
| 286 | using Fossil's <tt>chroot</tt> feature to wall it off from the rest of |
| 287 | the machine, it's fairly simple to set up email notifications: |
| 288 | |
| 289 | <ol> |
| 290 | <li>Go to Admin → Notification and fill out all of the |
| 291 | <b>Required</b> fields:</li> |
| 292 | |
| 293 | <ul> |
| 294 | <li><b>Canonical server URL</b> — Use the suggested URL</li> |
| 295 | <li><b>"From" email address</b> — <tt>[email protected]</tt> |
| 296 | is traditional, but do what you like</li> |
| 297 | <li><b>Repository nickname</b> — See the suggested examples on |
| 298 | the web page.</li> |
| 299 | </ul> |
| 300 | |
| 301 | <li>Set "Email Send Method" to "Pipe to a command"</li> |
| 302 | |
| 303 | <li>Set the "Administrator email address" to a suitable email address. |
| 304 | It could be the same value you used for the "From" address above, |
| 305 | or it could be a different value like |
| 306 | <tt>[email protected]</tt>.</li> |
| 307 | </ol> |
| 308 | |
| 309 | Save your changes. |
| 310 | |
| 311 | <a id="cd"></a>For all of the following <tt>fossil</tt> CLI commands, |
| 312 | we're going to assume that you've <tt>cd</tt>'d into a checkout |
| 313 | directory for your repository on the central server. Otherwise, we'd |
| 314 | need to add <tt>-R /path/to/repo.fossil</tt> to each of them. |
| 315 | |
| 316 | Give this command: |
| 317 | |
| 318 | <verbatim> |
| 319 | $ fossil set email-send-command |
| 320 | </verbatim> |
| 321 | |
| 322 | If that gives a blank value instead of <tt>sendmail -t</tt>, say |
| 323 | |
| 324 | <verbatim> |
| 325 | $ fossil set email-send-command "sendmail -t" |
| 326 | </verbatim> |
| 327 | |
| 328 | to force the setting. That's a |
| 329 | [https://fossil-scm.org/forum/forumpost/840b676410 | known bug] which |
| 330 | should be squished soon. |
| 331 | |
| 332 | This is the correct command even if you're running Postfix or Exim |
| 333 | rather than Sendmail. These mail servers (and perhaps others) provide a |
| 334 | <tt>sendmail</tt> command for this very sort of reason: it lets programs |
| 335 | send email without having to care exactly which server implementation is |
| 336 | running at a given site. |
| 337 | |
| 338 | <a id="status"></a>If you reload the Email Notification Setup page, the |
| 339 | Status section at the top should show: |
| 340 | |
| 341 | <verbatim> |
| 342 | Outgoing Email: Piped to command "sendmail -t" |
| 343 | Pending Alerts: 0 normal, 0 digest |
| 344 | Subscribers: 0 active, 0 total |
| 345 | </verbatim> |
| 346 | |
| 347 | |
| 348 | <h4>Subscribe to Alerts</h4> |
| 349 | |
| 350 | Above, we see that there are no subscribers, so the next step is to add |
| 351 | one. |
| 352 | |
| 353 | Go to the <tt>/subscribe</tt> page on your Fossil instance and sign your |
| 354 | regular Fossil user up for email alerts. (Alternate path: click the |
| 355 | login/logout link in the upper right corner, then go to "Email Alerts".) |
| 356 | You will need "Forum Posts" checked at the least for the testing steps |
| 357 | below. |
| 358 | |
| 359 | If you use the same user name and email address as you used for your |
| 360 | normal user login, Fossil will simply tie your alert preferences to your |
| 361 | login, and it will be considered already-verified. Otherwise, Fossil |
| 362 | will create up an alert-only record, and you will have to verify the |
| 363 | email address before Fossil will send notifications to it. |
| 364 | |
| 365 | This shows a key aspect of the way Fossil's email alerts system works, |
| 366 | by the way: a user can be signed up for email alerts without having a |
| 367 | full-fledged Fossil user account. Only when both user names are the same |
| 368 | are the two records tied together under the hood. |
| 369 | |
| 370 | |
| 371 | <h4>Test the Email Subsystem</h4> |
| 372 | |
| 373 | If you'd rather not create an inane "testing" post in your Fossil |
| 374 | instance just to force out an email alert, we can check whether the |
| 375 | email subsystem separate from the rest of the Fossil Email Alerts system |
| 376 | is working with the following command: |
| 377 | |
| 378 | <verbatim> |
| 379 | $ fossil alerts test-message [email protected] --body README.md --subject Test |
| 380 | </verbatim> |
| 381 | |
| 382 | That should send you an email with "Test" in the subject line and the |
| 383 | contents of your project's <tt>README.md</tt> file in the body. If it |
| 384 | works, the file's contents may be truncated. I'm uncertain whether |
| 385 | that's due to an intentionally-small buffer size or if it's a bug. |
| 386 | |
| 387 | That command assumes that your project [./foss-cklist.wiki | contains a |
| 388 | readme file]. Of course it does. Why would it not? |
| 389 | |
| 390 | |
| 391 | <h4>Frist Post</h4> |
| 392 | |
| 393 | Since you've already edited the skin per [#skin | the instructions |
| 394 | above], you can click the "Forum" link in the navbar and create a new |
| 395 | post. I suggest taking the time to compose a suitable introductory |
| 396 | message especially for your project's forum, suitable for pointing new |
| 397 | forum users at. |
| 398 | |
| 399 | Wait a few seconds, and you should receive a notification email with the |
| 400 | post's subject and body text in the email. |
| 401 | |
| 402 | |
| 403 | <h4>Troubleshooting</h4> |
| 404 | |
| 405 | If email alerts aren't working, there are several useful commands you |
| 406 | can give to figure out why. |
| 407 | |
| 408 | (Be sure to [#cd | <tt>cd</tt> into a repo checkout directory] first!) |
| 409 | |
| 410 | <verbatim> |
| 411 | $ fossil alerts status |
| 412 | </verbatim> |
| 413 | |
| 414 | This should give much the same information as you saw [#status | above]. |
| 415 | One difference is that, since you've created a forum post, the |
| 416 | <tt>pending-alerts</tt> value should only be zero if you did in fact get |
| 417 | the requested email alert. If it's zero, check your mailer's spam |
| 418 | folder. If it's nonzero, continue with these troubleshooting steps. |
| 419 | |
| 420 | <verbatim> |
| 421 | $ fossil backoffice |
| 422 | </verbatim> |
| 423 | |
| 424 | That forces Fossil to run its [./backoffice.md | "back office" process]. |
| 425 | Its only purpose at the time of this writing is to push out alert |
| 426 | emails, but it might do other things later. Sometimes it can get stuck |
| 427 | and needs to be kicked. For that reason, you might want to set up a |
| 428 | crontab entry to make sure it runs occasionally. |
| 429 | |
| 430 | <verbatim> |
| 431 | $ fossil alerts send |
| 432 | </verbatim> |
| 433 | |
| 434 | This should also kick off the backoffice processing, if there are any |
| 435 | pending alerts to send out. |
| 436 | |
| 437 | <verbatim> |
| 438 | $ fossil alert pending |
| 439 | $ fossil test-add-alerts f5900 |
| 440 | $ fossil alert send |
| 441 | </verbatim> |
| 442 | |
| 443 | If the first command gives no output and <tt>pending-alerts</tt> in the |
| 444 | earlier command is 0, the second command will add another alert, which |
| 445 | should shortly cause another notification email. The <tt>f</tt> in the |
| 446 | final parameter means you're scheduling a "forum" alert, and the integer |
| 447 | is the ID of a forum post, which you can find by visiting |
| 448 | <tt>/timeline?showid</tt> on your Fossil instance. |
| 449 | |
| 450 | The third command above is necessary because the |
| 451 | <tt>test-add-alerts</tt> command doesn't kick off a backoffice run. |
| 452 | |
| 453 | <verbatim> |
| 454 | $ fossil ale send |
| 455 | </verbatim> |
| 456 | |
| 457 | This only does the same thing as the final command above, rather than |
| 458 | send you an ale, as you might be hoping. Sorry. |
| 459 | |
| 460 | |
| 461 | <h2>Moderation</h2> |
| 462 | |
| 463 | TODO |
| 464 |