Dokuwiki bemutató

Posted on

Mire jó a dokuwiki?

A DokuWiki egy standardoknak megfelelő, egyszerűen használható wiki, amely szinte bármilyen dokumentáció létrehozásához jó eszköz lehet. Főként fejlesztői csapatoknak, munkacsoportoknak és kisebb vállalatoknak szánták. Egyszerű és nagyszerű formázó szintaktikája van, mellyel könnyedén készíthetünk jól strukturált szövegeket. Minden adatot szövegfájlokban tárol, tehát nincs szüksége adatbázisra.

https://www.dokuwiki.org/hu:dokuwiki

Én mire használom?

Tipikusan szöveges tartalmak (howtok) tárolására, képekkel illusztrálva. A benne tárolt információk döntő többsége nem nyilvános, így fel se merült bennem, hogy a wikipedia-t használjam erre a célra.

A korábbi munkahelyemen ismerkedtem meg vele (kb 17 éve), ott az volt a policy, hogy minden munkával kapcsolatos információt rögzíteni kell. Szerelem volt első látásra 🙂

Amióta van NAS-om, azóta van saját dokuwikim is.

Mik a legfontosabb tulajdonságai?

  • ahogy a bemutatóban is olvashattad, nem igényel adatbázis szervert a működéséhez, mindent szövegfájlokban tárol
  • egyszerű szintaktikája van, a 90%-át fejből ismerem, a legfontosabbakhoz van gomb a szerkesztőben
  • ACL-ezhető, azaz csoportok/felhasználók szerint lehet különböző jogosultságokat kiosztani
  • három üzemmódban használhatod:
    • nyílt wiki: mindenki olvashatja, írhatja, tölthet fel fájlokat
    • publikus wiki: mindenki olvashatja, de csak regisztrált felhasználók írhatják és tölthetnek fel fájlokat
    • zárt wiki: csak regisztrált felhasználók olvashatják, írhatják és tölthetnek fel fájlokat
  • egy olyan webszerverre lesz szükséged, amelyik beszéli a php-t (pl apache, nginx)
  • aktív közösség van mögötte, évente érkeznek az új kiadások/hibajavítások
  • több, mint 100 sablonnal tudjuk testre szabni a megjelenését
  • több, mint 1200 modullal tudjuk a képességeit bővíteni
  • igény szerint be lehet állítani, hogy sql-ből, vagy ldap-ból authentikálja a felhasználókat, gyárilag ezt is szövegfájlban tartja
  • kezeli a változásokat, össze lehet hasonlítani bármelyik állapotot bármelyikkel, vissza is lehet állítani

Én zárt módban használom, ahol szükség esetén egyedileg tudok 1-1 névteret vagy sima oldalt nyilvánossá tenni.

Hogyan tudjuk telepíteni?

Erre három módszert is fogok mutatni.

1. Az oldscool módszer szerint innen letöltöm a becsomagolt tgz fájlt. Én csak a magyar nyelvet pipálom be, és erősen javasolt az „upgrade plugint” is kiválasztani. Ezt a fájlt másoljuk a webszerverünkre, ott csomagoljuk ki a megfelelő mappába. CentOS/RedHat/Fedora alatt ez lehet a /var/www/html mappa.

Állítsuk be a megfelelő jogosultságokat, ugyanis az apache felhasználónak tudnia kell írnia a megfelelő könyvtárakat/fájlokat:

chown -R apache:apache /var/www/html/dokuwiki/

Kész is az előkészület, a beállításokat, használatot később mutatom meg, ugyanis az már közös lesz mindhárom módszerben. A weboldalt így érem el: http://localhost/dokuwiki/

2. Futtathatjuk konténerben is (pl docker). Ebben az esetben semmit sem kell letöltenünk, hozzunk létre egy mappát a jól megszokott környezetünkben:

mkdir ~/docker/dokuwiki

Hozzuk létre benne a docker-compose.yml fájlt (csak másold ki a teljes szöveget, és add ki egy parancssorban):

cat <<EOF > ~/docker/dokuwiki/docker-compose2.yml
volumes:
  data:

services:
  dokuwiki:
    container_name: dokuwiki
    image: lscr.io/linuxserver/dokuwiki:latest
    environment:
      - PUID=1000
      - PGID=1000
      - TZ=Europe/Budapest
    ports:
      - 8080:80
    volumes:
      - data:/config
EOF

Amennyiben foglalt a 8080-as portod, írd át egy üres portra.

Indítsuk el:

cd ~/docker/dokuwiki
docker-compose up -d

Kész is az előkészület, a beállításokat, használatot később mutatom meg, ugyanis az már közös lesz mindhárom módszerben. A weboldalt így érem el: http://localhost:8080/dokuwiki/

3. Futtathatjuk kubernetesben is. Erről ebben a cikkben írtam. A weboldalt így érem el: http://192.168.56.95:30180/

Jöhet a bemutatása.

Az általad választott módszer szerint töltsd be a dokuwiki weboldalát, ezt kellene neked is látnod:

Most nyílt módban működik, még nincs admin felhasználó, ráadásul angolul beszél. Töltsük be az install.php-t. Én a dockeres módszert választottam, szóval nyissuk meg ezt az oldalt: http://localhost:8080/install.php. A jobb felső sarokban váltsd át a „Choose your language”-t „hu”-ra, és értelemszerűen töltsd ki a mezőket:

Mentés után egy kattintsunk a „Látogasd meg az új DokuWikidet!” linkre. Írjuk be a korábban beállított felhasználónkat, jelszavunkat:

Belépés után az üdvözlő képernyő fogad minket:

A képernyő közepe felé láthatsz egy piros „start” linket, kattints rá:

Az „oldal létrehozása” gombot jobb szélen találod, vidd az egeret ceruza ikon fölé, és kattints rá:

Ha az egeret a gombok fölé húzod, ki fogja írni a funkcióját is (ami amúgy az ikonjából is jól látható). Az összes lehetőséget a zöld színű „formázás” linken nézheted meg (angolul), magyarul itt nézheted meg.

Érdemes minden változást 2-3 szóban összefoglalva leírni a „A változások összefoglalása” mezőbe. Ez megkönnyíti később az életünket. Érdemes minden módosítás után megnyomni az „Előnézet” gombot. Ha végeztünk a szerkesztéssel, mentsük el. Ennyire egyszerű egy oldalt létrehozni. Ha létre szeretnénk hozni egy névteret, és abban egy oldalt, akkor írjuk be a keresőbe (jobb felső sarok), például a „labor:start” szavakat, majd kattintsunk a nagyító ikonra:

Ahogy várható volt, nincs találat, ebben az esetben a piros linkre kattintva a szerkesztő nézetbe fogunk kerülni, majd ha végeztünk a kitöltésével, és elmentettük, létrejön a névtér/aloldalunk.

Ha szeretnéd megnézni, hogy milyen névterek és oldalak vannak a wikiben, kattints a jobb felül található Áttekintő linkre:

Ha a névterek kék linkjeire kattintasz, akkor láthatóvá válik az alatta lévő oldalak neve is:

A névterek start oldala különleges szerepet tölt be, amikor a névtérre kattintunk, automatikusan a start oldalra fog vinni a dokuwiki. Fontos kiemelnem, hogy ez téma függő tulajdonság, nem minden téma támogatja, szerencsére a gyári igen.

Milyen speciális oldalakat ismer még a dokuwiki?

sidebar – oldalsáv

Ezzel lehet egy fix tartalmú oldalsávot létrehozni. Vagy írjátok be a keresőbe, hogy sidebar, vagy töltsétek be az oldalát: http://localhost:8080/doku.php?id=sidebar

Töltsük fel tetszőleges tartalommal, például így:

kiemelt oldalak
  * [[https://www.dokuwiki.org/hu%3Asyntax|syntax magyarul]]
  * [[https://msandor.hu/dokuwiki-bemutato/|dokuwiki bemutató]]

Mentés után meg is fog jelenni bal oldalt (még egy tipp, ha rákattintasz a bal felső dokuwiki logóra, a kezdő oldalon fogod találni magad):

footer – lábléc

Ezzel lehet minden oldal aljára egy fix szöveget elhelyezni. Nyissuk meg a footer oldalt, és írjunk bele valamit:

copyleft 2024 [[admin@msandor.hu|msandor]]

Ez is téma függő, sajnos a gyári téma pont nem mutatja meg 🙁 Később mutatok egy témát, ami megjeleníti.

Térjünk vissza a szerkesztőre, pontosabban a változások követésére

Szerkesszük meg újra mondjuk a kezdő start oldalunkat, tetszőlegesen módosítsátok a tartalmát, mentsétek el, módosítsátok újra, mentsétek el, majd kattintsatok a jobb oldalon látható korábbi változatok-ra (óra ikon):

Mit látunk? Milyen lehetőségeink vannak?

Ebben a példában 4 sorban látszanak a módosítások, időben csökkenő, azaz fent van a legfrissebb módosítás, alul a létrehozása. A módosítás dátumával kezdődik -> szemüveg -> oldal neve (start) -> a módosítás rövid leírása -> zárójelben a felhasználó IP címe -> zölddel kiemelve a változás mérete byteban (+: nőtt, –: csökkent).

Ha valamelyik szemüvegre kattintunk, akkor azt a bizonyos változatot láthatjuk. Lehetőségünk van bármelyikre visszaállni.

Ha a bal szélső négyzetekből kettőt kiválasztunk, akkor össze tudjuk őket hasonlítani a „Különbségek az aktuális változathoz képest” gombra kattintással:

Ezen a felületen is van lehetőségünk bármelyik változatot bármelyikkel összehasonlítani.

Térjünk rá a dokuwiki adminisztrációjára

Az oldal tetején kattintsunk az Admin linkre:

Elég beszédesek a lehetőségeink, kezdjük a Beállítóközponttal:

Ez csak egy részlet, nagyon sok lehetőségünk van, csak azokat fogom megemlíteni, amiket én is használok:

  • Alapértelmezetten minden névtér látszik a DokuWiki áttekintő (index) oldalán. Ezen opció bekapcsolása után azok nem jelennek meg, melyekhez a felhasználónak nincs olvasás joga. De ezzel eltakarhatunk egyébként elérhető al-névtereket is, így bizonyos ACL beállításoknál használhatatlan indexet eredményez ez a beállítás: ezt bekapcsolom
  • Bizonyos DokuWiki tevékenységek (action) tiltása: a regisztráció engedését zárt wiki esetén jobb tiltani, legfeljebb még a saját felhasználó törlését szoktam tiltani
  • JPG tömörítés minősége (0-100): én erre 85%-ot szoktam beállítani
  • Oldalváltozás-listára feliratkozás engedélyezése: ezt bekapcsolom
  • Az automatikusan küldött levelekben használt e-mail cím: ezt érdemes létező címre beállítani
  • Szép URL-ek használata: én a „Dokuwiki saját módszerével” lehetőséget szoktam használni
  • A DokuWiki megpróbál hosztneveket keresni a távoli IP-címekhez. Amennyiben lassú, vagy nem működő DNS-szervered van vagy csak nem szeretnéd ezt a funkciót, tiltsd le ezt az opciót!: ezt kikapcsolom

Végül a lap alján a mentés gombbal elmentjük. Újra válasszuk ki az admin menüt, majd menjünk a bővítménykezelő menüre:

Azt javaslom, hogy az általunk nem használt bővítményeket, sablonokat tiltsuk le, én pl. ezeket szoktam:

  • authpdo plugin
  • Popularity Feedback Plugin
  • Revert Manager
  • styling plugin

Ezen az oldalon van lehetőségünk frissíteni a bővítményeket, sablonokat.

A „keresés és telepítés” fülön lehet új bővítményeket, sablonokat telepíteni:

A letöltős módszernél mondtam, hogy érdemes bepipálni az upgrade plugint, a konténeres változatnál (ilyen a kubernetes alatt futó is) kézzel kell feltelepítenünk.

Én a gyári helyett másik sablont használok, telepítsétek fel a dokubook template-t:

A téma telepítése után még ki is kell választani az admin/beállítóközpont oldalon a Sablon menüpontnál:

A lap alján mentsük el, majd a bal felső sarokban látható dokuwiki logóra kattintva visszakerülünk a nyitó lapra, máris megváltozott a kinézet, látható lett a footer is:

Ez a téma nem támogatja az oldalsávot (sidebar), de itt nincs is rá szükség, mert eleve mutat minden névteret és oldalt.

A dokuwiki frissítése

A demonstráció kedvéért letöltöttem egy régi változatot, amikor megjelenik a dokuwiki frissítése (10-12 havonta), akkor az oldal tetején meg fog jelenni a tájékoztatás:

Fontos, ezt csak az adminisztrátor csoport tagjai látják, a sima felhasználók nem!

A frissítéshez menjünk az admin menü wiki-frissítő menüpontjára:

A bővítmény automatikusan frissíti a wikit a legújabb elérhető DokuWiki-verzióra. A folytatás előtt olvassuk el a Changelog-ot (változások naplóját), ellenőrizendő, hogy a frissítés előtt vagy után szükséges-e bármilyen további lépés.

Az automatikus frissítéshez a PHP-folyamatnak írási jogosultságra van szüksége a DokuWiki-fájlokhoz. A bővítmény ellenőrzi a szükséges fájljogosultságokat a frissítési folyamat megkezdése előtt.

A bővítmény nem frissíti a már telepített bővítményeket vagy sablonokat.

Javasoljuk, hogy a frissítés előtt készítsünk biztonsági másolatot.

Nyomjuk meg a Folytatás gombot. Kiírja a jelenleg használt verziót, és az elérhető legfrissebb verziót. Nyomjuk meg a Folytatás gombot. Letölti a telepítőt. Nyomjuk meg a Folytatás gombot. Kicsomagolja a telepítőt. Nyomjuk meg a Folytatás gombot. Ha ezt látjátok: „Minden fájl írható. A frissítés készen áll a telepítésre.„, akkor nyomjuk meg a Folytatás gombot. Ha hibákat láttok, javítsátok ki őket. A konténeres dokuwiki így nem frissíthető, ott a docker image-t kell frissíteni. „Frissítés kész. Élvezzük az új DokuWiki-t!” El is tűnt a lap tetejéről a figyelmeztetés.

Felhasználók kezelése

Menjünk az admin menü felhasználók kezelése menüre, és hozzunk létre egy új felhasználót:

Nagyon egyszerű, csak meg kell adni a kért adatokat. Igény esetén tömegesen is létre lehet hozni felhasználókat, a mikéntje le van írva a felhasználók kezelése oldal alján.

Fontos információ: a dokuwiki levélküldésre a php-mail függvényt használja, ami a hagyományos telepítés esetén a localhoston futó smtp szerverhez fog csatlakozni, a konténeres verzióban viszont nincs smtp szerver! Ilyenkor telepítsük fel az smtp plugint (persze be is kell állítani).

A felhasználó ilyen levelet fog kapni:

Jogosultságok kezelése (ACL)

Csináljunk egy bemutatót, állítsuk be, hogy az imént létrehozott elek nevű felhasználó ne lássa a korábban létrehozott labor nevű névteret (és minden benne lévő oldalt).

Menjünk az admin menü Hozzáférési lista (ACL) kezelő menüjére, kattintsunk a labor linkre (be fog sárgulni), a csoportnál válasszuk ki az usert, válasszuk ki a semmi-t, majd mentsük el:

Ha kilépünk, és belépünk elekkel, akkor nem fogjuk látni a labor névteret:

Akkor sem fogja látni, ha valaki megsúgja neki a labor linkjét:

További hasznos bővítmények

Végszó

Nincs más hátra, mint használni a dokuwikinket, csak fel kell tölteni sok-sok hasznos tartalommal 🙂