Návod na upgrade webu KIV na OpenCms verze 7.5

Postup upgrade systémem "přenos do čistého OpenCms" je následující:

1. Nainstalovat čité OpenCms 7.5.2
2. Zkopírovat konfigurační soubory pro autentizaci protokolem Kerberos a nastavit Tomcat tak, aby tyto soubory uměl najít.
3. Zkopírovat jar soubor kerberos-authentication.jar s třídami potřebnými pro autentizaci Kerberem a opatchovat soubor opencms.jar.
4. Zabezpečit workspace - viz návod od p. Pavuka (otestovat na OpenCms 7.5.0)
5. Stáhnout knihovny potřebné pro běh KIVáckého rozšíření OpenCms
6. Nastavit soubory redsys-servlet.xml a jdbc.properties
7. Nainstalovat dump databáze s KIVáckými daty
8. Nainstalovat KIV moduly
9. Import obsahu ze staré verze OpenCms - při této činnosti je potřeba dávat pozor na umístění, ze kterého je starý obsah do OpenCms importován.
10. Oprava resp vytvoření konfigurace multisite
11. Ověření oproti původnímu stavu

Pokud by se dělalo "side-by-side" se stávajícím webem, pak je potřeba ještě poté překlopit konfiguraci apache httpd a proxy.

Na celou akci je třeba počítat aspoň 4h čistého času (když se něco vysype, je z toho klidně celý dlouhý den).

A. Instalace systému

1. Nainstalovat čité OpenCms 7.5.0

V tomto kroku se provede standardní instalace OpenCms. Je zde potřeba dát pozor na to, že v jedné instanci Tomcatu nemohou běžet dvě aplikace se stejným jménem. To je omezující faktor, pokud bude provozováno více verzí OpenCms současně. Vhodným řešením tohoto problému je přejmenovat soubor opencms.jar na opencms750.jar a tento soubor poté nasadit na Tomcata. Tím se umožní provozování dvou verzí OpenCms současně. Jediný rozdíl je v tom, že nová verze poběží na url ../opencms750/...

Zastavte Tomcat

2. Konfigurační soubory pro protokol Kerberos

Soubory z svn adresáře opencms-libs/krb/

• KerbNastaveni?.conf
• krb5.conf

zkopírovat do adresáře conf na rootu Tomcatu (adresář CATALINA_HOME, jsou tam třeba server.xml a další). Cesta k těmto souborům musí být přidána do proměnné CATALINA_OPTS:

• -Djava.security.auth.login.config=CESTA_K_SOUBORU_KerbNastaveni.conf
• -Djava.security.krb5.conf=CESTA_K_SOUBORU_krb5.conf

Na platformě windows se pro server Tomcat toto provede přidáním následujících řádků do souboru catalina.bat, pro platformu Linux se jedná o soubor catalina.sh, na cestě CATALINA_HOME\bin. Tyto řádky umístit do souboru catalina.sh (catalina.bat???) za část, kde se načtou standardní proměnné Javy.

• Pro Windows
  • set JAVA_OPTS=%JAVA_OPTS% -Djava.security.auth.login.config=%CATALINA_HOME%\Kerberos_Configuration\KerbNastaveni.conf
  • set JAVA_OPTS=%JAVA_OPTS% -Djava.security.krb5.conf=%CATALINA_HOME%\Kerberos_Configuration\krb5.conf
• Pro Linux(Ubuntu)
  • JAVA_OPTS="$JAVA_OPTS -Djava.security.auth.login.config=$CATALINA_HOME/conf/KerbNastaveni?.conf"
  • JAVA_OPTS="$JAVA_OPTS -Djava.security.krb5.conf=$CATALINA_HOME/conf/Kerberos/krb5.conf"

Pokud máte na jednom počítači nainstalováno více instancí Tomcatu a pro jejich start používáte volitelnou proměnnou , změntě na .

3. Zkopírování opatchovaného opencms.jar

Do <opencmsroot>/WEB-INF/lib adresáře se nakopíruje soubor kerberos-authentication.jar z svn. Není třeba, příslušné třídy jsou integrovány do opatchovaného opencms.jar souboru.

Soubor WEB-INF/lib/opencms.jar zazálohujte (například pod jménem opencms.jar.dist) a do adresáře nakopírujte opencms-7.5.2-patched.jar z svn.

Spusťte Tomcat

Nyní byste se měli být schopni se přihlásit pomocí Vašeho Orion uživatelského jména a hesla. Předpoklad pro to je, že v OpenCms existuje uživatel s uživatelským jménem shodným jako je Váš Orion login.

4. Zabezpečit workspace

Viz návod od p. Pavuka ZabezpecenePrihlaseni, v kostce: v httpd proxy modulu nastavit aby všechna URL začínající /system/ a /site/login/ byla vždy přesměrována na HTTPS.

B. Konfigurace pro moduly KIV

5. Nainstalovat knihovny a konfigurace potřebné pro běh KIVáckých modulů

Z svn adresáře opencms-libs/lib/ zkopírovat všechny .jar soubory do WEB-INF/lib. Neměly by vzniknout duplicity, je ale třeba zkontrolovat - pokud by se vedle sebe vyskytly např. mail.jar a mail-1.3.jar pak není jisté, který bude načten a použit tomcatem; nevhodné .jary tedy buď smazat nebo přejmenovat (např. přípona .x) aby je tomcat nenačetl.

6. Nainstalovat KIV moduly

Pomocí administačního rozhranní Administration - Module Management - Import Module with HTTP naimportujte modul Common v aktuální verzi (2.0.1.x).

Zastavit Tomcat

Zazálohujte soubor WEB-INF/web.xml a místo něj zkopírujte verzi z svn adresáře opencms-libs/. Dále pod WEB-INF zkopírujte soubory redsys-servlet.xml a webkiv.properties.

V souboru webkiv.properties nastavte správně název databáze pro data KIV, login+heslo pro přístup, a emailové konto které bude použito pro odesílání zpráv z modulů.

Spustit tomcat

Nainstalovat další moduly, v tomto pořadí:

1. login
2. aktuality
3. template
4. publikace
5. predmety
6. produkty
7. osoby

Pro potřeby stránky informatika.zcu.cz jsou potřeba ještě následující moduly:

Restartujte Tomcat

C. Import obsahu

7. Vytvoření konfigurace multisite

Přihlašte se k OpenCms jako administrátor, v poli Site zvolte / a v levém panelu otevřte adresář sites. V tomto umístění založte a publikujte dva adresáře: informatika.zcu.cz a www.kiv.zcu.cz. Tím jsme připravili OpenCms pro konfiguraci Multisite.

Nyní doplníme konfiguraci pro multisite. Nejdříve je potřeba přidat informace o těchto stránkách do souboru opencms-system.xml na cestě <opencmsroot>/WEB-INF/config/. V tomto souboru najděte sekci, která vypadá následujícím způsobem:

<sites>
    <workplace-server>http://www.mysite.com:8080</workplace-server>
    <default-uri>/sites/default/</default-uri>
    <site server="www.mysite.com" uri="/sites/default/"/>
</sites>

Do elementu <sites> přidejte následující text:

<site server="jmeno-serveru-a-port-pro-informatika" uri="/sites/informatika.zcu.cz/"/>
<site server="jmeno-serveru-a-port-pro-www.kiv" uri="/sites/www.kiv.zcu.cz/"/>

Jména serverů a portů musí být taková, aby každá site běžela na jiném portu v rámci serveru, na kterém běží daná instalace opencms. (Viz též svn opencms-libs/configs/opencms-system.xml a informace od systémového admina, které jsou to servery a porty.)

Jako další musí být v produkčním prostředí nastaven Tomcat a Apache, tak aby tyto sites poskytovaly bez opencms/opencms/ prefixu. Podrobnější popis viz http://opencms-wiki.org/MultiSite_configuration_instructions .

Pro samotný vývoj by výše uvedený popis měl stačit.

Restartujte Tomcata

8. Import obsahu ze staré verze OpenCms.

Protože import starého obsahu do OpenCms je poměrně pro Tomcat náročná operace, zkontrolujte, zda má nastaven dostatek paměti - zda je v souboru catalina.bat respektive catalina.sh (viz bod 5) nastavena JVM proměnná -Xmx a pokod ne, tak do tohoto souboru přidejte následující řádku:

• set JAVA_OPTS=%%JAVA_OPTS%% -Xmx512M , resp.
• export CATALINA_OPTS="$CATALINA_OPTS -Xmx512m"

Dále je potřeba zkontrolovat/nastavit, že MySQL má dost velký packet buffer: v my.ini nastavit

• max_allowed_packet = 64M (menší hodnoty nestačí při importu velkých souborů)

Vlastní import předpokládá, že jsou k dispozici jeden nebo více .zip archivů s obsahem webu. Ty musí vznikout exportem z (produkčního) OpenCms tak, že admin je v Site: www.kiv.zcu.cz kořenovém adresáři, přepne do Administration, udělá Administration - Database Management - Export Database a vybere v Resources to export kořenový adresář. Je potřeba mít krom resources vyexportované také uživatele. (Přemek: Já jsem si udělal dva exporty - v jednom je jen /robots.txt soubor a všichni uživatelé, v druhém jsou všechny soubory a nejsou uživatelská data; to mi pomáhá když chci dělat pokusy s právy a nechci přitom mít pakárnu s čekáním na dlouhý import celého webu.)

Přihlašte se do OpenCms a otevřte nebo se přepněte do okna Explorer. Přepněte se do Site: www.kiv.zcu.cz tak, abyste v poli Location viděli: /. Toto je důležité z toho důvodu, že při importu obsahu (dtabáze) do OpenCms je ta naimportována tam, kde v okně Explorer právě jste.

Zkopírujte archivy s daty do adresáře WEB-INF/packages/ v instalaci OpenCms. Otevřte administrační rozhraní: Administration - Database Management - Import File from Server a vyberte soubor s daty. Tento postup opakujte pro stránky informatika.zcu.cz a kiv.zcu.cz.

OpenCms by mělo naimportovat data uložená v těchto souborech. Při importu se může stát, že do okna budou vypsány i nějaké chybové hlášky - hlavně při importu uživatelů. Tato chyba zřejmě souvisí s importem uživatelů, kteří mají práva ROOT. Tito uživatelé jsou však v pořádku naimportováni.

• Vzhledem ke změnám v Account Managementu mezi verzemi 6 a 7 je dobré zkontrolovat a případně opravit nastavení skupin a rolí uživatelů. Zejména by všichni z KIV Staff měli mít roli Workplace user aby se vůbec mohli přihlásit.

Import archivu www.kiv.zcu.cz může trvat delší dobu kvůli velkým souborům (data "produktů" autorizovaného software). Po naimportování stránek proveďte: Publish Projekt. OpenCms nyní publikuje všechen naimportovaný obsah. Tato operace může trvat poměrně dlouhou dobu. Občas se kvůli velkým datům může stát, že import a/nebo publish zkrachuje. Je proto vhodné:

• před importem udělat zálohu databáze OpenCms, aby bylo možno ji případně obnovit kdyby se importem rozbil VFS
• koukat se do logu OpenCms, co to dělá (tail -f WEB-INF/logs/opencms.log)
• před "Publish" zapnout Preferences > Show publish notification popup a po spuštění publikování počkat, až se objeví okénko, že bylo publikování skončeno

(Po importu archivy z adresáře packages smažte, aby zbytečně nezabíraly místo.)

11. Ověření oproti původnímu stavu