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.
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.
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:
#
# IMAP login
# ----------
# set this to the IMAP login values of your email server
ACIT_IMAP_USER=bugs@example.com
ACIT_IMAP_PASS=SuperSecurePassword
ACIT_IMAP_SERVER=mail.example.com
ACIT_IMAP_PORT=993
# note we only support IMAP with Implicit TLS.
# usage of IMAP using STARTTLS and unencrypted imap aren't implemented.
ACIT_IMAP_POOL_SIZE=4 # the amount of IMAP connections to make. Note at least 2 is recommended.
# a pool size of 1 can lead to it taking ridiculously long to process new email or generate pages.
#
# SMTP login
# ----------
# set this to the SMTP login values of your email server
ACIT_SMTP_USER=bugs@example.com
ACIT_SMTP_PASS=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.
#
# Database
# --------
MYSQL_USER=acit # username for the mariadb server
MYSQL_PASSWORD=AnotherSecurePassword # password for said server
MYSQL_DATABASE=acit # the database to use
MYSQL_HOST=localhost # the hostname/ip of the server. to define a port, use host:port syntax.
#
# 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
#
# Settings
# --------
ACIT_HOME_REDIRECT=about:blank # where to redirect to when someone queries the webroot
ACIT_BEHIND_PROXY= # when set, acit displays the 'real ip' when behind a proxy
# the following option is the path used for the bug editor. note it's your own responsibility
# to provide a username/password or other authentication system on this path,
# ACIT DOES NOT CHECK WHETHER A USER IS ALLOWED TO EDIT AN ISSUE. See section `securing issue editing`
ACIT_SECURE_PATH=/secure/
# the following option should be the full path to an executable.
# said executable should return a table of trackers and urls.
# see #acit-list-trackers below in this README.md # TODO: write mentioned section
ACIT_LIST_TRACKERS=/usr/lib/acit-list-trackers
By default, the path set using ACIT_SECURE_PATH (defaults to /secure/) does not have any authentication or authorisation. It's your responsibility to secure it. You can do this by putting a reverse-proxy of some kind between acit and the internet that checks for that path, and then checks whether the password and username is correct.
Because I use caddy, here is an example adjusted from the examples in caddy's documentation:
example.com {
root * /srv
basic_auth /secure/* {
# Username "Bob", password "hiccup"
Bob $2a$14$Zkx19XLiW6VYouLHR5NmfOFU0z2GTNmpkT/5qqR7hx4IjWJPDhjvG
}
reverse_proxy :8080
}
This reverse-proxies all traffic to localhost:8080 without authentication. However, when someone tries to access anything matching the glob /secure/*, it'll ask for authentication before proxying. For more information, see caddy's documentation page I linked above.
Note: If you would like acit to do this itself, feel free to send me a patch. I'm not interested in writing it myself due to the amount of code it would add, and I can use caddy to do authentication already, which works for my scale.
