Lisää README.md

README.md

@@ -0,0 +1,65 @@
+# Tiedote.md
+
+Tiedote.md on yksinkertainen massasähköpostijärjestelmä, joka perustuu Gittiin,
+Pandocin markdowniin ja sähköpostiin.
+
+## Kehittäminen
+
+Kehitysympäristön saa luotua helposti komennolla `guix shell`. Muutoksia
+koodiin hallitaan Git-versionhallintatyökalulla ja muutosehdotuksia voi
+[lähettää `git send-email`:n avulla](https://git-send-email.io/) osoitteeseen
+<admin@mail.olarinmaensamoojat.fi> tai Gitean avulla.
+
+## Asentaminen
+
+Helpoin tapa asentaa tiedote.md on lisätä alla oleva kanava [Guix:n
+kanavalistaan](https://guix.gnu.org/manual/en/guix.html#Specifying-Additional-Channels). 
+
+```
+(channel
+ (name 'tiedote.md)
+ (url "https://git.olarinmaensamoojat.fi/OMS/tiedote.md.git")
+ (branch "main")
+ (introduction
+  (make-channel-introduction
+   "d9157e9e8aa78363d14344293d6a0bc47a8d5a7b"
+   (openpgp-fingerprint
+    "A0C9 1947 734F 076F 5F08 E9FF 257D 284A 2A1D 3A32"))))
+```
+
+Tämän jälkeen ajetun `guix pull` -komennon jälkeen tiedote.md on saatavilla
+tiedote-md nimisenä pakettina kaikkialla Guixissa.
+
+Koodin voi myös kääntää käsin Haskellin `cabal`-infrastruktuurin avulla.
+
+## Ajaminen
+
+Tiedote.md koostuu kahdesta osasta: palvelimesta ja sähköpostin toimittajasta.
+Sähköpostin toimittaja vastaanottaa sähköpostit ja toimittaa ne palvelimelle
+käsiteltäväksi. Palvelin vastaa kaikesta kirjanpidosta, sähköpostien
+lähettämisestä ja Git-tietovaraston päivittämisestä, kun se saa muutoksista
+ilmoituksen HTTP POST -pyyntönä (esim. Git-palvelun webhookista).
+
+Palvelimen voi käynnistää komennolla `tiedote.md server`. Mahdolliset asetukset
+saa listattua lisäämällä komentoon `--help` valitsimen. `--address`
+valitsimesta tulee huomata, että osoitteessa voi käyttää vain ASCII-merkkejä
+(ks. [#15](https://git.olarinmaensamoojat.fi/OMS/tiedote.md/issues/15)).
+
+Sähköpostin lähettämiseen tarvitaan `sendmail`-yhteensopiva MTA (mail transfer
+agent, sähköpostin välitysohjelma), jollaisen useimmat sähköpostipalvelimet
+tarjoavat. Jos tiedote.md:n palvelimella ei ole omaa sähköpostipalvelinta, voi
+tähän käyttää [`msmtp`:tä](https://marlam.de/msmtp/).
+
+Sähköposti saapuu tiedote.md:n tietoon niin, että se annetaan komennon
+`tiedote.md receive` syötteeksi (tarkista, että asetusvalitsimet vastaavat
+palvelimen asetuksia). Tämä on yleensä helppo automatisoida
+`.forward`-tiedostolla seuraavankaltaisella rivillä, jos tiedote.md on
+palvelimella, jolle toimitetaan tiedote.md:lle tulevat sähköpostit.
+
+```
+|/path/to/tiedote.md receive
+```
+
+Muissa tapauksissa joutuu todennekäisesti kirjoittamaan skriptin, joka hakee
+sähköpostit jostain muualta tai toimittaa ne esim. `ssh`:n yli
+`tiedote.md receive`:lle.