Tech:Overview
Technical documentation. Maintained by KurthBemis, last reviewed October 22, 2026.
This page gives a plain-language picture of the technology behind UVLists: what runs where, how a message travels from one neighbor to the rest of the list, and why things are built the way they are. It is written for volunteers, board members, and anyone curious. You do not need to be an engineer to follow it.
For help using the lists, see the help pages instead.
The big picture
UVLists runs on two servers, each with its own job:
| Server | What it does |
|---|---|
The lists server (lists.uvlists.org)
|
Runs the public town lists: receives messages, filters spam, sends each message to subscribers, keeps the archives, and hosts the web pages where people manage their subscriptions. |
| The organization server | Runs everything else: this wiki, the go.uvlists.org list pages, the helpdesk, UVLists staff email, and the private lists used by the board and committees.
|
Keeping the public lists on their own server is deliberate. A problem on one server, such as a flood of spam or a software failure, cannot take down the other. It also keeps the public lists' sending reputation (how much email providers trust our mail) separate from the organization's own email.
Each service runs in its own isolated container on its server, so that services do not interfere with one another and can be updated one at a time.
How a message travels
When a neighbor sends a message to their town list, it takes this path:
- The message arrives at the lists server, addressed to the list (for example,
norwich-discuss@lists.uvlists.org). - It is checked for spam and viruses. Obvious spam and infected messages are refused at the door, and the sender gets an error.
- The list software takes over. It checks that the sender is subscribed and that the message follows the list's rules, such as the size limit. A message that needs a human decision is held for the list's volunteer moderators.
- The message is prepared for delivery. The list adds its subject tag (such as
[Norwich-discuss]) and standard headers that let email programs show an Unsubscribe button. - It is signed. The server adds a digital signature (DKIM) that lets email providers verify the message really came from UVLists and was not altered on the way.
- A copy goes to every subscriber, either right away or bundled into a digest, depending on each person's settings.
- The message is saved in the list archive, where members (and, for most lists, the public) can read it on the web.
If a subscriber's email provider refuses a message, the list notices. After repeated refusals it pauses delivery to that address, as described in Delivery problems.
The software we use
UVLists uses established, open-source software wherever it can, and writes its own only to fill gaps.
| Software | What it does for UVLists |
|---|---|
| GNU Mailman 3 | The mailing list software. It includes Postorius, the web pages for managing subscriptions and lists, and HyperKitty, the web archive. |
| Postfix | The mail server that receives and sends email. |
| Rspamd and ClamAV | Spam and virus filtering for incoming mail. |
| MediaWiki | This wiki, which is also the UVLists website. |
| Request Tracker | The helpdesk. Every message to helpdesk@ and similar addresses becomes a ticket so nothing is lost. |
| Gitea | Where volunteers keep UVLists code, server configuration, and detailed technical documentation. |
| Debian and Incus | The operating system on the servers, and the container system that keeps each service separate. |
| Ansible and octoDNS | Tools that describe our server setup and DNS records as files, so changes are reviewed, repeatable, and recorded instead of made by hand. |
On top of these, volunteers have written a few small additions of our own, such as the daily digest emails, the go.uvlists.org list pages and contact cards, and the tools used to move the lists from their previous home.
How we chose
A few decisions shape everything else. The full records, with the alternatives we considered, are kept in Gitea for volunteers.
- Mailman 3 for the lists
- The lists previously ran on different software (Sympa). They now run on Mailman 3, which is open source, widely used, and actively maintained, and includes web pages for subscribers and list administrators. Subscribers' settings, including digest preferences, were carried over in the move.
- Our own servers
- The lists run on servers that UVLists operates itself, set up and maintained by UVLists volunteers.
- Public lists separate from everything else
- Explained in The big picture above: a problem on one server cannot take down the other, and the public lists' sending reputation stays separate.
- Configuration as code
- Server settings live in files in Gitea and are applied with Ansible. Anyone on the technical team can see exactly how a server is set up and what changed, and a server can be rebuilt from those files if it ever fails.
- New list names ending in -discuss
- See Renaming Lists.
Keeping things safe
- Only what is needed is reachable. The web pages and mail services are open to the internet. Administrative access is restricted to the technical team, and everything else on the servers is closed to outside connections.
- Accounts are limited. Wiki editing, list administration, and server access are each granted only to the volunteers who need them.
- Subscriber information is used only to run the lists. It is never sold or shared.
- Email is authenticated. UVLists publishes SPF, DKIM, and DMARC records so that email providers can recognize real UVLists mail and reject forgeries.
Security details, such as server addresses and firewall rules, are deliberately kept off this public wiki.
More technical pages
More pages in the Tech: section are planned, including privacy and data handling, the software we have written, email deliverability, and how to get involved on the technical side. In the meantime, see Get involved or email tech-comm@uvlists.org.