[docs] Add README with some basic info

1 files changed, 67 insertions, 0 deletions

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..f5d89be
--- /dev/null
+++ b/README.md
@@ -0,0 +1,67 @@
+
+# acit
+acit is Another Custom Issue Tracker. It could've been called EDIT (Email-Driven Issue Tracker), but acit was chosen as the eventual name.
+
+As the alternative name (EDIT) suggests, acit is an email-driven issue tracker. This means the primary way to interact with issues is email. It uses plus-addresses (eg `bugs+project1@example.com`) for sorting between projects, meaning it only needs 1 account on the mail server to track multiple projects.
+
+# projectlist
+This fetches your projects using a projectlist. This list is refreshed every few requests, and every time an email is received. The file should just be a newline-separated file of projects. `.git` is stripped off the end of each name if present. This allows for quick integration with gitolite's `project.list`.
+Note that if a project disappears from your projectlist file, acit will simply stop accepting emails for that project. It'll also stop displaying the project on the webui's projects lists. No data will be deleted though; readding the project to the file will simply start showing the project again.
+
+# configuration
+Acit requires all email is stored in a single imap account. Aliases are fine (I use them myself).
+
+To configure acit, use environment variables. Here's an overview of them, including example values:
+
+```sh
+#
+# IMAP login
+# ----------
+ # set this to the IMAP login values of your email server
+ ACIT_IMAP_USER="bugs@example.com"
+ ACIT_IMAP_PASSWD="SuperSecurePassword"
+ ACIT_IMAP_SERVER="mail.example.com"
+ ACIT_IMAP_PORT=0 # if set to 0, uses default port (993)
+ # note we only support IMAP with Implicit TLS.
+ # usage of IMAP using STARTTLS and unencrypted imap aren't implemented.
+
+#
+# SMTP login
+# ----------
+ # set this to the SMTP login values of your email server
+ ACIT_SMTP_USER="bugs@example.com"
+ ACIT_SMTP_PASSWD="SuperSecurePassword"
+ ACIT_SMTP_SERVER="mail.example.com"
+ ACIT_SMTP_PORT=0 # SMTP port to connect to. If set to 0, uses port 465
+ # note only SMTP using Implicit TLS is supported.
+ # STARTTLS and unencrypted SMTP are, just like with IMAP, not implemented.
+
+
+#
+# Email matching/formatting
+# -------------------------
+
+ ACIT_MAIL_NAME="bugs" # the user part of user@example.com
+ ACIT_MAIL_DOMAIN="example.com" # the domain of the emailaddress
+ ACIT_MAIL_USES_ALIASES= # if set to any value, enables the usage of aliases.
+ :<<-DOC
+ Normally, acit looks for an emailaddress that matches email addresses in this style:
+   bugs+projectname#15@example.com
+ where 'bugs' is your value of ACIT_MAIL_NAME, and 'example.com' is
+ your value of ACIT_MAIL_DOMAIN. 'projectname' can be any set of characters that
+ isn't one of: @+#
+ it then strips the value ACIT_MAIL_NAME and a plus (+) from the start and the value
+ of ACIT_MAIL_DOMAIN and an at (@) from the back, and splits it on the last hash (#).
+ anything before the hashtag is the project name, anything after is the issue number.
+
+ Note that if ACIT_MAIL_USES_ALIASES is set, it simply skips stripping the value of
+ ACIT_MAIL_NAME and plus from the start.
+
+ 
+ if ACIT_MAIL_NAME is unset, it uses everything before the at (@) in ACIT_IMAP_USER.
+ if ACIT_MAIL_DOMAIN is unset, it uses everything behind the at (@) in ACIT_IMAP_USER.
+ DOC
+
+
+```
+