Bobweb on erään kaveriporukan oma chättibotti.
Joka päivä henkilö joka sanoo ekana 1337 klo 1337 saa pisteen. Lisäksi, kerran viikossa on mahdollista ansaita ylennys mergeämällä muutos tämän repon main haaraan.
Tässä on nähty paljon vaivaa ja tehty tosi hieno CI/CD putki.
Bottia ajetaan Raspberry Pi 2B:llä.
Projekti on jaettu kahteen osioon: Bob ja Web. Bob on Telegram botin toteutus, Web on djangolla toteutettu webbisivu.
"Only way to go fast is to go well" - Uncle Bob
Projektissa on käytössä GitHub Actions ja Sonar Cloud quality gate. Pull requestin ja jokaisen siihen kohdistuvan puskun yhteydessä suoritetaan:
Kun main-haaraan pusketaan muutoksia tapahtuu sekä koko projektin Sonar laatuanalyysi, että automaattinen muutosten deployaaminen tuotantoon. Deployaamisessa buildataan projektista valmiit docker imaget alustoille [amd64, armv7] ja näistä pusketaan imaget DockerHubiin. Tuotantoympäristö tarkistaa uusimman version viiden minuutin välein ja uudelleenkäynnistää botin uusimmalla versiolla mikäli sellainen on saatavilla.
Telegram botti sisältää pitkän listan erilaisia kivoja ominaisuuksia. Suurin
osa näistä ominaisuuksista on nähtävissä /help
komennolla (WIP)
Tällä hetkellä ainakin nämä ominaisuudet löytyvät:
/sähkö
- näyttää kuluvan päivän pörssisähkön hintatilastot/ruoka
- Palauttaa satunnaisen ruokareseptin/space
- Palauttaa tiedon seuraavasta avaruusraketin
laukaisusta/sää [kaupunki]
- Palauttaa syötteenä annetun kaupungin
sään/käyttäjät
- Antaa listan keskustelun käyttäjistä, heidän
arvostaan ja kunniasta 1337-pelissä sekä lähetettyjen viestien määrän tietyn
hetken jälkeen/aika
- Antaa tämän hetken kellonajan sekunnin sadasosan
tarkkuudella1337
- Antaa pelaajalle pisteen tai "ylennyksen", jos kello on 13:37 ja
kukaan muu ei ole ehtinyt sanoa 1337/asetukset
voit säätää botin komentoja ja toimintoja päälle tai pois. Kuulutuksilla tarkoitetaan toimintoa, missä
Bob mm.
kuuluttaa uusimman gitin commit viestin käynnistyessään./ruoka
jotain tekstiä .vai jotain tekstiä .vai jotain tekstiä
- Arpoo
satunnaisesti 2 - n vaihtoehdon välillä, kun ne on eroteltu avainsanalla '.vai'/kunta
generoi satunnaisen kunnan/kysymys
- Päivän kysymykseen liittyvien toimintojen hallinta/twitch [kanava]
- Näyttää kanavan sen hetkisen striimin tiedot. Päivittää tietoja niin kauan kun kanavan striimi on päällä/epicgames
- hakee tiedon kysymyshetkellä epic games storessa ilmaiseksi jaossa olevista peleistä./huoneilma
- Näyttää sisälämpötilan ja ilmankosteuden "serverihuoneessa"/gpt [prompt]
generoi vastauksen annettuun kysymykseen. Generointi vie n. 30-60 sekuntia./dallemini [prompt]
generoi kuvan annetulla promptilla ja lähettää sen vastauksena. Käyttää Dallemini-mallia
generointiin./dalle [prompt]
generoi kuvan annetulla promptilla ja lähettää sen vastauksena. Käyttää Dall-e 2 mallia
generointiin./tekstitä
tekstittää komennon kohteena olevan viestin sisältämän median puheen tekstiksi. Esimerkiksi ääniviestiin
vastatessa tällä komennolla botti tekstittää kyseisen ääniviestin sisällön/lausu
lausuu komennon kohteena olevan viestin ääneen. Botti palauttaa ääniviestin.Muita ominaisuuksia:
"Mummo-ohjeet", miten Bobista saa kopion käyntiin omalle koneelle tai miten esimerkiksi yksikkötestit ajetaan.
Sovellusta voi ajaa joko paikallisesti asennetuilla ohjelmilla tai Docker-kontissa. Suositeltu kehitysympäristö on PyCharm, josta löytyy myös ilmainen community edition.
Asennettujen sovellusten vaatimukset
PyCharm Ultimate version suositellut asetukset
Botin ajamiseen paikallisesti on 2 vaihtoehtoa. Vaihtoehto 1 on käyttää paikallista ympäristöä, missä python ja botin käyttämät riippuvuudet on asennettu levylle käyttäjän käyttöjärjestelmän tiedostohierarkiaan. Vaihtoehto 2 on käyttää Docker-kontteja, jolloin kaikki bottiin liittyvä asennus tehdään eristetyn kontin sisällä. Molemmissa on omat hyvät ja huonot puolensa. Lähtökohtaisesti on helpompi ajaa bottia paikallisesti, mutta Docker konttien käyttö eristää bottiin liittyvät asiat omaan konttiinsa, jolloin muut asennetut python versiot tai kirjastot eivät aiheuta ongelmia.
Koska tietokanta luodaan Djangon migraatioilla, tarvii Docker-konttien vaihtoehdossa valmistella projekti osittain paikallista suoritusta varten.
git clone git@github.com:M4R774/bobweb2.git
# Asenna käytetyt kirjastot
cd bobweb2
pip install -r requirements.txt
bobweb/bob/config.py
. Ympäristömuuttujan
voi lisätä myös main.py
ajokonfiguraatioon jos ajat bottia paikallisesti. Dockeria käytettäessä tunnukset pitää
olla lisättynä ympäristömuuttujiin
BOT_TOKEN
= Tähän asetettava jonkin BotFatherilla luodun botin tunnus. Muut
ympäristömuuttujat ovat tarpeen vain osaan ominaisuuksiasetx {AVAIN} "{arvo}"
, missä {AVAIN} on
ympäristömuuttujan avain ja {arvo} on sen
arvo. Esim botin tokenin voi lisätä windowsin komentoriviltä setx BOT_TOKEN 123ASD456FGH
, joss jälkimmäinen
merkkijono on todellinen tokenipython bobweb/web/manage.py migrate
bobweb/bob/main.py
ja sen sisältä rivi, joka sisältää if __name__ == '__main__':
. Klikkaa sen vasemmalla
puolella marginaalissa olevaa nuolta (jos Pycharm) tai ajamalla komentoriviltä python bobweb/bob/main.py
komennolla./deploy.dev.sh
(linux) tai .\deploy.dev.bat
(windows). Ensimmäinen imagen build kestää joitakin minuutteja, jonka
jälkeen myöhemmät buildit ovat nopeampia.Jos haluat ajaa botin testejä paikallisesti komentoriviltä, onnistuu se alla olevilla komennoilla. Jos käytössäsi on PyCharm Ultimate, ja olet määritellyt testiajajaksi Djangon oman testiajurin (kts. alempaa "PyCharm Ultimate version suositellut asetukset") voit ajaa testejä myös suoraan PyCharmin käyttöliittymästä valitsemalla ajokonfiguraatioksi jonkin testiajon tai klikkaamalla editorin marginaalissa testiluokan/-metodin vieressä olevaa nuolta.
Community Editionilla testejä ajettaessa on käytössä Pythonin oletus testiajaja, jolloin paikalliseen tietokantaan voi jäädä testiajoissa luotua dataa. Community Editionillakin voi ajaa testejä suoraan editorin marginaalista. Tätä varten kannattaa projektiin määritellä ajokonfiguraatio template python-testeille niin, että niissä käytetään oikeaa working directorya. Ohjeet alempana.
Kaikki testit voi ajaa Djangon ajurilla komentoiriviltä alla olevilla komennoilla ja tämä on suositeltavaa aina kun haluaa varmistaa, ettei paikalliset tai kehityshaarassa olevat muutokset ole rikkoneet miään. Testikomentoon voi antaa lisäparametreja, joilla voi tarkentaa mitä testejä ajetaan. Lisätietoa parametreista löytyy Djangon dokumentaatiosta.
# Botin testit
python bobweb/web/manage.py test bobweb/bob
# Webbisivun testit
python bobweb/web/manage.py test bobweb/web
Tietokanta on Djangon hallinnoima. Näin ollen tietokannan ylläpitoon pätee Djangon perus workflow, joka on dokumentoitu täällä tarkemmin: https://docs.djangoproject.com/en/4.0/topics/migrations
Aina kun tietomalliin tulee muutoksia, eli esim. tietokantaan tulee lisää sarakkeita, sarakkeita poistuu tai sarakkeen nimi muuttuu, tulee tietokanta "migroida". Alta löytyy komentorivikomennot tämän toimenpiteen tekemiseksi.
# Luo migraatiotiedostot
python bobweb/web/manage.py makemigrations
# Lisää migraatiotiedostot versionhallintaan
git add .
# Migroi paikallinen tietokanta
python bobweb/web/manage.py migrate
Jos huomaat puutteita migraatiossa tai teet lisää muutoksia tietomalliin, on mielekästä lopuksi tiivistää kaikki samaan kokonaisuuteen liittyvät muutokset yhteen migraatioon, ettei jokaiselle pienelle muutokselle tule turhaan omaa migraatiotansa. Migraatioiden tiivistäminen onnistuu poistamalla kaikkia kehityshaarassa lisätyt migraatiotiedostot migraatio-kansiosta ja ajamalla komento
# Migratoi paikallisen kannan taaksepäin aiempaan versioon
python bobweb/web/manage.py migrate bobapp XXXX
# missä XXXX on viimeisin migraatio ennen nykyisiä muutoksia.
# Tämän jälkeen kun ajaa jälleen
python bobweb/web/manage.py makemigrations
python bobweb/web/manage.py migrate
# Niin luodaan 1 migraatio kaikille muutoksille ja tietokanta migratoidaan jälleen siihen versioon.
# HUOM! Migraatioissa kulkeminen taaksepäin voi aiheuttaa tiedon menetystä paikallisessa tietokannassa.
# Esim jos olet luonut uuden taulun ja lisännyt sinne jo tietoa, lisäämis-migraation poistaminen
# ja uudelleenluominen aiheuttaa kyseisen taulun sisällön katoamisen
Jos teit muutoksia esimerkiksi Dockerfile-tiedostoon, voit vielä varmistaa muutostesi toimivuuden paikallisesti alla olevalla komennolla. Tietokoneesi arkkitehtuuri (x86_64) poikkeaa Raspberry Pi:n arkkitehtuurista (armv7l) mikä vaikuttaa riippuvuuksien asentamiseen.
docker build --platform linux/armhf . -t bob-armhf --progress=plain --no-cache
Luo uusi moduuli ja sinne luokka joka perii ChatCommand luokan. Esim moduuli (tiedosto) uusi_komento_command.py
ja
siellä luokka:
class UusiKomento(ChatCommand):
def __init__(self):
super().__init__(
name='uusiKomento',
regex=regex_simple_command('uusiKomento'),
help_text_short=('uusiKomento', 'tähän pari sanaa enemmän')
)
def is_enabled_in(self, chat):
return True # Tähän ehto, että komento on käytössä kyseisessä chatissä.
async def handle_update(self, update: Update, context: CallbackContext = None):
# tähän komennon varsinainen toteutus, eli kaikki mitä tapahtuu kun komento laukeaa
await update.message.reply_text('Hei, tämä on uusi komento')
Tämän jälkeen lisää komento moduulin command_service.py
metodiin create_all_but_help_command()
. Tämän jälkeen
komento on käytettävissä normaalisti.
Ajokonfiguraatioiden muokkausikkunassa on vasemmassa alakulmassa Edit configuration templates...
joka avaa uuden
ikkunan mistä pystyy muokkaamaan projektin ajoasetusten oletusarvoja. Nämä oletusarvot tulevat aina jatkossa niille
ajokonfiguraatioille, jotka luodaan lennosta kun editorin marginaalista tai kontekstivalikosta valitseee Run..
-toiminnon.
Aseta Python tests
alla olevaan pytest
configuraatioon working directory
arvoksi projektin juurikansio ("bobweb2").
Tällöin testit mitkä lukevat testiä varten tiedostoja levyltä löytävät ne, eivätkä testit epäonnistu sen takia, että niitä
ajetaan väärästä tiedostopolusta.
Käy asettamassa PyCharmiin Django-asetukset. Ne löydät asetukset-valikosta polusta Languages & Frameworkds > Django. Aseta seuraavasti:
Asetus | Selite |
---|---|
Enable Django Support | ☑ (valittu) |
Django project root | Tähän polku projektin juuri-kansioon (bobweb2-kansio) |
Settings | Tähän polku settings.py moduuliin, eli bobweb\web\web\settings.py |
Do not use Django test runner | ☐ (tyhjä) |
Manage script | Polku manage.py moduuliin, eli bobweb\web\manage.py |
Näiden asettamisen jälkeen samassa ikkunassa olevasta napista Show Structure pitäisi aueta pieni ali-ikkuna, jossa näkyy mm. kohdan applications alla kohta bobweb.web.bobapp.
Nämä asetukset mahdollistavat monen toimenpiteen ajamisen ilman komentoriviä suoraan PyCharmin käyttöliittymän kautta. Esim testi-moduulissa yksittäisen testitapauksen voi ajaa marginaalissa sen otsikon vieressä olevasta nuolesta niin, että PyCharm osaa käyttää Djangon testien ajajaa.