You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@ponymail.apache.org by se...@apache.org on 2017/01/15 23:07:57 UTC
[1/2] incubator-ponymail-site git commit: Synch with code docs
Repository: incubator-ponymail-site
Updated Branches:
refs/heads/asf-site a4ad431ff -> e0ce656f0
Synch with code docs
Project: http://git-wip-us.apache.org/repos/asf/incubator-ponymail-site/repo
Commit: http://git-wip-us.apache.org/repos/asf/incubator-ponymail-site/commit/d7430b81
Tree: http://git-wip-us.apache.org/repos/asf/incubator-ponymail-site/tree/d7430b81
Diff: http://git-wip-us.apache.org/repos/asf/incubator-ponymail-site/diff/d7430b81
Branch: refs/heads/asf-site
Commit: d7430b8144b7aa97178a288d709adb79526d0000
Parents: dce3e8c
Author: Sebb <se...@apache.org>
Authored: Sun Jan 15 23:06:49 2017 +0000
Committer: Sebb <se...@apache.org>
Committed: Sun Jan 15 23:06:49 2017 +0000
----------------------------------------------------------------------
source/markdown/docs/API.md | 64 ++++++++++++++++++++++++++---
source/markdown/docs/IMPORTING.md | 36 +++++++++++-----
source/markdown/docs/INSTALL.fedora.md | 2 +-
source/markdown/docs/INSTALL.ubuntu.md | 5 +--
source/markdown/docs/INSTALLING.md | 15 +++----
5 files changed, 93 insertions(+), 29 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/incubator-ponymail-site/blob/d7430b81/source/markdown/docs/API.md
----------------------------------------------------------------------
diff --git a/source/markdown/docs/API.md b/source/markdown/docs/API.md
index 70461ea..0d868a1 100644
--- a/source/markdown/docs/API.md
+++ b/source/markdown/docs/API.md
@@ -3,10 +3,11 @@
### Fetching a specific email:
Usage:
-`GET /api/email.lua?id=$mid`
+`GET /api/email.lua?id=$mid[&attachment=true&file=$hash]`
Parameters: (cookie may be required)
- $mid: The email ID or Message-ID: header
+ - $hash: the file attachment hash
Response example:
@@ -37,18 +38,23 @@ Response example:
### Fetching list data
Usage:
-`GET /api/stats.lua?list=$list&domain=$domain[&d=$timespan][&q=$query][&header_from=$from][&header_subject=$subject]`
+`GET /api/stats.lua?list=$list&domain=$domain[&d=$timespan][&q=$query][&header_from=$from][&header_to=$to][&header_subject=$subject][&header_body=$body][&quick][&s=$s&e=$e]`
Parameters:
+
- $list: The list prefix (e.g. `dev`). Wildcards may be used
- $domain: The list domain (e.g. `httpd.apache.org`). Wildcards may be used
- $timespan: A [timespan](#Timespans) value
+ - $s: yyyy-mm start of month (day 1)
+ - $e: yyyy-mm end of month (last day)
- $query: A search query (may contain wildcards or negations):
- `foo`: Find all documents containing `foo` in headers or body
- `-foo`: Find all documents NOT containing `foo`.
- `foo*`: Find all documents containing `foo`, `fooa`, `foob` etc
- $from: Optional From: address
+ - $to: Optional To: address
- $subject: Optional Subject: line
+ - $body: Optional body text
Response example:
@@ -56,10 +62,30 @@ Response example:
{
"took": 437179,
"firstYear": 2015,
- "emails": {...},
+ "emails": {
+ {
+ "list_raw": "<dev.ponymail.apache.org>",
+ "gravatar": "66cf545ca7a1b8f595282bb9d8a59657",
+ "id": "b1d6446f5cc8f4846454cbabc48ddb08afbb601a77169f8e32e34102@<dev.ponymail.apache.org>",
+ "epoch": 1474883100,
+ "subject": "Re: Missing tag for 0.9 release",
+ "message-id": "<7f...@apache.org>",
+ "private": false,
+ "irt": "<CA...@mail.gmail.com>",
+ "from": "Daniel Gruno <h....@apache.org>",
+ "attachments": 0
+ },...
+ },
"no_threads": 10,
"domain": "ponymail.info",
- "participants": {...},
+ "participants": {
+ {
+ "count": 3,
+ "name": "Daniel Gruno",
+ "gravatar": "66cf545ca7a1b8f595282bb9d8a59657",
+ "email": "hu...@apache.org"
+ }, ...
+ },
"lastYear": 2015,
"name": "dev",
"cloud": {...},
@@ -73,13 +99,31 @@ Response example:
}
~~~
+### <a name="Timespans"></a>Timespans
+
+Timespans supported by the &d= parameter.
+
+ - d=yyyy-mm => equivalent to &s=yyyy-mm&e=yyyy-mm
+ - d=lte=n[wMyd] (less than n[wMyd] ago, inclusive)
+ - d=gte=n[wMyd] (more than n[wMyd] ago, inclusive)
+ - d=.*dfr=yyyy-mm-dd.* (start date for search, inclusive)
+ - d=.*dto=yyyy-mm-dd.* (end date for search, inclusive)
+ - [wMyd] = weeks, Months, years, days
+ - lte and gte are mutually exclusive
+ - dfr and dto are normally both present
### Fetching preferences and quick list overview
Usage:
-`GET /api/preferences.lua[?logout=true]`
+`GET /api/preferences.lua[?logout][?associate=$email][?verify&hash=$hash][?removealt=$email][?save][?addfav=$list][?remfav=$list]`
Parameters: (cookie required)
- logout: Whether to log out of the system (optional)
+ - associate=$email - associate the account with the $email address
+ - verify&hash=$hash - verify an association request $hash
+ - removealt=$email - remove an alternate $email address
+ - save - save preferences
+ - addfav=$list - add a favourite $list
+ - remfav=$list - remove a favourite $list
Response example:
@@ -132,3 +176,13 @@ Response example:
}
~~~
+### Fetching a month's data as an mbox file
+Usage:
+`GET /api/mbox.lua?list=issues@ponymail.apache.org&date=2016-06`
+
+Response example:
+
+~~~
+TBA
+~~~
+
http://git-wip-us.apache.org/repos/asf/incubator-ponymail-site/blob/d7430b81/source/markdown/docs/IMPORTING.md
----------------------------------------------------------------------
diff --git a/source/markdown/docs/IMPORTING.md b/source/markdown/docs/IMPORTING.md
index 7afeb4c..465cd28 100644
--- a/source/markdown/docs/IMPORTING.md
+++ b/source/markdown/docs/IMPORTING.md
@@ -3,15 +3,12 @@ Pony Mail supports many ways of importing your old mail archives via the
`import-mbox.py` script. For command line argument tips, run `python3
import-mbox.py --help`.
-Imports are digested equally every time, so you can
+Imports are digested equally every time (*), so you can
import from the same source multiple times without creating duplicate emails in
the archive. Both the archiver and the importer use the same digest method, so
they can overlap. Usually, you'll want to set up the archiver first, and when
emails start flowing through it, you'll use the importer to import older emails.
-## Importing attachments
-If you wish to import attached files, add the `--attachments` flag to your import command, otherwise, attachments will be stripped.
-
## Importing from mod_mbox
### Importing a single domain
@@ -20,11 +17,11 @@ https://your.tld/mod_mbox/$list-yourdomain/, you can import all lists from that
`python3 import-mbox.py --source https://your.tld/mod_mbox/ --mod-mbox --project yourdomain`
-For a quick update, which only imports the last 2 months of mail, append then `--quick` flag.
+For a quick update, which only imports the last 2 months of mail, append the `--quick` flag.
You can also import just a single list by specifying that list ID:
-`python3 import-mbox.py --source https://your.tld/mod_mbox/ --mod-mbox --project yourdomain-listname`
+`python3 import-mbox.py --source https://your.tld/mod_mbox/ --mod-mbox --project listname-yourdomain`
### Importing an entire archive (multiple domains)
To import an entire site, use the same command as above, but omit the `--project` flag
@@ -34,7 +31,7 @@ To import an entire site, use the same command as above, but omit the `--project
### Setting the domain or list id properly in case of variance
If your old archive varies in terms of list IDs across time, you can force harmonization by using the `--lid` or `--domain` flags:
-`python3 import-mbox.py --source https://your.tld/mod_mbox/ --mod-mbox --project listid-yourdomain --lid "<listid.youdomain.tld>"`
+`python3 import-mbox.py --source https://your.tld/mod_mbox/ --mod-mbox --project listid-yourdomain --lid "<listid.yourdomain.tld>"`
This should only be done one list at a time.
@@ -53,12 +50,31 @@ While the `project` flag is not needed here, you may wish to specify the list ID
## Importing from locally stored mbox files
To import from one or more local mbox files, specify a filesystem path as the source:
-`python3 import-mbox.py --source /tmp/mylists/ --attachments`
+`python3 import-mbox.py --source /tmp/mylists/`
+
+This will recursively import all files with the extension '.mbox'.
+
+You can change the extension as follows:
+
+`python3 import-mbox.py --source /tmp/mylists/ --ext .mbx`
+
+To match all files with any non-empty extension:
-If you have a mix of mbox and non-mbox files in the specific dir, you may wish to let Pony Mail know which files to scan:
+`python3 import-mbox.py --source /tmp/mylists/ --ext '.*'`
-`python3 import-mbox.py --source /tmp/mylists/ --ext .mbox --attachments`
+To match files regardless of extension:
+
+`python3 import-mbox.py --source /tmp/mylists/ --ext ''`
+
+Or you can import a single file:
+
+`python3 import-mbox.py --source 2016-11.mbox`
+
+(This is supported in versions after 0.9)
## Test archives
We have a few test archives for those that wish to test large imports.
They can be found in gzip format at [http://ponymail.info/mboxes/](http://ponymail.info/mboxes/)
+
+(*) The digest depends on the [archiver] generator setting in ponymail.cfg
+If that varies between imports, then duplicates will occur
http://git-wip-us.apache.org/repos/asf/incubator-ponymail-site/blob/d7430b81/source/markdown/docs/INSTALL.fedora.md
----------------------------------------------------------------------
diff --git a/source/markdown/docs/INSTALL.fedora.md b/source/markdown/docs/INSTALL.fedora.md
index a94ce6f..f27e1ee 100644
--- a/source/markdown/docs/INSTALL.fedora.md
+++ b/source/markdown/docs/INSTALL.fedora.md
@@ -109,4 +109,4 @@ elasticsearch settings once Pony mail is up and running.
Refer to the [General installation documentation](INSTALLING.md) for
detailed information about archiving messages, OAuth, mail settings and
-much more.
\ No newline at end of file
+much more.
http://git-wip-us.apache.org/repos/asf/incubator-ponymail-site/blob/d7430b81/source/markdown/docs/INSTALL.ubuntu.md
----------------------------------------------------------------------
diff --git a/source/markdown/docs/INSTALL.ubuntu.md b/source/markdown/docs/INSTALL.ubuntu.md
index dff4752..95c47a2 100644
--- a/source/markdown/docs/INSTALL.ubuntu.md
+++ b/source/markdown/docs/INSTALL.ubuntu.md
@@ -67,14 +67,14 @@ sudo python3 setup.py
Set up Apache httpd by adding, for example, the following virtual host configuration (e.g. in `/etc/apache2/sites-enabled/000-default.conf`):
~~~
-<VirtualHost *:80>
+<VirtualHost *:80>
ServerName mylists.foo.tld
DocumentRoot /var/www/ponymail/site
AddHandler lua-script .lua
LuaScope thread
LuaCodeCache stat
AcceptPathInfo On
-</VirtualHost>
+</VirtualHost>
~~~
Enable mod_lua and start apache, if not already enabled:
@@ -92,4 +92,3 @@ elasticsearch settings once Pony mail is up and running.
Refer to the [General installation documentation](INSTALLING.md) for
detailed information about archiving messages, OAuth, mail settings and
much more.
-
http://git-wip-us.apache.org/repos/asf/incubator-ponymail-site/blob/d7430b81/source/markdown/docs/INSTALLING.md
----------------------------------------------------------------------
diff --git a/source/markdown/docs/INSTALLING.md b/source/markdown/docs/INSTALLING.md
index 9f66882..e7244de 100644
--- a/source/markdown/docs/INSTALLING.md
+++ b/source/markdown/docs/INSTALLING.md
@@ -18,6 +18,7 @@ You will need the following software installed on your machine:
- Python 3.x for the archiver plugin (setup.py will handle dependencies) and importer
- Apache HTTP Server 2.4.x with mod_lua (see http://modlua.org/gs/installing if you need to build mod_lua manually)
- Lua >=5.1 with the following modules: cjson, luasec, luasocket
+ (Note: Lua 5.3 is not currently supported by httpd mod_lua or luasocket)
## Download and Install ##
@@ -108,16 +109,9 @@ Run `python3 edit-list.py --help` for CLI args.
## Setting up OAuth for Pony Mail ##
-If you want people to be able to log in and reply via the Web UI, you can either
-use the default Persona login (works for all email addresses) or specify an
-OAuth provider.
+If you want people to be able to log in and reply via the Web UI, you
+can specify an OAuth provider.
-### Setting up or disabling Persona ###
-Persona is enabled by default, as it's a fast and convenient way to enable
-logins for *public* lists. Should you wish to disable Persona, set the
-`enabled` variable to `false` in the persona section of `site/js/config.js`.
-Persona will only ever work for public lists. For private lists, you will need
-to specify and implement an OAuth provider.
### Setting up an OAuth provider ###
Pony Mail comes with a few default OAuth examples in `site/js/config.js`, such
@@ -216,4 +210,5 @@ body, timestamp and list-ID to generate the MID. There is also a 'short'
that only digests the body, and a 'full' that uses the entire message as
a bytestring to generate an ID. Medium is recommended for most setups
(especially clustered setups), while full can be used for single-machine
-setups.
\ No newline at end of file
+setups.
+N.B. At present, all the generators have issues, see (#176 #177 #178)
[2/2] incubator-ponymail-site git commit: Merge branch 'asf-site' of
https://git-wip-us.apache.org/repos/asf/incubator-ponymail-site into asf-site
Posted by se...@apache.org.
Merge branch 'asf-site' of https://git-wip-us.apache.org/repos/asf/incubator-ponymail-site into asf-site
Project: http://git-wip-us.apache.org/repos/asf/incubator-ponymail-site/repo
Commit: http://git-wip-us.apache.org/repos/asf/incubator-ponymail-site/commit/e0ce656f
Tree: http://git-wip-us.apache.org/repos/asf/incubator-ponymail-site/tree/e0ce656f
Diff: http://git-wip-us.apache.org/repos/asf/incubator-ponymail-site/diff/e0ce656f
Branch: refs/heads/asf-site
Commit: e0ce656f00854e98def042b3217dd553311650e0
Parents: d7430b8 a4ad431
Author: Sebb <se...@apache.org>
Authored: Sun Jan 15 23:07:44 2017 +0000
Committer: Sebb <se...@apache.org>
Committed: Sun Jan 15 23:07:44 2017 +0000
----------------------------------------------------------------------
content/source.html | 3 ++-
1 file changed, 2 insertions(+), 1 deletion(-)
----------------------------------------------------------------------