ICO wiki - User contributions [en]

Dot muzei

2015-03-06T18:10:34Z

Kveskima: /* XML andmefail */

=Raggakana=

==Liikmed==
#Aap Kaur Suvi
#Indrek Jõgi
#Kristjan Veskimäe
#Sandra Niinepuu - projektijuht

==XML andmefail==

XML fail on ''Eksponaadid.xml'', skeemifail on ''Eksponaadid.xsd'' ja transformatsioonifail on ''Eksponaadid.xslt''. XML faili valideerimiseks skeemifailiga peavad mõlemad failid asuma ühes ja samas kataloogis (kuna skeemifaili asukohaks on XML faili päises määratud Eksponaadid.xsd).

===XML fail===
<pre>
<?xml version="1.0" encoding="utf-8" ?>
<muuseumid xmlns="http://example.com/schemas/muuseumid/v1"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://example.com/schemas/muuseumid/v1
Eksponaadid.xsd">


<muuseum nimi="Eesti Sõjamuuseum" id="1">
<muuseumikogu tyyp="Esemekogu">
<eksponaat originaal="true" id="1">
<nimetus olemus="kinnas"><![CDATA["Labakinnas. M. Laidoneri (ema) kootud"]]></nimetus>
<number><![CDATA["KLM ET 22 A 22"]]></number>
<seisund>Hea</seisund>
</eksponaat>
<eksponaat originaal="true" id="2">
<nimetus olemus="tääk"><![CDATA["Mälestusese, miniatuurne tääk, USA Air Cavalry Divisioni sümboolikaga."]]></nimetus>
<number><![CDATA["KLM ET 365 A"]]></number>
<seisund>Hea</seisund>
</eksponaat>
</muuseumikogu>
<muuseumikogu tyyp="Tulirelvad">
<eksponaat originaal="false" id="1">
<nimetus olemus="tulirelv"><![CDATA["Otepää püss, koopia"]]></nimetus>
<number><![CDATA["KLM ET 1421 R1 457"]]></number>
<seisund>Hea</seisund>
</eksponaat>
<eksponaat originaal="true" id="2">
<nimetus olemus="tulirelv"><![CDATA["Tank 34-85"]]></nimetus>
<number><![CDATA["KLM ET 1603 R1 553"]]></number>
<seisund>Rahuldav</seisund>
</eksponaat>
</muuseumikogu>
</muuseum>

<muuseum nimi="Eesti Ajaloomuuseum" id="2">
<muuseumikogu tyyp="Fotod">
<eksponaat originaal="true" id="1">
<nimetus olemus="album"><![CDATA["Fotoalbum: Vene tsaariarmee - 141. Možaiski polk, polkovnik Aganjev, grupipildid, portreed, olustik, kohavaated, ettevalmistused lahinguteks, arstiabi, matused."]]></nimetus>
<number><![CDATA["AM _ 59 F 5501/1-305"]]></number>
<seisund>Hea</seisund>
</eksponaat>
<eksponaat originaal="true" id="2">
<nimetus olemus="album"><![CDATA["Fotoalbum: "Kaks aastat Punaarmee Eesti korpust 1942-1944." Illustreeritud, venekeelsed pildiallkirjad."]]></nimetus>
<number><![CDATA["AM _ 42 F 4100/1-270"]]></number>
<seisund>Hea</seisund>
</eksponaat>
</muuseumikogu>
<muuseumikogu tyyp="Mööblikollektsioon">
<eksponaat originaal="true" id="1">
<nimetus olemus="mööbel"><![CDATA["Laste söögitool, XIX saj. lõpp"]]></nimetus>
<number><![CDATA["AM _ 35566:1 Mb 1"]]></number>
<seisund>Hea</seisund>
</eksponaat>
</muuseumikogu>
</muuseum>

</muuseumid>
</pre>

===XML skeemifail===
<pre>
<?xml version="1.0" encoding="utf-8"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"
targetNamespace="http://example.com/schemas/muuseumid/v1"
xmlns="http://example.com/schemas/muuseumid/v1"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
attributeFormDefault="unqualified"
elementFormDefault="qualified">
<xs:element name="muuseumid">
<xs:complexType>
<xs:sequence>
<xs:element maxOccurs="unbounded" name="muuseum">
<xs:complexType>
<xs:sequence>
<xs:element maxOccurs="unbounded" name="muuseumikogu">
<xs:complexType>
<xs:sequence>
<xs:element maxOccurs="unbounded" name="eksponaat">
<xs:complexType>
<xs:sequence>
<xs:element name="nimetus">
<xs:complexType>
<xs:simpleContent>
<xs:extension base="xs:string">
<xs:attribute name="olemus" type="xs:string" use="required" />
</xs:extension>
</xs:simpleContent>
</xs:complexType>
</xs:element>
<xs:element name="number" type="xs:string" />
<xs:element name="seisund">
<xs:simpleType>
<xs:restriction base="xs:string">
<xs:enumeration value="Hea"></xs:enumeration>
<xs:enumeration value="Rahuldav"></xs:enumeration>
<xs:enumeration value="Halb"></xs:enumeration>
</xs:restriction>
</xs:simpleType>
</xs:element>
</xs:sequence>
<xs:attribute name="originaal" type="xs:boolean" use="required" />
<xs:attribute name="id" type="xs:integer" use="required" />
</xs:complexType>
</xs:element>
</xs:sequence>
<xs:attribute name="tyyp" type="xs:string" use="required" />
</xs:complexType>
</xs:element>
</xs:sequence>
<xs:attribute name="nimi" type="xs:string" use="required" />
<xs:attribute name="id" type="xs:integer" use="required" />
</xs:complexType>
</xs:element>
</xs:sequence>
</xs:complexType>
</xs:element>
</xs:schema>
</pre>

===XSLT failid===
<pre>
<?xml version="1.0" encoding="utf-8"?>
<xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
xmlns:msxsl="urn:schemas-microsoft-com:xslt" exclude-result-prefixes="msxsl"
>
<xsl:output method="html" indent="yes"/>

<xsl:template match="/">
<html>
<body>
<xsl:for-each select="muuseumid/muuseum">
<h1>
<xsl:variable name="nimi" select="@nimi"></xsl:variable>
<xsl:value-of select="@nimi"/>
</h1>
<xsl:for-each select="muuseumikogu">
<xsl:variable name="originaal" select="@originaal"></xsl:variable>
<xsl:variable name="tyyp" select="@tyyp"></xsl:variable>
<h2>
<xsl:value-of select="@tyyp"/>
</h2>
<xsl:for-each select="eksponaat">
Nimetus:
<xsl:value-of select="nimetus"/>


Number:
<xsl:value-of select="number"/>


Seisukord:
<xsl:value-of select="seisund"/>

------------
</xsl:for-each>

</xsl:for-each>
</xsl:for-each>
</body>
</html>
</xsl:template>
</xsl:stylesheet>
</pre>

==Veebiteenuse analüüs==

==Veebiteenus==

==Klientrakendus==

Dot muzei

2015-03-06T18:02:45Z

Kveskima: /* XML andmefail */

=Raggakana=

==Liikmed==
#Aap Kaur Suvi
#Indrek Jõgi
#Kristjan Veskimäe
#Sandra Niinepuu - projektijuht

==XML andmefail==

XML fail on [[Eksponaadid.xml]], skeemifail on [[Eksponaadid.xsd]] ja transformatsioonifail on [[Eksponaadid.xslt]]

===XML fail===
<pre>
<?xml version="1.0" encoding="utf-8" ?>
<muuseumid xmlns="http://example.com/schemas/muuseumid/v1"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://example.com/schemas/muuseumid/v1
Eksponaadid.xsd">


<muuseum nimi="Eesti Sõjamuuseum" id="1">
<muuseumikogu tyyp="Esemekogu">
<eksponaat originaal="true" id="1">
<nimetus olemus="kinnas"><![CDATA["Labakinnas. M. Laidoneri (ema) kootud"]]></nimetus>
<number><![CDATA["KLM ET 22 A 22"]]></number>
<seisund>Hea</seisund>
</eksponaat>
<eksponaat originaal="true" id="2">
<nimetus olemus="tääk"><![CDATA["Mälestusese, miniatuurne tääk, USA Air Cavalry Divisioni sümboolikaga."]]></nimetus>
<number><![CDATA["KLM ET 365 A"]]></number>
<seisund>Hea</seisund>
</eksponaat>
</muuseumikogu>
<muuseumikogu tyyp="Tulirelvad">
<eksponaat originaal="false" id="1">
<nimetus olemus="tulirelv"><![CDATA["Otepää püss, koopia"]]></nimetus>
<number><![CDATA["KLM ET 1421 R1 457"]]></number>
<seisund>Hea</seisund>
</eksponaat>
<eksponaat originaal="true" id="2">
<nimetus olemus="tulirelv"><![CDATA["Tank 34-85"]]></nimetus>
<number><![CDATA["KLM ET 1603 R1 553"]]></number>
<seisund>Rahuldav</seisund>
</eksponaat>
</muuseumikogu>
</muuseum>

<muuseum nimi="Eesti Ajaloomuuseum" id="2">
<muuseumikogu tyyp="Fotod">
<eksponaat originaal="true" id="1">
<nimetus olemus="album"><![CDATA["Fotoalbum: Vene tsaariarmee - 141. Možaiski polk, polkovnik Aganjev, grupipildid, portreed, olustik, kohavaated, ettevalmistused lahinguteks, arstiabi, matused."]]></nimetus>
<number><![CDATA["AM _ 59 F 5501/1-305"]]></number>
<seisund>Hea</seisund>
</eksponaat>
<eksponaat originaal="true" id="2">
<nimetus olemus="album"><![CDATA["Fotoalbum: "Kaks aastat Punaarmee Eesti korpust 1942-1944." Illustreeritud, venekeelsed pildiallkirjad."]]></nimetus>
<number><![CDATA["AM _ 42 F 4100/1-270"]]></number>
<seisund>Hea</seisund>
</eksponaat>
</muuseumikogu>
<muuseumikogu tyyp="Mööblikollektsioon">
<eksponaat originaal="true" id="1">
<nimetus olemus="mööbel"><![CDATA["Laste söögitool, XIX saj. lõpp"]]></nimetus>
<number><![CDATA["AM _ 35566:1 Mb 1"]]></number>
<seisund>Hea</seisund>
</eksponaat>
</muuseumikogu>
</muuseum>

</muuseumid>
</pre>

===XML skeemifail===
<pre>
<?xml version="1.0" encoding="utf-8"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"
targetNamespace="http://example.com/schemas/muuseumid/v1"
xmlns="http://example.com/schemas/muuseumid/v1"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
attributeFormDefault="unqualified"
elementFormDefault="qualified">
<xs:element name="muuseumid">
<xs:complexType>
<xs:sequence>
<xs:element maxOccurs="unbounded" name="muuseum">
<xs:complexType>
<xs:sequence>
<xs:element maxOccurs="unbounded" name="muuseumikogu">
<xs:complexType>
<xs:sequence>
<xs:element maxOccurs="unbounded" name="eksponaat">
<xs:complexType>
<xs:sequence>
<xs:element name="nimetus">
<xs:complexType>
<xs:simpleContent>
<xs:extension base="xs:string">
<xs:attribute name="olemus" type="xs:string" use="required" />
</xs:extension>
</xs:simpleContent>
</xs:complexType>
</xs:element>
<xs:element name="number" type="xs:string" />
<xs:element name="seisund">
<xs:simpleType>
<xs:restriction base="xs:string">
<xs:enumeration value="Hea"></xs:enumeration>
<xs:enumeration value="Rahuldav"></xs:enumeration>
<xs:enumeration value="Halb"></xs:enumeration>
</xs:restriction>
</xs:simpleType>
</xs:element>
</xs:sequence>
<xs:attribute name="originaal" type="xs:boolean" use="required" />
<xs:attribute name="id" type="xs:integer" use="required" />
</xs:complexType>
</xs:element>
</xs:sequence>
<xs:attribute name="tyyp" type="xs:string" use="required" />
</xs:complexType>
</xs:element>
</xs:sequence>
<xs:attribute name="nimi" type="xs:string" use="required" />
<xs:attribute name="id" type="xs:integer" use="required" />
</xs:complexType>
</xs:element>
</xs:sequence>
</xs:complexType>
</xs:element>
</xs:schema>
</pre>

===XSLT failid===
<pre>
<?xml version="1.0" encoding="utf-8"?>
<xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
xmlns:msxsl="urn:schemas-microsoft-com:xslt" exclude-result-prefixes="msxsl"
>
<xsl:output method="html" indent="yes"/>

<xsl:template match="/">
<html>
<body>
<xsl:for-each select="muuseumid/muuseum">
<h1>
<xsl:variable name="nimi" select="@nimi"></xsl:variable>
<xsl:value-of select="@nimi"/>
</h1>
<xsl:for-each select="muuseumikogu">
<xsl:variable name="originaal" select="@originaal"></xsl:variable>
<xsl:variable name="tyyp" select="@tyyp"></xsl:variable>
<h2>
<xsl:value-of select="@tyyp"/>
</h2>
<xsl:for-each select="eksponaat">
Nimetus:
<xsl:value-of select="nimetus"/>


Number:
<xsl:value-of select="number"/>


Seisukord:
<xsl:value-of select="seisund"/>

------------
</xsl:for-each>

</xsl:for-each>
</xsl:for-each>
</body>
</html>
</xsl:template>
</xsl:stylesheet>
</pre>

==Veebiteenuse analüüs==

==Veebiteenus==

==Klientrakendus==

Dot muzei

2015-03-06T17:23:57Z

Kveskima: /* XSLT failid */

=Raggakana=

==Liikmed==
#Aap Kaur Suvi
#Indrek Jõgi
#Kristjan Veskimäe
#Sandra Niinepuu - projektijuht

==XML andmefail==

===XML fail===
<pre>
<?xml version="1.0" encoding="utf-8" ?>
<muuseumid xmlns="http://example.com/schemas/muuseumid/v1"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://example.com/schemas/muuseumid/v1
Eksponaadid.xsd">


<muuseum nimi="Eesti Sõjamuuseum" id="1">
<muuseumikogu tyyp="Esemekogu">
<eksponaat originaal="true" id="1">
<nimetus olemus="kinnas"><![CDATA["Labakinnas. M. Laidoneri (ema) kootud"]]></nimetus>
<number><![CDATA["KLM ET 22 A 22"]]></number>
<seisund>Hea</seisund>
</eksponaat>
<eksponaat originaal="true" id="2">
<nimetus olemus="tääk"><![CDATA["Mälestusese, miniatuurne tääk, USA Air Cavalry Divisioni sümboolikaga."]]></nimetus>
<number><![CDATA["KLM ET 365 A"]]></number>
<seisund>Hea</seisund>
</eksponaat>
</muuseumikogu>
<muuseumikogu tyyp="Tulirelvad">
<eksponaat originaal="false" id="1">
<nimetus olemus="tulirelv"><![CDATA["Otepää püss, koopia"]]></nimetus>
<number><![CDATA["KLM ET 1421 R1 457"]]></number>
<seisund>Hea</seisund>
</eksponaat>
<eksponaat originaal="true" id="2">
<nimetus olemus="tulirelv"><![CDATA["Tank 34-85"]]></nimetus>
<number><![CDATA["KLM ET 1603 R1 553"]]></number>
<seisund>Rahuldav</seisund>
</eksponaat>
</muuseumikogu>
</muuseum>

<muuseum nimi="Eesti Ajaloomuuseum" id="2">
<muuseumikogu tyyp="Fotod">
<eksponaat originaal="true" id="1">
<nimetus olemus="album"><![CDATA["Fotoalbum: Vene tsaariarmee - 141. Možaiski polk, polkovnik Aganjev, grupipildid, portreed, olustik, kohavaated, ettevalmistused lahinguteks, arstiabi, matused."]]></nimetus>
<number><![CDATA["AM _ 59 F 5501/1-305"]]></number>
<seisund>Hea</seisund>
</eksponaat>
<eksponaat originaal="true" id="2">
<nimetus olemus="album"><![CDATA["Fotoalbum: "Kaks aastat Punaarmee Eesti korpust 1942-1944." Illustreeritud, venekeelsed pildiallkirjad."]]></nimetus>
<number><![CDATA["AM _ 42 F 4100/1-270"]]></number>
<seisund>Hea</seisund>
</eksponaat>
</muuseumikogu>
<muuseumikogu tyyp="Mööblikollektsioon">
<eksponaat originaal="true" id="1">
<nimetus olemus="mööbel"><![CDATA["Laste söögitool, XIX saj. lõpp"]]></nimetus>
<number><![CDATA["AM _ 35566:1 Mb 1"]]></number>
<seisund>Hea</seisund>
</eksponaat>
</muuseumikogu>
</muuseum>

</muuseumid>
</pre>

===XML skeemifail===
<pre>
<?xml version="1.0" encoding="utf-8"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"
targetNamespace="http://example.com/schemas/muuseumid/v1"
xmlns="http://example.com/schemas/muuseumid/v1"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
attributeFormDefault="unqualified"
elementFormDefault="qualified">
<xs:element name="muuseumid">
<xs:complexType>
<xs:sequence>
<xs:element maxOccurs="unbounded" name="muuseum">
<xs:complexType>
<xs:sequence>
<xs:element maxOccurs="unbounded" name="muuseumikogu">
<xs:complexType>
<xs:sequence>
<xs:element maxOccurs="unbounded" name="eksponaat">
<xs:complexType>
<xs:sequence>
<xs:element name="nimetus">
<xs:complexType>
<xs:simpleContent>
<xs:extension base="xs:string">
<xs:attribute name="olemus" type="xs:string" use="required" />
</xs:extension>
</xs:simpleContent>
</xs:complexType>
</xs:element>
<xs:element name="number" type="xs:string" />
<xs:element name="seisund">
<xs:simpleType>
<xs:restriction base="xs:string">
<xs:enumeration value="Hea"></xs:enumeration>
<xs:enumeration value="Rahuldav"></xs:enumeration>
<xs:enumeration value="Halb"></xs:enumeration>
</xs:restriction>
</xs:simpleType>
</xs:element>
</xs:sequence>
<xs:attribute name="originaal" type="xs:boolean" use="required" />
<xs:attribute name="id" type="xs:integer" use="required" />
</xs:complexType>
</xs:element>
</xs:sequence>
<xs:attribute name="tyyp" type="xs:string" use="required" />
</xs:complexType>
</xs:element>
</xs:sequence>
<xs:attribute name="nimi" type="xs:string" use="required" />
<xs:attribute name="id" type="xs:integer" use="required" />
</xs:complexType>
</xs:element>
</xs:sequence>
</xs:complexType>
</xs:element>
</xs:schema>
</pre>

===XSLT failid===
<pre>
<?xml version="1.0" encoding="utf-8"?>
<xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
xmlns:msxsl="urn:schemas-microsoft-com:xslt" exclude-result-prefixes="msxsl"
>
<xsl:output method="html" indent="yes"/>

<xsl:template match="/">
<html>
<body>
<xsl:for-each select="muuseumid/muuseum">
<h1>
<xsl:variable name="nimi" select="@nimi"></xsl:variable>
<xsl:value-of select="@nimi"/>
</h1>
<xsl:for-each select="muuseumikogu">
<xsl:variable name="originaal" select="@originaal"></xsl:variable>
<xsl:variable name="tyyp" select="@tyyp"></xsl:variable>
<h2>
<xsl:value-of select="@tyyp"/>
</h2>
<xsl:for-each select="eksponaat">
Nimetus:
<xsl:value-of select="nimetus"/>


Number:
<xsl:value-of select="number"/>


Seisukord:
<xsl:value-of select="seisund"/>

------------
</xsl:for-each>

</xsl:for-each>
</xsl:for-each>
</body>
</html>
</xsl:template>
</xsl:stylesheet>
</pre>

==Veebiteenuse analüüs==

==Veebiteenus==

==Klientrakendus==

Dot muzei

2015-03-06T17:23:03Z

Kveskima: /* XML skeemifail */

=Raggakana=

==Liikmed==
#Aap Kaur Suvi
#Indrek Jõgi
#Kristjan Veskimäe
#Sandra Niinepuu - projektijuht

==XML andmefail==

===XML fail===
<pre>
<?xml version="1.0" encoding="utf-8" ?>
<muuseumid xmlns="http://example.com/schemas/muuseumid/v1"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://example.com/schemas/muuseumid/v1
Eksponaadid.xsd">


<muuseum nimi="Eesti Sõjamuuseum" id="1">
<muuseumikogu tyyp="Esemekogu">
<eksponaat originaal="true" id="1">
<nimetus olemus="kinnas"><![CDATA["Labakinnas. M. Laidoneri (ema) kootud"]]></nimetus>
<number><![CDATA["KLM ET 22 A 22"]]></number>
<seisund>Hea</seisund>
</eksponaat>
<eksponaat originaal="true" id="2">
<nimetus olemus="tääk"><![CDATA["Mälestusese, miniatuurne tääk, USA Air Cavalry Divisioni sümboolikaga."]]></nimetus>
<number><![CDATA["KLM ET 365 A"]]></number>
<seisund>Hea</seisund>
</eksponaat>
</muuseumikogu>
<muuseumikogu tyyp="Tulirelvad">
<eksponaat originaal="false" id="1">
<nimetus olemus="tulirelv"><![CDATA["Otepää püss, koopia"]]></nimetus>
<number><![CDATA["KLM ET 1421 R1 457"]]></number>
<seisund>Hea</seisund>
</eksponaat>
<eksponaat originaal="true" id="2">
<nimetus olemus="tulirelv"><![CDATA["Tank 34-85"]]></nimetus>
<number><![CDATA["KLM ET 1603 R1 553"]]></number>
<seisund>Rahuldav</seisund>
</eksponaat>
</muuseumikogu>
</muuseum>

<muuseum nimi="Eesti Ajaloomuuseum" id="2">
<muuseumikogu tyyp="Fotod">
<eksponaat originaal="true" id="1">
<nimetus olemus="album"><![CDATA["Fotoalbum: Vene tsaariarmee - 141. Možaiski polk, polkovnik Aganjev, grupipildid, portreed, olustik, kohavaated, ettevalmistused lahinguteks, arstiabi, matused."]]></nimetus>
<number><![CDATA["AM _ 59 F 5501/1-305"]]></number>
<seisund>Hea</seisund>
</eksponaat>
<eksponaat originaal="true" id="2">
<nimetus olemus="album"><![CDATA["Fotoalbum: "Kaks aastat Punaarmee Eesti korpust 1942-1944." Illustreeritud, venekeelsed pildiallkirjad."]]></nimetus>
<number><![CDATA["AM _ 42 F 4100/1-270"]]></number>
<seisund>Hea</seisund>
</eksponaat>
</muuseumikogu>
<muuseumikogu tyyp="Mööblikollektsioon">
<eksponaat originaal="true" id="1">
<nimetus olemus="mööbel"><![CDATA["Laste söögitool, XIX saj. lõpp"]]></nimetus>
<number><![CDATA["AM _ 35566:1 Mb 1"]]></number>
<seisund>Hea</seisund>
</eksponaat>
</muuseumikogu>
</muuseum>

</muuseumid>
</pre>

===XML skeemifail===
<pre>
<?xml version="1.0" encoding="utf-8"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"
targetNamespace="http://example.com/schemas/muuseumid/v1"
xmlns="http://example.com/schemas/muuseumid/v1"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
attributeFormDefault="unqualified"
elementFormDefault="qualified">
<xs:element name="muuseumid">
<xs:complexType>
<xs:sequence>
<xs:element maxOccurs="unbounded" name="muuseum">
<xs:complexType>
<xs:sequence>
<xs:element maxOccurs="unbounded" name="muuseumikogu">
<xs:complexType>
<xs:sequence>
<xs:element maxOccurs="unbounded" name="eksponaat">
<xs:complexType>
<xs:sequence>
<xs:element name="nimetus">
<xs:complexType>
<xs:simpleContent>
<xs:extension base="xs:string">
<xs:attribute name="olemus" type="xs:string" use="required" />
</xs:extension>
</xs:simpleContent>
</xs:complexType>
</xs:element>
<xs:element name="number" type="xs:string" />
<xs:element name="seisund">
<xs:simpleType>
<xs:restriction base="xs:string">
<xs:enumeration value="Hea"></xs:enumeration>
<xs:enumeration value="Rahuldav"></xs:enumeration>
<xs:enumeration value="Halb"></xs:enumeration>
</xs:restriction>
</xs:simpleType>
</xs:element>
</xs:sequence>
<xs:attribute name="originaal" type="xs:boolean" use="required" />
<xs:attribute name="id" type="xs:integer" use="required" />
</xs:complexType>
</xs:element>
</xs:sequence>
<xs:attribute name="tyyp" type="xs:string" use="required" />
</xs:complexType>
</xs:element>
</xs:sequence>
<xs:attribute name="nimi" type="xs:string" use="required" />
<xs:attribute name="id" type="xs:integer" use="required" />
</xs:complexType>
</xs:element>
</xs:sequence>
</xs:complexType>
</xs:element>
</xs:schema>
</pre>

===XSLT failid===

==Veebiteenuse analüüs==

==Veebiteenus==

==Klientrakendus==

Dot muzei

2015-03-06T17:21:02Z

Kveskima: /* XML fail */

Tomcat

2014-01-02T22:44:54Z

Kveskima: /* Käigultvahetus */

==Autor==

Kristjan Veskimäe D32

2013

==Sissejuhatus==

Tomcat on vabalt kättesaadav server Java veebirakendustele. Põhimõtteliselt on tegemist Servlet/JSP spetsifikatsiooni toetava konteineriga. Kiire käivitumise ning rakenduste käigultvahetuse tõttu on Tomcat hea valik väiksemate ning keskmise suurusega Java veebirakenduste käitamiseks.

Antud töö kirjeldab Tomcati 8. versiooni. Põhiosa on üldiselt samasugune võrreldes paari eelmise versiooniga. Suuremad erinevused on versioonispetsiifilistes probleemides ja nende lahendamises, mida käesolev töö ei vaatle.

Töö vaatleb Tomcati paigaldamist ja seadistamist Unix-laadsesse keskkonda ning eeldab lugejalt algteadmisi sarnastes süsteemides. Tomcati on võimalik paigaldada ka Windows-keskkonda, kuid antud veebiserver eeldab kasutaja poolt käsureal töötamist ning Tomcati failihierarhias orienteerumist. Põhimõtteliselt on Java veebirakenduste arendamiseks IDE-abil võimalik siiski ka kasutada IDE-sse integreeritud Tomcati serverit - näiteks pakuvad sellist võimalust Eclipse EE ja NetBeans - kuid seda käesolev töö ei vaatle.

==Mõisted==

* '''Kontekst''' (context) - Tomcati mõistes üks konkreetne veebiaplikatsioon
* '''Konteiner''' (container) - veebiserver Tomcat ise
* '''Kontekstikirjeldus''' (context descriptor) - Tomcati-spetsiifiline konteksti konfiguratsioonimääratlus; peremehepõhine osa loetakse failist $CATALINA_HOME/conf/[enginename]/[hostname]/context.xml ja sellele lisatakse kontekstispetsiifilised täpsustused failist $CATALINA_BASE/conf/[enginename]/[hostname]/[webappname].xml; kontekstikirjeldus määrab näiteks nimed ressurssidele, sessioonihalduse parameetrid jmt. (olgu märgitud, et Tomcati varasemates versioonides sisaldusid kontekstikirjeldused põhikonfiguratsioonifailis server.xml)
* '''Dokumendipõhi''' (docBase) - kontekstile vastav kataloog Tomcati "webapps" kataloogis, mis tekib veebiaplikatsiooni serverisse rakendamisel
* '''Veebiarhiiv''' (Web application ARchive, war-file) - Java veebiaplikatsiooni jagatakse hea tava kohaselt selle üheainsa veebiarhiivi failina, mille laienditüübiks on "war". Tegemist on zip-protokolliga kokkupakitud kataloogiga, millel on Java veebirakenduste spetsifikatsioonile vastav ülesehitus. Siiski võib veebiaplikatsioon olla juurutamisel ka lahtipakendatud olekus (inglisekeelne termin on "war is exploded").

==Ülesehitus==

{| class="wikitable"
|+Kataloogid
|-
|style="color: green;" | $CATALINA_HOME
|baaskataloog, kuhu on Tomcat paigutatud
|-
|style="color: green;" | $CATALINA_BASE
|parasjagu töösoleva Tomcati eksemplari baaskataloog, mille alusel lahendatakse teed ülejäänud kataloogide ja failideni; ainult ühe kasutusel oleva Tomcati eksemplari puhul on see sama, mis $CATALINA_HOME

|-
|style="color: green;" | $CATALINA_BASE/bin
|serveri käivitus- ja abiskriptid
|-
|style="color: green;" | $CATALINA_BASE/conf
|konfiguratsioonifailid
|-
|style="color: green;" | $CATALINA_BASE/lib
|Tomcatile vaikimisi kättesaadavad Java klassiteegid (class libraries) ehk .jar-failid kuhu on Java kompileeritud kood kokku pakendatud
|-
|style="color: green;" | $CATALINA_BASE/logs
|logifailid paigutatakse vaikimisi siia
|-
|style="color: green;" | $CATALINA_BASE/webapps
|kataloog, kuhu paigutatakse serverisse juurutatavad veebiaplikatsioonid

|}

{| class="wikitable"
|+Mõned olulisemad failid
|-
|style="color: green;" | $CATALINA_BASE/bin/startup.sh
|serveri käivitusskript
|-
|style="color: green;" | $CATALINA_BASE/bin/shutdown.sh
|serveri peatusskript

|-
|style="color: green;" | $CATALINA_BASE/conf/server.xml
| konteineri peamine konfiguratsioonifail
|-
|style="color: green;" | $CATALINA_BASE/conf/[enginename]/[hostname]/[webappname].xml
|serveri administraatori jaoks konteinerisse endasse ümber kopeeritud rakendusepõhine kontekstikirjelduse konfiguratsioon failist $CATALINA_BASE/webapps/[ApplicationName]/META-INF/context.xml
|-
|style="color: green;" | $CATALINA_BASE/conf/[enginename]/[hostname]/context.xml
| fail, mis aitab administraatoril konteksti kohta käivat infot kirjeldada peremeesmasina-põhiselt ja halduseks mõeldud automaat-tööriistadel (näiteks Tomcat Manager ja TCD) oma tööd teha
|-
|style="color: green;" | $CATALINA_BASE/$CATALINA_BASE/conf/[enginename]/[hostname]/manager.xml
|fail, mis võimaldab lisada rakendustele ligipääsufiltreid
|-
|style="color: green;" | $CATALINA_BASE/webapps/[webappname]/META-INF/context.xml
|kontekstikirjeldusfail, mille veebirakenduse programmeerija on pakendanud oma aplikatsiooniga kaasa ning millega ta saab võimaluse kontekstikirjeldust omalt poolt mõjutada; kirjutatakse rakenduse uuestijuurutamisel üle, mistõttu administraator peaks muutma selle asemel konteinerisse ümber kopeeritud püsieksemplari $CATALINA_BASE/conf/[enginename]/[hostname]/context.xml
|-
|style="color: green;" | $CATALINA_BASE/webapps/[webappname]/WEB-INF/web.xml
|ka üks oluline Java veebiaplikatsiooni konfiguratsioonifail, mille pakendatakse koos veebiarhiiviga; enamasti muudab seda ainult programeerija; määrab muu hulgas millised aplikatsiooni osad vajavad autentimist või kui kiiresti veebisessioon aegub
|}

==Installeerimine==

===Installeerimine paketihalduriga===

<pre>
apt-cache search tomcat
apt-get install tomcat[version]-webapps
apt-get install tomcat[version]-admin
apt-get install tomcat[version]
</pre>

===Installeerimine käsitsi===

Paketihalduriga installeerides ei pruugi viimane Tomcati versioon olla kättesaadav ja see pakub ka vähem võimalusi kataloogide määramiseks jms. Käsitsi installeerimiseks tuleb laadida Tomcat kodulehelt alla. Lahtipakkimisel tekib kataloog, milles sisalduv fail "RUNNING.txt" on kõige kindlam allikas installeerimisel tekkivate probleemide vältimiseks ning lahendamiseks.

Vajaliku versiooni installeerimisfaili asukoha saab vaadata Tomcati kodulehelt sektsioonist "Download". Järgnevas näites installeerime Tomcati kõige uuema ebastabiilse kandidaatversiooni, mida näitab nimes sisalduv RC ehk "release candidate". Produktsioonikeskkonda tuleks siiski valida stabiilse versiooni. Käsitsi installeerimine on sarnane järgmisega:
<pre>
wget http://mirror.nexcess.net/apache/tomcat/tomcat-8/v8.0.0-RC5/bin/apache-tomcat-8.0.0-RC5.tar.gz
tar -zxvf apache-tomcat-8.0.0-RC5.tar.gz
mv /Users/kristjanveskimae/downloads/apache-tomcat-8.0.0-RC5 /usr/local/apache-tomcat-8.0.0-RC5
rm -f /Library/Tomcat
ln -s /usr/local/apache-tomcat-8.0.0-RC5/ /Library/Tomcat
chown -R kristjanveskimae /Library/Tomcat
chmod +x /Library/Tomcat/bin/*.sh
</pre>

==Käivitamine ja aplikatsiooni juurutamine==

===Konteineri käivitamine===

Tomcati käivitamise eelduseks on Java paigaldamine masinasse ning keskkonnamuutujate "JAVA_HOME" ja "JRE_HOME" defineerimine. Peale installeerimist võib kasutada skripte kataloogist $CATALINA_BASE/bin . Järgneb üks võimalik käivitamise ja peatamise näide, mis on kasutatav eelnevalt kirjeldatud käsitsi installeerimise juhul:
<pre>
/Library/Tomcat/bin/startup.sh
</pre>
ja peatamiseks
<pre>
/Library/Tomcat/bin/shutdown.sh
</pre>

===Näiteaplikatsiooni juurutamine===

Java veebiaplikatsiooni jagatakse hea tava kohaselt üheainsa veebiarhiivi failina. Siiski võib Tomcati juurutada ka lahtipakendatud olekus ("exploded") Java veebiaplikatsiooni.

====Käsitsi juurutamine ja mahavõtmine====

Näiteaplikatsiooni juurutamiseks lae selle veebiarhiivifail alla ning kopeeri oma konteineri juurutamiskataloogi 'webapps':
<pre>wget http://tomcat.apache.org/tomcat-8.0-doc/appdev/sample/sample.war
cp /Users/kristjanveskimae/downloads/sample.war /Library/Tomcat/webapps/sample.war</pre>

[[File:tomcat_sample_application.png|400px|thumb|right|Pilt 1: Õnnestunult rakendatud näiteaplikatsioon]]

Kui konfiguratsioonifailis $CATALINA_BASE/conf/server.xml on märgendi "Host" atribuudi "autoDeploy" väärtus "true", installeerib ja uuendab Tomcat aplikatsioone dünaamiliselt töötamise ajal. Kui väärtuseks on "false", käib installeerimine staatiliselt ning serverisse juurutamiseks tuleb teha konteineri taaskäivitus. [http://tomcat.apache.org/tomcat-8.0-doc/manager-howto.html#Deploy_A_New_Application_from_a_Local_Path 1] Mõlemal juhul pakib konteiner arhiveeritud faili ise lahti samasse kausta $CATALINA_BASE/webapps ning ka juurutab selle. Tekkiv aplikatsioon on lokaalsest masinast seejärel kättesaadav aadressil http://localhost:8080/sample/ . Kui rakendamine õnnestub, siis peaks olema brauserist nähtav sarnane lehekülg nagu pildil 1.

Veebirakenduse käsitsi mahavõtmiseks tuleb kustutada talle vastav dokumendipõhja kataloog "webapps" kataloogist. Samuti tuleks kustutada .war-fail olemaks kindel, et Tomcat ei rakenda uuel käivitamisel veebiaplikatsiooni veebiarhiivifailist. Veelgi lihtsam on mahavõtmine brauseriga haldusrakenduse kaudu.

Rakenduste baaskataloogi "webapps" asukohta saab muuta failis $CATALINA_BASE/conf/server.xml peremehepõhiselt määratava atribuudiga "appBase", sealjuures Tomcati vaikimisi peremees ehk "Host" on "localhost".

====Tomcati vahendid juurutamiseks====

Veebiaplikatsioonide juurutamine ja mahajuurutamine on võimalik ka kaughalduse teel tänu Tomcati internetipõhisele haldusrakendusele. Näiteks saab veebibrauserit kasutades teha serveri põhitoiminguid Tomcati enda HTML-põhise rakendusega "Tomcat Manager". Veebipõhine haldusrakendus töötab ka käsupõhise veebiteenusena, millele on valmis ehitatud Anti ja Maveni integratsioonid. Samuti eksisteerib käsurea kliendirakendus TCD (Tomcat Client Deployer). TCD ei kuulu Tomcati baaskoosseisu, kuid pakub peale serveri administreerimise tavatoimingute ka lisafunktsionaalsust nagu veebirakenduse kokkukompileerimine ja pakendamine. [http://tomcat.apache.org/tomcat-8.0-doc/manager-howto.html#Configuring_Manager_Application_Access 1]

====Haldurakendus "Tomcat Manager"====

Tomcati haldusrakendus "Tomcat Manager" (antud alamjaotuses lihtsalt haldusrakendus) on Tomcati enda veebiaplikatioon Tomcati brauseripõhiseks kaughalduseks, võimaldades muu hulgas järgnevat [http://tomcat.apache.org/tomcat-8.0-doc/manager-howto.html#Introduction 1]:
* Rakendada uue veebiaplikatsiooni war-faili üleslaadimisega;
* Näha kõiki rakendatud veebiaplikatsioone koos aktiivsete sessioonidega;
* Taasrakendada veebirakendust, näiteks veebiarhiivi pakitud klassifailide /WEB-INF/classes või teekide /WEB-INF/lib uuendamisel, kinnijooksmisel jms.;
* Peatada veebirakendust ilma serverist eemaldamata, samuti koos serverist eemaldamisega;
* Vaadata operatsioonisüsteemi ja Java parameetrite väärtusi;
* Näha kõiki saadaolevaid JNDI ressursse, k.a. andmebaasiühendusi, mis aitavad rakenduste programmeerijail defineerida <ResourceLink> elemendid web.xml konfiguratsioonifailis.

Tomcati installatsioon sisaldab haldusrakendust juba vaikimisi. Haldusrakenduse töölepanemiseks tuleb peremeesmasina konfiguratsioonikataloogi $CATALINA_BASE/conf/[enginename]/[hostname] lisada ka fail manager.xml. Vaikimisi valmiskonfigureeritud testrakendusel on see fail juba olemas asukohas $CATALINA_BASE/conf/Catalina/localhost/manager.xml . Rakendus asub vaikimisi aadressil http://[host]/manager/ , vaikimisi konfiguratsioone kasutades lahendub see asukohaks http://localhost:8080/manager/ . [http://tomcat.apache.org/tomcat-8.0-doc/manager-howto.html#Configuring_Manager_Application_Access 1]

====="Tomcat Manager" ligipääsu konfigureerimine=====

Vaikimisi on turvalisuspõhjustel ligipääs haldusrakendusele maha keeratud. Mismoodi täpselt kasutajatel ligipääsu võimaldada sõltub kasutatavast valdusest (realm). Vaikimisi defineerib $CATALINA_BASE/conf/server.xml valduseks "MemoryRealm". Vaikimisi loeb valdus "MemoryRealm" kasutajad failist $CATALINA_BASE/conf/tomcat-users.xml. Antud failis tuleb iga kasutaja defineerida omaette märgendiga <user>, mis näeb välja umbes järgmine [http://tomcat.apache.org/tomcat-8.0-doc/manager-howto.html#Configuring_Manager_Application_Access 1]:
<pre>
<user name="craig" password="secret" roles="manager-gui,manager-script" />
</pre>

Antud kasutajale on defineeritud korraga kaks rolli. Ligipääsu võimaldamiseks tulebki lihtsamal juhul kasutajatefailis $CATALINA_BASE/conf/tomcat-users.xml defineerida enda kasutaja. Kasutaja rolliks võib määrata näiteks "manager-gui", mis võimaldab ligipääsu kogu HTML liidese funktsionaalsusele.

Teised valdused on "JDBCRealm", mille puhul hoitakse kasutajatega seonduvat infot andmebaasis ja JNDIRealm, mille puhul kasutatakse lihtsustatud kataloogisirvimise protokolli (LDAP).
Lisaks saab haldusrakendusele keelata ligipääsu mujalt kui kindlaksmääratud IP-aadressidelt, lisades filtri "RemoteAddrValve" või "RemoteHostValve" konfigureerimisfaili manager.xml näiteks järgmiselt [http://tomcat.apache.org/tomcat-8.0-doc/manager-howto.html#Introduction 1]:
<pre>
<Context privileged="true">
<Valve className="org.apache.catalina.valves.RemoteAddrValve"
allow="127\.0\.0\.1"/>
</Context>
</pre>

=====Juurutamine ja mahavõtmine haldusrakendusega "Tomcat Manager"=====

Juurutamiseks lae kõigepealt veebiarhiivifail üles, kasutades esilehel asuvat sektsiooni "WAR file to deploy". Veebiarhiivi üleslaadimise liides on kujutatud plidil 2.

[[File:tomcat_manager_war_upload.png|600px|thumb|right|Pilt 2: Veebiarhiivi üleslaadimise nupp]]

Rakendus kuvatakse seejärel hallatavate rakenduste nimekirjas. Kui konteiner pole seadistatud üleslaetud aplikatsiooni kohe ka ise rakendama, tuleb vajutada "Start". Rakenduse peatamiseks kasuta "Stop", uuesti rakendamiseks "Redeploy" ja serverist eemaldamiseks "Undeploy". Nupud on näha ka pildil 3 olevas rakenduste nimekirjas.


[[File:tomcat_manager_apps_list.png|1000px|thumb|Pilt 3: Rakenduste nimekiri Tomcati haldusrakenduses "Tomcat Manager"]]

==Näpunäiteid Tomcati reaalseks kasutamiseks==

===Juurutamise järjekord===

Tomcati käivitumisel juurutatakse aplikatsioonid sellises järjekorras [http://www.mulesoft.com/tomcat-deploy-procedures 2]:
# Konteinerisse kopeeritud kontekstikirjelduste järgi $CATALINA_BASE/conf/[EngineName]/[HostName]/[ApplicationName].xml ;
# Lahtipakitud rakendused "webapps" kataloogis;
# Pakitud rakenduste veebiarhiivid "webapps" kataloogis.

Seetõttu peaks käsitsi taasjuurutamisel kindluse mõttes eelnevalt kustutama rakenduse lahtipakitud dokumendipõhja kataloogi "webapps" kataloogist. Kontekstikirjelduse muutumisel tuleb jälgida, kas kirjeldus on juba kopeeritud serverisse ning vajadusel eelmise versiooni ümber muuta või kustutada.

===Reaalsele domeenile konfigureerimine===

Järgnevalt eeldame, et domeen ''www.minukodukas.ee'' on juba serverimasinaga seostatud. Et Tomcat hakkaks ka reaalselt Internetist tulevatele päringutele vastama, tuleb muuta failis $CATALINA_BASE/conf/server.xml konteinerile ''Catalina'' vastava teenusemärgendi sisu sarnaselt järgnevaga:

<pre>
<Service name="Catalina">
<Connector port="80" protocol="HTTP/1.1" connectionTimeout="20000" URIEncoding="UTF-8" redirectPort="8443" />
<Engine name="Catalina" defaultHost="www.minukodukas.ee">
<Host name="www.minukodukas.ee" appBase="webapps" unpackWARs="true" autoDeploy="false" deployOnStartup="false" xmlValidation="false" xmlNamespaceAware="false">
<Context path="" docBase="kodukas" debug="0" reloadable="true" />
</Host>
</Engine>
</Service>
</pre>

Ülal defineerime põhiliselt selle, et Tomcat kuulaks domeeni ''www.minukodukas.ee'' ja kasutaks HTTP päringute jaoks porti 80. Ühtlasti otsib Tomcat juurutatavat rakendust failist $CATALINA_BASE/webapps/kodukas.war. Kuna rajalisandiks on määratud tühi sõne (path=""), siis juurutataksegi aplikatsioon aadressile ''www.minukodukas.ee'' ilma rajalisandita (a'la ''www.minukodukas.ee/wiki''). Seetõttu pakitakse ka veebiarhiiv tegelikult lahti kataloogi $CATALINA_BASE/webapps/ROOT mitte kataloogi $CATALINA_BASE/webapps/kodukas nagu võiks eeldada.

===Käigultvahetus===

Võimaldamaks käigultvahetust (hot deployment) peab konteineri konfiguratsioonifailis $CATALINA_BASE/conf/server.xml olema peremehepõhise märgendi "Host" atribuudi "autoDeploy" väärtus "true". Sel juhul installeerib ja uuendab Tomcat aplikatsioone dünaamiliselt töötamise ajal. Kui väärtuseks on "false", käib installeerimine staatiliselt ning serverisse juurutamiseks tuleb teha konteineri taaskäivitus. Käigultvahetust saab määrata ka peremehe defineerimisel "Host Manager" rakendusega, mis on kättesaadav aadressil http://localhost:8080/host-manager/html . Kasutamiseks tuleb lisada oma kasutajale rolli "admin-gui" (vt. alajaotus ""Tomcat Manager" ligipääsu konfigureerimine"). Antud rakenduse veebiliides on kujutatud pildil 4.

[[File:tomcat_host_manager_app.png|500px|thumb|Pilt 4: Tomcati haldusrakendus "Host Manage"]]

Käigultvahetust päästikuks on vaikimisi uuendatud veebiarhiivifaili või lahtipakitud veebirakenduse paigutamine "webapps" kataloogi. Käigultvahetuse päästikutele võib failis $CATALINA_BASE/conf/server.xml ka ise lisada kuulatavaid ressursse nagu web.xml muutmine või mõne teegifaili vahetamine (märgendis "Host").

===Klassiteekide väljatõstmine veebiarhiivifailist===

Kõik konteksti poolt kasutatavad Java klassiteegid võib pakendada veebiarhiivi sisse kataloogi "lib", kuid nii võib osutuda veebiarhiivi üleslaadimine ajakulukaks, eriti arenduskeskkonnas. Kui ei teki ohtu, et erinevad rakendused kasutavad sama teegi erinevaid versioone, siis on vahel parem lisada osa teeke konteineri kataloogi $CATALINA_BASE/libs, kust need tehakse siis konteineri poolt kättesaadavaks kõigile konteineris jooksutatavatele kontekstidele. Nii võib vähendada veebiarhiivi faili suurust märgatavalt, mis tõstab kokkuvõttes juurutamiskiirust ja ühes sellega programmeerijate tööviljakust.

===Mälukasutus===

Konteineri poolt kasutatavat mälu saab vaadata haldusrakendusest vajutades lingile "Server Status". Mälukasutus on toodud jaotuses "JVM", kus näidatakse nii maksimaalselt kättesaadavat mälu kui ka parasjagu reserveeritud mälu.

<pre>Free memory: 41.16 MB Total memory: 123.37 MB Max memory: 1027.56 MB</pre>

Mälu suurendamiseks võib näiteks defineerida skriptis $CATALINA_BASE/bin/catalina.sh muutuja "JAVA_OPTS" ning määrata Java mälukasutuse miinimum- ja maksimumväärtused sarnaselt järgnevatega [http://www.mkyong.com/tomcat/tomcat-javalangoutofmemoryerror-permgen-space/ 3]:
<pre>
JAVA_OPTS="-Xms1536m -Xmx1536m -XX:NewSize=256m -XX:MaxNewSize=256m -XX:PermSize=256m -XX:MaxPermSize=256m"
</pre>

===Logifailid===

Vaikimisi defineerib Tomcat failiga $CATALINA_BASE/conf/logging.properties viis logerit, mis tekitavad viis eraldi logifaili.

{| style="background:#cccc99;color:black;width:80%;" border="1" cellpadding="5" cellspacing="0" align="center"
|+ Tomcati tekitatavad logifailid "logs" kataloogis
!Fail !! Kasutus
|- style="background:white; color:black"
| style="width:300px" |catalina.out
| Tomcati käivitus- ja peatamisskriptide väljund, samuti juurutatud rakenduste prindilaused System.out ja veaväljundid System.err
|- style="background:white; color:black"
| style="width:300px" |catalina.[yyyy]-[mm]-[dd].log
| Pööratud (rotated) logifail catalina.out
|- style="background:white; color:black"
| style="width:300px" |host-manager.[yyyy]-[mm]-[dd].log
| Logi peremehehalduse rakendusele (rakendus on kättesaadav kohalikust masinast aadressil http://localhost:8080/host-manager/html )
|- style="background:white; color:black"
| style="width:300px" |localhost.[yyyy]-[mm]-[dd].log
| Peremehe "localhost" logi; mitme virtuaalse peremehe korral tekitatakse igale peremehele oma logi
|- style="background:white; color:black"
| style="width:300px" |localhost_access_log.[yyyy]-[mm]-[dd].txt
| Konteinerisse Internetist saabunud päringute logi
|- style="background:white; color:black"
| style="width:300px" |manager.[yyyy]-[mm]-[dd].log
| Haldusrakenduse tegevuste logi
|}

= Kokkuvõte =

Antud juhend aitab Unix-keskkonnas (ja operatsioonisüsteemi administreerimise algteadmiste olemasolul) Tomcati installeerida, käivitada ja juurutada Tomcatile ka Java näite veebiaplikatsioon. Lisaks on ära toodud ka mõned esmased näpunäited Tomcati kasutamiseks reaalse veebiserverina. Loodetavasti aitab juhend lugeja esmasel kokkupuutel Tomcatiga tekkivatest probleemidest jagu saada ja süveneda iseseisvalt veebiserveri Tomcat põhjalikumasse uurimisse.

= Autori märkused =

Tööl pole ma kahjuks Tomcati reaalselt kasutada saanud. Kuigi olen tegelenud Java ärirakendustega, on IT-juhtimise poolel seni otsustatud JBoss või Jetty kasuks. Siiski olen oma huviprojekte arendades või Java veebirakenduste tegemist õppides valinud just Tomcati. Seda eelkõige hea integreerituse tõttu IDE-dega. Tomcat töötab näiteks kohe koos NetBeansi installeerimisega, samuti pole kuigi keeruline tööle panna koos Java EE versiooniga Eclipse-ist. Tean ka vähemalt üht Eesti ettevõttet, mis kasutabki Tomcati reaalseks äriteenuste pakkumiseks.

Seni on tundunud Tomcati kasutus läbi IDE mugav, kuid probleemide tekkimisel olen hätta jäänud. Kuna tegemist on siiski Java ärirakendusi toetava veebikonteineriga, mis pakub muu hulgas JNDI-nimeteenust ja andmebaasiühenduste haldamist, siis pole selle ülesehitus sugugi lihtne. Siiski aitab algtõdede teadmine ka lihtsamini lahendada tekkivaid probleeme läbi IDE kasutades.

=Viiteid=

Palju vajalikku võib leida [http://tomcat.apache.org/tomcat-8.0-doc/index.html Tomcat 8 dokumentatsioonist]

Lisaks üks viide põhjalikule Tomcati versioon seitsme ülevaatele: http://www.ntu.edu.sg/home/ehchua/programming/howto/Tomcat_More.html

= Kasutatud materjalid =

#http://tomcat.apache.org/tomcat-8.0-doc/index.html
#http://www.mulesoft.com/tomcat-deploy-procedures
#http://www.mkyong.com/tomcat/tomcat-javalangoutofmemoryerror-permgen-space/

[[Category: Operatsioonisüsteemide administreerimine ja sidumine]]

Tomcat

2014-01-02T22:44:29Z

Kveskima: /* Viiteid */

==Autor==

Kristjan Veskimäe D32

2013

==Sissejuhatus==

Tomcat on vabalt kättesaadav server Java veebirakendustele. Põhimõtteliselt on tegemist Servlet/JSP spetsifikatsiooni toetava konteineriga. Kiire käivitumise ning rakenduste käigultvahetuse tõttu on Tomcat hea valik väiksemate ning keskmise suurusega Java veebirakenduste käitamiseks.

Antud töö kirjeldab Tomcati 8. versiooni. Põhiosa on üldiselt samasugune võrreldes paari eelmise versiooniga. Suuremad erinevused on versioonispetsiifilistes probleemides ja nende lahendamises, mida käesolev töö ei vaatle.

Töö vaatleb Tomcati paigaldamist ja seadistamist Unix-laadsesse keskkonda ning eeldab lugejalt algteadmisi sarnastes süsteemides. Tomcati on võimalik paigaldada ka Windows-keskkonda, kuid antud veebiserver eeldab kasutaja poolt käsureal töötamist ning Tomcati failihierarhias orienteerumist. Põhimõtteliselt on Java veebirakenduste arendamiseks IDE-abil võimalik siiski ka kasutada IDE-sse integreeritud Tomcati serverit - näiteks pakuvad sellist võimalust Eclipse EE ja NetBeans - kuid seda käesolev töö ei vaatle.

==Mõisted==

* '''Kontekst''' (context) - Tomcati mõistes üks konkreetne veebiaplikatsioon
* '''Konteiner''' (container) - veebiserver Tomcat ise
* '''Kontekstikirjeldus''' (context descriptor) - Tomcati-spetsiifiline konteksti konfiguratsioonimääratlus; peremehepõhine osa loetakse failist $CATALINA_HOME/conf/[enginename]/[hostname]/context.xml ja sellele lisatakse kontekstispetsiifilised täpsustused failist $CATALINA_BASE/conf/[enginename]/[hostname]/[webappname].xml; kontekstikirjeldus määrab näiteks nimed ressurssidele, sessioonihalduse parameetrid jmt. (olgu märgitud, et Tomcati varasemates versioonides sisaldusid kontekstikirjeldused põhikonfiguratsioonifailis server.xml)
* '''Dokumendipõhi''' (docBase) - kontekstile vastav kataloog Tomcati "webapps" kataloogis, mis tekib veebiaplikatsiooni serverisse rakendamisel
* '''Veebiarhiiv''' (Web application ARchive, war-file) - Java veebiaplikatsiooni jagatakse hea tava kohaselt selle üheainsa veebiarhiivi failina, mille laienditüübiks on "war". Tegemist on zip-protokolliga kokkupakitud kataloogiga, millel on Java veebirakenduste spetsifikatsioonile vastav ülesehitus. Siiski võib veebiaplikatsioon olla juurutamisel ka lahtipakendatud olekus (inglisekeelne termin on "war is exploded").

==Ülesehitus==

{| class="wikitable"
|+Kataloogid
|-
|style="color: green;" | $CATALINA_HOME
|baaskataloog, kuhu on Tomcat paigutatud
|-
|style="color: green;" | $CATALINA_BASE
|parasjagu töösoleva Tomcati eksemplari baaskataloog, mille alusel lahendatakse teed ülejäänud kataloogide ja failideni; ainult ühe kasutusel oleva Tomcati eksemplari puhul on see sama, mis $CATALINA_HOME

|-
|style="color: green;" | $CATALINA_BASE/bin
|serveri käivitus- ja abiskriptid
|-
|style="color: green;" | $CATALINA_BASE/conf
|konfiguratsioonifailid
|-
|style="color: green;" | $CATALINA_BASE/lib
|Tomcatile vaikimisi kättesaadavad Java klassiteegid (class libraries) ehk .jar-failid kuhu on Java kompileeritud kood kokku pakendatud
|-
|style="color: green;" | $CATALINA_BASE/logs
|logifailid paigutatakse vaikimisi siia
|-
|style="color: green;" | $CATALINA_BASE/webapps
|kataloog, kuhu paigutatakse serverisse juurutatavad veebiaplikatsioonid

|}

{| class="wikitable"
|+Mõned olulisemad failid
|-
|style="color: green;" | $CATALINA_BASE/bin/startup.sh
|serveri käivitusskript
|-
|style="color: green;" | $CATALINA_BASE/bin/shutdown.sh
|serveri peatusskript

|-
|style="color: green;" | $CATALINA_BASE/conf/server.xml
| konteineri peamine konfiguratsioonifail
|-
|style="color: green;" | $CATALINA_BASE/conf/[enginename]/[hostname]/[webappname].xml
|serveri administraatori jaoks konteinerisse endasse ümber kopeeritud rakendusepõhine kontekstikirjelduse konfiguratsioon failist $CATALINA_BASE/webapps/[ApplicationName]/META-INF/context.xml
|-
|style="color: green;" | $CATALINA_BASE/conf/[enginename]/[hostname]/context.xml
| fail, mis aitab administraatoril konteksti kohta käivat infot kirjeldada peremeesmasina-põhiselt ja halduseks mõeldud automaat-tööriistadel (näiteks Tomcat Manager ja TCD) oma tööd teha
|-
|style="color: green;" | $CATALINA_BASE/$CATALINA_BASE/conf/[enginename]/[hostname]/manager.xml
|fail, mis võimaldab lisada rakendustele ligipääsufiltreid
|-
|style="color: green;" | $CATALINA_BASE/webapps/[webappname]/META-INF/context.xml
|kontekstikirjeldusfail, mille veebirakenduse programmeerija on pakendanud oma aplikatsiooniga kaasa ning millega ta saab võimaluse kontekstikirjeldust omalt poolt mõjutada; kirjutatakse rakenduse uuestijuurutamisel üle, mistõttu administraator peaks muutma selle asemel konteinerisse ümber kopeeritud püsieksemplari $CATALINA_BASE/conf/[enginename]/[hostname]/context.xml
|-
|style="color: green;" | $CATALINA_BASE/webapps/[webappname]/WEB-INF/web.xml
|ka üks oluline Java veebiaplikatsiooni konfiguratsioonifail, mille pakendatakse koos veebiarhiiviga; enamasti muudab seda ainult programeerija; määrab muu hulgas millised aplikatsiooni osad vajavad autentimist või kui kiiresti veebisessioon aegub
|}

==Installeerimine==

===Installeerimine paketihalduriga===

<pre>
apt-cache search tomcat
apt-get install tomcat[version]-webapps
apt-get install tomcat[version]-admin
apt-get install tomcat[version]
</pre>

===Installeerimine käsitsi===

Paketihalduriga installeerides ei pruugi viimane Tomcati versioon olla kättesaadav ja see pakub ka vähem võimalusi kataloogide määramiseks jms. Käsitsi installeerimiseks tuleb laadida Tomcat kodulehelt alla. Lahtipakkimisel tekib kataloog, milles sisalduv fail "RUNNING.txt" on kõige kindlam allikas installeerimisel tekkivate probleemide vältimiseks ning lahendamiseks.

Vajaliku versiooni installeerimisfaili asukoha saab vaadata Tomcati kodulehelt sektsioonist "Download". Järgnevas näites installeerime Tomcati kõige uuema ebastabiilse kandidaatversiooni, mida näitab nimes sisalduv RC ehk "release candidate". Produktsioonikeskkonda tuleks siiski valida stabiilse versiooni. Käsitsi installeerimine on sarnane järgmisega:
<pre>
wget http://mirror.nexcess.net/apache/tomcat/tomcat-8/v8.0.0-RC5/bin/apache-tomcat-8.0.0-RC5.tar.gz
tar -zxvf apache-tomcat-8.0.0-RC5.tar.gz
mv /Users/kristjanveskimae/downloads/apache-tomcat-8.0.0-RC5 /usr/local/apache-tomcat-8.0.0-RC5
rm -f /Library/Tomcat
ln -s /usr/local/apache-tomcat-8.0.0-RC5/ /Library/Tomcat
chown -R kristjanveskimae /Library/Tomcat
chmod +x /Library/Tomcat/bin/*.sh
</pre>

==Käivitamine ja aplikatsiooni juurutamine==

===Konteineri käivitamine===

Tomcati käivitamise eelduseks on Java paigaldamine masinasse ning keskkonnamuutujate "JAVA_HOME" ja "JRE_HOME" defineerimine. Peale installeerimist võib kasutada skripte kataloogist $CATALINA_BASE/bin . Järgneb üks võimalik käivitamise ja peatamise näide, mis on kasutatav eelnevalt kirjeldatud käsitsi installeerimise juhul:
<pre>
/Library/Tomcat/bin/startup.sh
</pre>
ja peatamiseks
<pre>
/Library/Tomcat/bin/shutdown.sh
</pre>

===Näiteaplikatsiooni juurutamine===

Java veebiaplikatsiooni jagatakse hea tava kohaselt üheainsa veebiarhiivi failina. Siiski võib Tomcati juurutada ka lahtipakendatud olekus ("exploded") Java veebiaplikatsiooni.

====Käsitsi juurutamine ja mahavõtmine====

Näiteaplikatsiooni juurutamiseks lae selle veebiarhiivifail alla ning kopeeri oma konteineri juurutamiskataloogi 'webapps':
<pre>wget http://tomcat.apache.org/tomcat-8.0-doc/appdev/sample/sample.war
cp /Users/kristjanveskimae/downloads/sample.war /Library/Tomcat/webapps/sample.war</pre>

[[File:tomcat_sample_application.png|400px|thumb|right|Pilt 1: Õnnestunult rakendatud näiteaplikatsioon]]

Kui konfiguratsioonifailis $CATALINA_BASE/conf/server.xml on märgendi "Host" atribuudi "autoDeploy" väärtus "true", installeerib ja uuendab Tomcat aplikatsioone dünaamiliselt töötamise ajal. Kui väärtuseks on "false", käib installeerimine staatiliselt ning serverisse juurutamiseks tuleb teha konteineri taaskäivitus. [http://tomcat.apache.org/tomcat-8.0-doc/manager-howto.html#Deploy_A_New_Application_from_a_Local_Path 1] Mõlemal juhul pakib konteiner arhiveeritud faili ise lahti samasse kausta $CATALINA_BASE/webapps ning ka juurutab selle. Tekkiv aplikatsioon on lokaalsest masinast seejärel kättesaadav aadressil http://localhost:8080/sample/ . Kui rakendamine õnnestub, siis peaks olema brauserist nähtav sarnane lehekülg nagu pildil 1.

Veebirakenduse käsitsi mahavõtmiseks tuleb kustutada talle vastav dokumendipõhja kataloog "webapps" kataloogist. Samuti tuleks kustutada .war-fail olemaks kindel, et Tomcat ei rakenda uuel käivitamisel veebiaplikatsiooni veebiarhiivifailist. Veelgi lihtsam on mahavõtmine brauseriga haldusrakenduse kaudu.

Rakenduste baaskataloogi "webapps" asukohta saab muuta failis $CATALINA_BASE/conf/server.xml peremehepõhiselt määratava atribuudiga "appBase", sealjuures Tomcati vaikimisi peremees ehk "Host" on "localhost".

====Tomcati vahendid juurutamiseks====

Veebiaplikatsioonide juurutamine ja mahajuurutamine on võimalik ka kaughalduse teel tänu Tomcati internetipõhisele haldusrakendusele. Näiteks saab veebibrauserit kasutades teha serveri põhitoiminguid Tomcati enda HTML-põhise rakendusega "Tomcat Manager". Veebipõhine haldusrakendus töötab ka käsupõhise veebiteenusena, millele on valmis ehitatud Anti ja Maveni integratsioonid. Samuti eksisteerib käsurea kliendirakendus TCD (Tomcat Client Deployer). TCD ei kuulu Tomcati baaskoosseisu, kuid pakub peale serveri administreerimise tavatoimingute ka lisafunktsionaalsust nagu veebirakenduse kokkukompileerimine ja pakendamine. [http://tomcat.apache.org/tomcat-8.0-doc/manager-howto.html#Configuring_Manager_Application_Access 1]

====Haldurakendus "Tomcat Manager"====

Tomcati haldusrakendus "Tomcat Manager" (antud alamjaotuses lihtsalt haldusrakendus) on Tomcati enda veebiaplikatioon Tomcati brauseripõhiseks kaughalduseks, võimaldades muu hulgas järgnevat [http://tomcat.apache.org/tomcat-8.0-doc/manager-howto.html#Introduction 1]:
* Rakendada uue veebiaplikatsiooni war-faili üleslaadimisega;
* Näha kõiki rakendatud veebiaplikatsioone koos aktiivsete sessioonidega;
* Taasrakendada veebirakendust, näiteks veebiarhiivi pakitud klassifailide /WEB-INF/classes või teekide /WEB-INF/lib uuendamisel, kinnijooksmisel jms.;
* Peatada veebirakendust ilma serverist eemaldamata, samuti koos serverist eemaldamisega;
* Vaadata operatsioonisüsteemi ja Java parameetrite väärtusi;
* Näha kõiki saadaolevaid JNDI ressursse, k.a. andmebaasiühendusi, mis aitavad rakenduste programmeerijail defineerida <ResourceLink> elemendid web.xml konfiguratsioonifailis.

Tomcati installatsioon sisaldab haldusrakendust juba vaikimisi. Haldusrakenduse töölepanemiseks tuleb peremeesmasina konfiguratsioonikataloogi $CATALINA_BASE/conf/[enginename]/[hostname] lisada ka fail manager.xml. Vaikimisi valmiskonfigureeritud testrakendusel on see fail juba olemas asukohas $CATALINA_BASE/conf/Catalina/localhost/manager.xml . Rakendus asub vaikimisi aadressil http://[host]/manager/ , vaikimisi konfiguratsioone kasutades lahendub see asukohaks http://localhost:8080/manager/ . [http://tomcat.apache.org/tomcat-8.0-doc/manager-howto.html#Configuring_Manager_Application_Access 1]

====="Tomcat Manager" ligipääsu konfigureerimine=====

Vaikimisi on turvalisuspõhjustel ligipääs haldusrakendusele maha keeratud. Mismoodi täpselt kasutajatel ligipääsu võimaldada sõltub kasutatavast valdusest (realm). Vaikimisi defineerib $CATALINA_BASE/conf/server.xml valduseks "MemoryRealm". Vaikimisi loeb valdus "MemoryRealm" kasutajad failist $CATALINA_BASE/conf/tomcat-users.xml. Antud failis tuleb iga kasutaja defineerida omaette märgendiga <user>, mis näeb välja umbes järgmine [http://tomcat.apache.org/tomcat-8.0-doc/manager-howto.html#Configuring_Manager_Application_Access 1]:
<pre>
<user name="craig" password="secret" roles="manager-gui,manager-script" />
</pre>

Antud kasutajale on defineeritud korraga kaks rolli. Ligipääsu võimaldamiseks tulebki lihtsamal juhul kasutajatefailis $CATALINA_BASE/conf/tomcat-users.xml defineerida enda kasutaja. Kasutaja rolliks võib määrata näiteks "manager-gui", mis võimaldab ligipääsu kogu HTML liidese funktsionaalsusele.

Teised valdused on "JDBCRealm", mille puhul hoitakse kasutajatega seonduvat infot andmebaasis ja JNDIRealm, mille puhul kasutatakse lihtsustatud kataloogisirvimise protokolli (LDAP).
Lisaks saab haldusrakendusele keelata ligipääsu mujalt kui kindlaksmääratud IP-aadressidelt, lisades filtri "RemoteAddrValve" või "RemoteHostValve" konfigureerimisfaili manager.xml näiteks järgmiselt [http://tomcat.apache.org/tomcat-8.0-doc/manager-howto.html#Introduction 1]:
<pre>
<Context privileged="true">
<Valve className="org.apache.catalina.valves.RemoteAddrValve"
allow="127\.0\.0\.1"/>
</Context>
</pre>

=====Juurutamine ja mahavõtmine haldusrakendusega "Tomcat Manager"=====

Juurutamiseks lae kõigepealt veebiarhiivifail üles, kasutades esilehel asuvat sektsiooni "WAR file to deploy". Veebiarhiivi üleslaadimise liides on kujutatud plidil 2.

[[File:tomcat_manager_war_upload.png|600px|thumb|right|Pilt 2: Veebiarhiivi üleslaadimise nupp]]

Rakendus kuvatakse seejärel hallatavate rakenduste nimekirjas. Kui konteiner pole seadistatud üleslaetud aplikatsiooni kohe ka ise rakendama, tuleb vajutada "Start". Rakenduse peatamiseks kasuta "Stop", uuesti rakendamiseks "Redeploy" ja serverist eemaldamiseks "Undeploy". Nupud on näha ka pildil 3 olevas rakenduste nimekirjas.


[[File:tomcat_manager_apps_list.png|1000px|thumb|Pilt 3: Rakenduste nimekiri Tomcati haldusrakenduses "Tomcat Manager"]]

==Näpunäiteid Tomcati reaalseks kasutamiseks==

===Juurutamise järjekord===

Tomcati käivitumisel juurutatakse aplikatsioonid sellises järjekorras [http://www.mulesoft.com/tomcat-deploy-procedures 2]:
# Konteinerisse kopeeritud kontekstikirjelduste järgi $CATALINA_BASE/conf/[EngineName]/[HostName]/[ApplicationName].xml ;
# Lahtipakitud rakendused "webapps" kataloogis;
# Pakitud rakenduste veebiarhiivid "webapps" kataloogis.

Seetõttu peaks käsitsi taasjuurutamisel kindluse mõttes eelnevalt kustutama rakenduse lahtipakitud dokumendipõhja kataloogi "webapps" kataloogist. Kontekstikirjelduse muutumisel tuleb jälgida, kas kirjeldus on juba kopeeritud serverisse ning vajadusel eelmise versiooni ümber muuta või kustutada.

===Reaalsele domeenile konfigureerimine===

Järgnevalt eeldame, et domeen ''www.minukodukas.ee'' on juba serverimasinaga seostatud. Et Tomcat hakkaks ka reaalselt Internetist tulevatele päringutele vastama, tuleb muuta failis $CATALINA_BASE/conf/server.xml konteinerile ''Catalina'' vastava teenusemärgendi sisu sarnaselt järgnevaga:

<pre>
<Service name="Catalina">
<Connector port="80" protocol="HTTP/1.1" connectionTimeout="20000" URIEncoding="UTF-8" redirectPort="8443" />
<Engine name="Catalina" defaultHost="www.minukodukas.ee">
<Host name="www.minukodukas.ee" appBase="webapps" unpackWARs="true" autoDeploy="false" deployOnStartup="false" xmlValidation="false" xmlNamespaceAware="false">
<Context path="" docBase="kodukas" debug="0" reloadable="true" />
</Host>
</Engine>
</Service>
</pre>

Ülal defineerime põhiliselt selle, et Tomcat kuulaks domeeni ''www.minukodukas.ee'' ja kasutaks HTTP päringute jaoks porti 80. Ühtlasti otsib Tomcat juurutatavat rakendust failist $CATALINA_BASE/webapps/kodukas.war. Kuna rajalisandiks on määratud tühi sõne (path=""), siis juurutataksegi aplikatsioon aadressile ''www.minukodukas.ee'' ilma rajalisandita (a'la ''www.minukodukas.ee/wiki''). Seetõttu pakitakse ka veebiarhiiv tegelikult lahti kataloogi $CATALINA_BASE/webapps/ROOT mitte kataloogi $CATALINA_BASE/webapps/kodukas nagu võiks eeldada.

===Käigultvahetus===

Võimaldamaks käigultvahetust (hot deployment) peab konteineri konfiguratsioonifailis $CATALINA_BASE/conf/server.xml olema peremehepõhise märgendi "Host" atribuudi "autoDeploy" väärtus "true". Sel juhul installeerib ja uuendab Tomcat aplikatsioone dünaamiliselt töötamise ajal. Kui väärtuseks on "false", käib installeerimine staatiliselt ning serverisse juurutamiseks tuleb teha konteineri taaskäivitus. Käigultvahetust saab määrata ka peremehe defineerimisel "Host Manager" rakendusega, mis on kättesaadav aadressil http://localhost:8080/host-manager/html . Kasutamiseks tuleb lisada oma kasutajale rolli "admin-gui" (vt. alajaotus ""Tomcat Manager" ligipääsu konfigureerimine"). Antud rakenduse veebiliides on kujutatud joonisel 4.

[[File:tomcat_host_manager_app.png|500px|thumb|Pilt 4: Tomcati haldusrakendus "Host Manage"]]

Käigultvahetust päästikuks on vaikimisi uuendatud veebiarhiivifaili või lahtipakitud veebirakenduse paigutamine "webapps" kataloogi. Käigultvahetuse päästikutele võib failis $CATALINA_BASE/conf/server.xml ka ise lisada kuulatavaid ressursse nagu web.xml muutmine või mõne teegifaili vahetamine (märgendis "Host").

===Klassiteekide väljatõstmine veebiarhiivifailist===

Kõik konteksti poolt kasutatavad Java klassiteegid võib pakendada veebiarhiivi sisse kataloogi "lib", kuid nii võib osutuda veebiarhiivi üleslaadimine ajakulukaks, eriti arenduskeskkonnas. Kui ei teki ohtu, et erinevad rakendused kasutavad sama teegi erinevaid versioone, siis on vahel parem lisada osa teeke konteineri kataloogi $CATALINA_BASE/libs, kust need tehakse siis konteineri poolt kättesaadavaks kõigile konteineris jooksutatavatele kontekstidele. Nii võib vähendada veebiarhiivi faili suurust märgatavalt, mis tõstab kokkuvõttes juurutamiskiirust ja ühes sellega programmeerijate tööviljakust.

===Mälukasutus===

Konteineri poolt kasutatavat mälu saab vaadata haldusrakendusest vajutades lingile "Server Status". Mälukasutus on toodud jaotuses "JVM", kus näidatakse nii maksimaalselt kättesaadavat mälu kui ka parasjagu reserveeritud mälu.

<pre>Free memory: 41.16 MB Total memory: 123.37 MB Max memory: 1027.56 MB</pre>

Mälu suurendamiseks võib näiteks defineerida skriptis $CATALINA_BASE/bin/catalina.sh muutuja "JAVA_OPTS" ning määrata Java mälukasutuse miinimum- ja maksimumväärtused sarnaselt järgnevatega [http://www.mkyong.com/tomcat/tomcat-javalangoutofmemoryerror-permgen-space/ 3]:
<pre>
JAVA_OPTS="-Xms1536m -Xmx1536m -XX:NewSize=256m -XX:MaxNewSize=256m -XX:PermSize=256m -XX:MaxPermSize=256m"
</pre>

===Logifailid===

Vaikimisi defineerib Tomcat failiga $CATALINA_BASE/conf/logging.properties viis logerit, mis tekitavad viis eraldi logifaili.

{| style="background:#cccc99;color:black;width:80%;" border="1" cellpadding="5" cellspacing="0" align="center"
|+ Tomcati tekitatavad logifailid "logs" kataloogis
!Fail !! Kasutus
|- style="background:white; color:black"
| style="width:300px" |catalina.out
| Tomcati käivitus- ja peatamisskriptide väljund, samuti juurutatud rakenduste prindilaused System.out ja veaväljundid System.err
|- style="background:white; color:black"
| style="width:300px" |catalina.[yyyy]-[mm]-[dd].log
| Pööratud (rotated) logifail catalina.out
|- style="background:white; color:black"
| style="width:300px" |host-manager.[yyyy]-[mm]-[dd].log
| Logi peremehehalduse rakendusele (rakendus on kättesaadav kohalikust masinast aadressil http://localhost:8080/host-manager/html )
|- style="background:white; color:black"
| style="width:300px" |localhost.[yyyy]-[mm]-[dd].log
| Peremehe "localhost" logi; mitme virtuaalse peremehe korral tekitatakse igale peremehele oma logi
|- style="background:white; color:black"
| style="width:300px" |localhost_access_log.[yyyy]-[mm]-[dd].txt
| Konteinerisse Internetist saabunud päringute logi
|- style="background:white; color:black"
| style="width:300px" |manager.[yyyy]-[mm]-[dd].log
| Haldusrakenduse tegevuste logi
|}

= Kokkuvõte =

Antud juhend aitab Unix-keskkonnas (ja operatsioonisüsteemi administreerimise algteadmiste olemasolul) Tomcati installeerida, käivitada ja juurutada Tomcatile ka Java näite veebiaplikatsioon. Lisaks on ära toodud ka mõned esmased näpunäited Tomcati kasutamiseks reaalse veebiserverina. Loodetavasti aitab juhend lugeja esmasel kokkupuutel Tomcatiga tekkivatest probleemidest jagu saada ja süveneda iseseisvalt veebiserveri Tomcat põhjalikumasse uurimisse.

= Autori märkused =

Tööl pole ma kahjuks Tomcati reaalselt kasutada saanud. Kuigi olen tegelenud Java ärirakendustega, on IT-juhtimise poolel seni otsustatud JBoss või Jetty kasuks. Siiski olen oma huviprojekte arendades või Java veebirakenduste tegemist õppides valinud just Tomcati. Seda eelkõige hea integreerituse tõttu IDE-dega. Tomcat töötab näiteks kohe koos NetBeansi installeerimisega, samuti pole kuigi keeruline tööle panna koos Java EE versiooniga Eclipse-ist. Tean ka vähemalt üht Eesti ettevõttet, mis kasutabki Tomcati reaalseks äriteenuste pakkumiseks.

Seni on tundunud Tomcati kasutus läbi IDE mugav, kuid probleemide tekkimisel olen hätta jäänud. Kuna tegemist on siiski Java ärirakendusi toetava veebikonteineriga, mis pakub muu hulgas JNDI-nimeteenust ja andmebaasiühenduste haldamist, siis pole selle ülesehitus sugugi lihtne. Siiski aitab algtõdede teadmine ka lihtsamini lahendada tekkivaid probleeme läbi IDE kasutades.

=Viiteid=

Palju vajalikku võib leida [http://tomcat.apache.org/tomcat-8.0-doc/index.html Tomcat 8 dokumentatsioonist]

Lisaks üks viide põhjalikule Tomcati versioon seitsme ülevaatele: http://www.ntu.edu.sg/home/ehchua/programming/howto/Tomcat_More.html

= Kasutatud materjalid =

#http://tomcat.apache.org/tomcat-8.0-doc/index.html
#http://www.mulesoft.com/tomcat-deploy-procedures
#http://www.mkyong.com/tomcat/tomcat-javalangoutofmemoryerror-permgen-space/

[[Category: Operatsioonisüsteemide administreerimine ja sidumine]]

Tomcat

2014-01-02T22:44:17Z

Kveskima: /* Autori märkused */

==Autor==

Kristjan Veskimäe D32

2013

==Sissejuhatus==

Tomcat on vabalt kättesaadav server Java veebirakendustele. Põhimõtteliselt on tegemist Servlet/JSP spetsifikatsiooni toetava konteineriga. Kiire käivitumise ning rakenduste käigultvahetuse tõttu on Tomcat hea valik väiksemate ning keskmise suurusega Java veebirakenduste käitamiseks.

Antud töö kirjeldab Tomcati 8. versiooni. Põhiosa on üldiselt samasugune võrreldes paari eelmise versiooniga. Suuremad erinevused on versioonispetsiifilistes probleemides ja nende lahendamises, mida käesolev töö ei vaatle.

Töö vaatleb Tomcati paigaldamist ja seadistamist Unix-laadsesse keskkonda ning eeldab lugejalt algteadmisi sarnastes süsteemides. Tomcati on võimalik paigaldada ka Windows-keskkonda, kuid antud veebiserver eeldab kasutaja poolt käsureal töötamist ning Tomcati failihierarhias orienteerumist. Põhimõtteliselt on Java veebirakenduste arendamiseks IDE-abil võimalik siiski ka kasutada IDE-sse integreeritud Tomcati serverit - näiteks pakuvad sellist võimalust Eclipse EE ja NetBeans - kuid seda käesolev töö ei vaatle.

==Mõisted==

* '''Kontekst''' (context) - Tomcati mõistes üks konkreetne veebiaplikatsioon
* '''Konteiner''' (container) - veebiserver Tomcat ise
* '''Kontekstikirjeldus''' (context descriptor) - Tomcati-spetsiifiline konteksti konfiguratsioonimääratlus; peremehepõhine osa loetakse failist $CATALINA_HOME/conf/[enginename]/[hostname]/context.xml ja sellele lisatakse kontekstispetsiifilised täpsustused failist $CATALINA_BASE/conf/[enginename]/[hostname]/[webappname].xml; kontekstikirjeldus määrab näiteks nimed ressurssidele, sessioonihalduse parameetrid jmt. (olgu märgitud, et Tomcati varasemates versioonides sisaldusid kontekstikirjeldused põhikonfiguratsioonifailis server.xml)
* '''Dokumendipõhi''' (docBase) - kontekstile vastav kataloog Tomcati "webapps" kataloogis, mis tekib veebiaplikatsiooni serverisse rakendamisel
* '''Veebiarhiiv''' (Web application ARchive, war-file) - Java veebiaplikatsiooni jagatakse hea tava kohaselt selle üheainsa veebiarhiivi failina, mille laienditüübiks on "war". Tegemist on zip-protokolliga kokkupakitud kataloogiga, millel on Java veebirakenduste spetsifikatsioonile vastav ülesehitus. Siiski võib veebiaplikatsioon olla juurutamisel ka lahtipakendatud olekus (inglisekeelne termin on "war is exploded").

==Ülesehitus==

{| class="wikitable"
|+Kataloogid
|-
|style="color: green;" | $CATALINA_HOME
|baaskataloog, kuhu on Tomcat paigutatud
|-
|style="color: green;" | $CATALINA_BASE
|parasjagu töösoleva Tomcati eksemplari baaskataloog, mille alusel lahendatakse teed ülejäänud kataloogide ja failideni; ainult ühe kasutusel oleva Tomcati eksemplari puhul on see sama, mis $CATALINA_HOME

|-
|style="color: green;" | $CATALINA_BASE/bin
|serveri käivitus- ja abiskriptid
|-
|style="color: green;" | $CATALINA_BASE/conf
|konfiguratsioonifailid
|-
|style="color: green;" | $CATALINA_BASE/lib
|Tomcatile vaikimisi kättesaadavad Java klassiteegid (class libraries) ehk .jar-failid kuhu on Java kompileeritud kood kokku pakendatud
|-
|style="color: green;" | $CATALINA_BASE/logs
|logifailid paigutatakse vaikimisi siia
|-
|style="color: green;" | $CATALINA_BASE/webapps
|kataloog, kuhu paigutatakse serverisse juurutatavad veebiaplikatsioonid

|}

{| class="wikitable"
|+Mõned olulisemad failid
|-
|style="color: green;" | $CATALINA_BASE/bin/startup.sh
|serveri käivitusskript
|-
|style="color: green;" | $CATALINA_BASE/bin/shutdown.sh
|serveri peatusskript

|-
|style="color: green;" | $CATALINA_BASE/conf/server.xml
| konteineri peamine konfiguratsioonifail
|-
|style="color: green;" | $CATALINA_BASE/conf/[enginename]/[hostname]/[webappname].xml
|serveri administraatori jaoks konteinerisse endasse ümber kopeeritud rakendusepõhine kontekstikirjelduse konfiguratsioon failist $CATALINA_BASE/webapps/[ApplicationName]/META-INF/context.xml
|-
|style="color: green;" | $CATALINA_BASE/conf/[enginename]/[hostname]/context.xml
| fail, mis aitab administraatoril konteksti kohta käivat infot kirjeldada peremeesmasina-põhiselt ja halduseks mõeldud automaat-tööriistadel (näiteks Tomcat Manager ja TCD) oma tööd teha
|-
|style="color: green;" | $CATALINA_BASE/$CATALINA_BASE/conf/[enginename]/[hostname]/manager.xml
|fail, mis võimaldab lisada rakendustele ligipääsufiltreid
|-
|style="color: green;" | $CATALINA_BASE/webapps/[webappname]/META-INF/context.xml
|kontekstikirjeldusfail, mille veebirakenduse programmeerija on pakendanud oma aplikatsiooniga kaasa ning millega ta saab võimaluse kontekstikirjeldust omalt poolt mõjutada; kirjutatakse rakenduse uuestijuurutamisel üle, mistõttu administraator peaks muutma selle asemel konteinerisse ümber kopeeritud püsieksemplari $CATALINA_BASE/conf/[enginename]/[hostname]/context.xml
|-
|style="color: green;" | $CATALINA_BASE/webapps/[webappname]/WEB-INF/web.xml
|ka üks oluline Java veebiaplikatsiooni konfiguratsioonifail, mille pakendatakse koos veebiarhiiviga; enamasti muudab seda ainult programeerija; määrab muu hulgas millised aplikatsiooni osad vajavad autentimist või kui kiiresti veebisessioon aegub
|}

==Installeerimine==

===Installeerimine paketihalduriga===

<pre>
apt-cache search tomcat
apt-get install tomcat[version]-webapps
apt-get install tomcat[version]-admin
apt-get install tomcat[version]
</pre>

===Installeerimine käsitsi===

Paketihalduriga installeerides ei pruugi viimane Tomcati versioon olla kättesaadav ja see pakub ka vähem võimalusi kataloogide määramiseks jms. Käsitsi installeerimiseks tuleb laadida Tomcat kodulehelt alla. Lahtipakkimisel tekib kataloog, milles sisalduv fail "RUNNING.txt" on kõige kindlam allikas installeerimisel tekkivate probleemide vältimiseks ning lahendamiseks.

Vajaliku versiooni installeerimisfaili asukoha saab vaadata Tomcati kodulehelt sektsioonist "Download". Järgnevas näites installeerime Tomcati kõige uuema ebastabiilse kandidaatversiooni, mida näitab nimes sisalduv RC ehk "release candidate". Produktsioonikeskkonda tuleks siiski valida stabiilse versiooni. Käsitsi installeerimine on sarnane järgmisega:
<pre>
wget http://mirror.nexcess.net/apache/tomcat/tomcat-8/v8.0.0-RC5/bin/apache-tomcat-8.0.0-RC5.tar.gz
tar -zxvf apache-tomcat-8.0.0-RC5.tar.gz
mv /Users/kristjanveskimae/downloads/apache-tomcat-8.0.0-RC5 /usr/local/apache-tomcat-8.0.0-RC5
rm -f /Library/Tomcat
ln -s /usr/local/apache-tomcat-8.0.0-RC5/ /Library/Tomcat
chown -R kristjanveskimae /Library/Tomcat
chmod +x /Library/Tomcat/bin/*.sh
</pre>

==Käivitamine ja aplikatsiooni juurutamine==

===Konteineri käivitamine===

Tomcati käivitamise eelduseks on Java paigaldamine masinasse ning keskkonnamuutujate "JAVA_HOME" ja "JRE_HOME" defineerimine. Peale installeerimist võib kasutada skripte kataloogist $CATALINA_BASE/bin . Järgneb üks võimalik käivitamise ja peatamise näide, mis on kasutatav eelnevalt kirjeldatud käsitsi installeerimise juhul:
<pre>
/Library/Tomcat/bin/startup.sh
</pre>
ja peatamiseks
<pre>
/Library/Tomcat/bin/shutdown.sh
</pre>

===Näiteaplikatsiooni juurutamine===

Java veebiaplikatsiooni jagatakse hea tava kohaselt üheainsa veebiarhiivi failina. Siiski võib Tomcati juurutada ka lahtipakendatud olekus ("exploded") Java veebiaplikatsiooni.

====Käsitsi juurutamine ja mahavõtmine====

Näiteaplikatsiooni juurutamiseks lae selle veebiarhiivifail alla ning kopeeri oma konteineri juurutamiskataloogi 'webapps':
<pre>wget http://tomcat.apache.org/tomcat-8.0-doc/appdev/sample/sample.war
cp /Users/kristjanveskimae/downloads/sample.war /Library/Tomcat/webapps/sample.war</pre>

[[File:tomcat_sample_application.png|400px|thumb|right|Pilt 1: Õnnestunult rakendatud näiteaplikatsioon]]

Kui konfiguratsioonifailis $CATALINA_BASE/conf/server.xml on märgendi "Host" atribuudi "autoDeploy" väärtus "true", installeerib ja uuendab Tomcat aplikatsioone dünaamiliselt töötamise ajal. Kui väärtuseks on "false", käib installeerimine staatiliselt ning serverisse juurutamiseks tuleb teha konteineri taaskäivitus. [http://tomcat.apache.org/tomcat-8.0-doc/manager-howto.html#Deploy_A_New_Application_from_a_Local_Path 1] Mõlemal juhul pakib konteiner arhiveeritud faili ise lahti samasse kausta $CATALINA_BASE/webapps ning ka juurutab selle. Tekkiv aplikatsioon on lokaalsest masinast seejärel kättesaadav aadressil http://localhost:8080/sample/ . Kui rakendamine õnnestub, siis peaks olema brauserist nähtav sarnane lehekülg nagu pildil 1.

Veebirakenduse käsitsi mahavõtmiseks tuleb kustutada talle vastav dokumendipõhja kataloog "webapps" kataloogist. Samuti tuleks kustutada .war-fail olemaks kindel, et Tomcat ei rakenda uuel käivitamisel veebiaplikatsiooni veebiarhiivifailist. Veelgi lihtsam on mahavõtmine brauseriga haldusrakenduse kaudu.

Rakenduste baaskataloogi "webapps" asukohta saab muuta failis $CATALINA_BASE/conf/server.xml peremehepõhiselt määratava atribuudiga "appBase", sealjuures Tomcati vaikimisi peremees ehk "Host" on "localhost".

====Tomcati vahendid juurutamiseks====

Veebiaplikatsioonide juurutamine ja mahajuurutamine on võimalik ka kaughalduse teel tänu Tomcati internetipõhisele haldusrakendusele. Näiteks saab veebibrauserit kasutades teha serveri põhitoiminguid Tomcati enda HTML-põhise rakendusega "Tomcat Manager". Veebipõhine haldusrakendus töötab ka käsupõhise veebiteenusena, millele on valmis ehitatud Anti ja Maveni integratsioonid. Samuti eksisteerib käsurea kliendirakendus TCD (Tomcat Client Deployer). TCD ei kuulu Tomcati baaskoosseisu, kuid pakub peale serveri administreerimise tavatoimingute ka lisafunktsionaalsust nagu veebirakenduse kokkukompileerimine ja pakendamine. [http://tomcat.apache.org/tomcat-8.0-doc/manager-howto.html#Configuring_Manager_Application_Access 1]

====Haldurakendus "Tomcat Manager"====

Tomcati haldusrakendus "Tomcat Manager" (antud alamjaotuses lihtsalt haldusrakendus) on Tomcati enda veebiaplikatioon Tomcati brauseripõhiseks kaughalduseks, võimaldades muu hulgas järgnevat [http://tomcat.apache.org/tomcat-8.0-doc/manager-howto.html#Introduction 1]:
* Rakendada uue veebiaplikatsiooni war-faili üleslaadimisega;
* Näha kõiki rakendatud veebiaplikatsioone koos aktiivsete sessioonidega;
* Taasrakendada veebirakendust, näiteks veebiarhiivi pakitud klassifailide /WEB-INF/classes või teekide /WEB-INF/lib uuendamisel, kinnijooksmisel jms.;
* Peatada veebirakendust ilma serverist eemaldamata, samuti koos serverist eemaldamisega;
* Vaadata operatsioonisüsteemi ja Java parameetrite väärtusi;
* Näha kõiki saadaolevaid JNDI ressursse, k.a. andmebaasiühendusi, mis aitavad rakenduste programmeerijail defineerida <ResourceLink> elemendid web.xml konfiguratsioonifailis.

Tomcati installatsioon sisaldab haldusrakendust juba vaikimisi. Haldusrakenduse töölepanemiseks tuleb peremeesmasina konfiguratsioonikataloogi $CATALINA_BASE/conf/[enginename]/[hostname] lisada ka fail manager.xml. Vaikimisi valmiskonfigureeritud testrakendusel on see fail juba olemas asukohas $CATALINA_BASE/conf/Catalina/localhost/manager.xml . Rakendus asub vaikimisi aadressil http://[host]/manager/ , vaikimisi konfiguratsioone kasutades lahendub see asukohaks http://localhost:8080/manager/ . [http://tomcat.apache.org/tomcat-8.0-doc/manager-howto.html#Configuring_Manager_Application_Access 1]

====="Tomcat Manager" ligipääsu konfigureerimine=====

Vaikimisi on turvalisuspõhjustel ligipääs haldusrakendusele maha keeratud. Mismoodi täpselt kasutajatel ligipääsu võimaldada sõltub kasutatavast valdusest (realm). Vaikimisi defineerib $CATALINA_BASE/conf/server.xml valduseks "MemoryRealm". Vaikimisi loeb valdus "MemoryRealm" kasutajad failist $CATALINA_BASE/conf/tomcat-users.xml. Antud failis tuleb iga kasutaja defineerida omaette märgendiga <user>, mis näeb välja umbes järgmine [http://tomcat.apache.org/tomcat-8.0-doc/manager-howto.html#Configuring_Manager_Application_Access 1]:
<pre>
<user name="craig" password="secret" roles="manager-gui,manager-script" />
</pre>

Antud kasutajale on defineeritud korraga kaks rolli. Ligipääsu võimaldamiseks tulebki lihtsamal juhul kasutajatefailis $CATALINA_BASE/conf/tomcat-users.xml defineerida enda kasutaja. Kasutaja rolliks võib määrata näiteks "manager-gui", mis võimaldab ligipääsu kogu HTML liidese funktsionaalsusele.

Teised valdused on "JDBCRealm", mille puhul hoitakse kasutajatega seonduvat infot andmebaasis ja JNDIRealm, mille puhul kasutatakse lihtsustatud kataloogisirvimise protokolli (LDAP).
Lisaks saab haldusrakendusele keelata ligipääsu mujalt kui kindlaksmääratud IP-aadressidelt, lisades filtri "RemoteAddrValve" või "RemoteHostValve" konfigureerimisfaili manager.xml näiteks järgmiselt [http://tomcat.apache.org/tomcat-8.0-doc/manager-howto.html#Introduction 1]:
<pre>
<Context privileged="true">
<Valve className="org.apache.catalina.valves.RemoteAddrValve"
allow="127\.0\.0\.1"/>
</Context>
</pre>

=====Juurutamine ja mahavõtmine haldusrakendusega "Tomcat Manager"=====

Juurutamiseks lae kõigepealt veebiarhiivifail üles, kasutades esilehel asuvat sektsiooni "WAR file to deploy". Veebiarhiivi üleslaadimise liides on kujutatud plidil 2.

[[File:tomcat_manager_war_upload.png|600px|thumb|right|Pilt 2: Veebiarhiivi üleslaadimise nupp]]

Rakendus kuvatakse seejärel hallatavate rakenduste nimekirjas. Kui konteiner pole seadistatud üleslaetud aplikatsiooni kohe ka ise rakendama, tuleb vajutada "Start". Rakenduse peatamiseks kasuta "Stop", uuesti rakendamiseks "Redeploy" ja serverist eemaldamiseks "Undeploy". Nupud on näha ka pildil 3 olevas rakenduste nimekirjas.


[[File:tomcat_manager_apps_list.png|1000px|thumb|Pilt 3: Rakenduste nimekiri Tomcati haldusrakenduses "Tomcat Manager"]]

==Näpunäiteid Tomcati reaalseks kasutamiseks==

===Juurutamise järjekord===

Tomcati käivitumisel juurutatakse aplikatsioonid sellises järjekorras [http://www.mulesoft.com/tomcat-deploy-procedures 2]:
# Konteinerisse kopeeritud kontekstikirjelduste järgi $CATALINA_BASE/conf/[EngineName]/[HostName]/[ApplicationName].xml ;
# Lahtipakitud rakendused "webapps" kataloogis;
# Pakitud rakenduste veebiarhiivid "webapps" kataloogis.

Seetõttu peaks käsitsi taasjuurutamisel kindluse mõttes eelnevalt kustutama rakenduse lahtipakitud dokumendipõhja kataloogi "webapps" kataloogist. Kontekstikirjelduse muutumisel tuleb jälgida, kas kirjeldus on juba kopeeritud serverisse ning vajadusel eelmise versiooni ümber muuta või kustutada.

===Reaalsele domeenile konfigureerimine===

Järgnevalt eeldame, et domeen ''www.minukodukas.ee'' on juba serverimasinaga seostatud. Et Tomcat hakkaks ka reaalselt Internetist tulevatele päringutele vastama, tuleb muuta failis $CATALINA_BASE/conf/server.xml konteinerile ''Catalina'' vastava teenusemärgendi sisu sarnaselt järgnevaga:

<pre>
<Service name="Catalina">
<Connector port="80" protocol="HTTP/1.1" connectionTimeout="20000" URIEncoding="UTF-8" redirectPort="8443" />
<Engine name="Catalina" defaultHost="www.minukodukas.ee">
<Host name="www.minukodukas.ee" appBase="webapps" unpackWARs="true" autoDeploy="false" deployOnStartup="false" xmlValidation="false" xmlNamespaceAware="false">
<Context path="" docBase="kodukas" debug="0" reloadable="true" />
</Host>
</Engine>
</Service>
</pre>

Ülal defineerime põhiliselt selle, et Tomcat kuulaks domeeni ''www.minukodukas.ee'' ja kasutaks HTTP päringute jaoks porti 80. Ühtlasti otsib Tomcat juurutatavat rakendust failist $CATALINA_BASE/webapps/kodukas.war. Kuna rajalisandiks on määratud tühi sõne (path=""), siis juurutataksegi aplikatsioon aadressile ''www.minukodukas.ee'' ilma rajalisandita (a'la ''www.minukodukas.ee/wiki''). Seetõttu pakitakse ka veebiarhiiv tegelikult lahti kataloogi $CATALINA_BASE/webapps/ROOT mitte kataloogi $CATALINA_BASE/webapps/kodukas nagu võiks eeldada.

===Käigultvahetus===

Võimaldamaks käigultvahetust (hot deployment) peab konteineri konfiguratsioonifailis $CATALINA_BASE/conf/server.xml olema peremehepõhise märgendi "Host" atribuudi "autoDeploy" väärtus "true". Sel juhul installeerib ja uuendab Tomcat aplikatsioone dünaamiliselt töötamise ajal. Kui väärtuseks on "false", käib installeerimine staatiliselt ning serverisse juurutamiseks tuleb teha konteineri taaskäivitus. Käigultvahetust saab määrata ka peremehe defineerimisel "Host Manager" rakendusega, mis on kättesaadav aadressil http://localhost:8080/host-manager/html . Kasutamiseks tuleb lisada oma kasutajale rolli "admin-gui" (vt. alajaotus ""Tomcat Manager" ligipääsu konfigureerimine"). Antud rakenduse veebiliides on kujutatud joonisel 4.

[[File:tomcat_host_manager_app.png|500px|thumb|Pilt 4: Tomcati haldusrakendus "Host Manage"]]

Käigultvahetust päästikuks on vaikimisi uuendatud veebiarhiivifaili või lahtipakitud veebirakenduse paigutamine "webapps" kataloogi. Käigultvahetuse päästikutele võib failis $CATALINA_BASE/conf/server.xml ka ise lisada kuulatavaid ressursse nagu web.xml muutmine või mõne teegifaili vahetamine (märgendis "Host").

===Klassiteekide väljatõstmine veebiarhiivifailist===

Kõik konteksti poolt kasutatavad Java klassiteegid võib pakendada veebiarhiivi sisse kataloogi "lib", kuid nii võib osutuda veebiarhiivi üleslaadimine ajakulukaks, eriti arenduskeskkonnas. Kui ei teki ohtu, et erinevad rakendused kasutavad sama teegi erinevaid versioone, siis on vahel parem lisada osa teeke konteineri kataloogi $CATALINA_BASE/libs, kust need tehakse siis konteineri poolt kättesaadavaks kõigile konteineris jooksutatavatele kontekstidele. Nii võib vähendada veebiarhiivi faili suurust märgatavalt, mis tõstab kokkuvõttes juurutamiskiirust ja ühes sellega programmeerijate tööviljakust.

===Mälukasutus===

Konteineri poolt kasutatavat mälu saab vaadata haldusrakendusest vajutades lingile "Server Status". Mälukasutus on toodud jaotuses "JVM", kus näidatakse nii maksimaalselt kättesaadavat mälu kui ka parasjagu reserveeritud mälu.

<pre>Free memory: 41.16 MB Total memory: 123.37 MB Max memory: 1027.56 MB</pre>

Mälu suurendamiseks võib näiteks defineerida skriptis $CATALINA_BASE/bin/catalina.sh muutuja "JAVA_OPTS" ning määrata Java mälukasutuse miinimum- ja maksimumväärtused sarnaselt järgnevatega [http://www.mkyong.com/tomcat/tomcat-javalangoutofmemoryerror-permgen-space/ 3]:
<pre>
JAVA_OPTS="-Xms1536m -Xmx1536m -XX:NewSize=256m -XX:MaxNewSize=256m -XX:PermSize=256m -XX:MaxPermSize=256m"
</pre>

===Logifailid===

Vaikimisi defineerib Tomcat failiga $CATALINA_BASE/conf/logging.properties viis logerit, mis tekitavad viis eraldi logifaili.

{| style="background:#cccc99;color:black;width:80%;" border="1" cellpadding="5" cellspacing="0" align="center"
|+ Tomcati tekitatavad logifailid "logs" kataloogis
!Fail !! Kasutus
|- style="background:white; color:black"
| style="width:300px" |catalina.out
| Tomcati käivitus- ja peatamisskriptide väljund, samuti juurutatud rakenduste prindilaused System.out ja veaväljundid System.err
|- style="background:white; color:black"
| style="width:300px" |catalina.[yyyy]-[mm]-[dd].log
| Pööratud (rotated) logifail catalina.out
|- style="background:white; color:black"
| style="width:300px" |host-manager.[yyyy]-[mm]-[dd].log
| Logi peremehehalduse rakendusele (rakendus on kättesaadav kohalikust masinast aadressil http://localhost:8080/host-manager/html )
|- style="background:white; color:black"
| style="width:300px" |localhost.[yyyy]-[mm]-[dd].log
| Peremehe "localhost" logi; mitme virtuaalse peremehe korral tekitatakse igale peremehele oma logi
|- style="background:white; color:black"
| style="width:300px" |localhost_access_log.[yyyy]-[mm]-[dd].txt
| Konteinerisse Internetist saabunud päringute logi
|- style="background:white; color:black"
| style="width:300px" |manager.[yyyy]-[mm]-[dd].log
| Haldusrakenduse tegevuste logi
|}

= Kokkuvõte =

Antud juhend aitab Unix-keskkonnas (ja operatsioonisüsteemi administreerimise algteadmiste olemasolul) Tomcati installeerida, käivitada ja juurutada Tomcatile ka Java näite veebiaplikatsioon. Lisaks on ära toodud ka mõned esmased näpunäited Tomcati kasutamiseks reaalse veebiserverina. Loodetavasti aitab juhend lugeja esmasel kokkupuutel Tomcatiga tekkivatest probleemidest jagu saada ja süveneda iseseisvalt veebiserveri Tomcat põhjalikumasse uurimisse.

= Autori märkused =

Tööl pole ma kahjuks Tomcati reaalselt kasutada saanud. Kuigi olen tegelenud Java ärirakendustega, on IT-juhtimise poolel seni otsustatud JBoss või Jetty kasuks. Siiski olen oma huviprojekte arendades või Java veebirakenduste tegemist õppides valinud just Tomcati. Seda eelkõige hea integreerituse tõttu IDE-dega. Tomcat töötab näiteks kohe koos NetBeansi installeerimisega, samuti pole kuigi keeruline tööle panna koos Java EE versiooniga Eclipse-ist. Tean ka vähemalt üht Eesti ettevõttet, mis kasutabki Tomcati reaalseks äriteenuste pakkumiseks.

Seni on tundunud Tomcati kasutus läbi IDE mugav, kuid probleemide tekkimisel olen hätta jäänud. Kuna tegemist on siiski Java ärirakendusi toetava veebikonteineriga, mis pakub muu hulgas JNDI-nimeteenust ja andmebaasiühenduste haldamist, siis pole selle ülesehitus sugugi lihtne. Siiski aitab algtõdede teadmine ka lihtsamini lahendada tekkivaid probleeme läbi IDE kasutades.

===Viiteid===

Palju vajalikku võib leida [http://tomcat.apache.org/tomcat-8.0-doc/index.html Tomcat 8 dokumentatsioonist]

Lisaks üks viide põhjalikule Tomcati versioon seitsme ülevaatele: http://www.ntu.edu.sg/home/ehchua/programming/howto/Tomcat_More.html

= Kasutatud materjalid =

#http://tomcat.apache.org/tomcat-8.0-doc/index.html
#http://www.mulesoft.com/tomcat-deploy-procedures
#http://www.mkyong.com/tomcat/tomcat-javalangoutofmemoryerror-permgen-space/

[[Category: Operatsioonisüsteemide administreerimine ja sidumine]]

Tomcat

2014-01-02T22:44:05Z

Kveskima: /* Kokkuvõte */

==Autor==

Kristjan Veskimäe D32

2013

==Sissejuhatus==

Tomcat on vabalt kättesaadav server Java veebirakendustele. Põhimõtteliselt on tegemist Servlet/JSP spetsifikatsiooni toetava konteineriga. Kiire käivitumise ning rakenduste käigultvahetuse tõttu on Tomcat hea valik väiksemate ning keskmise suurusega Java veebirakenduste käitamiseks.

Antud töö kirjeldab Tomcati 8. versiooni. Põhiosa on üldiselt samasugune võrreldes paari eelmise versiooniga. Suuremad erinevused on versioonispetsiifilistes probleemides ja nende lahendamises, mida käesolev töö ei vaatle.

Töö vaatleb Tomcati paigaldamist ja seadistamist Unix-laadsesse keskkonda ning eeldab lugejalt algteadmisi sarnastes süsteemides. Tomcati on võimalik paigaldada ka Windows-keskkonda, kuid antud veebiserver eeldab kasutaja poolt käsureal töötamist ning Tomcati failihierarhias orienteerumist. Põhimõtteliselt on Java veebirakenduste arendamiseks IDE-abil võimalik siiski ka kasutada IDE-sse integreeritud Tomcati serverit - näiteks pakuvad sellist võimalust Eclipse EE ja NetBeans - kuid seda käesolev töö ei vaatle.

==Mõisted==

* '''Kontekst''' (context) - Tomcati mõistes üks konkreetne veebiaplikatsioon
* '''Konteiner''' (container) - veebiserver Tomcat ise
* '''Kontekstikirjeldus''' (context descriptor) - Tomcati-spetsiifiline konteksti konfiguratsioonimääratlus; peremehepõhine osa loetakse failist $CATALINA_HOME/conf/[enginename]/[hostname]/context.xml ja sellele lisatakse kontekstispetsiifilised täpsustused failist $CATALINA_BASE/conf/[enginename]/[hostname]/[webappname].xml; kontekstikirjeldus määrab näiteks nimed ressurssidele, sessioonihalduse parameetrid jmt. (olgu märgitud, et Tomcati varasemates versioonides sisaldusid kontekstikirjeldused põhikonfiguratsioonifailis server.xml)
* '''Dokumendipõhi''' (docBase) - kontekstile vastav kataloog Tomcati "webapps" kataloogis, mis tekib veebiaplikatsiooni serverisse rakendamisel
* '''Veebiarhiiv''' (Web application ARchive, war-file) - Java veebiaplikatsiooni jagatakse hea tava kohaselt selle üheainsa veebiarhiivi failina, mille laienditüübiks on "war". Tegemist on zip-protokolliga kokkupakitud kataloogiga, millel on Java veebirakenduste spetsifikatsioonile vastav ülesehitus. Siiski võib veebiaplikatsioon olla juurutamisel ka lahtipakendatud olekus (inglisekeelne termin on "war is exploded").

==Ülesehitus==

{| class="wikitable"
|+Kataloogid
|-
|style="color: green;" | $CATALINA_HOME
|baaskataloog, kuhu on Tomcat paigutatud
|-
|style="color: green;" | $CATALINA_BASE
|parasjagu töösoleva Tomcati eksemplari baaskataloog, mille alusel lahendatakse teed ülejäänud kataloogide ja failideni; ainult ühe kasutusel oleva Tomcati eksemplari puhul on see sama, mis $CATALINA_HOME

|-
|style="color: green;" | $CATALINA_BASE/bin
|serveri käivitus- ja abiskriptid
|-
|style="color: green;" | $CATALINA_BASE/conf
|konfiguratsioonifailid
|-
|style="color: green;" | $CATALINA_BASE/lib
|Tomcatile vaikimisi kättesaadavad Java klassiteegid (class libraries) ehk .jar-failid kuhu on Java kompileeritud kood kokku pakendatud
|-
|style="color: green;" | $CATALINA_BASE/logs
|logifailid paigutatakse vaikimisi siia
|-
|style="color: green;" | $CATALINA_BASE/webapps
|kataloog, kuhu paigutatakse serverisse juurutatavad veebiaplikatsioonid

|}

{| class="wikitable"
|+Mõned olulisemad failid
|-
|style="color: green;" | $CATALINA_BASE/bin/startup.sh
|serveri käivitusskript
|-
|style="color: green;" | $CATALINA_BASE/bin/shutdown.sh
|serveri peatusskript

|-
|style="color: green;" | $CATALINA_BASE/conf/server.xml
| konteineri peamine konfiguratsioonifail
|-
|style="color: green;" | $CATALINA_BASE/conf/[enginename]/[hostname]/[webappname].xml
|serveri administraatori jaoks konteinerisse endasse ümber kopeeritud rakendusepõhine kontekstikirjelduse konfiguratsioon failist $CATALINA_BASE/webapps/[ApplicationName]/META-INF/context.xml
|-
|style="color: green;" | $CATALINA_BASE/conf/[enginename]/[hostname]/context.xml
| fail, mis aitab administraatoril konteksti kohta käivat infot kirjeldada peremeesmasina-põhiselt ja halduseks mõeldud automaat-tööriistadel (näiteks Tomcat Manager ja TCD) oma tööd teha
|-
|style="color: green;" | $CATALINA_BASE/$CATALINA_BASE/conf/[enginename]/[hostname]/manager.xml
|fail, mis võimaldab lisada rakendustele ligipääsufiltreid
|-
|style="color: green;" | $CATALINA_BASE/webapps/[webappname]/META-INF/context.xml
|kontekstikirjeldusfail, mille veebirakenduse programmeerija on pakendanud oma aplikatsiooniga kaasa ning millega ta saab võimaluse kontekstikirjeldust omalt poolt mõjutada; kirjutatakse rakenduse uuestijuurutamisel üle, mistõttu administraator peaks muutma selle asemel konteinerisse ümber kopeeritud püsieksemplari $CATALINA_BASE/conf/[enginename]/[hostname]/context.xml
|-
|style="color: green;" | $CATALINA_BASE/webapps/[webappname]/WEB-INF/web.xml
|ka üks oluline Java veebiaplikatsiooni konfiguratsioonifail, mille pakendatakse koos veebiarhiiviga; enamasti muudab seda ainult programeerija; määrab muu hulgas millised aplikatsiooni osad vajavad autentimist või kui kiiresti veebisessioon aegub
|}

==Installeerimine==

===Installeerimine paketihalduriga===

<pre>
apt-cache search tomcat
apt-get install tomcat[version]-webapps
apt-get install tomcat[version]-admin
apt-get install tomcat[version]
</pre>

===Installeerimine käsitsi===

Paketihalduriga installeerides ei pruugi viimane Tomcati versioon olla kättesaadav ja see pakub ka vähem võimalusi kataloogide määramiseks jms. Käsitsi installeerimiseks tuleb laadida Tomcat kodulehelt alla. Lahtipakkimisel tekib kataloog, milles sisalduv fail "RUNNING.txt" on kõige kindlam allikas installeerimisel tekkivate probleemide vältimiseks ning lahendamiseks.

Vajaliku versiooni installeerimisfaili asukoha saab vaadata Tomcati kodulehelt sektsioonist "Download". Järgnevas näites installeerime Tomcati kõige uuema ebastabiilse kandidaatversiooni, mida näitab nimes sisalduv RC ehk "release candidate". Produktsioonikeskkonda tuleks siiski valida stabiilse versiooni. Käsitsi installeerimine on sarnane järgmisega:
<pre>
wget http://mirror.nexcess.net/apache/tomcat/tomcat-8/v8.0.0-RC5/bin/apache-tomcat-8.0.0-RC5.tar.gz
tar -zxvf apache-tomcat-8.0.0-RC5.tar.gz
mv /Users/kristjanveskimae/downloads/apache-tomcat-8.0.0-RC5 /usr/local/apache-tomcat-8.0.0-RC5
rm -f /Library/Tomcat
ln -s /usr/local/apache-tomcat-8.0.0-RC5/ /Library/Tomcat
chown -R kristjanveskimae /Library/Tomcat
chmod +x /Library/Tomcat/bin/*.sh
</pre>

==Käivitamine ja aplikatsiooni juurutamine==

===Konteineri käivitamine===

Tomcati käivitamise eelduseks on Java paigaldamine masinasse ning keskkonnamuutujate "JAVA_HOME" ja "JRE_HOME" defineerimine. Peale installeerimist võib kasutada skripte kataloogist $CATALINA_BASE/bin . Järgneb üks võimalik käivitamise ja peatamise näide, mis on kasutatav eelnevalt kirjeldatud käsitsi installeerimise juhul:
<pre>
/Library/Tomcat/bin/startup.sh
</pre>
ja peatamiseks
<pre>
/Library/Tomcat/bin/shutdown.sh
</pre>

===Näiteaplikatsiooni juurutamine===

Java veebiaplikatsiooni jagatakse hea tava kohaselt üheainsa veebiarhiivi failina. Siiski võib Tomcati juurutada ka lahtipakendatud olekus ("exploded") Java veebiaplikatsiooni.

====Käsitsi juurutamine ja mahavõtmine====

Näiteaplikatsiooni juurutamiseks lae selle veebiarhiivifail alla ning kopeeri oma konteineri juurutamiskataloogi 'webapps':
<pre>wget http://tomcat.apache.org/tomcat-8.0-doc/appdev/sample/sample.war
cp /Users/kristjanveskimae/downloads/sample.war /Library/Tomcat/webapps/sample.war</pre>

[[File:tomcat_sample_application.png|400px|thumb|right|Pilt 1: Õnnestunult rakendatud näiteaplikatsioon]]

Kui konfiguratsioonifailis $CATALINA_BASE/conf/server.xml on märgendi "Host" atribuudi "autoDeploy" väärtus "true", installeerib ja uuendab Tomcat aplikatsioone dünaamiliselt töötamise ajal. Kui väärtuseks on "false", käib installeerimine staatiliselt ning serverisse juurutamiseks tuleb teha konteineri taaskäivitus. [http://tomcat.apache.org/tomcat-8.0-doc/manager-howto.html#Deploy_A_New_Application_from_a_Local_Path 1] Mõlemal juhul pakib konteiner arhiveeritud faili ise lahti samasse kausta $CATALINA_BASE/webapps ning ka juurutab selle. Tekkiv aplikatsioon on lokaalsest masinast seejärel kättesaadav aadressil http://localhost:8080/sample/ . Kui rakendamine õnnestub, siis peaks olema brauserist nähtav sarnane lehekülg nagu pildil 1.

Veebirakenduse käsitsi mahavõtmiseks tuleb kustutada talle vastav dokumendipõhja kataloog "webapps" kataloogist. Samuti tuleks kustutada .war-fail olemaks kindel, et Tomcat ei rakenda uuel käivitamisel veebiaplikatsiooni veebiarhiivifailist. Veelgi lihtsam on mahavõtmine brauseriga haldusrakenduse kaudu.

Rakenduste baaskataloogi "webapps" asukohta saab muuta failis $CATALINA_BASE/conf/server.xml peremehepõhiselt määratava atribuudiga "appBase", sealjuures Tomcati vaikimisi peremees ehk "Host" on "localhost".

====Tomcati vahendid juurutamiseks====

Veebiaplikatsioonide juurutamine ja mahajuurutamine on võimalik ka kaughalduse teel tänu Tomcati internetipõhisele haldusrakendusele. Näiteks saab veebibrauserit kasutades teha serveri põhitoiminguid Tomcati enda HTML-põhise rakendusega "Tomcat Manager". Veebipõhine haldusrakendus töötab ka käsupõhise veebiteenusena, millele on valmis ehitatud Anti ja Maveni integratsioonid. Samuti eksisteerib käsurea kliendirakendus TCD (Tomcat Client Deployer). TCD ei kuulu Tomcati baaskoosseisu, kuid pakub peale serveri administreerimise tavatoimingute ka lisafunktsionaalsust nagu veebirakenduse kokkukompileerimine ja pakendamine. [http://tomcat.apache.org/tomcat-8.0-doc/manager-howto.html#Configuring_Manager_Application_Access 1]

====Haldurakendus "Tomcat Manager"====

Tomcati haldusrakendus "Tomcat Manager" (antud alamjaotuses lihtsalt haldusrakendus) on Tomcati enda veebiaplikatioon Tomcati brauseripõhiseks kaughalduseks, võimaldades muu hulgas järgnevat [http://tomcat.apache.org/tomcat-8.0-doc/manager-howto.html#Introduction 1]:
* Rakendada uue veebiaplikatsiooni war-faili üleslaadimisega;
* Näha kõiki rakendatud veebiaplikatsioone koos aktiivsete sessioonidega;
* Taasrakendada veebirakendust, näiteks veebiarhiivi pakitud klassifailide /WEB-INF/classes või teekide /WEB-INF/lib uuendamisel, kinnijooksmisel jms.;
* Peatada veebirakendust ilma serverist eemaldamata, samuti koos serverist eemaldamisega;
* Vaadata operatsioonisüsteemi ja Java parameetrite väärtusi;
* Näha kõiki saadaolevaid JNDI ressursse, k.a. andmebaasiühendusi, mis aitavad rakenduste programmeerijail defineerida <ResourceLink> elemendid web.xml konfiguratsioonifailis.

Tomcati installatsioon sisaldab haldusrakendust juba vaikimisi. Haldusrakenduse töölepanemiseks tuleb peremeesmasina konfiguratsioonikataloogi $CATALINA_BASE/conf/[enginename]/[hostname] lisada ka fail manager.xml. Vaikimisi valmiskonfigureeritud testrakendusel on see fail juba olemas asukohas $CATALINA_BASE/conf/Catalina/localhost/manager.xml . Rakendus asub vaikimisi aadressil http://[host]/manager/ , vaikimisi konfiguratsioone kasutades lahendub see asukohaks http://localhost:8080/manager/ . [http://tomcat.apache.org/tomcat-8.0-doc/manager-howto.html#Configuring_Manager_Application_Access 1]

====="Tomcat Manager" ligipääsu konfigureerimine=====

Vaikimisi on turvalisuspõhjustel ligipääs haldusrakendusele maha keeratud. Mismoodi täpselt kasutajatel ligipääsu võimaldada sõltub kasutatavast valdusest (realm). Vaikimisi defineerib $CATALINA_BASE/conf/server.xml valduseks "MemoryRealm". Vaikimisi loeb valdus "MemoryRealm" kasutajad failist $CATALINA_BASE/conf/tomcat-users.xml. Antud failis tuleb iga kasutaja defineerida omaette märgendiga <user>, mis näeb välja umbes järgmine [http://tomcat.apache.org/tomcat-8.0-doc/manager-howto.html#Configuring_Manager_Application_Access 1]:
<pre>
<user name="craig" password="secret" roles="manager-gui,manager-script" />
</pre>

Antud kasutajale on defineeritud korraga kaks rolli. Ligipääsu võimaldamiseks tulebki lihtsamal juhul kasutajatefailis $CATALINA_BASE/conf/tomcat-users.xml defineerida enda kasutaja. Kasutaja rolliks võib määrata näiteks "manager-gui", mis võimaldab ligipääsu kogu HTML liidese funktsionaalsusele.

Teised valdused on "JDBCRealm", mille puhul hoitakse kasutajatega seonduvat infot andmebaasis ja JNDIRealm, mille puhul kasutatakse lihtsustatud kataloogisirvimise protokolli (LDAP).
Lisaks saab haldusrakendusele keelata ligipääsu mujalt kui kindlaksmääratud IP-aadressidelt, lisades filtri "RemoteAddrValve" või "RemoteHostValve" konfigureerimisfaili manager.xml näiteks järgmiselt [http://tomcat.apache.org/tomcat-8.0-doc/manager-howto.html#Introduction 1]:
<pre>
<Context privileged="true">
<Valve className="org.apache.catalina.valves.RemoteAddrValve"
allow="127\.0\.0\.1"/>
</Context>
</pre>

=====Juurutamine ja mahavõtmine haldusrakendusega "Tomcat Manager"=====

Juurutamiseks lae kõigepealt veebiarhiivifail üles, kasutades esilehel asuvat sektsiooni "WAR file to deploy". Veebiarhiivi üleslaadimise liides on kujutatud plidil 2.

[[File:tomcat_manager_war_upload.png|600px|thumb|right|Pilt 2: Veebiarhiivi üleslaadimise nupp]]

Rakendus kuvatakse seejärel hallatavate rakenduste nimekirjas. Kui konteiner pole seadistatud üleslaetud aplikatsiooni kohe ka ise rakendama, tuleb vajutada "Start". Rakenduse peatamiseks kasuta "Stop", uuesti rakendamiseks "Redeploy" ja serverist eemaldamiseks "Undeploy". Nupud on näha ka pildil 3 olevas rakenduste nimekirjas.


[[File:tomcat_manager_apps_list.png|1000px|thumb|Pilt 3: Rakenduste nimekiri Tomcati haldusrakenduses "Tomcat Manager"]]

==Näpunäiteid Tomcati reaalseks kasutamiseks==

===Juurutamise järjekord===

Tomcati käivitumisel juurutatakse aplikatsioonid sellises järjekorras [http://www.mulesoft.com/tomcat-deploy-procedures 2]:
# Konteinerisse kopeeritud kontekstikirjelduste järgi $CATALINA_BASE/conf/[EngineName]/[HostName]/[ApplicationName].xml ;
# Lahtipakitud rakendused "webapps" kataloogis;
# Pakitud rakenduste veebiarhiivid "webapps" kataloogis.

Seetõttu peaks käsitsi taasjuurutamisel kindluse mõttes eelnevalt kustutama rakenduse lahtipakitud dokumendipõhja kataloogi "webapps" kataloogist. Kontekstikirjelduse muutumisel tuleb jälgida, kas kirjeldus on juba kopeeritud serverisse ning vajadusel eelmise versiooni ümber muuta või kustutada.

===Reaalsele domeenile konfigureerimine===

Järgnevalt eeldame, et domeen ''www.minukodukas.ee'' on juba serverimasinaga seostatud. Et Tomcat hakkaks ka reaalselt Internetist tulevatele päringutele vastama, tuleb muuta failis $CATALINA_BASE/conf/server.xml konteinerile ''Catalina'' vastava teenusemärgendi sisu sarnaselt järgnevaga:

<pre>
<Service name="Catalina">
<Connector port="80" protocol="HTTP/1.1" connectionTimeout="20000" URIEncoding="UTF-8" redirectPort="8443" />
<Engine name="Catalina" defaultHost="www.minukodukas.ee">
<Host name="www.minukodukas.ee" appBase="webapps" unpackWARs="true" autoDeploy="false" deployOnStartup="false" xmlValidation="false" xmlNamespaceAware="false">
<Context path="" docBase="kodukas" debug="0" reloadable="true" />
</Host>
</Engine>
</Service>
</pre>

Ülal defineerime põhiliselt selle, et Tomcat kuulaks domeeni ''www.minukodukas.ee'' ja kasutaks HTTP päringute jaoks porti 80. Ühtlasti otsib Tomcat juurutatavat rakendust failist $CATALINA_BASE/webapps/kodukas.war. Kuna rajalisandiks on määratud tühi sõne (path=""), siis juurutataksegi aplikatsioon aadressile ''www.minukodukas.ee'' ilma rajalisandita (a'la ''www.minukodukas.ee/wiki''). Seetõttu pakitakse ka veebiarhiiv tegelikult lahti kataloogi $CATALINA_BASE/webapps/ROOT mitte kataloogi $CATALINA_BASE/webapps/kodukas nagu võiks eeldada.

===Käigultvahetus===

Võimaldamaks käigultvahetust (hot deployment) peab konteineri konfiguratsioonifailis $CATALINA_BASE/conf/server.xml olema peremehepõhise märgendi "Host" atribuudi "autoDeploy" väärtus "true". Sel juhul installeerib ja uuendab Tomcat aplikatsioone dünaamiliselt töötamise ajal. Kui väärtuseks on "false", käib installeerimine staatiliselt ning serverisse juurutamiseks tuleb teha konteineri taaskäivitus. Käigultvahetust saab määrata ka peremehe defineerimisel "Host Manager" rakendusega, mis on kättesaadav aadressil http://localhost:8080/host-manager/html . Kasutamiseks tuleb lisada oma kasutajale rolli "admin-gui" (vt. alajaotus ""Tomcat Manager" ligipääsu konfigureerimine"). Antud rakenduse veebiliides on kujutatud joonisel 4.

[[File:tomcat_host_manager_app.png|500px|thumb|Pilt 4: Tomcati haldusrakendus "Host Manage"]]

Käigultvahetust päästikuks on vaikimisi uuendatud veebiarhiivifaili või lahtipakitud veebirakenduse paigutamine "webapps" kataloogi. Käigultvahetuse päästikutele võib failis $CATALINA_BASE/conf/server.xml ka ise lisada kuulatavaid ressursse nagu web.xml muutmine või mõne teegifaili vahetamine (märgendis "Host").

===Klassiteekide väljatõstmine veebiarhiivifailist===

Kõik konteksti poolt kasutatavad Java klassiteegid võib pakendada veebiarhiivi sisse kataloogi "lib", kuid nii võib osutuda veebiarhiivi üleslaadimine ajakulukaks, eriti arenduskeskkonnas. Kui ei teki ohtu, et erinevad rakendused kasutavad sama teegi erinevaid versioone, siis on vahel parem lisada osa teeke konteineri kataloogi $CATALINA_BASE/libs, kust need tehakse siis konteineri poolt kättesaadavaks kõigile konteineris jooksutatavatele kontekstidele. Nii võib vähendada veebiarhiivi faili suurust märgatavalt, mis tõstab kokkuvõttes juurutamiskiirust ja ühes sellega programmeerijate tööviljakust.

===Mälukasutus===

Konteineri poolt kasutatavat mälu saab vaadata haldusrakendusest vajutades lingile "Server Status". Mälukasutus on toodud jaotuses "JVM", kus näidatakse nii maksimaalselt kättesaadavat mälu kui ka parasjagu reserveeritud mälu.

<pre>Free memory: 41.16 MB Total memory: 123.37 MB Max memory: 1027.56 MB</pre>

Mälu suurendamiseks võib näiteks defineerida skriptis $CATALINA_BASE/bin/catalina.sh muutuja "JAVA_OPTS" ning määrata Java mälukasutuse miinimum- ja maksimumväärtused sarnaselt järgnevatega [http://www.mkyong.com/tomcat/tomcat-javalangoutofmemoryerror-permgen-space/ 3]:
<pre>
JAVA_OPTS="-Xms1536m -Xmx1536m -XX:NewSize=256m -XX:MaxNewSize=256m -XX:PermSize=256m -XX:MaxPermSize=256m"
</pre>

===Logifailid===

Vaikimisi defineerib Tomcat failiga $CATALINA_BASE/conf/logging.properties viis logerit, mis tekitavad viis eraldi logifaili.

{| style="background:#cccc99;color:black;width:80%;" border="1" cellpadding="5" cellspacing="0" align="center"
|+ Tomcati tekitatavad logifailid "logs" kataloogis
!Fail !! Kasutus
|- style="background:white; color:black"
| style="width:300px" |catalina.out
| Tomcati käivitus- ja peatamisskriptide väljund, samuti juurutatud rakenduste prindilaused System.out ja veaväljundid System.err
|- style="background:white; color:black"
| style="width:300px" |catalina.[yyyy]-[mm]-[dd].log
| Pööratud (rotated) logifail catalina.out
|- style="background:white; color:black"
| style="width:300px" |host-manager.[yyyy]-[mm]-[dd].log
| Logi peremehehalduse rakendusele (rakendus on kättesaadav kohalikust masinast aadressil http://localhost:8080/host-manager/html )
|- style="background:white; color:black"
| style="width:300px" |localhost.[yyyy]-[mm]-[dd].log
| Peremehe "localhost" logi; mitme virtuaalse peremehe korral tekitatakse igale peremehele oma logi
|- style="background:white; color:black"
| style="width:300px" |localhost_access_log.[yyyy]-[mm]-[dd].txt
| Konteinerisse Internetist saabunud päringute logi
|- style="background:white; color:black"
| style="width:300px" |manager.[yyyy]-[mm]-[dd].log
| Haldusrakenduse tegevuste logi
|}

= Kokkuvõte =

Antud juhend aitab Unix-keskkonnas (ja operatsioonisüsteemi administreerimise algteadmiste olemasolul) Tomcati installeerida, käivitada ja juurutada Tomcatile ka Java näite veebiaplikatsioon. Lisaks on ära toodud ka mõned esmased näpunäited Tomcati kasutamiseks reaalse veebiserverina. Loodetavasti aitab juhend lugeja esmasel kokkupuutel Tomcatiga tekkivatest probleemidest jagu saada ja süveneda iseseisvalt veebiserveri Tomcat põhjalikumasse uurimisse.

=== Autori märkused ===

Tööl pole ma kahjuks Tomcati reaalselt kasutada saanud. Kuigi olen tegelenud Java ärirakendustega, on IT-juhtimise poolel seni otsustatud JBoss või Jetty kasuks. Siiski olen oma huviprojekte arendades või Java veebirakenduste tegemist õppides valinud just Tomcati. Seda eelkõige hea integreerituse tõttu IDE-dega. Tomcat töötab näiteks kohe koos NetBeansi installeerimisega, samuti pole kuigi keeruline tööle panna koos Java EE versiooniga Eclipse-ist. Tean ka vähemalt üht Eesti ettevõttet, mis kasutabki Tomcati reaalseks äriteenuste pakkumiseks.

Seni on tundunud Tomcati kasutus läbi IDE mugav, kuid probleemide tekkimisel olen hätta jäänud. Kuna tegemist on siiski Java ärirakendusi toetava veebikonteineriga, mis pakub muu hulgas JNDI-nimeteenust ja andmebaasiühenduste haldamist, siis pole selle ülesehitus sugugi lihtne. Siiski aitab algtõdede teadmine ka lihtsamini lahendada tekkivaid probleeme läbi IDE kasutades.

===Viiteid===

Palju vajalikku võib leida [http://tomcat.apache.org/tomcat-8.0-doc/index.html Tomcat 8 dokumentatsioonist]

Lisaks üks viide põhjalikule Tomcati versioon seitsme ülevaatele: http://www.ntu.edu.sg/home/ehchua/programming/howto/Tomcat_More.html

= Kasutatud materjalid =

#http://tomcat.apache.org/tomcat-8.0-doc/index.html
#http://www.mulesoft.com/tomcat-deploy-procedures
#http://www.mkyong.com/tomcat/tomcat-javalangoutofmemoryerror-permgen-space/

[[Category: Operatsioonisüsteemide administreerimine ja sidumine]]

Tomcat

2014-01-02T22:43:27Z

Kveskima:

==Autor==

Kristjan Veskimäe D32

2013

==Sissejuhatus==

Tomcat on vabalt kättesaadav server Java veebirakendustele. Põhimõtteliselt on tegemist Servlet/JSP spetsifikatsiooni toetava konteineriga. Kiire käivitumise ning rakenduste käigultvahetuse tõttu on Tomcat hea valik väiksemate ning keskmise suurusega Java veebirakenduste käitamiseks.

Antud töö kirjeldab Tomcati 8. versiooni. Põhiosa on üldiselt samasugune võrreldes paari eelmise versiooniga. Suuremad erinevused on versioonispetsiifilistes probleemides ja nende lahendamises, mida käesolev töö ei vaatle.

Töö vaatleb Tomcati paigaldamist ja seadistamist Unix-laadsesse keskkonda ning eeldab lugejalt algteadmisi sarnastes süsteemides. Tomcati on võimalik paigaldada ka Windows-keskkonda, kuid antud veebiserver eeldab kasutaja poolt käsureal töötamist ning Tomcati failihierarhias orienteerumist. Põhimõtteliselt on Java veebirakenduste arendamiseks IDE-abil võimalik siiski ka kasutada IDE-sse integreeritud Tomcati serverit - näiteks pakuvad sellist võimalust Eclipse EE ja NetBeans - kuid seda käesolev töö ei vaatle.

==Mõisted==

* '''Kontekst''' (context) - Tomcati mõistes üks konkreetne veebiaplikatsioon
* '''Konteiner''' (container) - veebiserver Tomcat ise
* '''Kontekstikirjeldus''' (context descriptor) - Tomcati-spetsiifiline konteksti konfiguratsioonimääratlus; peremehepõhine osa loetakse failist $CATALINA_HOME/conf/[enginename]/[hostname]/context.xml ja sellele lisatakse kontekstispetsiifilised täpsustused failist $CATALINA_BASE/conf/[enginename]/[hostname]/[webappname].xml; kontekstikirjeldus määrab näiteks nimed ressurssidele, sessioonihalduse parameetrid jmt. (olgu märgitud, et Tomcati varasemates versioonides sisaldusid kontekstikirjeldused põhikonfiguratsioonifailis server.xml)
* '''Dokumendipõhi''' (docBase) - kontekstile vastav kataloog Tomcati "webapps" kataloogis, mis tekib veebiaplikatsiooni serverisse rakendamisel
* '''Veebiarhiiv''' (Web application ARchive, war-file) - Java veebiaplikatsiooni jagatakse hea tava kohaselt selle üheainsa veebiarhiivi failina, mille laienditüübiks on "war". Tegemist on zip-protokolliga kokkupakitud kataloogiga, millel on Java veebirakenduste spetsifikatsioonile vastav ülesehitus. Siiski võib veebiaplikatsioon olla juurutamisel ka lahtipakendatud olekus (inglisekeelne termin on "war is exploded").

==Ülesehitus==

{| class="wikitable"
|+Kataloogid
|-
|style="color: green;" | $CATALINA_HOME
|baaskataloog, kuhu on Tomcat paigutatud
|-
|style="color: green;" | $CATALINA_BASE
|parasjagu töösoleva Tomcati eksemplari baaskataloog, mille alusel lahendatakse teed ülejäänud kataloogide ja failideni; ainult ühe kasutusel oleva Tomcati eksemplari puhul on see sama, mis $CATALINA_HOME

|-
|style="color: green;" | $CATALINA_BASE/bin
|serveri käivitus- ja abiskriptid
|-
|style="color: green;" | $CATALINA_BASE/conf
|konfiguratsioonifailid
|-
|style="color: green;" | $CATALINA_BASE/lib
|Tomcatile vaikimisi kättesaadavad Java klassiteegid (class libraries) ehk .jar-failid kuhu on Java kompileeritud kood kokku pakendatud
|-
|style="color: green;" | $CATALINA_BASE/logs
|logifailid paigutatakse vaikimisi siia
|-
|style="color: green;" | $CATALINA_BASE/webapps
|kataloog, kuhu paigutatakse serverisse juurutatavad veebiaplikatsioonid

|}

{| class="wikitable"
|+Mõned olulisemad failid
|-
|style="color: green;" | $CATALINA_BASE/bin/startup.sh
|serveri käivitusskript
|-
|style="color: green;" | $CATALINA_BASE/bin/shutdown.sh
|serveri peatusskript

|-
|style="color: green;" | $CATALINA_BASE/conf/server.xml
| konteineri peamine konfiguratsioonifail
|-
|style="color: green;" | $CATALINA_BASE/conf/[enginename]/[hostname]/[webappname].xml
|serveri administraatori jaoks konteinerisse endasse ümber kopeeritud rakendusepõhine kontekstikirjelduse konfiguratsioon failist $CATALINA_BASE/webapps/[ApplicationName]/META-INF/context.xml
|-
|style="color: green;" | $CATALINA_BASE/conf/[enginename]/[hostname]/context.xml
| fail, mis aitab administraatoril konteksti kohta käivat infot kirjeldada peremeesmasina-põhiselt ja halduseks mõeldud automaat-tööriistadel (näiteks Tomcat Manager ja TCD) oma tööd teha
|-
|style="color: green;" | $CATALINA_BASE/$CATALINA_BASE/conf/[enginename]/[hostname]/manager.xml
|fail, mis võimaldab lisada rakendustele ligipääsufiltreid
|-
|style="color: green;" | $CATALINA_BASE/webapps/[webappname]/META-INF/context.xml
|kontekstikirjeldusfail, mille veebirakenduse programmeerija on pakendanud oma aplikatsiooniga kaasa ning millega ta saab võimaluse kontekstikirjeldust omalt poolt mõjutada; kirjutatakse rakenduse uuestijuurutamisel üle, mistõttu administraator peaks muutma selle asemel konteinerisse ümber kopeeritud püsieksemplari $CATALINA_BASE/conf/[enginename]/[hostname]/context.xml
|-
|style="color: green;" | $CATALINA_BASE/webapps/[webappname]/WEB-INF/web.xml
|ka üks oluline Java veebiaplikatsiooni konfiguratsioonifail, mille pakendatakse koos veebiarhiiviga; enamasti muudab seda ainult programeerija; määrab muu hulgas millised aplikatsiooni osad vajavad autentimist või kui kiiresti veebisessioon aegub
|}

==Installeerimine==

===Installeerimine paketihalduriga===

<pre>
apt-cache search tomcat
apt-get install tomcat[version]-webapps
apt-get install tomcat[version]-admin
apt-get install tomcat[version]
</pre>

===Installeerimine käsitsi===

Paketihalduriga installeerides ei pruugi viimane Tomcati versioon olla kättesaadav ja see pakub ka vähem võimalusi kataloogide määramiseks jms. Käsitsi installeerimiseks tuleb laadida Tomcat kodulehelt alla. Lahtipakkimisel tekib kataloog, milles sisalduv fail "RUNNING.txt" on kõige kindlam allikas installeerimisel tekkivate probleemide vältimiseks ning lahendamiseks.

Vajaliku versiooni installeerimisfaili asukoha saab vaadata Tomcati kodulehelt sektsioonist "Download". Järgnevas näites installeerime Tomcati kõige uuema ebastabiilse kandidaatversiooni, mida näitab nimes sisalduv RC ehk "release candidate". Produktsioonikeskkonda tuleks siiski valida stabiilse versiooni. Käsitsi installeerimine on sarnane järgmisega:
<pre>
wget http://mirror.nexcess.net/apache/tomcat/tomcat-8/v8.0.0-RC5/bin/apache-tomcat-8.0.0-RC5.tar.gz
tar -zxvf apache-tomcat-8.0.0-RC5.tar.gz
mv /Users/kristjanveskimae/downloads/apache-tomcat-8.0.0-RC5 /usr/local/apache-tomcat-8.0.0-RC5
rm -f /Library/Tomcat
ln -s /usr/local/apache-tomcat-8.0.0-RC5/ /Library/Tomcat
chown -R kristjanveskimae /Library/Tomcat
chmod +x /Library/Tomcat/bin/*.sh
</pre>

==Käivitamine ja aplikatsiooni juurutamine==

===Konteineri käivitamine===

Tomcati käivitamise eelduseks on Java paigaldamine masinasse ning keskkonnamuutujate "JAVA_HOME" ja "JRE_HOME" defineerimine. Peale installeerimist võib kasutada skripte kataloogist $CATALINA_BASE/bin . Järgneb üks võimalik käivitamise ja peatamise näide, mis on kasutatav eelnevalt kirjeldatud käsitsi installeerimise juhul:
<pre>
/Library/Tomcat/bin/startup.sh
</pre>
ja peatamiseks
<pre>
/Library/Tomcat/bin/shutdown.sh
</pre>

===Näiteaplikatsiooni juurutamine===

Java veebiaplikatsiooni jagatakse hea tava kohaselt üheainsa veebiarhiivi failina. Siiski võib Tomcati juurutada ka lahtipakendatud olekus ("exploded") Java veebiaplikatsiooni.

====Käsitsi juurutamine ja mahavõtmine====

Näiteaplikatsiooni juurutamiseks lae selle veebiarhiivifail alla ning kopeeri oma konteineri juurutamiskataloogi 'webapps':
<pre>wget http://tomcat.apache.org/tomcat-8.0-doc/appdev/sample/sample.war
cp /Users/kristjanveskimae/downloads/sample.war /Library/Tomcat/webapps/sample.war</pre>

[[File:tomcat_sample_application.png|400px|thumb|right|Pilt 1: Õnnestunult rakendatud näiteaplikatsioon]]

Kui konfiguratsioonifailis $CATALINA_BASE/conf/server.xml on märgendi "Host" atribuudi "autoDeploy" väärtus "true", installeerib ja uuendab Tomcat aplikatsioone dünaamiliselt töötamise ajal. Kui väärtuseks on "false", käib installeerimine staatiliselt ning serverisse juurutamiseks tuleb teha konteineri taaskäivitus. [http://tomcat.apache.org/tomcat-8.0-doc/manager-howto.html#Deploy_A_New_Application_from_a_Local_Path 1] Mõlemal juhul pakib konteiner arhiveeritud faili ise lahti samasse kausta $CATALINA_BASE/webapps ning ka juurutab selle. Tekkiv aplikatsioon on lokaalsest masinast seejärel kättesaadav aadressil http://localhost:8080/sample/ . Kui rakendamine õnnestub, siis peaks olema brauserist nähtav sarnane lehekülg nagu pildil 1.

Veebirakenduse käsitsi mahavõtmiseks tuleb kustutada talle vastav dokumendipõhja kataloog "webapps" kataloogist. Samuti tuleks kustutada .war-fail olemaks kindel, et Tomcat ei rakenda uuel käivitamisel veebiaplikatsiooni veebiarhiivifailist. Veelgi lihtsam on mahavõtmine brauseriga haldusrakenduse kaudu.

Rakenduste baaskataloogi "webapps" asukohta saab muuta failis $CATALINA_BASE/conf/server.xml peremehepõhiselt määratava atribuudiga "appBase", sealjuures Tomcati vaikimisi peremees ehk "Host" on "localhost".

====Tomcati vahendid juurutamiseks====

Veebiaplikatsioonide juurutamine ja mahajuurutamine on võimalik ka kaughalduse teel tänu Tomcati internetipõhisele haldusrakendusele. Näiteks saab veebibrauserit kasutades teha serveri põhitoiminguid Tomcati enda HTML-põhise rakendusega "Tomcat Manager". Veebipõhine haldusrakendus töötab ka käsupõhise veebiteenusena, millele on valmis ehitatud Anti ja Maveni integratsioonid. Samuti eksisteerib käsurea kliendirakendus TCD (Tomcat Client Deployer). TCD ei kuulu Tomcati baaskoosseisu, kuid pakub peale serveri administreerimise tavatoimingute ka lisafunktsionaalsust nagu veebirakenduse kokkukompileerimine ja pakendamine. [http://tomcat.apache.org/tomcat-8.0-doc/manager-howto.html#Configuring_Manager_Application_Access 1]

====Haldurakendus "Tomcat Manager"====

Tomcati haldusrakendus "Tomcat Manager" (antud alamjaotuses lihtsalt haldusrakendus) on Tomcati enda veebiaplikatioon Tomcati brauseripõhiseks kaughalduseks, võimaldades muu hulgas järgnevat [http://tomcat.apache.org/tomcat-8.0-doc/manager-howto.html#Introduction 1]:
* Rakendada uue veebiaplikatsiooni war-faili üleslaadimisega;
* Näha kõiki rakendatud veebiaplikatsioone koos aktiivsete sessioonidega;
* Taasrakendada veebirakendust, näiteks veebiarhiivi pakitud klassifailide /WEB-INF/classes või teekide /WEB-INF/lib uuendamisel, kinnijooksmisel jms.;
* Peatada veebirakendust ilma serverist eemaldamata, samuti koos serverist eemaldamisega;
* Vaadata operatsioonisüsteemi ja Java parameetrite väärtusi;
* Näha kõiki saadaolevaid JNDI ressursse, k.a. andmebaasiühendusi, mis aitavad rakenduste programmeerijail defineerida <ResourceLink> elemendid web.xml konfiguratsioonifailis.

Tomcati installatsioon sisaldab haldusrakendust juba vaikimisi. Haldusrakenduse töölepanemiseks tuleb peremeesmasina konfiguratsioonikataloogi $CATALINA_BASE/conf/[enginename]/[hostname] lisada ka fail manager.xml. Vaikimisi valmiskonfigureeritud testrakendusel on see fail juba olemas asukohas $CATALINA_BASE/conf/Catalina/localhost/manager.xml . Rakendus asub vaikimisi aadressil http://[host]/manager/ , vaikimisi konfiguratsioone kasutades lahendub see asukohaks http://localhost:8080/manager/ . [http://tomcat.apache.org/tomcat-8.0-doc/manager-howto.html#Configuring_Manager_Application_Access 1]

====="Tomcat Manager" ligipääsu konfigureerimine=====

Vaikimisi on turvalisuspõhjustel ligipääs haldusrakendusele maha keeratud. Mismoodi täpselt kasutajatel ligipääsu võimaldada sõltub kasutatavast valdusest (realm). Vaikimisi defineerib $CATALINA_BASE/conf/server.xml valduseks "MemoryRealm". Vaikimisi loeb valdus "MemoryRealm" kasutajad failist $CATALINA_BASE/conf/tomcat-users.xml. Antud failis tuleb iga kasutaja defineerida omaette märgendiga <user>, mis näeb välja umbes järgmine [http://tomcat.apache.org/tomcat-8.0-doc/manager-howto.html#Configuring_Manager_Application_Access 1]:
<pre>
<user name="craig" password="secret" roles="manager-gui,manager-script" />
</pre>

Antud kasutajale on defineeritud korraga kaks rolli. Ligipääsu võimaldamiseks tulebki lihtsamal juhul kasutajatefailis $CATALINA_BASE/conf/tomcat-users.xml defineerida enda kasutaja. Kasutaja rolliks võib määrata näiteks "manager-gui", mis võimaldab ligipääsu kogu HTML liidese funktsionaalsusele.

Teised valdused on "JDBCRealm", mille puhul hoitakse kasutajatega seonduvat infot andmebaasis ja JNDIRealm, mille puhul kasutatakse lihtsustatud kataloogisirvimise protokolli (LDAP).
Lisaks saab haldusrakendusele keelata ligipääsu mujalt kui kindlaksmääratud IP-aadressidelt, lisades filtri "RemoteAddrValve" või "RemoteHostValve" konfigureerimisfaili manager.xml näiteks järgmiselt [http://tomcat.apache.org/tomcat-8.0-doc/manager-howto.html#Introduction 1]:
<pre>
<Context privileged="true">
<Valve className="org.apache.catalina.valves.RemoteAddrValve"
allow="127\.0\.0\.1"/>
</Context>
</pre>

=====Juurutamine ja mahavõtmine haldusrakendusega "Tomcat Manager"=====

Juurutamiseks lae kõigepealt veebiarhiivifail üles, kasutades esilehel asuvat sektsiooni "WAR file to deploy". Veebiarhiivi üleslaadimise liides on kujutatud plidil 2.

[[File:tomcat_manager_war_upload.png|600px|thumb|right|Pilt 2: Veebiarhiivi üleslaadimise nupp]]

Rakendus kuvatakse seejärel hallatavate rakenduste nimekirjas. Kui konteiner pole seadistatud üleslaetud aplikatsiooni kohe ka ise rakendama, tuleb vajutada "Start". Rakenduse peatamiseks kasuta "Stop", uuesti rakendamiseks "Redeploy" ja serverist eemaldamiseks "Undeploy". Nupud on näha ka pildil 3 olevas rakenduste nimekirjas.


[[File:tomcat_manager_apps_list.png|1000px|thumb|Pilt 3: Rakenduste nimekiri Tomcati haldusrakenduses "Tomcat Manager"]]

==Näpunäiteid Tomcati reaalseks kasutamiseks==

===Juurutamise järjekord===

Tomcati käivitumisel juurutatakse aplikatsioonid sellises järjekorras [http://www.mulesoft.com/tomcat-deploy-procedures 2]:
# Konteinerisse kopeeritud kontekstikirjelduste järgi $CATALINA_BASE/conf/[EngineName]/[HostName]/[ApplicationName].xml ;
# Lahtipakitud rakendused "webapps" kataloogis;
# Pakitud rakenduste veebiarhiivid "webapps" kataloogis.

Seetõttu peaks käsitsi taasjuurutamisel kindluse mõttes eelnevalt kustutama rakenduse lahtipakitud dokumendipõhja kataloogi "webapps" kataloogist. Kontekstikirjelduse muutumisel tuleb jälgida, kas kirjeldus on juba kopeeritud serverisse ning vajadusel eelmise versiooni ümber muuta või kustutada.

===Reaalsele domeenile konfigureerimine===

Järgnevalt eeldame, et domeen ''www.minukodukas.ee'' on juba serverimasinaga seostatud. Et Tomcat hakkaks ka reaalselt Internetist tulevatele päringutele vastama, tuleb muuta failis $CATALINA_BASE/conf/server.xml konteinerile ''Catalina'' vastava teenusemärgendi sisu sarnaselt järgnevaga:

<pre>
<Service name="Catalina">
<Connector port="80" protocol="HTTP/1.1" connectionTimeout="20000" URIEncoding="UTF-8" redirectPort="8443" />
<Engine name="Catalina" defaultHost="www.minukodukas.ee">
<Host name="www.minukodukas.ee" appBase="webapps" unpackWARs="true" autoDeploy="false" deployOnStartup="false" xmlValidation="false" xmlNamespaceAware="false">
<Context path="" docBase="kodukas" debug="0" reloadable="true" />
</Host>
</Engine>
</Service>
</pre>

Ülal defineerime põhiliselt selle, et Tomcat kuulaks domeeni ''www.minukodukas.ee'' ja kasutaks HTTP päringute jaoks porti 80. Ühtlasti otsib Tomcat juurutatavat rakendust failist $CATALINA_BASE/webapps/kodukas.war. Kuna rajalisandiks on määratud tühi sõne (path=""), siis juurutataksegi aplikatsioon aadressile ''www.minukodukas.ee'' ilma rajalisandita (a'la ''www.minukodukas.ee/wiki''). Seetõttu pakitakse ka veebiarhiiv tegelikult lahti kataloogi $CATALINA_BASE/webapps/ROOT mitte kataloogi $CATALINA_BASE/webapps/kodukas nagu võiks eeldada.

===Käigultvahetus===

Võimaldamaks käigultvahetust (hot deployment) peab konteineri konfiguratsioonifailis $CATALINA_BASE/conf/server.xml olema peremehepõhise märgendi "Host" atribuudi "autoDeploy" väärtus "true". Sel juhul installeerib ja uuendab Tomcat aplikatsioone dünaamiliselt töötamise ajal. Kui väärtuseks on "false", käib installeerimine staatiliselt ning serverisse juurutamiseks tuleb teha konteineri taaskäivitus. Käigultvahetust saab määrata ka peremehe defineerimisel "Host Manager" rakendusega, mis on kättesaadav aadressil http://localhost:8080/host-manager/html . Kasutamiseks tuleb lisada oma kasutajale rolli "admin-gui" (vt. alajaotus ""Tomcat Manager" ligipääsu konfigureerimine"). Antud rakenduse veebiliides on kujutatud joonisel 4.

[[File:tomcat_host_manager_app.png|500px|thumb|Pilt 4: Tomcati haldusrakendus "Host Manage"]]

Käigultvahetust päästikuks on vaikimisi uuendatud veebiarhiivifaili või lahtipakitud veebirakenduse paigutamine "webapps" kataloogi. Käigultvahetuse päästikutele võib failis $CATALINA_BASE/conf/server.xml ka ise lisada kuulatavaid ressursse nagu web.xml muutmine või mõne teegifaili vahetamine (märgendis "Host").

===Klassiteekide väljatõstmine veebiarhiivifailist===

Kõik konteksti poolt kasutatavad Java klassiteegid võib pakendada veebiarhiivi sisse kataloogi "lib", kuid nii võib osutuda veebiarhiivi üleslaadimine ajakulukaks, eriti arenduskeskkonnas. Kui ei teki ohtu, et erinevad rakendused kasutavad sama teegi erinevaid versioone, siis on vahel parem lisada osa teeke konteineri kataloogi $CATALINA_BASE/libs, kust need tehakse siis konteineri poolt kättesaadavaks kõigile konteineris jooksutatavatele kontekstidele. Nii võib vähendada veebiarhiivi faili suurust märgatavalt, mis tõstab kokkuvõttes juurutamiskiirust ja ühes sellega programmeerijate tööviljakust.

===Mälukasutus===

Konteineri poolt kasutatavat mälu saab vaadata haldusrakendusest vajutades lingile "Server Status". Mälukasutus on toodud jaotuses "JVM", kus näidatakse nii maksimaalselt kättesaadavat mälu kui ka parasjagu reserveeritud mälu.

<pre>Free memory: 41.16 MB Total memory: 123.37 MB Max memory: 1027.56 MB</pre>

Mälu suurendamiseks võib näiteks defineerida skriptis $CATALINA_BASE/bin/catalina.sh muutuja "JAVA_OPTS" ning määrata Java mälukasutuse miinimum- ja maksimumväärtused sarnaselt järgnevatega [http://www.mkyong.com/tomcat/tomcat-javalangoutofmemoryerror-permgen-space/ 3]:
<pre>
JAVA_OPTS="-Xms1536m -Xmx1536m -XX:NewSize=256m -XX:MaxNewSize=256m -XX:PermSize=256m -XX:MaxPermSize=256m"
</pre>

===Logifailid===

Vaikimisi defineerib Tomcat failiga $CATALINA_BASE/conf/logging.properties viis logerit, mis tekitavad viis eraldi logifaili.

{| style="background:#cccc99;color:black;width:80%;" border="1" cellpadding="5" cellspacing="0" align="center"
|+ Tomcati tekitatavad logifailid "logs" kataloogis
!Fail !! Kasutus
|- style="background:white; color:black"
| style="width:300px" |catalina.out
| Tomcati käivitus- ja peatamisskriptide väljund, samuti juurutatud rakenduste prindilaused System.out ja veaväljundid System.err
|- style="background:white; color:black"
| style="width:300px" |catalina.[yyyy]-[mm]-[dd].log
| Pööratud (rotated) logifail catalina.out
|- style="background:white; color:black"
| style="width:300px" |host-manager.[yyyy]-[mm]-[dd].log
| Logi peremehehalduse rakendusele (rakendus on kättesaadav kohalikust masinast aadressil http://localhost:8080/host-manager/html )
|- style="background:white; color:black"
| style="width:300px" |localhost.[yyyy]-[mm]-[dd].log
| Peremehe "localhost" logi; mitme virtuaalse peremehe korral tekitatakse igale peremehele oma logi
|- style="background:white; color:black"
| style="width:300px" |localhost_access_log.[yyyy]-[mm]-[dd].txt
| Konteinerisse Internetist saabunud päringute logi
|- style="background:white; color:black"
| style="width:300px" |manager.[yyyy]-[mm]-[dd].log
| Haldusrakenduse tegevuste logi
|}

=== Kokkuvõte ===

Antud juhend aitab Unix-keskkonnas (ja operatsioonisüsteemi administreerimise algteadmiste olemasolul) Tomcati installeerida, käivitada ja juurutada Tomcatile ka Java näite veebiaplikatsioon. Lisaks on ära toodud ka mõned esmased näpunäited Tomcati kasutamiseks reaalse veebiserverina. Loodetavasti aitab juhend lugeja esmasel kokkupuutel Tomcatiga tekkivatest probleemidest jagu saada ja süveneda iseseisvalt veebiserveri Tomcat põhjalikumasse uurimisse.

=== Autori märkused ===

Tööl pole ma kahjuks Tomcati reaalselt kasutada saanud. Kuigi olen tegelenud Java ärirakendustega, on IT-juhtimise poolel seni otsustatud JBoss või Jetty kasuks. Siiski olen oma huviprojekte arendades või Java veebirakenduste tegemist õppides valinud just Tomcati. Seda eelkõige hea integreerituse tõttu IDE-dega. Tomcat töötab näiteks kohe koos NetBeansi installeerimisega, samuti pole kuigi keeruline tööle panna koos Java EE versiooniga Eclipse-ist. Tean ka vähemalt üht Eesti ettevõttet, mis kasutabki Tomcati reaalseks äriteenuste pakkumiseks.

Seni on tundunud Tomcati kasutus läbi IDE mugav, kuid probleemide tekkimisel olen hätta jäänud. Kuna tegemist on siiski Java ärirakendusi toetava veebikonteineriga, mis pakub muu hulgas JNDI-nimeteenust ja andmebaasiühenduste haldamist, siis pole selle ülesehitus sugugi lihtne. Siiski aitab algtõdede teadmine ka lihtsamini lahendada tekkivaid probleeme läbi IDE kasutades.

===Viiteid===

Palju vajalikku võib leida [http://tomcat.apache.org/tomcat-8.0-doc/index.html Tomcat 8 dokumentatsioonist]

Lisaks üks viide põhjalikule Tomcati versioon seitsme ülevaatele: http://www.ntu.edu.sg/home/ehchua/programming/howto/Tomcat_More.html

= Kasutatud materjalid =

#http://tomcat.apache.org/tomcat-8.0-doc/index.html
#http://www.mulesoft.com/tomcat-deploy-procedures
#http://www.mkyong.com/tomcat/tomcat-javalangoutofmemoryerror-permgen-space/

[[Category: Operatsioonisüsteemide administreerimine ja sidumine]]

File:Tomcat sample application.png

2014-01-02T22:23:53Z

Kveskima:

Tomcat

2014-01-02T22:23:32Z

Kveskima: /* Käsitsi juurutamine ja mahavõtmine */

==Autor==

Kristjan Veskimäe D32

2013

==Sissejuhatus==

Tomcat on vabalt kättesaadav server Java veebirakendustele. Põhimõtteliselt on tegemist Servlet/JSP spetsifikatsiooni toetava konteineriga. Kiire käivitumise ning rakenduste käigultvahetuse tõttu on Tomcat hea valik väiksemate ning keskmise suurusega Java veebirakenduste käitamiseks.

Antud töö kirjeldab Tomcati 8. versiooni. Põhiosa on üldiselt samasugune võrreldes paari eelmise versiooniga. Suuremad erinevused on versioonispetsiifilistes probleemides ja nende lahendamises, mida käesolev töö ei vaatle.

Töö vaatleb Tomcati paigaldamist ja seadistamist Unix-laadsesse keskkonda ning eeldab lugejalt algteadmisi sarnastes süsteemides. Tomcati on võimalik paigaldada ka Windows-keskkonda, kuid antud veebiserver eeldab kasutaja poolt käsureal töötamist ning Tomcati failihierarhias orienteerumist. Põhimõtteliselt on Java veebirakenduste arendamiseks IDE-abil võimalik siiski ka kasutada IDE-sse integreeritud Tomcati serverit - näiteks pakuvad sellist võimalust Eclipse EE ja NetBeans - kuid seda käesolev töö ei vaatle.

==Mõisted==

* '''Kontekst''' (context) - Tomcati mõistes üks konkreetne veebiaplikatsioon
* '''Konteiner''' (container) - veebiserver Tomcat ise
* '''Kontekstikirjeldus''' (context descriptor) - Tomcati-spetsiifiline konteksti konfiguratsioonimääratlus; peremehepõhine osa loetakse failist $CATALINA_HOME/conf/[enginename]/[hostname]/context.xml ja sellele lisatakse kontekstispetsiifilised täpsustused failist $CATALINA_BASE/conf/[enginename]/[hostname]/[webappname].xml; kontekstikirjeldus määrab näiteks nimed ressurssidele, sessioonihalduse parameetrid jmt. (olgu märgitud, et Tomcati varasemates versioonides sisaldusid kontekstikirjeldused põhikonfiguratsioonifailis server.xml)
* '''Dokumendipõhi''' (docBase) - kontekstile vastav kataloog Tomcati "webapps" kataloogis, mis tekib veebiaplikatsiooni serverisse rakendamisel
* '''Veebiarhiiv''' (Web application ARchive, war-file) - Java veebiaplikatsiooni jagatakse hea tava kohaselt selle üheainsa veebiarhiivi failina, mille laienditüübiks on "war". Tegemist on zip-protokolliga kokkupakitud kataloogiga, millel on Java veebirakenduste spetsifikatsioonile vastav ülesehitus. Siiski võib veebiaplikatsioon olla juurutamisel ka lahtipakendatud olekus (inglisekeelne termin on "war is exploded").

==Ülesehitus==

{| class="wikitable"
|+Kataloogid
|-
|style="color: green;" | $CATALINA_HOME
|baaskataloog, kuhu on Tomcat paigutatud
|-
|style="color: green;" | $CATALINA_BASE
|parasjagu töösoleva Tomcati eksemplari baaskataloog, mille alusel lahendatakse teed ülejäänud kataloogide ja failideni; ainult ühe kasutusel oleva Tomcati eksemplari puhul on see sama, mis $CATALINA_HOME

|-
|style="color: green;" | $CATALINA_BASE/bin
|serveri käivitus- ja abiskriptid
|-
|style="color: green;" | $CATALINA_BASE/conf
|konfiguratsioonifailid
|-
|style="color: green;" | $CATALINA_BASE/lib
|Tomcatile vaikimisi kättesaadavad Java klassiteegid (class libraries) ehk .jar-failid kuhu on Java kompileeritud kood kokku pakendatud
|-
|style="color: green;" | $CATALINA_BASE/logs
|logifailid paigutatakse vaikimisi siia
|-
|style="color: green;" | $CATALINA_BASE/webapps
|kataloog, kuhu paigutatakse serverisse juurutatavad veebiaplikatsioonid

|}

{| class="wikitable"
|+Mõned olulisemad failid
|-
|style="color: green;" | $CATALINA_BASE/bin/startup.sh
|serveri käivitusskript
|-
|style="color: green;" | $CATALINA_BASE/bin/shutdown.sh
|serveri peatusskript

|-
|style="color: green;" | $CATALINA_BASE/conf/server.xml
| konteineri peamine konfiguratsioonifail
|-
|style="color: green;" | $CATALINA_BASE/conf/[enginename]/[hostname]/[webappname].xml
|serveri administraatori jaoks konteinerisse endasse ümber kopeeritud rakendusepõhine kontekstikirjelduse konfiguratsioon failist $CATALINA_BASE/webapps/[ApplicationName]/META-INF/context.xml
|-
|style="color: green;" | $CATALINA_BASE/conf/[enginename]/[hostname]/context.xml
| fail, mis aitab administraatoril konteksti kohta käivat infot kirjeldada peremeesmasina-põhiselt ja halduseks mõeldud automaat-tööriistadel (näiteks Tomcat Manager ja TCD) oma tööd teha
|-
|style="color: green;" | $CATALINA_BASE/$CATALINA_BASE/conf/[enginename]/[hostname]/manager.xml
|fail, mis võimaldab lisada rakendustele ligipääsufiltreid
|-
|style="color: green;" | $CATALINA_BASE/webapps/[webappname]/META-INF/context.xml
|kontekstikirjeldusfail, mille veebirakenduse programmeerija on pakendanud oma aplikatsiooniga kaasa ning millega ta saab võimaluse kontekstikirjeldust omalt poolt mõjutada; kirjutatakse rakenduse uuestijuurutamisel üle, mistõttu administraator peaks muutma selle asemel konteinerisse ümber kopeeritud püsieksemplari $CATALINA_BASE/conf/[enginename]/[hostname]/context.xml
|-
|style="color: green;" | $CATALINA_BASE/webapps/[webappname]/WEB-INF/web.xml
|ka üks oluline Java veebiaplikatsiooni konfiguratsioonifail, mille pakendatakse koos veebiarhiiviga; enamasti muudab seda ainult programeerija; määrab muu hulgas millised aplikatsiooni osad vajavad autentimist või kui kiiresti veebisessioon aegub
|}

==Installeerimine==

===Installeerimine paketihalduriga===

<pre>
apt-cache search tomcat
apt-get install tomcat[version]-webapps
apt-get install tomcat[version]-admin
apt-get install tomcat[version]
</pre>

===Installeerimine käsitsi===

Paketihalduriga installeerides ei pruugi viimane Tomcati versioon olla kättesaadav ja see pakub ka vähem võimalusi kataloogide määramiseks jms. Käsitsi installeerimiseks tuleb laadida Tomcat kodulehelt alla. Lahtipakkimisel tekib kataloog, milles sisalduv fail "RUNNING.txt" on kõige kindlam allikas installeerimisel tekkivate probleemide vältimiseks ning lahendamiseks.

Vajaliku versiooni installeerimisfaili asukoha saab vaadata Tomcati kodulehelt sektsioonist "Download". Järgnevas näites installeerime Tomcati kõige uuema ebastabiilse kandidaatversiooni, mida näitab nimes sisalduv RC ehk "release candidate". Produktsioonikeskkonda tuleks siiski valida stabiilse versiooni. Käsitsi installeerimine on sarnane järgmisega:
<pre>
wget http://mirror.nexcess.net/apache/tomcat/tomcat-8/v8.0.0-RC5/bin/apache-tomcat-8.0.0-RC5.tar.gz
tar -zxvf apache-tomcat-8.0.0-RC5.tar.gz
mv /Users/kristjanveskimae/downloads/apache-tomcat-8.0.0-RC5 /usr/local/apache-tomcat-8.0.0-RC5
rm -f /Library/Tomcat
ln -s /usr/local/apache-tomcat-8.0.0-RC5/ /Library/Tomcat
chown -R kristjanveskimae /Library/Tomcat
chmod +x /Library/Tomcat/bin/*.sh
</pre>

==Käivitamine ja aplikatsiooni juurutamine==

===Konteineri käivitamine===

Tomcati käivitamise eelduseks on Java paigaldamine masinasse ning keskkonnamuutujate "JAVA_HOME" ja "JRE_HOME" defineerimine. Peale installeerimist võib kasutada skripte kataloogist $CATALINA_BASE/bin . Järgneb üks võimalik käivitamise ja peatamise näide, mis on kasutatav eelnevalt kirjeldatud käsitsi installeerimise juhul:
<pre>
/Library/Tomcat/bin/startup.sh
</pre>
ja peatamiseks
<pre>
/Library/Tomcat/bin/shutdown.sh
</pre>

===Näiteaplikatsiooni juurutamine===

Java veebiaplikatsiooni jagatakse hea tava kohaselt üheainsa veebiarhiivi failina. Siiski võib Tomcati juurutada ka lahtipakendatud olekus ("exploded") Java veebiaplikatsiooni.

====Käsitsi juurutamine ja mahavõtmine====

Näiteaplikatsiooni juurutamiseks lae selle veebiarhiivifail alla ning kopeeri oma konteineri juurutamiskataloogi 'webapps':
<pre>wget http://tomcat.apache.org/tomcat-8.0-doc/appdev/sample/sample.war
cp /Users/kristjanveskimae/downloads/sample.war /Library/Tomcat/webapps/sample.war</pre>

[[File:tomcat_sample_application.png|400px|thumb|right|Pilt 1: Õnnestunult rakendatud näiteaplikatsioon]]

Kui konfiguratsioonifailis $CATALINA_BASE/conf/server.xml on märgendi "Host" atribuudi "autoDeploy" väärtus "true", installeerib ja uuendab Tomcat aplikatsioone dünaamiliselt töötamise ajal. Kui väärtuseks on "false", käib installeerimine staatiliselt ning serverisse juurutamiseks tuleb teha konteineri taaskäivitus. [http://tomcat.apache.org/tomcat-8.0-doc/manager-howto.html#Deploy_A_New_Application_from_a_Local_Path 1] Mõlemal juhul pakib konteiner arhiveeritud faili ise lahti samasse kausta $CATALINA_BASE/webapps ning ka juurutab selle. Tekkiv aplikatsioon on lokaalsest masinast seejärel kättesaadav aadressil http://localhost:8080/sample/ . Kui rakendamine õnnestub, siis peaks olema brauserist nähtav sarnane lehekülg nagu pildil 1.

Veebirakenduse käsitsi mahavõtmiseks tuleb kustutada talle vastav dokumendipõhja kataloog "webapps" kataloogist. Samuti tuleks kustutada .war-fail olemaks kindel, et Tomcat ei rakenda uuel käivitamisel veebiaplikatsiooni veebiarhiivifailist. Veelgi lihtsam on mahavõtmine brauseriga haldusrakenduse kaudu.

Rakenduste baaskataloogi "webapps" asukohta saab muuta failis $CATALINA_BASE/conf/server.xml peremehepõhiselt määratava atribuudiga "appBase", sealjuures Tomcati vaikimisi peremees ehk "Host" on "localhost".

====Tomcati vahendid juurutamiseks====

Veebiaplikatsioonide juurutamine ja mahajuurutamine on võimalik ka kaughalduse teel tänu Tomcati internetipõhisele haldusrakendusele. Näiteks saab veebibrauserit kasutades teha serveri põhitoiminguid Tomcati enda HTML-põhise rakendusega "Tomcat Manager". Veebipõhine haldusrakendus töötab ka käsupõhise veebiteenusena, millele on valmis ehitatud Anti ja Maveni integratsioonid. Samuti eksisteerib käsurea kliendirakendus TCD (Tomcat Client Deployer). TCD ei kuulu Tomcati baaskoosseisu, kuid pakub peale serveri administreerimise tavatoimingute ka lisafunktsionaalsust nagu veebirakenduse kokkukompileerimine ja pakendamine. [http://tomcat.apache.org/tomcat-8.0-doc/manager-howto.html#Configuring_Manager_Application_Access 1]

====Haldurakendus "Tomcat Manager"====

Tomcati haldusrakendus "Tomcat Manager" (antud alamjaotuses lihtsalt haldusrakendus) on Tomcati enda veebiaplikatioon Tomcati brauseripõhiseks kaughalduseks, võimaldades muu hulgas järgnevat [http://tomcat.apache.org/tomcat-8.0-doc/manager-howto.html#Introduction 1]:
* Rakendada uue veebiaplikatsiooni war-faili üleslaadimisega;
* Näha kõiki rakendatud veebiaplikatsioone koos aktiivsete sessioonidega;
* Taasrakendada veebirakendust, näiteks veebiarhiivi pakitud klassifailide /WEB-INF/classes või teekide /WEB-INF/lib uuendamisel, kinnijooksmisel jms.;
* Peatada veebirakendust ilma serverist eemaldamata, samuti koos serverist eemaldamisega;
* Vaadata operatsioonisüsteemi ja Java parameetrite väärtusi;
* Näha kõiki saadaolevaid JNDI ressursse, k.a. andmebaasiühendusi, mis aitavad rakenduste programmeerijail defineerida <ResourceLink> elemendid web.xml konfiguratsioonifailis.

Tomcati installatsioon sisaldab haldusrakendust juba vaikimisi. Haldusrakenduse töölepanemiseks tuleb peremeesmasina konfiguratsioonikataloogi $CATALINA_BASE/conf/[enginename]/[hostname] lisada ka fail manager.xml. Vaikimisi valmiskonfigureeritud testrakendusel on see fail juba olemas asukohas $CATALINA_BASE/conf/Catalina/localhost/manager.xml . Rakendus asub vaikimisi aadressil http://[host]/manager/ , vaikimisi konfiguratsioone kasutades lahendub see asukohaks http://localhost:8080/manager/ . [http://tomcat.apache.org/tomcat-8.0-doc/manager-howto.html#Configuring_Manager_Application_Access 1]

====="Tomcat Manager" ligipääsu konfigureerimine=====

Vaikimisi on turvalisuspõhjustel ligipääs haldusrakendusele maha keeratud. Mismoodi täpselt kasutajatel ligipääsu võimaldada sõltub kasutatavast valdusest (realm). Vaikimisi defineerib $CATALINA_BASE/conf/server.xml valduseks "MemoryRealm". Vaikimisi loeb valdus "MemoryRealm" kasutajad failist $CATALINA_BASE/conf/tomcat-users.xml. Antud failis tuleb iga kasutaja defineerida omaette märgendiga <user>, mis näeb välja umbes järgmine [http://tomcat.apache.org/tomcat-8.0-doc/manager-howto.html#Configuring_Manager_Application_Access 1]:
<pre>
<user name="craig" password="secret" roles="manager-gui,manager-script" />
</pre>

Antud kasutajale on defineeritud korraga kaks rolli. Ligipääsu võimaldamiseks tulebki lihtsamal juhul kasutajatefailis $CATALINA_BASE/conf/tomcat-users.xml defineerida enda kasutaja. Kasutaja rolliks võib määrata näiteks "manager-gui", mis võimaldab ligipääsu kogu HTML liidese funktsionaalsusele.

Teised valdused on "JDBCRealm", mille puhul hoitakse kasutajatega seonduvat infot andmebaasis ja JNDIRealm, mille puhul kasutatakse lihtsustatud kataloogisirvimise protokolli (LDAP).
Lisaks saab haldusrakendusele keelata ligipääsu mujalt kui kindlaksmääratud IP-aadressidelt, lisades filtri "RemoteAddrValve" või "RemoteHostValve" konfigureerimisfaili manager.xml näiteks järgmiselt [http://tomcat.apache.org/tomcat-8.0-doc/manager-howto.html#Introduction 1]:
<pre>
<Context privileged="true">
<Valve className="org.apache.catalina.valves.RemoteAddrValve"
allow="127\.0\.0\.1"/>
</Context>
</pre>

=====Juurutamine ja mahavõtmine haldusrakendusega "Tomcat Manager"=====

Juurutamiseks lae kõigepealt veebiarhiivifail üles, kasutades esilehel asuvat sektsiooni "WAR file to deploy". Veebiarhiivi üleslaadimise liides on kujutatud plidil 2.

[[File:tomcat_manager_war_upload.png|600px|thumb|right|Pilt 2: Veebiarhiivi üleslaadimise nupp]]

Rakendus kuvatakse seejärel hallatavate rakenduste nimekirjas. Kui konteiner pole seadistatud üleslaetud aplikatsiooni kohe ka ise rakendama, tuleb vajutada "Start". Rakenduse peatamiseks kasuta "Stop", uuesti rakendamiseks "Redeploy" ja serverist eemaldamiseks "Undeploy". Nupud on näha ka pildil 3 olevas rakenduste nimekirjas.


[[File:tomcat_manager_apps_list.png|1000px|thumb|Pilt 3: Rakenduste nimekiri Tomcati haldusrakenduses "Tomcat Manager"]]

==Näpunäiteid Tomcati reaalseks kasutamiseks==

===Juurutamise järjekord===

Tomcati käivitumisel juurutatakse aplikatsioonid sellises järjekorras [http://www.mulesoft.com/tomcat-deploy-procedures 2]:
# Konteinerisse kopeeritud kontekstikirjelduste järgi $CATALINA_BASE/conf/[EngineName]/[HostName]/[ApplicationName].xml ;
# Lahtipakitud rakendused "webapps" kataloogis;
# Pakitud rakenduste veebiarhiivid "webapps" kataloogis.

Seetõttu peaks käsitsi taasjuurutamisel kindluse mõttes eelnevalt kustutama rakenduse lahtipakitud dokumendipõhja kataloogi "webapps" kataloogist. Kontekstikirjelduse muutumisel tuleb jälgida, kas kirjeldus on juba kopeeritud serverisse ning vajadusel eelmise versiooni ümber muuta või kustutada.

===Reaalsele domeenile konfigureerimine===

Järgnevalt eeldame, et domeen ''www.minukodukas.ee'' on juba serverimasinaga seostatud. Et Tomcat hakkaks ka reaalselt Internetist tulevatele päringutele vastama, tuleb muuta failis $CATALINA_BASE/conf/server.xml konteinerile ''Catalina'' vastava teenusemärgendi sisu sarnaselt järgnevaga:

<pre>
<Service name="Catalina">
<Connector port="80" protocol="HTTP/1.1" connectionTimeout="20000" URIEncoding="UTF-8" redirectPort="8443" />
<Engine name="Catalina" defaultHost="www.minukodukas.ee">
<Host name="www.minukodukas.ee" appBase="webapps" unpackWARs="true" autoDeploy="false" deployOnStartup="false" xmlValidation="false" xmlNamespaceAware="false">
<Context path="" docBase="kodukas" debug="0" reloadable="true" />
</Host>
</Engine>
</Service>
</pre>

Ülal defineerime põhiliselt selle, et Tomcat kuulaks domeeni ''www.minukodukas.ee'' ja kasutaks HTTP päringute jaoks porti 80. Ühtlasti otsib Tomcat juurutatavat rakendust failist $CATALINA_BASE/webapps/kodukas.war. Kuna rajalisandiks on määratud tühi sõne (path=""), siis juurutataksegi aplikatsioon aadressile ''www.minukodukas.ee'' ilma rajalisandita (a'la ''www.minukodukas.ee/wiki''). Seetõttu pakitakse ka veebiarhiiv tegelikult lahti kataloogi $CATALINA_BASE/webapps/ROOT mitte kataloogi $CATALINA_BASE/webapps/kodukas nagu võiks eeldada.

===Käigultvahetus===

Võimaldamaks käigultvahetust (hot deployment) peab konteineri konfiguratsioonifailis $CATALINA_BASE/conf/server.xml olema peremehepõhise märgendi "Host" atribuudi "autoDeploy" väärtus "true". Sel juhul installeerib ja uuendab Tomcat aplikatsioone dünaamiliselt töötamise ajal. Kui väärtuseks on "false", käib installeerimine staatiliselt ning serverisse juurutamiseks tuleb teha konteineri taaskäivitus. Käigultvahetust saab määrata ka peremehe defineerimisel "Host Manager" rakendusega, mis on kättesaadav aadressil http://localhost:8080/host-manager/html . Kasutamiseks tuleb lisada oma kasutajale rolli "admin-gui" (vt. alajaotus ""Tomcat Manager" ligipääsu konfigureerimine"). Antud rakenduse veebiliides on kujutatud joonisel 4.

[[File:tomcat_host_manager_app.png|500px|thumb|Pilt 4: Tomcati haldusrakendus "Host Manage"]]

Käigultvahetust päästikuks on vaikimisi uuendatud veebiarhiivifaili või lahtipakitud veebirakenduse paigutamine "webapps" kataloogi. Käigultvahetuse päästikutele võib failis $CATALINA_BASE/conf/server.xml ka ise lisada kuulatavaid ressursse nagu web.xml muutmine või mõne teegifaili vahetamine (märgendis "Host").

===Klassiteekide väljatõstmine veebiarhiivifailist===

Kõik konteksti poolt kasutatavad Java klassiteegid võib pakendada veebiarhiivi sisse kataloogi "lib", kuid nii võib osutuda veebiarhiivi üleslaadimine ajakulukaks, eriti arenduskeskkonnas. Kui ei teki ohtu, et erinevad rakendused kasutavad sama teegi erinevaid versioone, siis on vahel parem lisada osa teeke konteineri kataloogi $CATALINA_BASE/libs, kust need tehakse siis konteineri poolt kättesaadavaks kõigile konteineris jooksutatavatele kontekstidele. Nii võib vähendada veebiarhiivi faili suurust märgatavalt, mis tõstab kokkuvõttes juurutamiskiirust ja ühes sellega programmeerijate tööviljakust.

===Mälukasutus===

Konteineri poolt kasutatavat mälu saab vaadata haldusrakendusest vajutades lingile "Server Status". Mälukasutus on toodud jaotuses "JVM", kus näidatakse nii maksimaalselt kättesaadavat mälu kui ka parasjagu reserveeritud mälu.

<pre>Free memory: 41.16 MB Total memory: 123.37 MB Max memory: 1027.56 MB</pre>

Mälu suurendamiseks võib näiteks defineerida skriptis $CATALINA_BASE/bin/catalina.sh muutuja "JAVA_OPTS" ning määrata Java mälukasutuse miinimum- ja maksimumväärtused sarnaselt järgnevatega [http://www.mkyong.com/tomcat/tomcat-javalangoutofmemoryerror-permgen-space/ 3]:
<pre>
JAVA_OPTS="-Xms1536m -Xmx1536m -XX:NewSize=256m -XX:MaxNewSize=256m -XX:PermSize=256m -XX:MaxPermSize=256m"
</pre>

===Logifailid===

Vaikimisi defineerib Tomcat failiga $CATALINA_BASE/conf/logging.properties viis logerit, mis tekitavad viis eraldi logifaili.

{| style="background:#cccc99;color:black;width:80%;" border="1" cellpadding="5" cellspacing="0" align="center"
|+ Tomcati tekitatavad logifailid "logs" kataloogis
!Fail !! Kasutus
|- style="background:white; color:black"
| style="width:300px" |catalina.out
| Tomcati käivitus- ja peatamisskriptide väljund, samuti juurutatud rakenduste prindilaused System.out ja veaväljundid System.err
|- style="background:white; color:black"
| style="width:300px" |catalina.[yyyy]-[mm]-[dd].log
| Pööratud (rotated) logifail catalina.out
|- style="background:white; color:black"
| style="width:300px" |host-manager.[yyyy]-[mm]-[dd].log
| Logi peremehehalduse rakendusele (rakendus on kättesaadav kohalikust masinast aadressil http://localhost:8080/host-manager/html )
|- style="background:white; color:black"
| style="width:300px" |localhost.[yyyy]-[mm]-[dd].log
| Peremehe "localhost" logi; mitme virtuaalse peremehe korral tekitatakse igale peremehele oma logi
|- style="background:white; color:black"
| style="width:300px" |localhost_access_log.[yyyy]-[mm]-[dd].txt
| Konteinerisse Internetist saabunud päringute logi
|- style="background:white; color:black"
| style="width:300px" |manager.[yyyy]-[mm]-[dd].log
| Haldusrakenduse tegevuste logi
|}

===Viiteid===

Palju vajalikku võib leida [http://tomcat.apache.org/tomcat-8.0-doc/index.html Tomcat 8 dokumentatsioonist]

Lisaks üks viide põhjalikule Tomcati versioon seitsme ülevaatele: http://www.ntu.edu.sg/home/ehchua/programming/howto/Tomcat_More.html

= Kasutatud materjalid =

#http://tomcat.apache.org/tomcat-8.0-doc/index.html
#http://www.mulesoft.com/tomcat-deploy-procedures
#http://www.mkyong.com/tomcat/tomcat-javalangoutofmemoryerror-permgen-space/

[[Category: Operatsioonisüsteemide administreerimine ja sidumine]]

Tomcat

2014-01-02T22:22:23Z

Kveskima: /* Juurutamine ja mahavõtmine haldusrakendusega "Tomcat Manager" */

==Autor==

Kristjan Veskimäe D32

2013

==Sissejuhatus==

Tomcat on vabalt kättesaadav server Java veebirakendustele. Põhimõtteliselt on tegemist Servlet/JSP spetsifikatsiooni toetava konteineriga. Kiire käivitumise ning rakenduste käigultvahetuse tõttu on Tomcat hea valik väiksemate ning keskmise suurusega Java veebirakenduste käitamiseks.

Antud töö kirjeldab Tomcati 8. versiooni. Põhiosa on üldiselt samasugune võrreldes paari eelmise versiooniga. Suuremad erinevused on versioonispetsiifilistes probleemides ja nende lahendamises, mida käesolev töö ei vaatle.

Töö vaatleb Tomcati paigaldamist ja seadistamist Unix-laadsesse keskkonda ning eeldab lugejalt algteadmisi sarnastes süsteemides. Tomcati on võimalik paigaldada ka Windows-keskkonda, kuid antud veebiserver eeldab kasutaja poolt käsureal töötamist ning Tomcati failihierarhias orienteerumist. Põhimõtteliselt on Java veebirakenduste arendamiseks IDE-abil võimalik siiski ka kasutada IDE-sse integreeritud Tomcati serverit - näiteks pakuvad sellist võimalust Eclipse EE ja NetBeans - kuid seda käesolev töö ei vaatle.

==Mõisted==

* '''Kontekst''' (context) - Tomcati mõistes üks konkreetne veebiaplikatsioon
* '''Konteiner''' (container) - veebiserver Tomcat ise
* '''Kontekstikirjeldus''' (context descriptor) - Tomcati-spetsiifiline konteksti konfiguratsioonimääratlus; peremehepõhine osa loetakse failist $CATALINA_HOME/conf/[enginename]/[hostname]/context.xml ja sellele lisatakse kontekstispetsiifilised täpsustused failist $CATALINA_BASE/conf/[enginename]/[hostname]/[webappname].xml; kontekstikirjeldus määrab näiteks nimed ressurssidele, sessioonihalduse parameetrid jmt. (olgu märgitud, et Tomcati varasemates versioonides sisaldusid kontekstikirjeldused põhikonfiguratsioonifailis server.xml)
* '''Dokumendipõhi''' (docBase) - kontekstile vastav kataloog Tomcati "webapps" kataloogis, mis tekib veebiaplikatsiooni serverisse rakendamisel
* '''Veebiarhiiv''' (Web application ARchive, war-file) - Java veebiaplikatsiooni jagatakse hea tava kohaselt selle üheainsa veebiarhiivi failina, mille laienditüübiks on "war". Tegemist on zip-protokolliga kokkupakitud kataloogiga, millel on Java veebirakenduste spetsifikatsioonile vastav ülesehitus. Siiski võib veebiaplikatsioon olla juurutamisel ka lahtipakendatud olekus (inglisekeelne termin on "war is exploded").

==Ülesehitus==

{| class="wikitable"
|+Kataloogid
|-
|style="color: green;" | $CATALINA_HOME
|baaskataloog, kuhu on Tomcat paigutatud
|-
|style="color: green;" | $CATALINA_BASE
|parasjagu töösoleva Tomcati eksemplari baaskataloog, mille alusel lahendatakse teed ülejäänud kataloogide ja failideni; ainult ühe kasutusel oleva Tomcati eksemplari puhul on see sama, mis $CATALINA_HOME

|-
|style="color: green;" | $CATALINA_BASE/bin
|serveri käivitus- ja abiskriptid
|-
|style="color: green;" | $CATALINA_BASE/conf
|konfiguratsioonifailid
|-
|style="color: green;" | $CATALINA_BASE/lib
|Tomcatile vaikimisi kättesaadavad Java klassiteegid (class libraries) ehk .jar-failid kuhu on Java kompileeritud kood kokku pakendatud
|-
|style="color: green;" | $CATALINA_BASE/logs
|logifailid paigutatakse vaikimisi siia
|-
|style="color: green;" | $CATALINA_BASE/webapps
|kataloog, kuhu paigutatakse serverisse juurutatavad veebiaplikatsioonid

|}

{| class="wikitable"
|+Mõned olulisemad failid
|-
|style="color: green;" | $CATALINA_BASE/bin/startup.sh
|serveri käivitusskript
|-
|style="color: green;" | $CATALINA_BASE/bin/shutdown.sh
|serveri peatusskript

|-
|style="color: green;" | $CATALINA_BASE/conf/server.xml
| konteineri peamine konfiguratsioonifail
|-
|style="color: green;" | $CATALINA_BASE/conf/[enginename]/[hostname]/[webappname].xml
|serveri administraatori jaoks konteinerisse endasse ümber kopeeritud rakendusepõhine kontekstikirjelduse konfiguratsioon failist $CATALINA_BASE/webapps/[ApplicationName]/META-INF/context.xml
|-
|style="color: green;" | $CATALINA_BASE/conf/[enginename]/[hostname]/context.xml
| fail, mis aitab administraatoril konteksti kohta käivat infot kirjeldada peremeesmasina-põhiselt ja halduseks mõeldud automaat-tööriistadel (näiteks Tomcat Manager ja TCD) oma tööd teha
|-
|style="color: green;" | $CATALINA_BASE/$CATALINA_BASE/conf/[enginename]/[hostname]/manager.xml
|fail, mis võimaldab lisada rakendustele ligipääsufiltreid
|-
|style="color: green;" | $CATALINA_BASE/webapps/[webappname]/META-INF/context.xml
|kontekstikirjeldusfail, mille veebirakenduse programmeerija on pakendanud oma aplikatsiooniga kaasa ning millega ta saab võimaluse kontekstikirjeldust omalt poolt mõjutada; kirjutatakse rakenduse uuestijuurutamisel üle, mistõttu administraator peaks muutma selle asemel konteinerisse ümber kopeeritud püsieksemplari $CATALINA_BASE/conf/[enginename]/[hostname]/context.xml
|-
|style="color: green;" | $CATALINA_BASE/webapps/[webappname]/WEB-INF/web.xml
|ka üks oluline Java veebiaplikatsiooni konfiguratsioonifail, mille pakendatakse koos veebiarhiiviga; enamasti muudab seda ainult programeerija; määrab muu hulgas millised aplikatsiooni osad vajavad autentimist või kui kiiresti veebisessioon aegub
|}

==Installeerimine==

===Installeerimine paketihalduriga===

<pre>
apt-cache search tomcat
apt-get install tomcat[version]-webapps
apt-get install tomcat[version]-admin
apt-get install tomcat[version]
</pre>

===Installeerimine käsitsi===

Paketihalduriga installeerides ei pruugi viimane Tomcati versioon olla kättesaadav ja see pakub ka vähem võimalusi kataloogide määramiseks jms. Käsitsi installeerimiseks tuleb laadida Tomcat kodulehelt alla. Lahtipakkimisel tekib kataloog, milles sisalduv fail "RUNNING.txt" on kõige kindlam allikas installeerimisel tekkivate probleemide vältimiseks ning lahendamiseks.

Vajaliku versiooni installeerimisfaili asukoha saab vaadata Tomcati kodulehelt sektsioonist "Download". Järgnevas näites installeerime Tomcati kõige uuema ebastabiilse kandidaatversiooni, mida näitab nimes sisalduv RC ehk "release candidate". Produktsioonikeskkonda tuleks siiski valida stabiilse versiooni. Käsitsi installeerimine on sarnane järgmisega:
<pre>
wget http://mirror.nexcess.net/apache/tomcat/tomcat-8/v8.0.0-RC5/bin/apache-tomcat-8.0.0-RC5.tar.gz
tar -zxvf apache-tomcat-8.0.0-RC5.tar.gz
mv /Users/kristjanveskimae/downloads/apache-tomcat-8.0.0-RC5 /usr/local/apache-tomcat-8.0.0-RC5
rm -f /Library/Tomcat
ln -s /usr/local/apache-tomcat-8.0.0-RC5/ /Library/Tomcat
chown -R kristjanveskimae /Library/Tomcat
chmod +x /Library/Tomcat/bin/*.sh
</pre>

==Käivitamine ja aplikatsiooni juurutamine==

===Konteineri käivitamine===

Tomcati käivitamise eelduseks on Java paigaldamine masinasse ning keskkonnamuutujate "JAVA_HOME" ja "JRE_HOME" defineerimine. Peale installeerimist võib kasutada skripte kataloogist $CATALINA_BASE/bin . Järgneb üks võimalik käivitamise ja peatamise näide, mis on kasutatav eelnevalt kirjeldatud käsitsi installeerimise juhul:
<pre>
/Library/Tomcat/bin/startup.sh
</pre>
ja peatamiseks
<pre>
/Library/Tomcat/bin/shutdown.sh
</pre>

===Näiteaplikatsiooni juurutamine===

Java veebiaplikatsiooni jagatakse hea tava kohaselt üheainsa veebiarhiivi failina. Siiski võib Tomcati juurutada ka lahtipakendatud olekus ("exploded") Java veebiaplikatsiooni.

====Käsitsi juurutamine ja mahavõtmine====

Näiteaplikatsiooni juurutamiseks lae selle veebiarhiivifail alla ning kopeeri oma konteineri juurutamiskataloogi 'webapps':
<pre>wget http://tomcat.apache.org/tomcat-8.0-doc/appdev/sample/sample.war
cp /Users/kristjanveskimae/downloads/sample.war /Library/Tomcat/webapps/sample.war</pre>

[[File:sample_app.png|400px|thumb|right|Pilt 1: Õnnestunult rakendatud näiteaplikatsioon]]

Kui konfiguratsioonifailis $CATALINA_BASE/conf/server.xml on märgendi "Host" atribuudi "autoDeploy" väärtus "true", installeerib ja uuendab Tomcat aplikatsioone dünaamiliselt töötamise ajal. Kui väärtuseks on "false", käib installeerimine staatiliselt ning serverisse juurutamiseks tuleb teha konteineri taaskäivitus. [http://tomcat.apache.org/tomcat-8.0-doc/manager-howto.html#Deploy_A_New_Application_from_a_Local_Path 1] Mõlemal juhul pakib konteiner arhiveeritud faili ise lahti samasse kausta $CATALINA_BASE/webapps ning ka juurutab selle. Tekkiv aplikatsioon on lokaalsest masinast seejärel kättesaadav aadressil http://localhost:8080/sample/ . Kui rakendamine õnnestub, siis peaks olema brauserist nähtav sarnane lehekülg nagu pildil 1.

Veebirakenduse käsitsi mahavõtmiseks tuleb kustutada talle vastav dokumendipõhja kataloog "webapps" kataloogist. Samuti tuleks kustutada .war-fail olemaks kindel, et Tomcat ei rakenda uuel käivitamisel veebiaplikatsiooni veebiarhiivifailist. Veelgi lihtsam on mahavõtmine brauseriga haldusrakenduse kaudu.

Rakenduste baaskataloogi "webapps" asukohta saab muuta failis $CATALINA_BASE/conf/server.xml peremehepõhiselt määratava atribuudiga "appBase", sealjuures Tomcati vaikimisi peremees ehk "Host" on "localhost".

====Tomcati vahendid juurutamiseks====

Veebiaplikatsioonide juurutamine ja mahajuurutamine on võimalik ka kaughalduse teel tänu Tomcati internetipõhisele haldusrakendusele. Näiteks saab veebibrauserit kasutades teha serveri põhitoiminguid Tomcati enda HTML-põhise rakendusega "Tomcat Manager". Veebipõhine haldusrakendus töötab ka käsupõhise veebiteenusena, millele on valmis ehitatud Anti ja Maveni integratsioonid. Samuti eksisteerib käsurea kliendirakendus TCD (Tomcat Client Deployer). TCD ei kuulu Tomcati baaskoosseisu, kuid pakub peale serveri administreerimise tavatoimingute ka lisafunktsionaalsust nagu veebirakenduse kokkukompileerimine ja pakendamine. [http://tomcat.apache.org/tomcat-8.0-doc/manager-howto.html#Configuring_Manager_Application_Access 1]

====Haldurakendus "Tomcat Manager"====

Tomcati haldusrakendus "Tomcat Manager" (antud alamjaotuses lihtsalt haldusrakendus) on Tomcati enda veebiaplikatioon Tomcati brauseripõhiseks kaughalduseks, võimaldades muu hulgas järgnevat [http://tomcat.apache.org/tomcat-8.0-doc/manager-howto.html#Introduction 1]:
* Rakendada uue veebiaplikatsiooni war-faili üleslaadimisega;
* Näha kõiki rakendatud veebiaplikatsioone koos aktiivsete sessioonidega;
* Taasrakendada veebirakendust, näiteks veebiarhiivi pakitud klassifailide /WEB-INF/classes või teekide /WEB-INF/lib uuendamisel, kinnijooksmisel jms.;
* Peatada veebirakendust ilma serverist eemaldamata, samuti koos serverist eemaldamisega;
* Vaadata operatsioonisüsteemi ja Java parameetrite väärtusi;
* Näha kõiki saadaolevaid JNDI ressursse, k.a. andmebaasiühendusi, mis aitavad rakenduste programmeerijail defineerida <ResourceLink> elemendid web.xml konfiguratsioonifailis.

Tomcati installatsioon sisaldab haldusrakendust juba vaikimisi. Haldusrakenduse töölepanemiseks tuleb peremeesmasina konfiguratsioonikataloogi $CATALINA_BASE/conf/[enginename]/[hostname] lisada ka fail manager.xml. Vaikimisi valmiskonfigureeritud testrakendusel on see fail juba olemas asukohas $CATALINA_BASE/conf/Catalina/localhost/manager.xml . Rakendus asub vaikimisi aadressil http://[host]/manager/ , vaikimisi konfiguratsioone kasutades lahendub see asukohaks http://localhost:8080/manager/ . [http://tomcat.apache.org/tomcat-8.0-doc/manager-howto.html#Configuring_Manager_Application_Access 1]

====="Tomcat Manager" ligipääsu konfigureerimine=====

Vaikimisi on turvalisuspõhjustel ligipääs haldusrakendusele maha keeratud. Mismoodi täpselt kasutajatel ligipääsu võimaldada sõltub kasutatavast valdusest (realm). Vaikimisi defineerib $CATALINA_BASE/conf/server.xml valduseks "MemoryRealm". Vaikimisi loeb valdus "MemoryRealm" kasutajad failist $CATALINA_BASE/conf/tomcat-users.xml. Antud failis tuleb iga kasutaja defineerida omaette märgendiga <user>, mis näeb välja umbes järgmine [http://tomcat.apache.org/tomcat-8.0-doc/manager-howto.html#Configuring_Manager_Application_Access 1]:
<pre>
<user name="craig" password="secret" roles="manager-gui,manager-script" />
</pre>

Antud kasutajale on defineeritud korraga kaks rolli. Ligipääsu võimaldamiseks tulebki lihtsamal juhul kasutajatefailis $CATALINA_BASE/conf/tomcat-users.xml defineerida enda kasutaja. Kasutaja rolliks võib määrata näiteks "manager-gui", mis võimaldab ligipääsu kogu HTML liidese funktsionaalsusele.

Teised valdused on "JDBCRealm", mille puhul hoitakse kasutajatega seonduvat infot andmebaasis ja JNDIRealm, mille puhul kasutatakse lihtsustatud kataloogisirvimise protokolli (LDAP).
Lisaks saab haldusrakendusele keelata ligipääsu mujalt kui kindlaksmääratud IP-aadressidelt, lisades filtri "RemoteAddrValve" või "RemoteHostValve" konfigureerimisfaili manager.xml näiteks järgmiselt [http://tomcat.apache.org/tomcat-8.0-doc/manager-howto.html#Introduction 1]:
<pre>
<Context privileged="true">
<Valve className="org.apache.catalina.valves.RemoteAddrValve"
allow="127\.0\.0\.1"/>
</Context>
</pre>

=====Juurutamine ja mahavõtmine haldusrakendusega "Tomcat Manager"=====

Juurutamiseks lae kõigepealt veebiarhiivifail üles, kasutades esilehel asuvat sektsiooni "WAR file to deploy". Veebiarhiivi üleslaadimise liides on kujutatud plidil 2.

[[File:tomcat_manager_war_upload.png|600px|thumb|right|Pilt 2: Veebiarhiivi üleslaadimise nupp]]

Rakendus kuvatakse seejärel hallatavate rakenduste nimekirjas. Kui konteiner pole seadistatud üleslaetud aplikatsiooni kohe ka ise rakendama, tuleb vajutada "Start". Rakenduse peatamiseks kasuta "Stop", uuesti rakendamiseks "Redeploy" ja serverist eemaldamiseks "Undeploy". Nupud on näha ka pildil 3 olevas rakenduste nimekirjas.


[[File:tomcat_manager_apps_list.png|1000px|thumb|Pilt 3: Rakenduste nimekiri Tomcati haldusrakenduses "Tomcat Manager"]]

==Näpunäiteid Tomcati reaalseks kasutamiseks==

===Juurutamise järjekord===

Tomcati käivitumisel juurutatakse aplikatsioonid sellises järjekorras [http://www.mulesoft.com/tomcat-deploy-procedures 2]:
# Konteinerisse kopeeritud kontekstikirjelduste järgi $CATALINA_BASE/conf/[EngineName]/[HostName]/[ApplicationName].xml ;
# Lahtipakitud rakendused "webapps" kataloogis;
# Pakitud rakenduste veebiarhiivid "webapps" kataloogis.

Seetõttu peaks käsitsi taasjuurutamisel kindluse mõttes eelnevalt kustutama rakenduse lahtipakitud dokumendipõhja kataloogi "webapps" kataloogist. Kontekstikirjelduse muutumisel tuleb jälgida, kas kirjeldus on juba kopeeritud serverisse ning vajadusel eelmise versiooni ümber muuta või kustutada.

===Reaalsele domeenile konfigureerimine===

Järgnevalt eeldame, et domeen ''www.minukodukas.ee'' on juba serverimasinaga seostatud. Et Tomcat hakkaks ka reaalselt Internetist tulevatele päringutele vastama, tuleb muuta failis $CATALINA_BASE/conf/server.xml konteinerile ''Catalina'' vastava teenusemärgendi sisu sarnaselt järgnevaga:

<pre>
<Service name="Catalina">
<Connector port="80" protocol="HTTP/1.1" connectionTimeout="20000" URIEncoding="UTF-8" redirectPort="8443" />
<Engine name="Catalina" defaultHost="www.minukodukas.ee">
<Host name="www.minukodukas.ee" appBase="webapps" unpackWARs="true" autoDeploy="false" deployOnStartup="false" xmlValidation="false" xmlNamespaceAware="false">
<Context path="" docBase="kodukas" debug="0" reloadable="true" />
</Host>
</Engine>
</Service>
</pre>

Ülal defineerime põhiliselt selle, et Tomcat kuulaks domeeni ''www.minukodukas.ee'' ja kasutaks HTTP päringute jaoks porti 80. Ühtlasti otsib Tomcat juurutatavat rakendust failist $CATALINA_BASE/webapps/kodukas.war. Kuna rajalisandiks on määratud tühi sõne (path=""), siis juurutataksegi aplikatsioon aadressile ''www.minukodukas.ee'' ilma rajalisandita (a'la ''www.minukodukas.ee/wiki''). Seetõttu pakitakse ka veebiarhiiv tegelikult lahti kataloogi $CATALINA_BASE/webapps/ROOT mitte kataloogi $CATALINA_BASE/webapps/kodukas nagu võiks eeldada.

===Käigultvahetus===

Võimaldamaks käigultvahetust (hot deployment) peab konteineri konfiguratsioonifailis $CATALINA_BASE/conf/server.xml olema peremehepõhise märgendi "Host" atribuudi "autoDeploy" väärtus "true". Sel juhul installeerib ja uuendab Tomcat aplikatsioone dünaamiliselt töötamise ajal. Kui väärtuseks on "false", käib installeerimine staatiliselt ning serverisse juurutamiseks tuleb teha konteineri taaskäivitus. Käigultvahetust saab määrata ka peremehe defineerimisel "Host Manager" rakendusega, mis on kättesaadav aadressil http://localhost:8080/host-manager/html . Kasutamiseks tuleb lisada oma kasutajale rolli "admin-gui" (vt. alajaotus ""Tomcat Manager" ligipääsu konfigureerimine"). Antud rakenduse veebiliides on kujutatud joonisel 4.

[[File:tomcat_host_manager_app.png|500px|thumb|Pilt 4: Tomcati haldusrakendus "Host Manage"]]

Käigultvahetust päästikuks on vaikimisi uuendatud veebiarhiivifaili või lahtipakitud veebirakenduse paigutamine "webapps" kataloogi. Käigultvahetuse päästikutele võib failis $CATALINA_BASE/conf/server.xml ka ise lisada kuulatavaid ressursse nagu web.xml muutmine või mõne teegifaili vahetamine (märgendis "Host").

===Klassiteekide väljatõstmine veebiarhiivifailist===

Kõik konteksti poolt kasutatavad Java klassiteegid võib pakendada veebiarhiivi sisse kataloogi "lib", kuid nii võib osutuda veebiarhiivi üleslaadimine ajakulukaks, eriti arenduskeskkonnas. Kui ei teki ohtu, et erinevad rakendused kasutavad sama teegi erinevaid versioone, siis on vahel parem lisada osa teeke konteineri kataloogi $CATALINA_BASE/libs, kust need tehakse siis konteineri poolt kättesaadavaks kõigile konteineris jooksutatavatele kontekstidele. Nii võib vähendada veebiarhiivi faili suurust märgatavalt, mis tõstab kokkuvõttes juurutamiskiirust ja ühes sellega programmeerijate tööviljakust.

===Mälukasutus===

Konteineri poolt kasutatavat mälu saab vaadata haldusrakendusest vajutades lingile "Server Status". Mälukasutus on toodud jaotuses "JVM", kus näidatakse nii maksimaalselt kättesaadavat mälu kui ka parasjagu reserveeritud mälu.

<pre>Free memory: 41.16 MB Total memory: 123.37 MB Max memory: 1027.56 MB</pre>

Mälu suurendamiseks võib näiteks defineerida skriptis $CATALINA_BASE/bin/catalina.sh muutuja "JAVA_OPTS" ning määrata Java mälukasutuse miinimum- ja maksimumväärtused sarnaselt järgnevatega [http://www.mkyong.com/tomcat/tomcat-javalangoutofmemoryerror-permgen-space/ 3]:
<pre>
JAVA_OPTS="-Xms1536m -Xmx1536m -XX:NewSize=256m -XX:MaxNewSize=256m -XX:PermSize=256m -XX:MaxPermSize=256m"
</pre>

===Logifailid===

Vaikimisi defineerib Tomcat failiga $CATALINA_BASE/conf/logging.properties viis logerit, mis tekitavad viis eraldi logifaili.

{| style="background:#cccc99;color:black;width:80%;" border="1" cellpadding="5" cellspacing="0" align="center"
|+ Tomcati tekitatavad logifailid "logs" kataloogis
!Fail !! Kasutus
|- style="background:white; color:black"
| style="width:300px" |catalina.out
| Tomcati käivitus- ja peatamisskriptide väljund, samuti juurutatud rakenduste prindilaused System.out ja veaväljundid System.err
|- style="background:white; color:black"
| style="width:300px" |catalina.[yyyy]-[mm]-[dd].log
| Pööratud (rotated) logifail catalina.out
|- style="background:white; color:black"
| style="width:300px" |host-manager.[yyyy]-[mm]-[dd].log
| Logi peremehehalduse rakendusele (rakendus on kättesaadav kohalikust masinast aadressil http://localhost:8080/host-manager/html )
|- style="background:white; color:black"
| style="width:300px" |localhost.[yyyy]-[mm]-[dd].log
| Peremehe "localhost" logi; mitme virtuaalse peremehe korral tekitatakse igale peremehele oma logi
|- style="background:white; color:black"
| style="width:300px" |localhost_access_log.[yyyy]-[mm]-[dd].txt
| Konteinerisse Internetist saabunud päringute logi
|- style="background:white; color:black"
| style="width:300px" |manager.[yyyy]-[mm]-[dd].log
| Haldusrakenduse tegevuste logi
|}

===Viiteid===

Palju vajalikku võib leida [http://tomcat.apache.org/tomcat-8.0-doc/index.html Tomcat 8 dokumentatsioonist]

Lisaks üks viide põhjalikule Tomcati versioon seitsme ülevaatele: http://www.ntu.edu.sg/home/ehchua/programming/howto/Tomcat_More.html

= Kasutatud materjalid =

#http://tomcat.apache.org/tomcat-8.0-doc/index.html
#http://www.mulesoft.com/tomcat-deploy-procedures
#http://www.mkyong.com/tomcat/tomcat-javalangoutofmemoryerror-permgen-space/

[[Category: Operatsioonisüsteemide administreerimine ja sidumine]]

Tomcat

2014-01-02T22:22:10Z

Kveskima: /* Juurutamine ja mahavõtmine haldusrakendusega "Tomcat Manager" */

==Autor==

Kristjan Veskimäe D32

2013

==Sissejuhatus==

Tomcat on vabalt kättesaadav server Java veebirakendustele. Põhimõtteliselt on tegemist Servlet/JSP spetsifikatsiooni toetava konteineriga. Kiire käivitumise ning rakenduste käigultvahetuse tõttu on Tomcat hea valik väiksemate ning keskmise suurusega Java veebirakenduste käitamiseks.

Antud töö kirjeldab Tomcati 8. versiooni. Põhiosa on üldiselt samasugune võrreldes paari eelmise versiooniga. Suuremad erinevused on versioonispetsiifilistes probleemides ja nende lahendamises, mida käesolev töö ei vaatle.

Töö vaatleb Tomcati paigaldamist ja seadistamist Unix-laadsesse keskkonda ning eeldab lugejalt algteadmisi sarnastes süsteemides. Tomcati on võimalik paigaldada ka Windows-keskkonda, kuid antud veebiserver eeldab kasutaja poolt käsureal töötamist ning Tomcati failihierarhias orienteerumist. Põhimõtteliselt on Java veebirakenduste arendamiseks IDE-abil võimalik siiski ka kasutada IDE-sse integreeritud Tomcati serverit - näiteks pakuvad sellist võimalust Eclipse EE ja NetBeans - kuid seda käesolev töö ei vaatle.

==Mõisted==

* '''Kontekst''' (context) - Tomcati mõistes üks konkreetne veebiaplikatsioon
* '''Konteiner''' (container) - veebiserver Tomcat ise
* '''Kontekstikirjeldus''' (context descriptor) - Tomcati-spetsiifiline konteksti konfiguratsioonimääratlus; peremehepõhine osa loetakse failist $CATALINA_HOME/conf/[enginename]/[hostname]/context.xml ja sellele lisatakse kontekstispetsiifilised täpsustused failist $CATALINA_BASE/conf/[enginename]/[hostname]/[webappname].xml; kontekstikirjeldus määrab näiteks nimed ressurssidele, sessioonihalduse parameetrid jmt. (olgu märgitud, et Tomcati varasemates versioonides sisaldusid kontekstikirjeldused põhikonfiguratsioonifailis server.xml)
* '''Dokumendipõhi''' (docBase) - kontekstile vastav kataloog Tomcati "webapps" kataloogis, mis tekib veebiaplikatsiooni serverisse rakendamisel
* '''Veebiarhiiv''' (Web application ARchive, war-file) - Java veebiaplikatsiooni jagatakse hea tava kohaselt selle üheainsa veebiarhiivi failina, mille laienditüübiks on "war". Tegemist on zip-protokolliga kokkupakitud kataloogiga, millel on Java veebirakenduste spetsifikatsioonile vastav ülesehitus. Siiski võib veebiaplikatsioon olla juurutamisel ka lahtipakendatud olekus (inglisekeelne termin on "war is exploded").

==Ülesehitus==

{| class="wikitable"
|+Kataloogid
|-
|style="color: green;" | $CATALINA_HOME
|baaskataloog, kuhu on Tomcat paigutatud
|-
|style="color: green;" | $CATALINA_BASE
|parasjagu töösoleva Tomcati eksemplari baaskataloog, mille alusel lahendatakse teed ülejäänud kataloogide ja failideni; ainult ühe kasutusel oleva Tomcati eksemplari puhul on see sama, mis $CATALINA_HOME

|-
|style="color: green;" | $CATALINA_BASE/bin
|serveri käivitus- ja abiskriptid
|-
|style="color: green;" | $CATALINA_BASE/conf
|konfiguratsioonifailid
|-
|style="color: green;" | $CATALINA_BASE/lib
|Tomcatile vaikimisi kättesaadavad Java klassiteegid (class libraries) ehk .jar-failid kuhu on Java kompileeritud kood kokku pakendatud
|-
|style="color: green;" | $CATALINA_BASE/logs
|logifailid paigutatakse vaikimisi siia
|-
|style="color: green;" | $CATALINA_BASE/webapps
|kataloog, kuhu paigutatakse serverisse juurutatavad veebiaplikatsioonid

|}

{| class="wikitable"
|+Mõned olulisemad failid
|-
|style="color: green;" | $CATALINA_BASE/bin/startup.sh
|serveri käivitusskript
|-
|style="color: green;" | $CATALINA_BASE/bin/shutdown.sh
|serveri peatusskript

|-
|style="color: green;" | $CATALINA_BASE/conf/server.xml
| konteineri peamine konfiguratsioonifail
|-
|style="color: green;" | $CATALINA_BASE/conf/[enginename]/[hostname]/[webappname].xml
|serveri administraatori jaoks konteinerisse endasse ümber kopeeritud rakendusepõhine kontekstikirjelduse konfiguratsioon failist $CATALINA_BASE/webapps/[ApplicationName]/META-INF/context.xml
|-
|style="color: green;" | $CATALINA_BASE/conf/[enginename]/[hostname]/context.xml
| fail, mis aitab administraatoril konteksti kohta käivat infot kirjeldada peremeesmasina-põhiselt ja halduseks mõeldud automaat-tööriistadel (näiteks Tomcat Manager ja TCD) oma tööd teha
|-
|style="color: green;" | $CATALINA_BASE/$CATALINA_BASE/conf/[enginename]/[hostname]/manager.xml
|fail, mis võimaldab lisada rakendustele ligipääsufiltreid
|-
|style="color: green;" | $CATALINA_BASE/webapps/[webappname]/META-INF/context.xml
|kontekstikirjeldusfail, mille veebirakenduse programmeerija on pakendanud oma aplikatsiooniga kaasa ning millega ta saab võimaluse kontekstikirjeldust omalt poolt mõjutada; kirjutatakse rakenduse uuestijuurutamisel üle, mistõttu administraator peaks muutma selle asemel konteinerisse ümber kopeeritud püsieksemplari $CATALINA_BASE/conf/[enginename]/[hostname]/context.xml
|-
|style="color: green;" | $CATALINA_BASE/webapps/[webappname]/WEB-INF/web.xml
|ka üks oluline Java veebiaplikatsiooni konfiguratsioonifail, mille pakendatakse koos veebiarhiiviga; enamasti muudab seda ainult programeerija; määrab muu hulgas millised aplikatsiooni osad vajavad autentimist või kui kiiresti veebisessioon aegub
|}

==Installeerimine==

===Installeerimine paketihalduriga===

<pre>
apt-cache search tomcat
apt-get install tomcat[version]-webapps
apt-get install tomcat[version]-admin
apt-get install tomcat[version]
</pre>

===Installeerimine käsitsi===

Paketihalduriga installeerides ei pruugi viimane Tomcati versioon olla kättesaadav ja see pakub ka vähem võimalusi kataloogide määramiseks jms. Käsitsi installeerimiseks tuleb laadida Tomcat kodulehelt alla. Lahtipakkimisel tekib kataloog, milles sisalduv fail "RUNNING.txt" on kõige kindlam allikas installeerimisel tekkivate probleemide vältimiseks ning lahendamiseks.

Vajaliku versiooni installeerimisfaili asukoha saab vaadata Tomcati kodulehelt sektsioonist "Download". Järgnevas näites installeerime Tomcati kõige uuema ebastabiilse kandidaatversiooni, mida näitab nimes sisalduv RC ehk "release candidate". Produktsioonikeskkonda tuleks siiski valida stabiilse versiooni. Käsitsi installeerimine on sarnane järgmisega:
<pre>
wget http://mirror.nexcess.net/apache/tomcat/tomcat-8/v8.0.0-RC5/bin/apache-tomcat-8.0.0-RC5.tar.gz
tar -zxvf apache-tomcat-8.0.0-RC5.tar.gz
mv /Users/kristjanveskimae/downloads/apache-tomcat-8.0.0-RC5 /usr/local/apache-tomcat-8.0.0-RC5
rm -f /Library/Tomcat
ln -s /usr/local/apache-tomcat-8.0.0-RC5/ /Library/Tomcat
chown -R kristjanveskimae /Library/Tomcat
chmod +x /Library/Tomcat/bin/*.sh
</pre>

==Käivitamine ja aplikatsiooni juurutamine==

===Konteineri käivitamine===

Tomcati käivitamise eelduseks on Java paigaldamine masinasse ning keskkonnamuutujate "JAVA_HOME" ja "JRE_HOME" defineerimine. Peale installeerimist võib kasutada skripte kataloogist $CATALINA_BASE/bin . Järgneb üks võimalik käivitamise ja peatamise näide, mis on kasutatav eelnevalt kirjeldatud käsitsi installeerimise juhul:
<pre>
/Library/Tomcat/bin/startup.sh
</pre>
ja peatamiseks
<pre>
/Library/Tomcat/bin/shutdown.sh
</pre>

===Näiteaplikatsiooni juurutamine===

Java veebiaplikatsiooni jagatakse hea tava kohaselt üheainsa veebiarhiivi failina. Siiski võib Tomcati juurutada ka lahtipakendatud olekus ("exploded") Java veebiaplikatsiooni.

====Käsitsi juurutamine ja mahavõtmine====

Näiteaplikatsiooni juurutamiseks lae selle veebiarhiivifail alla ning kopeeri oma konteineri juurutamiskataloogi 'webapps':
<pre>wget http://tomcat.apache.org/tomcat-8.0-doc/appdev/sample/sample.war
cp /Users/kristjanveskimae/downloads/sample.war /Library/Tomcat/webapps/sample.war</pre>

[[File:sample_app.png|400px|thumb|right|Pilt 1: Õnnestunult rakendatud näiteaplikatsioon]]

Kui konfiguratsioonifailis $CATALINA_BASE/conf/server.xml on märgendi "Host" atribuudi "autoDeploy" väärtus "true", installeerib ja uuendab Tomcat aplikatsioone dünaamiliselt töötamise ajal. Kui väärtuseks on "false", käib installeerimine staatiliselt ning serverisse juurutamiseks tuleb teha konteineri taaskäivitus. [http://tomcat.apache.org/tomcat-8.0-doc/manager-howto.html#Deploy_A_New_Application_from_a_Local_Path 1] Mõlemal juhul pakib konteiner arhiveeritud faili ise lahti samasse kausta $CATALINA_BASE/webapps ning ka juurutab selle. Tekkiv aplikatsioon on lokaalsest masinast seejärel kättesaadav aadressil http://localhost:8080/sample/ . Kui rakendamine õnnestub, siis peaks olema brauserist nähtav sarnane lehekülg nagu pildil 1.

Veebirakenduse käsitsi mahavõtmiseks tuleb kustutada talle vastav dokumendipõhja kataloog "webapps" kataloogist. Samuti tuleks kustutada .war-fail olemaks kindel, et Tomcat ei rakenda uuel käivitamisel veebiaplikatsiooni veebiarhiivifailist. Veelgi lihtsam on mahavõtmine brauseriga haldusrakenduse kaudu.

Rakenduste baaskataloogi "webapps" asukohta saab muuta failis $CATALINA_BASE/conf/server.xml peremehepõhiselt määratava atribuudiga "appBase", sealjuures Tomcati vaikimisi peremees ehk "Host" on "localhost".

====Tomcati vahendid juurutamiseks====

Veebiaplikatsioonide juurutamine ja mahajuurutamine on võimalik ka kaughalduse teel tänu Tomcati internetipõhisele haldusrakendusele. Näiteks saab veebibrauserit kasutades teha serveri põhitoiminguid Tomcati enda HTML-põhise rakendusega "Tomcat Manager". Veebipõhine haldusrakendus töötab ka käsupõhise veebiteenusena, millele on valmis ehitatud Anti ja Maveni integratsioonid. Samuti eksisteerib käsurea kliendirakendus TCD (Tomcat Client Deployer). TCD ei kuulu Tomcati baaskoosseisu, kuid pakub peale serveri administreerimise tavatoimingute ka lisafunktsionaalsust nagu veebirakenduse kokkukompileerimine ja pakendamine. [http://tomcat.apache.org/tomcat-8.0-doc/manager-howto.html#Configuring_Manager_Application_Access 1]

====Haldurakendus "Tomcat Manager"====

Tomcati haldusrakendus "Tomcat Manager" (antud alamjaotuses lihtsalt haldusrakendus) on Tomcati enda veebiaplikatioon Tomcati brauseripõhiseks kaughalduseks, võimaldades muu hulgas järgnevat [http://tomcat.apache.org/tomcat-8.0-doc/manager-howto.html#Introduction 1]:
* Rakendada uue veebiaplikatsiooni war-faili üleslaadimisega;
* Näha kõiki rakendatud veebiaplikatsioone koos aktiivsete sessioonidega;
* Taasrakendada veebirakendust, näiteks veebiarhiivi pakitud klassifailide /WEB-INF/classes või teekide /WEB-INF/lib uuendamisel, kinnijooksmisel jms.;
* Peatada veebirakendust ilma serverist eemaldamata, samuti koos serverist eemaldamisega;
* Vaadata operatsioonisüsteemi ja Java parameetrite väärtusi;
* Näha kõiki saadaolevaid JNDI ressursse, k.a. andmebaasiühendusi, mis aitavad rakenduste programmeerijail defineerida <ResourceLink> elemendid web.xml konfiguratsioonifailis.

Tomcati installatsioon sisaldab haldusrakendust juba vaikimisi. Haldusrakenduse töölepanemiseks tuleb peremeesmasina konfiguratsioonikataloogi $CATALINA_BASE/conf/[enginename]/[hostname] lisada ka fail manager.xml. Vaikimisi valmiskonfigureeritud testrakendusel on see fail juba olemas asukohas $CATALINA_BASE/conf/Catalina/localhost/manager.xml . Rakendus asub vaikimisi aadressil http://[host]/manager/ , vaikimisi konfiguratsioone kasutades lahendub see asukohaks http://localhost:8080/manager/ . [http://tomcat.apache.org/tomcat-8.0-doc/manager-howto.html#Configuring_Manager_Application_Access 1]

====="Tomcat Manager" ligipääsu konfigureerimine=====

Vaikimisi on turvalisuspõhjustel ligipääs haldusrakendusele maha keeratud. Mismoodi täpselt kasutajatel ligipääsu võimaldada sõltub kasutatavast valdusest (realm). Vaikimisi defineerib $CATALINA_BASE/conf/server.xml valduseks "MemoryRealm". Vaikimisi loeb valdus "MemoryRealm" kasutajad failist $CATALINA_BASE/conf/tomcat-users.xml. Antud failis tuleb iga kasutaja defineerida omaette märgendiga <user>, mis näeb välja umbes järgmine [http://tomcat.apache.org/tomcat-8.0-doc/manager-howto.html#Configuring_Manager_Application_Access 1]:
<pre>
<user name="craig" password="secret" roles="manager-gui,manager-script" />
</pre>

Antud kasutajale on defineeritud korraga kaks rolli. Ligipääsu võimaldamiseks tulebki lihtsamal juhul kasutajatefailis $CATALINA_BASE/conf/tomcat-users.xml defineerida enda kasutaja. Kasutaja rolliks võib määrata näiteks "manager-gui", mis võimaldab ligipääsu kogu HTML liidese funktsionaalsusele.

Teised valdused on "JDBCRealm", mille puhul hoitakse kasutajatega seonduvat infot andmebaasis ja JNDIRealm, mille puhul kasutatakse lihtsustatud kataloogisirvimise protokolli (LDAP).
Lisaks saab haldusrakendusele keelata ligipääsu mujalt kui kindlaksmääratud IP-aadressidelt, lisades filtri "RemoteAddrValve" või "RemoteHostValve" konfigureerimisfaili manager.xml näiteks järgmiselt [http://tomcat.apache.org/tomcat-8.0-doc/manager-howto.html#Introduction 1]:
<pre>
<Context privileged="true">
<Valve className="org.apache.catalina.valves.RemoteAddrValve"
allow="127\.0\.0\.1"/>
</Context>
</pre>

=====Juurutamine ja mahavõtmine haldusrakendusega "Tomcat Manager"=====

Juurutamiseks lae kõigepealt veebiarhiivifail üles, kasutades esilehel asuvat sektsiooni "WAR file to deploy". Veebiarhiivi üleslaadimise liides on kujutatud plidil 2.

[[File:tomcat_manager_war_upload.png|600px|thumb|right|Pilt 2: Veebiarhiivi üleslaadimise nupp]]

Rakendus kuvatakse seejärel hallatavate rakenduste nimekirjas. Kui konteiner pole seadistatud üleslaetud aplikatsiooni kohe ka ise rakendama, tuleb vajutada "Start". Rakenduse peatamiseks kasuta "Stop", uuesti rakendamiseks "Redeploy" ja serverist eemaldamiseks "Undeploy". Nupud on näha ka pildil 3 olevas rakenduste nimekirjas.


[[File:tomcat_manager_apps_list.png|1000px|thumb|Pilt 3: Rakenduste nimekiri Tomcati haldusrakenduses ""Tomcat Manager""]]

==Näpunäiteid Tomcati reaalseks kasutamiseks==

===Juurutamise järjekord===

Tomcati käivitumisel juurutatakse aplikatsioonid sellises järjekorras [http://www.mulesoft.com/tomcat-deploy-procedures 2]:
# Konteinerisse kopeeritud kontekstikirjelduste järgi $CATALINA_BASE/conf/[EngineName]/[HostName]/[ApplicationName].xml ;
# Lahtipakitud rakendused "webapps" kataloogis;
# Pakitud rakenduste veebiarhiivid "webapps" kataloogis.

Seetõttu peaks käsitsi taasjuurutamisel kindluse mõttes eelnevalt kustutama rakenduse lahtipakitud dokumendipõhja kataloogi "webapps" kataloogist. Kontekstikirjelduse muutumisel tuleb jälgida, kas kirjeldus on juba kopeeritud serverisse ning vajadusel eelmise versiooni ümber muuta või kustutada.

===Reaalsele domeenile konfigureerimine===

Järgnevalt eeldame, et domeen ''www.minukodukas.ee'' on juba serverimasinaga seostatud. Et Tomcat hakkaks ka reaalselt Internetist tulevatele päringutele vastama, tuleb muuta failis $CATALINA_BASE/conf/server.xml konteinerile ''Catalina'' vastava teenusemärgendi sisu sarnaselt järgnevaga:

<pre>
<Service name="Catalina">
<Connector port="80" protocol="HTTP/1.1" connectionTimeout="20000" URIEncoding="UTF-8" redirectPort="8443" />
<Engine name="Catalina" defaultHost="www.minukodukas.ee">
<Host name="www.minukodukas.ee" appBase="webapps" unpackWARs="true" autoDeploy="false" deployOnStartup="false" xmlValidation="false" xmlNamespaceAware="false">
<Context path="" docBase="kodukas" debug="0" reloadable="true" />
</Host>
</Engine>
</Service>
</pre>

Ülal defineerime põhiliselt selle, et Tomcat kuulaks domeeni ''www.minukodukas.ee'' ja kasutaks HTTP päringute jaoks porti 80. Ühtlasti otsib Tomcat juurutatavat rakendust failist $CATALINA_BASE/webapps/kodukas.war. Kuna rajalisandiks on määratud tühi sõne (path=""), siis juurutataksegi aplikatsioon aadressile ''www.minukodukas.ee'' ilma rajalisandita (a'la ''www.minukodukas.ee/wiki''). Seetõttu pakitakse ka veebiarhiiv tegelikult lahti kataloogi $CATALINA_BASE/webapps/ROOT mitte kataloogi $CATALINA_BASE/webapps/kodukas nagu võiks eeldada.

===Käigultvahetus===

Võimaldamaks käigultvahetust (hot deployment) peab konteineri konfiguratsioonifailis $CATALINA_BASE/conf/server.xml olema peremehepõhise märgendi "Host" atribuudi "autoDeploy" väärtus "true". Sel juhul installeerib ja uuendab Tomcat aplikatsioone dünaamiliselt töötamise ajal. Kui väärtuseks on "false", käib installeerimine staatiliselt ning serverisse juurutamiseks tuleb teha konteineri taaskäivitus. Käigultvahetust saab määrata ka peremehe defineerimisel "Host Manager" rakendusega, mis on kättesaadav aadressil http://localhost:8080/host-manager/html . Kasutamiseks tuleb lisada oma kasutajale rolli "admin-gui" (vt. alajaotus ""Tomcat Manager" ligipääsu konfigureerimine"). Antud rakenduse veebiliides on kujutatud joonisel 4.

[[File:tomcat_host_manager_app.png|500px|thumb|Pilt 4: Tomcati haldusrakendus "Host Manage"]]

Käigultvahetust päästikuks on vaikimisi uuendatud veebiarhiivifaili või lahtipakitud veebirakenduse paigutamine "webapps" kataloogi. Käigultvahetuse päästikutele võib failis $CATALINA_BASE/conf/server.xml ka ise lisada kuulatavaid ressursse nagu web.xml muutmine või mõne teegifaili vahetamine (märgendis "Host").

===Klassiteekide väljatõstmine veebiarhiivifailist===

Kõik konteksti poolt kasutatavad Java klassiteegid võib pakendada veebiarhiivi sisse kataloogi "lib", kuid nii võib osutuda veebiarhiivi üleslaadimine ajakulukaks, eriti arenduskeskkonnas. Kui ei teki ohtu, et erinevad rakendused kasutavad sama teegi erinevaid versioone, siis on vahel parem lisada osa teeke konteineri kataloogi $CATALINA_BASE/libs, kust need tehakse siis konteineri poolt kättesaadavaks kõigile konteineris jooksutatavatele kontekstidele. Nii võib vähendada veebiarhiivi faili suurust märgatavalt, mis tõstab kokkuvõttes juurutamiskiirust ja ühes sellega programmeerijate tööviljakust.

===Mälukasutus===

Konteineri poolt kasutatavat mälu saab vaadata haldusrakendusest vajutades lingile "Server Status". Mälukasutus on toodud jaotuses "JVM", kus näidatakse nii maksimaalselt kättesaadavat mälu kui ka parasjagu reserveeritud mälu.

<pre>Free memory: 41.16 MB Total memory: 123.37 MB Max memory: 1027.56 MB</pre>

Mälu suurendamiseks võib näiteks defineerida skriptis $CATALINA_BASE/bin/catalina.sh muutuja "JAVA_OPTS" ning määrata Java mälukasutuse miinimum- ja maksimumväärtused sarnaselt järgnevatega [http://www.mkyong.com/tomcat/tomcat-javalangoutofmemoryerror-permgen-space/ 3]:
<pre>
JAVA_OPTS="-Xms1536m -Xmx1536m -XX:NewSize=256m -XX:MaxNewSize=256m -XX:PermSize=256m -XX:MaxPermSize=256m"
</pre>

===Logifailid===

Vaikimisi defineerib Tomcat failiga $CATALINA_BASE/conf/logging.properties viis logerit, mis tekitavad viis eraldi logifaili.

{| style="background:#cccc99;color:black;width:80%;" border="1" cellpadding="5" cellspacing="0" align="center"
|+ Tomcati tekitatavad logifailid "logs" kataloogis
!Fail !! Kasutus
|- style="background:white; color:black"
| style="width:300px" |catalina.out
| Tomcati käivitus- ja peatamisskriptide väljund, samuti juurutatud rakenduste prindilaused System.out ja veaväljundid System.err
|- style="background:white; color:black"
| style="width:300px" |catalina.[yyyy]-[mm]-[dd].log
| Pööratud (rotated) logifail catalina.out
|- style="background:white; color:black"
| style="width:300px" |host-manager.[yyyy]-[mm]-[dd].log
| Logi peremehehalduse rakendusele (rakendus on kättesaadav kohalikust masinast aadressil http://localhost:8080/host-manager/html )
|- style="background:white; color:black"
| style="width:300px" |localhost.[yyyy]-[mm]-[dd].log
| Peremehe "localhost" logi; mitme virtuaalse peremehe korral tekitatakse igale peremehele oma logi
|- style="background:white; color:black"
| style="width:300px" |localhost_access_log.[yyyy]-[mm]-[dd].txt
| Konteinerisse Internetist saabunud päringute logi
|- style="background:white; color:black"
| style="width:300px" |manager.[yyyy]-[mm]-[dd].log
| Haldusrakenduse tegevuste logi
|}

===Viiteid===

Palju vajalikku võib leida [http://tomcat.apache.org/tomcat-8.0-doc/index.html Tomcat 8 dokumentatsioonist]

Lisaks üks viide põhjalikule Tomcati versioon seitsme ülevaatele: http://www.ntu.edu.sg/home/ehchua/programming/howto/Tomcat_More.html

= Kasutatud materjalid =

#http://tomcat.apache.org/tomcat-8.0-doc/index.html
#http://www.mulesoft.com/tomcat-deploy-procedures
#http://www.mkyong.com/tomcat/tomcat-javalangoutofmemoryerror-permgen-space/

[[Category: Operatsioonisüsteemide administreerimine ja sidumine]]

Tomcat

2014-01-02T22:21:16Z

Kveskima: /* Käigultvahetus */

==Autor==

Kristjan Veskimäe D32

2013

==Sissejuhatus==

Tomcat on vabalt kättesaadav server Java veebirakendustele. Põhimõtteliselt on tegemist Servlet/JSP spetsifikatsiooni toetava konteineriga. Kiire käivitumise ning rakenduste käigultvahetuse tõttu on Tomcat hea valik väiksemate ning keskmise suurusega Java veebirakenduste käitamiseks.

Antud töö kirjeldab Tomcati 8. versiooni. Põhiosa on üldiselt samasugune võrreldes paari eelmise versiooniga. Suuremad erinevused on versioonispetsiifilistes probleemides ja nende lahendamises, mida käesolev töö ei vaatle.

Töö vaatleb Tomcati paigaldamist ja seadistamist Unix-laadsesse keskkonda ning eeldab lugejalt algteadmisi sarnastes süsteemides. Tomcati on võimalik paigaldada ka Windows-keskkonda, kuid antud veebiserver eeldab kasutaja poolt käsureal töötamist ning Tomcati failihierarhias orienteerumist. Põhimõtteliselt on Java veebirakenduste arendamiseks IDE-abil võimalik siiski ka kasutada IDE-sse integreeritud Tomcati serverit - näiteks pakuvad sellist võimalust Eclipse EE ja NetBeans - kuid seda käesolev töö ei vaatle.

==Mõisted==

* '''Kontekst''' (context) - Tomcati mõistes üks konkreetne veebiaplikatsioon
* '''Konteiner''' (container) - veebiserver Tomcat ise
* '''Kontekstikirjeldus''' (context descriptor) - Tomcati-spetsiifiline konteksti konfiguratsioonimääratlus; peremehepõhine osa loetakse failist $CATALINA_HOME/conf/[enginename]/[hostname]/context.xml ja sellele lisatakse kontekstispetsiifilised täpsustused failist $CATALINA_BASE/conf/[enginename]/[hostname]/[webappname].xml; kontekstikirjeldus määrab näiteks nimed ressurssidele, sessioonihalduse parameetrid jmt. (olgu märgitud, et Tomcati varasemates versioonides sisaldusid kontekstikirjeldused põhikonfiguratsioonifailis server.xml)
* '''Dokumendipõhi''' (docBase) - kontekstile vastav kataloog Tomcati "webapps" kataloogis, mis tekib veebiaplikatsiooni serverisse rakendamisel
* '''Veebiarhiiv''' (Web application ARchive, war-file) - Java veebiaplikatsiooni jagatakse hea tava kohaselt selle üheainsa veebiarhiivi failina, mille laienditüübiks on "war". Tegemist on zip-protokolliga kokkupakitud kataloogiga, millel on Java veebirakenduste spetsifikatsioonile vastav ülesehitus. Siiski võib veebiaplikatsioon olla juurutamisel ka lahtipakendatud olekus (inglisekeelne termin on "war is exploded").

==Ülesehitus==

{| class="wikitable"
|+Kataloogid
|-
|style="color: green;" | $CATALINA_HOME
|baaskataloog, kuhu on Tomcat paigutatud
|-
|style="color: green;" | $CATALINA_BASE
|parasjagu töösoleva Tomcati eksemplari baaskataloog, mille alusel lahendatakse teed ülejäänud kataloogide ja failideni; ainult ühe kasutusel oleva Tomcati eksemplari puhul on see sama, mis $CATALINA_HOME

|-
|style="color: green;" | $CATALINA_BASE/bin
|serveri käivitus- ja abiskriptid
|-
|style="color: green;" | $CATALINA_BASE/conf
|konfiguratsioonifailid
|-
|style="color: green;" | $CATALINA_BASE/lib
|Tomcatile vaikimisi kättesaadavad Java klassiteegid (class libraries) ehk .jar-failid kuhu on Java kompileeritud kood kokku pakendatud
|-
|style="color: green;" | $CATALINA_BASE/logs
|logifailid paigutatakse vaikimisi siia
|-
|style="color: green;" | $CATALINA_BASE/webapps
|kataloog, kuhu paigutatakse serverisse juurutatavad veebiaplikatsioonid

|}

{| class="wikitable"
|+Mõned olulisemad failid
|-
|style="color: green;" | $CATALINA_BASE/bin/startup.sh
|serveri käivitusskript
|-
|style="color: green;" | $CATALINA_BASE/bin/shutdown.sh
|serveri peatusskript

|-
|style="color: green;" | $CATALINA_BASE/conf/server.xml
| konteineri peamine konfiguratsioonifail
|-
|style="color: green;" | $CATALINA_BASE/conf/[enginename]/[hostname]/[webappname].xml
|serveri administraatori jaoks konteinerisse endasse ümber kopeeritud rakendusepõhine kontekstikirjelduse konfiguratsioon failist $CATALINA_BASE/webapps/[ApplicationName]/META-INF/context.xml
|-
|style="color: green;" | $CATALINA_BASE/conf/[enginename]/[hostname]/context.xml
| fail, mis aitab administraatoril konteksti kohta käivat infot kirjeldada peremeesmasina-põhiselt ja halduseks mõeldud automaat-tööriistadel (näiteks Tomcat Manager ja TCD) oma tööd teha
|-
|style="color: green;" | $CATALINA_BASE/$CATALINA_BASE/conf/[enginename]/[hostname]/manager.xml
|fail, mis võimaldab lisada rakendustele ligipääsufiltreid
|-
|style="color: green;" | $CATALINA_BASE/webapps/[webappname]/META-INF/context.xml
|kontekstikirjeldusfail, mille veebirakenduse programmeerija on pakendanud oma aplikatsiooniga kaasa ning millega ta saab võimaluse kontekstikirjeldust omalt poolt mõjutada; kirjutatakse rakenduse uuestijuurutamisel üle, mistõttu administraator peaks muutma selle asemel konteinerisse ümber kopeeritud püsieksemplari $CATALINA_BASE/conf/[enginename]/[hostname]/context.xml
|-
|style="color: green;" | $CATALINA_BASE/webapps/[webappname]/WEB-INF/web.xml
|ka üks oluline Java veebiaplikatsiooni konfiguratsioonifail, mille pakendatakse koos veebiarhiiviga; enamasti muudab seda ainult programeerija; määrab muu hulgas millised aplikatsiooni osad vajavad autentimist või kui kiiresti veebisessioon aegub
|}

==Installeerimine==

===Installeerimine paketihalduriga===

<pre>
apt-cache search tomcat
apt-get install tomcat[version]-webapps
apt-get install tomcat[version]-admin
apt-get install tomcat[version]
</pre>

===Installeerimine käsitsi===

Paketihalduriga installeerides ei pruugi viimane Tomcati versioon olla kättesaadav ja see pakub ka vähem võimalusi kataloogide määramiseks jms. Käsitsi installeerimiseks tuleb laadida Tomcat kodulehelt alla. Lahtipakkimisel tekib kataloog, milles sisalduv fail "RUNNING.txt" on kõige kindlam allikas installeerimisel tekkivate probleemide vältimiseks ning lahendamiseks.

Vajaliku versiooni installeerimisfaili asukoha saab vaadata Tomcati kodulehelt sektsioonist "Download". Järgnevas näites installeerime Tomcati kõige uuema ebastabiilse kandidaatversiooni, mida näitab nimes sisalduv RC ehk "release candidate". Produktsioonikeskkonda tuleks siiski valida stabiilse versiooni. Käsitsi installeerimine on sarnane järgmisega:
<pre>
wget http://mirror.nexcess.net/apache/tomcat/tomcat-8/v8.0.0-RC5/bin/apache-tomcat-8.0.0-RC5.tar.gz
tar -zxvf apache-tomcat-8.0.0-RC5.tar.gz
mv /Users/kristjanveskimae/downloads/apache-tomcat-8.0.0-RC5 /usr/local/apache-tomcat-8.0.0-RC5
rm -f /Library/Tomcat
ln -s /usr/local/apache-tomcat-8.0.0-RC5/ /Library/Tomcat
chown -R kristjanveskimae /Library/Tomcat
chmod +x /Library/Tomcat/bin/*.sh
</pre>

==Käivitamine ja aplikatsiooni juurutamine==

===Konteineri käivitamine===

Tomcati käivitamise eelduseks on Java paigaldamine masinasse ning keskkonnamuutujate "JAVA_HOME" ja "JRE_HOME" defineerimine. Peale installeerimist võib kasutada skripte kataloogist $CATALINA_BASE/bin . Järgneb üks võimalik käivitamise ja peatamise näide, mis on kasutatav eelnevalt kirjeldatud käsitsi installeerimise juhul:
<pre>
/Library/Tomcat/bin/startup.sh
</pre>
ja peatamiseks
<pre>
/Library/Tomcat/bin/shutdown.sh
</pre>

===Näiteaplikatsiooni juurutamine===

Java veebiaplikatsiooni jagatakse hea tava kohaselt üheainsa veebiarhiivi failina. Siiski võib Tomcati juurutada ka lahtipakendatud olekus ("exploded") Java veebiaplikatsiooni.

====Käsitsi juurutamine ja mahavõtmine====

Näiteaplikatsiooni juurutamiseks lae selle veebiarhiivifail alla ning kopeeri oma konteineri juurutamiskataloogi 'webapps':
<pre>wget http://tomcat.apache.org/tomcat-8.0-doc/appdev/sample/sample.war
cp /Users/kristjanveskimae/downloads/sample.war /Library/Tomcat/webapps/sample.war</pre>

[[File:sample_app.png|400px|thumb|right|Pilt 1: Õnnestunult rakendatud näiteaplikatsioon]]

Kui konfiguratsioonifailis $CATALINA_BASE/conf/server.xml on märgendi "Host" atribuudi "autoDeploy" väärtus "true", installeerib ja uuendab Tomcat aplikatsioone dünaamiliselt töötamise ajal. Kui väärtuseks on "false", käib installeerimine staatiliselt ning serverisse juurutamiseks tuleb teha konteineri taaskäivitus. [http://tomcat.apache.org/tomcat-8.0-doc/manager-howto.html#Deploy_A_New_Application_from_a_Local_Path 1] Mõlemal juhul pakib konteiner arhiveeritud faili ise lahti samasse kausta $CATALINA_BASE/webapps ning ka juurutab selle. Tekkiv aplikatsioon on lokaalsest masinast seejärel kättesaadav aadressil http://localhost:8080/sample/ . Kui rakendamine õnnestub, siis peaks olema brauserist nähtav sarnane lehekülg nagu pildil 1.

Veebirakenduse käsitsi mahavõtmiseks tuleb kustutada talle vastav dokumendipõhja kataloog "webapps" kataloogist. Samuti tuleks kustutada .war-fail olemaks kindel, et Tomcat ei rakenda uuel käivitamisel veebiaplikatsiooni veebiarhiivifailist. Veelgi lihtsam on mahavõtmine brauseriga haldusrakenduse kaudu.

Rakenduste baaskataloogi "webapps" asukohta saab muuta failis $CATALINA_BASE/conf/server.xml peremehepõhiselt määratava atribuudiga "appBase", sealjuures Tomcati vaikimisi peremees ehk "Host" on "localhost".

====Tomcati vahendid juurutamiseks====

Veebiaplikatsioonide juurutamine ja mahajuurutamine on võimalik ka kaughalduse teel tänu Tomcati internetipõhisele haldusrakendusele. Näiteks saab veebibrauserit kasutades teha serveri põhitoiminguid Tomcati enda HTML-põhise rakendusega "Tomcat Manager". Veebipõhine haldusrakendus töötab ka käsupõhise veebiteenusena, millele on valmis ehitatud Anti ja Maveni integratsioonid. Samuti eksisteerib käsurea kliendirakendus TCD (Tomcat Client Deployer). TCD ei kuulu Tomcati baaskoosseisu, kuid pakub peale serveri administreerimise tavatoimingute ka lisafunktsionaalsust nagu veebirakenduse kokkukompileerimine ja pakendamine. [http://tomcat.apache.org/tomcat-8.0-doc/manager-howto.html#Configuring_Manager_Application_Access 1]

====Haldurakendus "Tomcat Manager"====

Tomcati haldusrakendus "Tomcat Manager" (antud alamjaotuses lihtsalt haldusrakendus) on Tomcati enda veebiaplikatioon Tomcati brauseripõhiseks kaughalduseks, võimaldades muu hulgas järgnevat [http://tomcat.apache.org/tomcat-8.0-doc/manager-howto.html#Introduction 1]:
* Rakendada uue veebiaplikatsiooni war-faili üleslaadimisega;
* Näha kõiki rakendatud veebiaplikatsioone koos aktiivsete sessioonidega;
* Taasrakendada veebirakendust, näiteks veebiarhiivi pakitud klassifailide /WEB-INF/classes või teekide /WEB-INF/lib uuendamisel, kinnijooksmisel jms.;
* Peatada veebirakendust ilma serverist eemaldamata, samuti koos serverist eemaldamisega;
* Vaadata operatsioonisüsteemi ja Java parameetrite väärtusi;
* Näha kõiki saadaolevaid JNDI ressursse, k.a. andmebaasiühendusi, mis aitavad rakenduste programmeerijail defineerida <ResourceLink> elemendid web.xml konfiguratsioonifailis.

Tomcati installatsioon sisaldab haldusrakendust juba vaikimisi. Haldusrakenduse töölepanemiseks tuleb peremeesmasina konfiguratsioonikataloogi $CATALINA_BASE/conf/[enginename]/[hostname] lisada ka fail manager.xml. Vaikimisi valmiskonfigureeritud testrakendusel on see fail juba olemas asukohas $CATALINA_BASE/conf/Catalina/localhost/manager.xml . Rakendus asub vaikimisi aadressil http://[host]/manager/ , vaikimisi konfiguratsioone kasutades lahendub see asukohaks http://localhost:8080/manager/ . [http://tomcat.apache.org/tomcat-8.0-doc/manager-howto.html#Configuring_Manager_Application_Access 1]

====="Tomcat Manager" ligipääsu konfigureerimine=====

Vaikimisi on turvalisuspõhjustel ligipääs haldusrakendusele maha keeratud. Mismoodi täpselt kasutajatel ligipääsu võimaldada sõltub kasutatavast valdusest (realm). Vaikimisi defineerib $CATALINA_BASE/conf/server.xml valduseks "MemoryRealm". Vaikimisi loeb valdus "MemoryRealm" kasutajad failist $CATALINA_BASE/conf/tomcat-users.xml. Antud failis tuleb iga kasutaja defineerida omaette märgendiga <user>, mis näeb välja umbes järgmine [http://tomcat.apache.org/tomcat-8.0-doc/manager-howto.html#Configuring_Manager_Application_Access 1]:
<pre>
<user name="craig" password="secret" roles="manager-gui,manager-script" />
</pre>

Antud kasutajale on defineeritud korraga kaks rolli. Ligipääsu võimaldamiseks tulebki lihtsamal juhul kasutajatefailis $CATALINA_BASE/conf/tomcat-users.xml defineerida enda kasutaja. Kasutaja rolliks võib määrata näiteks "manager-gui", mis võimaldab ligipääsu kogu HTML liidese funktsionaalsusele.

Teised valdused on "JDBCRealm", mille puhul hoitakse kasutajatega seonduvat infot andmebaasis ja JNDIRealm, mille puhul kasutatakse lihtsustatud kataloogisirvimise protokolli (LDAP).
Lisaks saab haldusrakendusele keelata ligipääsu mujalt kui kindlaksmääratud IP-aadressidelt, lisades filtri "RemoteAddrValve" või "RemoteHostValve" konfigureerimisfaili manager.xml näiteks järgmiselt [http://tomcat.apache.org/tomcat-8.0-doc/manager-howto.html#Introduction 1]:
<pre>
<Context privileged="true">
<Valve className="org.apache.catalina.valves.RemoteAddrValve"
allow="127\.0\.0\.1"/>
</Context>
</pre>

=====Juurutamine ja mahavõtmine haldusrakendusega "Tomcat Manager"=====

Juurutamiseks lae kõigepealt veebiarhiivifail üles, kasutades esilehel asuvat sektsiooni "WAR file to deploy". Veebiarhiivi üleslaadimise liides on kujutatud plidil 2.

[[File:tomcat_manager_war_upload.png|600px|thumb|right|Pilt 2: Veebiarhiivi üleslaadimise nupp]]

Rakendus kuvatakse seejärel hallatavate rakenduste nimekirjas. Kui konteiner pole seadistatud üleslaetud aplikatsiooni kohe ka ise rakendama, tuleb vajutada "Start". Rakenduse peatamiseks kasuta "Stop", uuesti rakendamiseks "Redeploy" ja serverist eemaldamiseks "Undeploy". Nupud on näha ka pildil 3 olevas rakenduste nimekirjas.


[[File:tomcat_manager_apps_list.png|1000px|thumb|Pilt 3: Rakenduste nimekiri]]

==Näpunäiteid Tomcati reaalseks kasutamiseks==

===Juurutamise järjekord===

Tomcati käivitumisel juurutatakse aplikatsioonid sellises järjekorras [http://www.mulesoft.com/tomcat-deploy-procedures 2]:
# Konteinerisse kopeeritud kontekstikirjelduste järgi $CATALINA_BASE/conf/[EngineName]/[HostName]/[ApplicationName].xml ;
# Lahtipakitud rakendused "webapps" kataloogis;
# Pakitud rakenduste veebiarhiivid "webapps" kataloogis.

Seetõttu peaks käsitsi taasjuurutamisel kindluse mõttes eelnevalt kustutama rakenduse lahtipakitud dokumendipõhja kataloogi "webapps" kataloogist. Kontekstikirjelduse muutumisel tuleb jälgida, kas kirjeldus on juba kopeeritud serverisse ning vajadusel eelmise versiooni ümber muuta või kustutada.

===Reaalsele domeenile konfigureerimine===

Järgnevalt eeldame, et domeen ''www.minukodukas.ee'' on juba serverimasinaga seostatud. Et Tomcat hakkaks ka reaalselt Internetist tulevatele päringutele vastama, tuleb muuta failis $CATALINA_BASE/conf/server.xml konteinerile ''Catalina'' vastava teenusemärgendi sisu sarnaselt järgnevaga:

<pre>
<Service name="Catalina">
<Connector port="80" protocol="HTTP/1.1" connectionTimeout="20000" URIEncoding="UTF-8" redirectPort="8443" />
<Engine name="Catalina" defaultHost="www.minukodukas.ee">
<Host name="www.minukodukas.ee" appBase="webapps" unpackWARs="true" autoDeploy="false" deployOnStartup="false" xmlValidation="false" xmlNamespaceAware="false">
<Context path="" docBase="kodukas" debug="0" reloadable="true" />
</Host>
</Engine>
</Service>
</pre>

Ülal defineerime põhiliselt selle, et Tomcat kuulaks domeeni ''www.minukodukas.ee'' ja kasutaks HTTP päringute jaoks porti 80. Ühtlasti otsib Tomcat juurutatavat rakendust failist $CATALINA_BASE/webapps/kodukas.war. Kuna rajalisandiks on määratud tühi sõne (path=""), siis juurutataksegi aplikatsioon aadressile ''www.minukodukas.ee'' ilma rajalisandita (a'la ''www.minukodukas.ee/wiki''). Seetõttu pakitakse ka veebiarhiiv tegelikult lahti kataloogi $CATALINA_BASE/webapps/ROOT mitte kataloogi $CATALINA_BASE/webapps/kodukas nagu võiks eeldada.

===Käigultvahetus===

Võimaldamaks käigultvahetust (hot deployment) peab konteineri konfiguratsioonifailis $CATALINA_BASE/conf/server.xml olema peremehepõhise märgendi "Host" atribuudi "autoDeploy" väärtus "true". Sel juhul installeerib ja uuendab Tomcat aplikatsioone dünaamiliselt töötamise ajal. Kui väärtuseks on "false", käib installeerimine staatiliselt ning serverisse juurutamiseks tuleb teha konteineri taaskäivitus. Käigultvahetust saab määrata ka peremehe defineerimisel "Host Manager" rakendusega, mis on kättesaadav aadressil http://localhost:8080/host-manager/html . Kasutamiseks tuleb lisada oma kasutajale rolli "admin-gui" (vt. alajaotus ""Tomcat Manager" ligipääsu konfigureerimine"). Antud rakenduse veebiliides on kujutatud joonisel 4.

[[File:tomcat_host_manager_app.png|500px|thumb|Pilt 4: Tomcati haldusrakendus "Host Manage"]]

Käigultvahetust päästikuks on vaikimisi uuendatud veebiarhiivifaili või lahtipakitud veebirakenduse paigutamine "webapps" kataloogi. Käigultvahetuse päästikutele võib failis $CATALINA_BASE/conf/server.xml ka ise lisada kuulatavaid ressursse nagu web.xml muutmine või mõne teegifaili vahetamine (märgendis "Host").

===Klassiteekide väljatõstmine veebiarhiivifailist===

Kõik konteksti poolt kasutatavad Java klassiteegid võib pakendada veebiarhiivi sisse kataloogi "lib", kuid nii võib osutuda veebiarhiivi üleslaadimine ajakulukaks, eriti arenduskeskkonnas. Kui ei teki ohtu, et erinevad rakendused kasutavad sama teegi erinevaid versioone, siis on vahel parem lisada osa teeke konteineri kataloogi $CATALINA_BASE/libs, kust need tehakse siis konteineri poolt kättesaadavaks kõigile konteineris jooksutatavatele kontekstidele. Nii võib vähendada veebiarhiivi faili suurust märgatavalt, mis tõstab kokkuvõttes juurutamiskiirust ja ühes sellega programmeerijate tööviljakust.

===Mälukasutus===

Konteineri poolt kasutatavat mälu saab vaadata haldusrakendusest vajutades lingile "Server Status". Mälukasutus on toodud jaotuses "JVM", kus näidatakse nii maksimaalselt kättesaadavat mälu kui ka parasjagu reserveeritud mälu.

<pre>Free memory: 41.16 MB Total memory: 123.37 MB Max memory: 1027.56 MB</pre>

Mälu suurendamiseks võib näiteks defineerida skriptis $CATALINA_BASE/bin/catalina.sh muutuja "JAVA_OPTS" ning määrata Java mälukasutuse miinimum- ja maksimumväärtused sarnaselt järgnevatega [http://www.mkyong.com/tomcat/tomcat-javalangoutofmemoryerror-permgen-space/ 3]:
<pre>
JAVA_OPTS="-Xms1536m -Xmx1536m -XX:NewSize=256m -XX:MaxNewSize=256m -XX:PermSize=256m -XX:MaxPermSize=256m"
</pre>

===Logifailid===

Vaikimisi defineerib Tomcat failiga $CATALINA_BASE/conf/logging.properties viis logerit, mis tekitavad viis eraldi logifaili.

{| style="background:#cccc99;color:black;width:80%;" border="1" cellpadding="5" cellspacing="0" align="center"
|+ Tomcati tekitatavad logifailid "logs" kataloogis
!Fail !! Kasutus
|- style="background:white; color:black"
| style="width:300px" |catalina.out
| Tomcati käivitus- ja peatamisskriptide väljund, samuti juurutatud rakenduste prindilaused System.out ja veaväljundid System.err
|- style="background:white; color:black"
| style="width:300px" |catalina.[yyyy]-[mm]-[dd].log
| Pööratud (rotated) logifail catalina.out
|- style="background:white; color:black"
| style="width:300px" |host-manager.[yyyy]-[mm]-[dd].log
| Logi peremehehalduse rakendusele (rakendus on kättesaadav kohalikust masinast aadressil http://localhost:8080/host-manager/html )
|- style="background:white; color:black"
| style="width:300px" |localhost.[yyyy]-[mm]-[dd].log
| Peremehe "localhost" logi; mitme virtuaalse peremehe korral tekitatakse igale peremehele oma logi
|- style="background:white; color:black"
| style="width:300px" |localhost_access_log.[yyyy]-[mm]-[dd].txt
| Konteinerisse Internetist saabunud päringute logi
|- style="background:white; color:black"
| style="width:300px" |manager.[yyyy]-[mm]-[dd].log
| Haldusrakenduse tegevuste logi
|}

===Viiteid===

Palju vajalikku võib leida [http://tomcat.apache.org/tomcat-8.0-doc/index.html Tomcat 8 dokumentatsioonist]

Lisaks üks viide põhjalikule Tomcati versioon seitsme ülevaatele: http://www.ntu.edu.sg/home/ehchua/programming/howto/Tomcat_More.html

= Kasutatud materjalid =

#http://tomcat.apache.org/tomcat-8.0-doc/index.html
#http://www.mulesoft.com/tomcat-deploy-procedures
#http://www.mkyong.com/tomcat/tomcat-javalangoutofmemoryerror-permgen-space/

[[Category: Operatsioonisüsteemide administreerimine ja sidumine]]

Tomcat

2014-01-02T22:20:52Z

Kveskima: /* Käigultvahetus */

==Autor==

Kristjan Veskimäe D32

2013

==Sissejuhatus==

Tomcat on vabalt kättesaadav server Java veebirakendustele. Põhimõtteliselt on tegemist Servlet/JSP spetsifikatsiooni toetava konteineriga. Kiire käivitumise ning rakenduste käigultvahetuse tõttu on Tomcat hea valik väiksemate ning keskmise suurusega Java veebirakenduste käitamiseks.

Antud töö kirjeldab Tomcati 8. versiooni. Põhiosa on üldiselt samasugune võrreldes paari eelmise versiooniga. Suuremad erinevused on versioonispetsiifilistes probleemides ja nende lahendamises, mida käesolev töö ei vaatle.

Töö vaatleb Tomcati paigaldamist ja seadistamist Unix-laadsesse keskkonda ning eeldab lugejalt algteadmisi sarnastes süsteemides. Tomcati on võimalik paigaldada ka Windows-keskkonda, kuid antud veebiserver eeldab kasutaja poolt käsureal töötamist ning Tomcati failihierarhias orienteerumist. Põhimõtteliselt on Java veebirakenduste arendamiseks IDE-abil võimalik siiski ka kasutada IDE-sse integreeritud Tomcati serverit - näiteks pakuvad sellist võimalust Eclipse EE ja NetBeans - kuid seda käesolev töö ei vaatle.

==Mõisted==

* '''Kontekst''' (context) - Tomcati mõistes üks konkreetne veebiaplikatsioon
* '''Konteiner''' (container) - veebiserver Tomcat ise
* '''Kontekstikirjeldus''' (context descriptor) - Tomcati-spetsiifiline konteksti konfiguratsioonimääratlus; peremehepõhine osa loetakse failist $CATALINA_HOME/conf/[enginename]/[hostname]/context.xml ja sellele lisatakse kontekstispetsiifilised täpsustused failist $CATALINA_BASE/conf/[enginename]/[hostname]/[webappname].xml; kontekstikirjeldus määrab näiteks nimed ressurssidele, sessioonihalduse parameetrid jmt. (olgu märgitud, et Tomcati varasemates versioonides sisaldusid kontekstikirjeldused põhikonfiguratsioonifailis server.xml)
* '''Dokumendipõhi''' (docBase) - kontekstile vastav kataloog Tomcati "webapps" kataloogis, mis tekib veebiaplikatsiooni serverisse rakendamisel
* '''Veebiarhiiv''' (Web application ARchive, war-file) - Java veebiaplikatsiooni jagatakse hea tava kohaselt selle üheainsa veebiarhiivi failina, mille laienditüübiks on "war". Tegemist on zip-protokolliga kokkupakitud kataloogiga, millel on Java veebirakenduste spetsifikatsioonile vastav ülesehitus. Siiski võib veebiaplikatsioon olla juurutamisel ka lahtipakendatud olekus (inglisekeelne termin on "war is exploded").

==Ülesehitus==

{| class="wikitable"
|+Kataloogid
|-
|style="color: green;" | $CATALINA_HOME
|baaskataloog, kuhu on Tomcat paigutatud
|-
|style="color: green;" | $CATALINA_BASE
|parasjagu töösoleva Tomcati eksemplari baaskataloog, mille alusel lahendatakse teed ülejäänud kataloogide ja failideni; ainult ühe kasutusel oleva Tomcati eksemplari puhul on see sama, mis $CATALINA_HOME

|-
|style="color: green;" | $CATALINA_BASE/bin
|serveri käivitus- ja abiskriptid
|-
|style="color: green;" | $CATALINA_BASE/conf
|konfiguratsioonifailid
|-
|style="color: green;" | $CATALINA_BASE/lib
|Tomcatile vaikimisi kättesaadavad Java klassiteegid (class libraries) ehk .jar-failid kuhu on Java kompileeritud kood kokku pakendatud
|-
|style="color: green;" | $CATALINA_BASE/logs
|logifailid paigutatakse vaikimisi siia
|-
|style="color: green;" | $CATALINA_BASE/webapps
|kataloog, kuhu paigutatakse serverisse juurutatavad veebiaplikatsioonid

|}

{| class="wikitable"
|+Mõned olulisemad failid
|-
|style="color: green;" | $CATALINA_BASE/bin/startup.sh
|serveri käivitusskript
|-
|style="color: green;" | $CATALINA_BASE/bin/shutdown.sh
|serveri peatusskript

|-
|style="color: green;" | $CATALINA_BASE/conf/server.xml
| konteineri peamine konfiguratsioonifail
|-
|style="color: green;" | $CATALINA_BASE/conf/[enginename]/[hostname]/[webappname].xml
|serveri administraatori jaoks konteinerisse endasse ümber kopeeritud rakendusepõhine kontekstikirjelduse konfiguratsioon failist $CATALINA_BASE/webapps/[ApplicationName]/META-INF/context.xml
|-
|style="color: green;" | $CATALINA_BASE/conf/[enginename]/[hostname]/context.xml
| fail, mis aitab administraatoril konteksti kohta käivat infot kirjeldada peremeesmasina-põhiselt ja halduseks mõeldud automaat-tööriistadel (näiteks Tomcat Manager ja TCD) oma tööd teha
|-
|style="color: green;" | $CATALINA_BASE/$CATALINA_BASE/conf/[enginename]/[hostname]/manager.xml
|fail, mis võimaldab lisada rakendustele ligipääsufiltreid
|-
|style="color: green;" | $CATALINA_BASE/webapps/[webappname]/META-INF/context.xml
|kontekstikirjeldusfail, mille veebirakenduse programmeerija on pakendanud oma aplikatsiooniga kaasa ning millega ta saab võimaluse kontekstikirjeldust omalt poolt mõjutada; kirjutatakse rakenduse uuestijuurutamisel üle, mistõttu administraator peaks muutma selle asemel konteinerisse ümber kopeeritud püsieksemplari $CATALINA_BASE/conf/[enginename]/[hostname]/context.xml
|-
|style="color: green;" | $CATALINA_BASE/webapps/[webappname]/WEB-INF/web.xml
|ka üks oluline Java veebiaplikatsiooni konfiguratsioonifail, mille pakendatakse koos veebiarhiiviga; enamasti muudab seda ainult programeerija; määrab muu hulgas millised aplikatsiooni osad vajavad autentimist või kui kiiresti veebisessioon aegub
|}

==Installeerimine==

===Installeerimine paketihalduriga===

<pre>
apt-cache search tomcat
apt-get install tomcat[version]-webapps
apt-get install tomcat[version]-admin
apt-get install tomcat[version]
</pre>

===Installeerimine käsitsi===

Paketihalduriga installeerides ei pruugi viimane Tomcati versioon olla kättesaadav ja see pakub ka vähem võimalusi kataloogide määramiseks jms. Käsitsi installeerimiseks tuleb laadida Tomcat kodulehelt alla. Lahtipakkimisel tekib kataloog, milles sisalduv fail "RUNNING.txt" on kõige kindlam allikas installeerimisel tekkivate probleemide vältimiseks ning lahendamiseks.

Vajaliku versiooni installeerimisfaili asukoha saab vaadata Tomcati kodulehelt sektsioonist "Download". Järgnevas näites installeerime Tomcati kõige uuema ebastabiilse kandidaatversiooni, mida näitab nimes sisalduv RC ehk "release candidate". Produktsioonikeskkonda tuleks siiski valida stabiilse versiooni. Käsitsi installeerimine on sarnane järgmisega:
<pre>
wget http://mirror.nexcess.net/apache/tomcat/tomcat-8/v8.0.0-RC5/bin/apache-tomcat-8.0.0-RC5.tar.gz
tar -zxvf apache-tomcat-8.0.0-RC5.tar.gz
mv /Users/kristjanveskimae/downloads/apache-tomcat-8.0.0-RC5 /usr/local/apache-tomcat-8.0.0-RC5
rm -f /Library/Tomcat
ln -s /usr/local/apache-tomcat-8.0.0-RC5/ /Library/Tomcat
chown -R kristjanveskimae /Library/Tomcat
chmod +x /Library/Tomcat/bin/*.sh
</pre>

==Käivitamine ja aplikatsiooni juurutamine==

===Konteineri käivitamine===

Tomcati käivitamise eelduseks on Java paigaldamine masinasse ning keskkonnamuutujate "JAVA_HOME" ja "JRE_HOME" defineerimine. Peale installeerimist võib kasutada skripte kataloogist $CATALINA_BASE/bin . Järgneb üks võimalik käivitamise ja peatamise näide, mis on kasutatav eelnevalt kirjeldatud käsitsi installeerimise juhul:
<pre>
/Library/Tomcat/bin/startup.sh
</pre>
ja peatamiseks
<pre>
/Library/Tomcat/bin/shutdown.sh
</pre>

===Näiteaplikatsiooni juurutamine===

Java veebiaplikatsiooni jagatakse hea tava kohaselt üheainsa veebiarhiivi failina. Siiski võib Tomcati juurutada ka lahtipakendatud olekus ("exploded") Java veebiaplikatsiooni.

====Käsitsi juurutamine ja mahavõtmine====

Näiteaplikatsiooni juurutamiseks lae selle veebiarhiivifail alla ning kopeeri oma konteineri juurutamiskataloogi 'webapps':
<pre>wget http://tomcat.apache.org/tomcat-8.0-doc/appdev/sample/sample.war
cp /Users/kristjanveskimae/downloads/sample.war /Library/Tomcat/webapps/sample.war</pre>

[[File:sample_app.png|400px|thumb|right|Pilt 1: Õnnestunult rakendatud näiteaplikatsioon]]

Kui konfiguratsioonifailis $CATALINA_BASE/conf/server.xml on märgendi "Host" atribuudi "autoDeploy" väärtus "true", installeerib ja uuendab Tomcat aplikatsioone dünaamiliselt töötamise ajal. Kui väärtuseks on "false", käib installeerimine staatiliselt ning serverisse juurutamiseks tuleb teha konteineri taaskäivitus. [http://tomcat.apache.org/tomcat-8.0-doc/manager-howto.html#Deploy_A_New_Application_from_a_Local_Path 1] Mõlemal juhul pakib konteiner arhiveeritud faili ise lahti samasse kausta $CATALINA_BASE/webapps ning ka juurutab selle. Tekkiv aplikatsioon on lokaalsest masinast seejärel kättesaadav aadressil http://localhost:8080/sample/ . Kui rakendamine õnnestub, siis peaks olema brauserist nähtav sarnane lehekülg nagu pildil 1.

Veebirakenduse käsitsi mahavõtmiseks tuleb kustutada talle vastav dokumendipõhja kataloog "webapps" kataloogist. Samuti tuleks kustutada .war-fail olemaks kindel, et Tomcat ei rakenda uuel käivitamisel veebiaplikatsiooni veebiarhiivifailist. Veelgi lihtsam on mahavõtmine brauseriga haldusrakenduse kaudu.

Rakenduste baaskataloogi "webapps" asukohta saab muuta failis $CATALINA_BASE/conf/server.xml peremehepõhiselt määratava atribuudiga "appBase", sealjuures Tomcati vaikimisi peremees ehk "Host" on "localhost".

====Tomcati vahendid juurutamiseks====

Veebiaplikatsioonide juurutamine ja mahajuurutamine on võimalik ka kaughalduse teel tänu Tomcati internetipõhisele haldusrakendusele. Näiteks saab veebibrauserit kasutades teha serveri põhitoiminguid Tomcati enda HTML-põhise rakendusega "Tomcat Manager". Veebipõhine haldusrakendus töötab ka käsupõhise veebiteenusena, millele on valmis ehitatud Anti ja Maveni integratsioonid. Samuti eksisteerib käsurea kliendirakendus TCD (Tomcat Client Deployer). TCD ei kuulu Tomcati baaskoosseisu, kuid pakub peale serveri administreerimise tavatoimingute ka lisafunktsionaalsust nagu veebirakenduse kokkukompileerimine ja pakendamine. [http://tomcat.apache.org/tomcat-8.0-doc/manager-howto.html#Configuring_Manager_Application_Access 1]

====Haldurakendus "Tomcat Manager"====

Tomcati haldusrakendus "Tomcat Manager" (antud alamjaotuses lihtsalt haldusrakendus) on Tomcati enda veebiaplikatioon Tomcati brauseripõhiseks kaughalduseks, võimaldades muu hulgas järgnevat [http://tomcat.apache.org/tomcat-8.0-doc/manager-howto.html#Introduction 1]:
* Rakendada uue veebiaplikatsiooni war-faili üleslaadimisega;
* Näha kõiki rakendatud veebiaplikatsioone koos aktiivsete sessioonidega;
* Taasrakendada veebirakendust, näiteks veebiarhiivi pakitud klassifailide /WEB-INF/classes või teekide /WEB-INF/lib uuendamisel, kinnijooksmisel jms.;
* Peatada veebirakendust ilma serverist eemaldamata, samuti koos serverist eemaldamisega;
* Vaadata operatsioonisüsteemi ja Java parameetrite väärtusi;
* Näha kõiki saadaolevaid JNDI ressursse, k.a. andmebaasiühendusi, mis aitavad rakenduste programmeerijail defineerida <ResourceLink> elemendid web.xml konfiguratsioonifailis.

Tomcati installatsioon sisaldab haldusrakendust juba vaikimisi. Haldusrakenduse töölepanemiseks tuleb peremeesmasina konfiguratsioonikataloogi $CATALINA_BASE/conf/[enginename]/[hostname] lisada ka fail manager.xml. Vaikimisi valmiskonfigureeritud testrakendusel on see fail juba olemas asukohas $CATALINA_BASE/conf/Catalina/localhost/manager.xml . Rakendus asub vaikimisi aadressil http://[host]/manager/ , vaikimisi konfiguratsioone kasutades lahendub see asukohaks http://localhost:8080/manager/ . [http://tomcat.apache.org/tomcat-8.0-doc/manager-howto.html#Configuring_Manager_Application_Access 1]

====="Tomcat Manager" ligipääsu konfigureerimine=====

Vaikimisi on turvalisuspõhjustel ligipääs haldusrakendusele maha keeratud. Mismoodi täpselt kasutajatel ligipääsu võimaldada sõltub kasutatavast valdusest (realm). Vaikimisi defineerib $CATALINA_BASE/conf/server.xml valduseks "MemoryRealm". Vaikimisi loeb valdus "MemoryRealm" kasutajad failist $CATALINA_BASE/conf/tomcat-users.xml. Antud failis tuleb iga kasutaja defineerida omaette märgendiga <user>, mis näeb välja umbes järgmine [http://tomcat.apache.org/tomcat-8.0-doc/manager-howto.html#Configuring_Manager_Application_Access 1]:
<pre>
<user name="craig" password="secret" roles="manager-gui,manager-script" />
</pre>

Antud kasutajale on defineeritud korraga kaks rolli. Ligipääsu võimaldamiseks tulebki lihtsamal juhul kasutajatefailis $CATALINA_BASE/conf/tomcat-users.xml defineerida enda kasutaja. Kasutaja rolliks võib määrata näiteks "manager-gui", mis võimaldab ligipääsu kogu HTML liidese funktsionaalsusele.

Teised valdused on "JDBCRealm", mille puhul hoitakse kasutajatega seonduvat infot andmebaasis ja JNDIRealm, mille puhul kasutatakse lihtsustatud kataloogisirvimise protokolli (LDAP).
Lisaks saab haldusrakendusele keelata ligipääsu mujalt kui kindlaksmääratud IP-aadressidelt, lisades filtri "RemoteAddrValve" või "RemoteHostValve" konfigureerimisfaili manager.xml näiteks järgmiselt [http://tomcat.apache.org/tomcat-8.0-doc/manager-howto.html#Introduction 1]:
<pre>
<Context privileged="true">
<Valve className="org.apache.catalina.valves.RemoteAddrValve"
allow="127\.0\.0\.1"/>
</Context>
</pre>

=====Juurutamine ja mahavõtmine haldusrakendusega "Tomcat Manager"=====

Juurutamiseks lae kõigepealt veebiarhiivifail üles, kasutades esilehel asuvat sektsiooni "WAR file to deploy". Veebiarhiivi üleslaadimise liides on kujutatud plidil 2.

[[File:tomcat_manager_war_upload.png|600px|thumb|right|Pilt 2: Veebiarhiivi üleslaadimise nupp]]

Rakendus kuvatakse seejärel hallatavate rakenduste nimekirjas. Kui konteiner pole seadistatud üleslaetud aplikatsiooni kohe ka ise rakendama, tuleb vajutada "Start". Rakenduse peatamiseks kasuta "Stop", uuesti rakendamiseks "Redeploy" ja serverist eemaldamiseks "Undeploy". Nupud on näha ka pildil 3 olevas rakenduste nimekirjas.


[[File:tomcat_manager_apps_list.png|1000px|thumb|Pilt 3: Rakenduste nimekiri]]

==Näpunäiteid Tomcati reaalseks kasutamiseks==

===Juurutamise järjekord===

Tomcati käivitumisel juurutatakse aplikatsioonid sellises järjekorras [http://www.mulesoft.com/tomcat-deploy-procedures 2]:
# Konteinerisse kopeeritud kontekstikirjelduste järgi $CATALINA_BASE/conf/[EngineName]/[HostName]/[ApplicationName].xml ;
# Lahtipakitud rakendused "webapps" kataloogis;
# Pakitud rakenduste veebiarhiivid "webapps" kataloogis.

Seetõttu peaks käsitsi taasjuurutamisel kindluse mõttes eelnevalt kustutama rakenduse lahtipakitud dokumendipõhja kataloogi "webapps" kataloogist. Kontekstikirjelduse muutumisel tuleb jälgida, kas kirjeldus on juba kopeeritud serverisse ning vajadusel eelmise versiooni ümber muuta või kustutada.

===Reaalsele domeenile konfigureerimine===

Järgnevalt eeldame, et domeen ''www.minukodukas.ee'' on juba serverimasinaga seostatud. Et Tomcat hakkaks ka reaalselt Internetist tulevatele päringutele vastama, tuleb muuta failis $CATALINA_BASE/conf/server.xml konteinerile ''Catalina'' vastava teenusemärgendi sisu sarnaselt järgnevaga:

<pre>
<Service name="Catalina">
<Connector port="80" protocol="HTTP/1.1" connectionTimeout="20000" URIEncoding="UTF-8" redirectPort="8443" />
<Engine name="Catalina" defaultHost="www.minukodukas.ee">
<Host name="www.minukodukas.ee" appBase="webapps" unpackWARs="true" autoDeploy="false" deployOnStartup="false" xmlValidation="false" xmlNamespaceAware="false">
<Context path="" docBase="kodukas" debug="0" reloadable="true" />
</Host>
</Engine>
</Service>
</pre>

Ülal defineerime põhiliselt selle, et Tomcat kuulaks domeeni ''www.minukodukas.ee'' ja kasutaks HTTP päringute jaoks porti 80. Ühtlasti otsib Tomcat juurutatavat rakendust failist $CATALINA_BASE/webapps/kodukas.war. Kuna rajalisandiks on määratud tühi sõne (path=""), siis juurutataksegi aplikatsioon aadressile ''www.minukodukas.ee'' ilma rajalisandita (a'la ''www.minukodukas.ee/wiki''). Seetõttu pakitakse ka veebiarhiiv tegelikult lahti kataloogi $CATALINA_BASE/webapps/ROOT mitte kataloogi $CATALINA_BASE/webapps/kodukas nagu võiks eeldada.

===Käigultvahetus===

Võimaldamaks käigultvahetust (hot deployment) peab konteineri konfiguratsioonifailis $CATALINA_BASE/conf/server.xml olema peremehepõhise märgendi "Host" atribuudi "autoDeploy" väärtus "true". Sel juhul installeerib ja uuendab Tomcat aplikatsioone dünaamiliselt töötamise ajal. Kui väärtuseks on "false", käib installeerimine staatiliselt ning serverisse juurutamiseks tuleb teha konteineri taaskäivitus. Käigultvahetust saab määrata ka peremehe defineerimisel "Host Manager" rakendusega, mis on kättesaadav aadressil http://localhost:8080/host-manager/html . Kasutamiseks tuleb lisada oma kasutajale rolli "admin-gui" (vt. alajaotus ""Tomcat Manager" ligipääsu konfigureerimine"). Antud rakenduse veebiliides on kujutatud joonisel 4.

[[File:tomcat_host_manager_app.png|500px|thumb|Pilt 4: Tomcati haldusrakendus]]

Käigultvahetust päästikuks on vaikimisi uuendatud veebiarhiivifaili või lahtipakitud veebirakenduse paigutamine "webapps" kataloogi. Käigultvahetuse päästikutele võib failis $CATALINA_BASE/conf/server.xml ka ise lisada kuulatavaid ressursse nagu web.xml muutmine või mõne teegifaili vahetamine (märgendis "Host").

===Klassiteekide väljatõstmine veebiarhiivifailist===

Kõik konteksti poolt kasutatavad Java klassiteegid võib pakendada veebiarhiivi sisse kataloogi "lib", kuid nii võib osutuda veebiarhiivi üleslaadimine ajakulukaks, eriti arenduskeskkonnas. Kui ei teki ohtu, et erinevad rakendused kasutavad sama teegi erinevaid versioone, siis on vahel parem lisada osa teeke konteineri kataloogi $CATALINA_BASE/libs, kust need tehakse siis konteineri poolt kättesaadavaks kõigile konteineris jooksutatavatele kontekstidele. Nii võib vähendada veebiarhiivi faili suurust märgatavalt, mis tõstab kokkuvõttes juurutamiskiirust ja ühes sellega programmeerijate tööviljakust.

===Mälukasutus===

Konteineri poolt kasutatavat mälu saab vaadata haldusrakendusest vajutades lingile "Server Status". Mälukasutus on toodud jaotuses "JVM", kus näidatakse nii maksimaalselt kättesaadavat mälu kui ka parasjagu reserveeritud mälu.

<pre>Free memory: 41.16 MB Total memory: 123.37 MB Max memory: 1027.56 MB</pre>

Mälu suurendamiseks võib näiteks defineerida skriptis $CATALINA_BASE/bin/catalina.sh muutuja "JAVA_OPTS" ning määrata Java mälukasutuse miinimum- ja maksimumväärtused sarnaselt järgnevatega [http://www.mkyong.com/tomcat/tomcat-javalangoutofmemoryerror-permgen-space/ 3]:
<pre>
JAVA_OPTS="-Xms1536m -Xmx1536m -XX:NewSize=256m -XX:MaxNewSize=256m -XX:PermSize=256m -XX:MaxPermSize=256m"
</pre>

===Logifailid===

Vaikimisi defineerib Tomcat failiga $CATALINA_BASE/conf/logging.properties viis logerit, mis tekitavad viis eraldi logifaili.

{| style="background:#cccc99;color:black;width:80%;" border="1" cellpadding="5" cellspacing="0" align="center"
|+ Tomcati tekitatavad logifailid "logs" kataloogis
!Fail !! Kasutus
|- style="background:white; color:black"
| style="width:300px" |catalina.out
| Tomcati käivitus- ja peatamisskriptide väljund, samuti juurutatud rakenduste prindilaused System.out ja veaväljundid System.err
|- style="background:white; color:black"
| style="width:300px" |catalina.[yyyy]-[mm]-[dd].log
| Pööratud (rotated) logifail catalina.out
|- style="background:white; color:black"
| style="width:300px" |host-manager.[yyyy]-[mm]-[dd].log
| Logi peremehehalduse rakendusele (rakendus on kättesaadav kohalikust masinast aadressil http://localhost:8080/host-manager/html )
|- style="background:white; color:black"
| style="width:300px" |localhost.[yyyy]-[mm]-[dd].log
| Peremehe "localhost" logi; mitme virtuaalse peremehe korral tekitatakse igale peremehele oma logi
|- style="background:white; color:black"
| style="width:300px" |localhost_access_log.[yyyy]-[mm]-[dd].txt
| Konteinerisse Internetist saabunud päringute logi
|- style="background:white; color:black"
| style="width:300px" |manager.[yyyy]-[mm]-[dd].log
| Haldusrakenduse tegevuste logi
|}

===Viiteid===

Palju vajalikku võib leida [http://tomcat.apache.org/tomcat-8.0-doc/index.html Tomcat 8 dokumentatsioonist]

Lisaks üks viide põhjalikule Tomcati versioon seitsme ülevaatele: http://www.ntu.edu.sg/home/ehchua/programming/howto/Tomcat_More.html

= Kasutatud materjalid =

#http://tomcat.apache.org/tomcat-8.0-doc/index.html
#http://www.mulesoft.com/tomcat-deploy-procedures
#http://www.mkyong.com/tomcat/tomcat-javalangoutofmemoryerror-permgen-space/

[[Category: Operatsioonisüsteemide administreerimine ja sidumine]]

File:Tomcat host manager app.png

2014-01-02T22:19:40Z

Kveskima:

Tomcat

2014-01-02T22:17:12Z

Kveskima:

==Autor==

Kristjan Veskimäe D32

2013

==Sissejuhatus==

Tomcat on vabalt kättesaadav server Java veebirakendustele. Põhimõtteliselt on tegemist Servlet/JSP spetsifikatsiooni toetava konteineriga. Kiire käivitumise ning rakenduste käigultvahetuse tõttu on Tomcat hea valik väiksemate ning keskmise suurusega Java veebirakenduste käitamiseks.

Antud töö kirjeldab Tomcati 8. versiooni. Põhiosa on üldiselt samasugune võrreldes paari eelmise versiooniga. Suuremad erinevused on versioonispetsiifilistes probleemides ja nende lahendamises, mida käesolev töö ei vaatle.

Töö vaatleb Tomcati paigaldamist ja seadistamist Unix-laadsesse keskkonda ning eeldab lugejalt algteadmisi sarnastes süsteemides. Tomcati on võimalik paigaldada ka Windows-keskkonda, kuid antud veebiserver eeldab kasutaja poolt käsureal töötamist ning Tomcati failihierarhias orienteerumist. Põhimõtteliselt on Java veebirakenduste arendamiseks IDE-abil võimalik siiski ka kasutada IDE-sse integreeritud Tomcati serverit - näiteks pakuvad sellist võimalust Eclipse EE ja NetBeans - kuid seda käesolev töö ei vaatle.

==Mõisted==

* '''Kontekst''' (context) - Tomcati mõistes üks konkreetne veebiaplikatsioon
* '''Konteiner''' (container) - veebiserver Tomcat ise
* '''Kontekstikirjeldus''' (context descriptor) - Tomcati-spetsiifiline konteksti konfiguratsioonimääratlus; peremehepõhine osa loetakse failist $CATALINA_HOME/conf/[enginename]/[hostname]/context.xml ja sellele lisatakse kontekstispetsiifilised täpsustused failist $CATALINA_BASE/conf/[enginename]/[hostname]/[webappname].xml; kontekstikirjeldus määrab näiteks nimed ressurssidele, sessioonihalduse parameetrid jmt. (olgu märgitud, et Tomcati varasemates versioonides sisaldusid kontekstikirjeldused põhikonfiguratsioonifailis server.xml)
* '''Dokumendipõhi''' (docBase) - kontekstile vastav kataloog Tomcati "webapps" kataloogis, mis tekib veebiaplikatsiooni serverisse rakendamisel
* '''Veebiarhiiv''' (Web application ARchive, war-file) - Java veebiaplikatsiooni jagatakse hea tava kohaselt selle üheainsa veebiarhiivi failina, mille laienditüübiks on "war". Tegemist on zip-protokolliga kokkupakitud kataloogiga, millel on Java veebirakenduste spetsifikatsioonile vastav ülesehitus. Siiski võib veebiaplikatsioon olla juurutamisel ka lahtipakendatud olekus (inglisekeelne termin on "war is exploded").

==Ülesehitus==

{| class="wikitable"
|+Kataloogid
|-
|style="color: green;" | $CATALINA_HOME
|baaskataloog, kuhu on Tomcat paigutatud
|-
|style="color: green;" | $CATALINA_BASE
|parasjagu töösoleva Tomcati eksemplari baaskataloog, mille alusel lahendatakse teed ülejäänud kataloogide ja failideni; ainult ühe kasutusel oleva Tomcati eksemplari puhul on see sama, mis $CATALINA_HOME

|-
|style="color: green;" | $CATALINA_BASE/bin
|serveri käivitus- ja abiskriptid
|-
|style="color: green;" | $CATALINA_BASE/conf
|konfiguratsioonifailid
|-
|style="color: green;" | $CATALINA_BASE/lib
|Tomcatile vaikimisi kättesaadavad Java klassiteegid (class libraries) ehk .jar-failid kuhu on Java kompileeritud kood kokku pakendatud
|-
|style="color: green;" | $CATALINA_BASE/logs
|logifailid paigutatakse vaikimisi siia
|-
|style="color: green;" | $CATALINA_BASE/webapps
|kataloog, kuhu paigutatakse serverisse juurutatavad veebiaplikatsioonid

|}

{| class="wikitable"
|+Mõned olulisemad failid
|-
|style="color: green;" | $CATALINA_BASE/bin/startup.sh
|serveri käivitusskript
|-
|style="color: green;" | $CATALINA_BASE/bin/shutdown.sh
|serveri peatusskript

|-
|style="color: green;" | $CATALINA_BASE/conf/server.xml
| konteineri peamine konfiguratsioonifail
|-
|style="color: green;" | $CATALINA_BASE/conf/[enginename]/[hostname]/[webappname].xml
|serveri administraatori jaoks konteinerisse endasse ümber kopeeritud rakendusepõhine kontekstikirjelduse konfiguratsioon failist $CATALINA_BASE/webapps/[ApplicationName]/META-INF/context.xml
|-
|style="color: green;" | $CATALINA_BASE/conf/[enginename]/[hostname]/context.xml
| fail, mis aitab administraatoril konteksti kohta käivat infot kirjeldada peremeesmasina-põhiselt ja halduseks mõeldud automaat-tööriistadel (näiteks Tomcat Manager ja TCD) oma tööd teha
|-
|style="color: green;" | $CATALINA_BASE/$CATALINA_BASE/conf/[enginename]/[hostname]/manager.xml
|fail, mis võimaldab lisada rakendustele ligipääsufiltreid
|-
|style="color: green;" | $CATALINA_BASE/webapps/[webappname]/META-INF/context.xml
|kontekstikirjeldusfail, mille veebirakenduse programmeerija on pakendanud oma aplikatsiooniga kaasa ning millega ta saab võimaluse kontekstikirjeldust omalt poolt mõjutada; kirjutatakse rakenduse uuestijuurutamisel üle, mistõttu administraator peaks muutma selle asemel konteinerisse ümber kopeeritud püsieksemplari $CATALINA_BASE/conf/[enginename]/[hostname]/context.xml
|-
|style="color: green;" | $CATALINA_BASE/webapps/[webappname]/WEB-INF/web.xml
|ka üks oluline Java veebiaplikatsiooni konfiguratsioonifail, mille pakendatakse koos veebiarhiiviga; enamasti muudab seda ainult programeerija; määrab muu hulgas millised aplikatsiooni osad vajavad autentimist või kui kiiresti veebisessioon aegub
|}

==Installeerimine==

===Installeerimine paketihalduriga===

<pre>
apt-cache search tomcat
apt-get install tomcat[version]-webapps
apt-get install tomcat[version]-admin
apt-get install tomcat[version]
</pre>

===Installeerimine käsitsi===

Paketihalduriga installeerides ei pruugi viimane Tomcati versioon olla kättesaadav ja see pakub ka vähem võimalusi kataloogide määramiseks jms. Käsitsi installeerimiseks tuleb laadida Tomcat kodulehelt alla. Lahtipakkimisel tekib kataloog, milles sisalduv fail "RUNNING.txt" on kõige kindlam allikas installeerimisel tekkivate probleemide vältimiseks ning lahendamiseks.

Vajaliku versiooni installeerimisfaili asukoha saab vaadata Tomcati kodulehelt sektsioonist "Download". Järgnevas näites installeerime Tomcati kõige uuema ebastabiilse kandidaatversiooni, mida näitab nimes sisalduv RC ehk "release candidate". Produktsioonikeskkonda tuleks siiski valida stabiilse versiooni. Käsitsi installeerimine on sarnane järgmisega:
<pre>
wget http://mirror.nexcess.net/apache/tomcat/tomcat-8/v8.0.0-RC5/bin/apache-tomcat-8.0.0-RC5.tar.gz
tar -zxvf apache-tomcat-8.0.0-RC5.tar.gz
mv /Users/kristjanveskimae/downloads/apache-tomcat-8.0.0-RC5 /usr/local/apache-tomcat-8.0.0-RC5
rm -f /Library/Tomcat
ln -s /usr/local/apache-tomcat-8.0.0-RC5/ /Library/Tomcat
chown -R kristjanveskimae /Library/Tomcat
chmod +x /Library/Tomcat/bin/*.sh
</pre>

==Käivitamine ja aplikatsiooni juurutamine==

===Konteineri käivitamine===

Tomcati käivitamise eelduseks on Java paigaldamine masinasse ning keskkonnamuutujate "JAVA_HOME" ja "JRE_HOME" defineerimine. Peale installeerimist võib kasutada skripte kataloogist $CATALINA_BASE/bin . Järgneb üks võimalik käivitamise ja peatamise näide, mis on kasutatav eelnevalt kirjeldatud käsitsi installeerimise juhul:
<pre>
/Library/Tomcat/bin/startup.sh
</pre>
ja peatamiseks
<pre>
/Library/Tomcat/bin/shutdown.sh
</pre>

===Näiteaplikatsiooni juurutamine===

Java veebiaplikatsiooni jagatakse hea tava kohaselt üheainsa veebiarhiivi failina. Siiski võib Tomcati juurutada ka lahtipakendatud olekus ("exploded") Java veebiaplikatsiooni.

====Käsitsi juurutamine ja mahavõtmine====

Näiteaplikatsiooni juurutamiseks lae selle veebiarhiivifail alla ning kopeeri oma konteineri juurutamiskataloogi 'webapps':
<pre>wget http://tomcat.apache.org/tomcat-8.0-doc/appdev/sample/sample.war
cp /Users/kristjanveskimae/downloads/sample.war /Library/Tomcat/webapps/sample.war</pre>

[[File:sample_app.png|400px|thumb|right|Pilt 1: Õnnestunult rakendatud näiteaplikatsioon]]

Kui konfiguratsioonifailis $CATALINA_BASE/conf/server.xml on märgendi "Host" atribuudi "autoDeploy" väärtus "true", installeerib ja uuendab Tomcat aplikatsioone dünaamiliselt töötamise ajal. Kui väärtuseks on "false", käib installeerimine staatiliselt ning serverisse juurutamiseks tuleb teha konteineri taaskäivitus. [http://tomcat.apache.org/tomcat-8.0-doc/manager-howto.html#Deploy_A_New_Application_from_a_Local_Path 1] Mõlemal juhul pakib konteiner arhiveeritud faili ise lahti samasse kausta $CATALINA_BASE/webapps ning ka juurutab selle. Tekkiv aplikatsioon on lokaalsest masinast seejärel kättesaadav aadressil http://localhost:8080/sample/ . Kui rakendamine õnnestub, siis peaks olema brauserist nähtav sarnane lehekülg nagu pildil 1.

Veebirakenduse käsitsi mahavõtmiseks tuleb kustutada talle vastav dokumendipõhja kataloog "webapps" kataloogist. Samuti tuleks kustutada .war-fail olemaks kindel, et Tomcat ei rakenda uuel käivitamisel veebiaplikatsiooni veebiarhiivifailist. Veelgi lihtsam on mahavõtmine brauseriga haldusrakenduse kaudu.

Rakenduste baaskataloogi "webapps" asukohta saab muuta failis $CATALINA_BASE/conf/server.xml peremehepõhiselt määratava atribuudiga "appBase", sealjuures Tomcati vaikimisi peremees ehk "Host" on "localhost".

====Tomcati vahendid juurutamiseks====

Veebiaplikatsioonide juurutamine ja mahajuurutamine on võimalik ka kaughalduse teel tänu Tomcati internetipõhisele haldusrakendusele. Näiteks saab veebibrauserit kasutades teha serveri põhitoiminguid Tomcati enda HTML-põhise rakendusega "Tomcat Manager". Veebipõhine haldusrakendus töötab ka käsupõhise veebiteenusena, millele on valmis ehitatud Anti ja Maveni integratsioonid. Samuti eksisteerib käsurea kliendirakendus TCD (Tomcat Client Deployer). TCD ei kuulu Tomcati baaskoosseisu, kuid pakub peale serveri administreerimise tavatoimingute ka lisafunktsionaalsust nagu veebirakenduse kokkukompileerimine ja pakendamine. [http://tomcat.apache.org/tomcat-8.0-doc/manager-howto.html#Configuring_Manager_Application_Access 1]

====Haldurakendus "Tomcat Manager"====

Tomcati haldusrakendus "Tomcat Manager" (antud alamjaotuses lihtsalt haldusrakendus) on Tomcati enda veebiaplikatioon Tomcati brauseripõhiseks kaughalduseks, võimaldades muu hulgas järgnevat [http://tomcat.apache.org/tomcat-8.0-doc/manager-howto.html#Introduction 1]:
* Rakendada uue veebiaplikatsiooni war-faili üleslaadimisega;
* Näha kõiki rakendatud veebiaplikatsioone koos aktiivsete sessioonidega;
* Taasrakendada veebirakendust, näiteks veebiarhiivi pakitud klassifailide /WEB-INF/classes või teekide /WEB-INF/lib uuendamisel, kinnijooksmisel jms.;
* Peatada veebirakendust ilma serverist eemaldamata, samuti koos serverist eemaldamisega;
* Vaadata operatsioonisüsteemi ja Java parameetrite väärtusi;
* Näha kõiki saadaolevaid JNDI ressursse, k.a. andmebaasiühendusi, mis aitavad rakenduste programmeerijail defineerida <ResourceLink> elemendid web.xml konfiguratsioonifailis.

Tomcati installatsioon sisaldab haldusrakendust juba vaikimisi. Haldusrakenduse töölepanemiseks tuleb peremeesmasina konfiguratsioonikataloogi $CATALINA_BASE/conf/[enginename]/[hostname] lisada ka fail manager.xml. Vaikimisi valmiskonfigureeritud testrakendusel on see fail juba olemas asukohas $CATALINA_BASE/conf/Catalina/localhost/manager.xml . Rakendus asub vaikimisi aadressil http://[host]/manager/ , vaikimisi konfiguratsioone kasutades lahendub see asukohaks http://localhost:8080/manager/ . [http://tomcat.apache.org/tomcat-8.0-doc/manager-howto.html#Configuring_Manager_Application_Access 1]

====="Tomcat Manager" ligipääsu konfigureerimine=====

Vaikimisi on turvalisuspõhjustel ligipääs haldusrakendusele maha keeratud. Mismoodi täpselt kasutajatel ligipääsu võimaldada sõltub kasutatavast valdusest (realm). Vaikimisi defineerib $CATALINA_BASE/conf/server.xml valduseks "MemoryRealm". Vaikimisi loeb valdus "MemoryRealm" kasutajad failist $CATALINA_BASE/conf/tomcat-users.xml. Antud failis tuleb iga kasutaja defineerida omaette märgendiga <user>, mis näeb välja umbes järgmine [http://tomcat.apache.org/tomcat-8.0-doc/manager-howto.html#Configuring_Manager_Application_Access 1]:
<pre>
<user name="craig" password="secret" roles="manager-gui,manager-script" />
</pre>

Antud kasutajale on defineeritud korraga kaks rolli. Ligipääsu võimaldamiseks tulebki lihtsamal juhul kasutajatefailis $CATALINA_BASE/conf/tomcat-users.xml defineerida enda kasutaja. Kasutaja rolliks võib määrata näiteks "manager-gui", mis võimaldab ligipääsu kogu HTML liidese funktsionaalsusele.

Teised valdused on "JDBCRealm", mille puhul hoitakse kasutajatega seonduvat infot andmebaasis ja JNDIRealm, mille puhul kasutatakse lihtsustatud kataloogisirvimise protokolli (LDAP).
Lisaks saab haldusrakendusele keelata ligipääsu mujalt kui kindlaksmääratud IP-aadressidelt, lisades filtri "RemoteAddrValve" või "RemoteHostValve" konfigureerimisfaili manager.xml näiteks järgmiselt [http://tomcat.apache.org/tomcat-8.0-doc/manager-howto.html#Introduction 1]:
<pre>
<Context privileged="true">
<Valve className="org.apache.catalina.valves.RemoteAddrValve"
allow="127\.0\.0\.1"/>
</Context>
</pre>

=====Juurutamine ja mahavõtmine haldusrakendusega "Tomcat Manager"=====

Juurutamiseks lae kõigepealt veebiarhiivifail üles, kasutades esilehel asuvat sektsiooni "WAR file to deploy". Veebiarhiivi üleslaadimise liides on kujutatud plidil 2.

[[File:tomcat_manager_war_upload.png|600px|thumb|right|Pilt 2: Veebiarhiivi üleslaadimise nupp]]

Rakendus kuvatakse seejärel hallatavate rakenduste nimekirjas. Kui konteiner pole seadistatud üleslaetud aplikatsiooni kohe ka ise rakendama, tuleb vajutada "Start". Rakenduse peatamiseks kasuta "Stop", uuesti rakendamiseks "Redeploy" ja serverist eemaldamiseks "Undeploy". Nupud on näha ka pildil 3 olevas rakenduste nimekirjas.


[[File:tomcat_manager_apps_list.png|1000px|thumb|Pilt 3: Rakenduste nimekiri]]

==Näpunäiteid Tomcati reaalseks kasutamiseks==

===Juurutamise järjekord===

Tomcati käivitumisel juurutatakse aplikatsioonid sellises järjekorras [http://www.mulesoft.com/tomcat-deploy-procedures 2]:
# Konteinerisse kopeeritud kontekstikirjelduste järgi $CATALINA_BASE/conf/[EngineName]/[HostName]/[ApplicationName].xml ;
# Lahtipakitud rakendused "webapps" kataloogis;
# Pakitud rakenduste veebiarhiivid "webapps" kataloogis.

Seetõttu peaks käsitsi taasjuurutamisel kindluse mõttes eelnevalt kustutama rakenduse lahtipakitud dokumendipõhja kataloogi "webapps" kataloogist. Kontekstikirjelduse muutumisel tuleb jälgida, kas kirjeldus on juba kopeeritud serverisse ning vajadusel eelmise versiooni ümber muuta või kustutada.

===Reaalsele domeenile konfigureerimine===

Järgnevalt eeldame, et domeen ''www.minukodukas.ee'' on juba serverimasinaga seostatud. Et Tomcat hakkaks ka reaalselt Internetist tulevatele päringutele vastama, tuleb muuta failis $CATALINA_BASE/conf/server.xml konteinerile ''Catalina'' vastava teenusemärgendi sisu sarnaselt järgnevaga:

<pre>
<Service name="Catalina">
<Connector port="80" protocol="HTTP/1.1" connectionTimeout="20000" URIEncoding="UTF-8" redirectPort="8443" />
<Engine name="Catalina" defaultHost="www.minukodukas.ee">
<Host name="www.minukodukas.ee" appBase="webapps" unpackWARs="true" autoDeploy="false" deployOnStartup="false" xmlValidation="false" xmlNamespaceAware="false">
<Context path="" docBase="kodukas" debug="0" reloadable="true" />
</Host>
</Engine>
</Service>
</pre>

Ülal defineerime põhiliselt selle, et Tomcat kuulaks domeeni ''www.minukodukas.ee'' ja kasutaks HTTP päringute jaoks porti 80. Ühtlasti otsib Tomcat juurutatavat rakendust failist $CATALINA_BASE/webapps/kodukas.war. Kuna rajalisandiks on määratud tühi sõne (path=""), siis juurutataksegi aplikatsioon aadressile ''www.minukodukas.ee'' ilma rajalisandita (a'la ''www.minukodukas.ee/wiki''). Seetõttu pakitakse ka veebiarhiiv tegelikult lahti kataloogi $CATALINA_BASE/webapps/ROOT mitte kataloogi $CATALINA_BASE/webapps/kodukas nagu võiks eeldada.

===Käigultvahetus===

Võimaldamaks käigultvahetust (hot deployment) peab konteineri konfiguratsioonifailis $CATALINA_BASE/conf/server.xml olema peremehepõhise märgendi "Host" atribuudi "autoDeploy" väärtus "true". Sel juhul installeerib ja uuendab Tomcat aplikatsioone dünaamiliselt töötamise ajal. Kui väärtuseks on "false", käib installeerimine staatiliselt ning serverisse juurutamiseks tuleb teha konteineri taaskäivitus. Käigultvahetust saab määrata ka peremehe defineerimisel "Host Manager" rakendusega, mis on kättesaadav aadressil http://localhost:8080/host-manager/html . Kasutamiseks tuleb lisada oma kasutajale rolli "admin-gui" (vt. alajaotus ""Tomcat Manager" ligipääsu konfigureerimine").

[[File:tomcat_host_manager_app.png|500px|thumb|Pilt 4: Tomcati haldusrakendus]]

Käigultvahetust päästikuks on vaikimisi uuendatud veebiarhiivifaili või lahtipakitud veebirakenduse paigutamine "webapps" kataloogi. Käigultvahetuse päästikutele võib failis $CATALINA_BASE/conf/server.xml ka ise lisada kuulatavaid ressursse nagu web.xml muutmine või mõne teegifaili vahetamine (märgendis "Host").

===Klassiteekide väljatõstmine veebiarhiivifailist===

Kõik konteksti poolt kasutatavad Java klassiteegid võib pakendada veebiarhiivi sisse kataloogi "lib", kuid nii võib osutuda veebiarhiivi üleslaadimine ajakulukaks, eriti arenduskeskkonnas. Kui ei teki ohtu, et erinevad rakendused kasutavad sama teegi erinevaid versioone, siis on vahel parem lisada osa teeke konteineri kataloogi $CATALINA_BASE/libs, kust need tehakse siis konteineri poolt kättesaadavaks kõigile konteineris jooksutatavatele kontekstidele. Nii võib vähendada veebiarhiivi faili suurust märgatavalt, mis tõstab kokkuvõttes juurutamiskiirust ja ühes sellega programmeerijate tööviljakust.

===Mälukasutus===

Konteineri poolt kasutatavat mälu saab vaadata haldusrakendusest vajutades lingile "Server Status". Mälukasutus on toodud jaotuses "JVM", kus näidatakse nii maksimaalselt kättesaadavat mälu kui ka parasjagu reserveeritud mälu.

<pre>Free memory: 41.16 MB Total memory: 123.37 MB Max memory: 1027.56 MB</pre>

Mälu suurendamiseks võib näiteks defineerida skriptis $CATALINA_BASE/bin/catalina.sh muutuja "JAVA_OPTS" ning määrata Java mälukasutuse miinimum- ja maksimumväärtused sarnaselt järgnevatega [http://www.mkyong.com/tomcat/tomcat-javalangoutofmemoryerror-permgen-space/ 3]:
<pre>
JAVA_OPTS="-Xms1536m -Xmx1536m -XX:NewSize=256m -XX:MaxNewSize=256m -XX:PermSize=256m -XX:MaxPermSize=256m"
</pre>

===Logifailid===

Vaikimisi defineerib Tomcat failiga $CATALINA_BASE/conf/logging.properties viis logerit, mis tekitavad viis eraldi logifaili.

{| style="background:#cccc99;color:black;width:80%;" border="1" cellpadding="5" cellspacing="0" align="center"
|+ Tomcati tekitatavad logifailid "logs" kataloogis
!Fail !! Kasutus
|- style="background:white; color:black"
| style="width:300px" |catalina.out
| Tomcati käivitus- ja peatamisskriptide väljund, samuti juurutatud rakenduste prindilaused System.out ja veaväljundid System.err
|- style="background:white; color:black"
| style="width:300px" |catalina.[yyyy]-[mm]-[dd].log
| Pööratud (rotated) logifail catalina.out
|- style="background:white; color:black"
| style="width:300px" |host-manager.[yyyy]-[mm]-[dd].log
| Logi peremehehalduse rakendusele (rakendus on kättesaadav kohalikust masinast aadressil http://localhost:8080/host-manager/html )
|- style="background:white; color:black"
| style="width:300px" |localhost.[yyyy]-[mm]-[dd].log
| Peremehe "localhost" logi; mitme virtuaalse peremehe korral tekitatakse igale peremehele oma logi
|- style="background:white; color:black"
| style="width:300px" |localhost_access_log.[yyyy]-[mm]-[dd].txt
| Konteinerisse Internetist saabunud päringute logi
|- style="background:white; color:black"
| style="width:300px" |manager.[yyyy]-[mm]-[dd].log
| Haldusrakenduse tegevuste logi
|}

===Viiteid===

Palju vajalikku võib leida [http://tomcat.apache.org/tomcat-8.0-doc/index.html Tomcat 8 dokumentatsioonist]

Lisaks üks viide põhjalikule Tomcati versioon seitsme ülevaatele: http://www.ntu.edu.sg/home/ehchua/programming/howto/Tomcat_More.html

= Kasutatud materjalid =

#http://tomcat.apache.org/tomcat-8.0-doc/index.html
#http://www.mulesoft.com/tomcat-deploy-procedures
#http://www.mkyong.com/tomcat/tomcat-javalangoutofmemoryerror-permgen-space/

[[Category: Operatsioonisüsteemide administreerimine ja sidumine]]

Tomcat

2014-01-02T22:13:31Z

Kveskima: /* Juurutamine ja mahavõtmine haldusrakendusega "Tomcat Manager" */

==Autor==

Kristjan Veskimäe D32

2013

==Sissejuhatus==

Tomcat on vabalt kättesaadav server Java veebirakendustele. Põhimõtteliselt on tegemist Servlet/JSP spetsifikatsiooni toetava konteineriga. Kiire käivitumise ning rakenduste käigultvahetuse tõttu on Tomcat hea valik väiksemate ning keskmise suurusega Java veebirakenduste käitamiseks.

Antud töö kirjeldab Tomcati 8. versiooni. Põhiosa on üldiselt samasugune võrreldes paari eelmise versiooniga. Suuremad erinevused on versioonispetsiifilistes probleemides ja nende lahendamises, mida käesolev töö ei vaatle.

Töö vaatleb Tomcati paigaldamist ja seadistamist Unix-laadsesse keskkonda ning eeldab lugejalt algteadmisi sarnastes süsteemides. Tomcati on võimalik paigaldada ka Windows-keskkonda, kuid antud veebiserver eeldab kasutaja poolt käsureal töötamist ning Tomcati failihierarhias orienteerumist. Põhimõtteliselt on Java veebirakenduste arendamiseks IDE-abil võimalik siiski ka kasutada IDE-sse integreeritud Tomcati serverit - näiteks pakuvad sellist võimalust Eclipse EE ja NetBeans - kuid seda käesolev töö ei vaatle.

==Mõisted==

* '''Kontekst''' (context) - Tomcati mõistes üks konkreetne veebiaplikatsioon
* '''Konteiner''' (container) - veebiserver Tomcat ise
* '''Kontekstikirjeldus''' (context descriptor) - Tomcati-spetsiifiline konteksti konfiguratsioonimääratlus; peremehepõhine osa loetakse failist $CATALINA_HOME/conf/[enginename]/[hostname]/context.xml ja sellele lisatakse kontekstispetsiifilised täpsustused failist $CATALINA_BASE/conf/[enginename]/[hostname]/[webappname].xml; kontekstikirjeldus määrab näiteks nimed ressurssidele, sessioonihalduse parameetrid jmt. (olgu märgitud, et Tomcati varasemates versioonides sisaldusid kontekstikirjeldused põhikonfiguratsioonifailis server.xml)
* '''Dokumendipõhi''' (docBase) - kontekstile vastav kataloog Tomcati "webapps" kataloogis, mis tekib veebiaplikatsiooni serverisse rakendamisel
* '''Veebiarhiiv''' (Web application ARchive, war-file) - Java veebiaplikatsiooni jagatakse hea tava kohaselt selle üheainsa veebiarhiivi failina, mille laienditüübiks on "war". Tegemist on zip-protokolliga kokkupakitud kataloogiga, millel on Java veebirakenduste spetsifikatsioonile vastav ülesehitus. Siiski võib veebiaplikatsioon olla juurutamisel ka lahtipakendatud olekus (inglisekeelne termin on "war is exploded").

==Ülesehitus==

{| class="wikitable"
|+Kataloogid
|-
|style="color: green;" | $CATALINA_HOME
|baaskataloog, kuhu on Tomcat paigutatud
|-
|style="color: green;" | $CATALINA_BASE
|parasjagu töösoleva Tomcati eksemplari baaskataloog, mille alusel lahendatakse teed ülejäänud kataloogide ja failideni; ainult ühe kasutusel oleva Tomcati eksemplari puhul on see sama, mis $CATALINA_HOME

|-
|style="color: green;" | $CATALINA_BASE/bin
|serveri käivitus- ja abiskriptid
|-
|style="color: green;" | $CATALINA_BASE/conf
|konfiguratsioonifailid
|-
|style="color: green;" | $CATALINA_BASE/lib
|Tomcatile vaikimisi kättesaadavad Java klassiteegid (class libraries) ehk .jar-failid kuhu on Java kompileeritud kood kokku pakendatud
|-
|style="color: green;" | $CATALINA_BASE/logs
|logifailid paigutatakse vaikimisi siia
|-
|style="color: green;" | $CATALINA_BASE/webapps
|kataloog, kuhu paigutatakse serverisse juurutatavad veebiaplikatsioonid

|}

{| class="wikitable"
|+Mõned olulisemad failid
|-
|style="color: green;" | $CATALINA_BASE/bin/startup.sh
|serveri käivitusskript
|-
|style="color: green;" | $CATALINA_BASE/bin/shutdown.sh
|serveri peatusskript

|-
|style="color: green;" | $CATALINA_BASE/conf/server.xml
| konteineri peamine konfiguratsioonifail
|-
|style="color: green;" | $CATALINA_BASE/conf/[enginename]/[hostname]/[webappname].xml
|serveri administraatori jaoks konteinerisse endasse ümber kopeeritud rakendusepõhine kontekstikirjelduse konfiguratsioon failist $CATALINA_BASE/webapps/[ApplicationName]/META-INF/context.xml
|-
|style="color: green;" | $CATALINA_BASE/conf/[enginename]/[hostname]/context.xml
| fail, mis aitab administraatoril konteksti kohta käivat infot kirjeldada peremeesmasina-põhiselt ja halduseks mõeldud automaat-tööriistadel (näiteks Tomcat Manager ja TCD) oma tööd teha
|-
|style="color: green;" | $CATALINA_BASE/$CATALINA_BASE/conf/[enginename]/[hostname]/manager.xml
|fail, mis võimaldab lisada rakendustele ligipääsufiltreid
|-
|style="color: green;" | $CATALINA_BASE/webapps/[webappname]/META-INF/context.xml
|kontekstikirjeldusfail, mille veebirakenduse programmeerija on pakendanud oma aplikatsiooniga kaasa ning millega ta saab võimaluse kontekstikirjeldust omalt poolt mõjutada; kirjutatakse rakenduse uuestijuurutamisel üle, mistõttu administraator peaks muutma selle asemel konteinerisse ümber kopeeritud püsieksemplari $CATALINA_BASE/conf/[enginename]/[hostname]/context.xml
|-
|style="color: green;" | $CATALINA_BASE/webapps/[webappname]/WEB-INF/web.xml
|ka üks oluline Java veebiaplikatsiooni konfiguratsioonifail, mille pakendatakse koos veebiarhiiviga; enamasti muudab seda ainult programeerija; määrab muu hulgas millised aplikatsiooni osad vajavad autentimist või kui kiiresti veebisessioon aegub
|}

==Installeerimine==

===Installeerimine paketihalduriga===

<pre>
apt-cache search tomcat
apt-get install tomcat[version]-webapps
apt-get install tomcat[version]-admin
apt-get install tomcat[version]
</pre>

===Installeerimine käsitsi===

Paketihalduriga installeerides ei pruugi viimane Tomcati versioon olla kättesaadav ja see pakub ka vähem võimalusi kataloogide määramiseks jms. Käsitsi installeerimiseks tuleb laadida Tomcat kodulehelt alla. Lahtipakkimisel tekib kataloog, milles sisalduv fail "RUNNING.txt" on kõige kindlam allikas installeerimisel tekkivate probleemide vältimiseks ning lahendamiseks.

Vajaliku versiooni installeerimisfaili asukoha saab vaadata Tomcati kodulehelt sektsioonist "Download". Järgnevas näites installeerime Tomcati kõige uuema ebastabiilse kandidaatversiooni, mida näitab nimes sisalduv RC ehk "release candidate". Produktsioonikeskkonda tuleks siiski valida stabiilse versiooni. Käsitsi installeerimine on sarnane järgmisega:
<pre>
wget http://mirror.nexcess.net/apache/tomcat/tomcat-8/v8.0.0-RC5/bin/apache-tomcat-8.0.0-RC5.tar.gz
tar -zxvf apache-tomcat-8.0.0-RC5.tar.gz
mv /Users/kristjanveskimae/downloads/apache-tomcat-8.0.0-RC5 /usr/local/apache-tomcat-8.0.0-RC5
rm -f /Library/Tomcat
ln -s /usr/local/apache-tomcat-8.0.0-RC5/ /Library/Tomcat
chown -R kristjanveskimae /Library/Tomcat
chmod +x /Library/Tomcat/bin/*.sh
</pre>

==Käivitamine ja aplikatsiooni juurutamine==

===Konteineri käivitamine===

Tomcati käivitamise eelduseks on Java paigaldamine masinasse ning keskkonnamuutujate "JAVA_HOME" ja "JRE_HOME" defineerimine. Peale installeerimist võib kasutada skripte kataloogist $CATALINA_BASE/bin . Järgneb üks võimalik käivitamise ja peatamise näide, mis on kasutatav eelnevalt kirjeldatud käsitsi installeerimise juhul:
<pre>
/Library/Tomcat/bin/startup.sh
</pre>
ja peatamiseks
<pre>
/Library/Tomcat/bin/shutdown.sh
</pre>

===Näiteaplikatsiooni juurutamine===

Java veebiaplikatsiooni jagatakse hea tava kohaselt üheainsa veebiarhiivi failina. Siiski võib Tomcati juurutada ka lahtipakendatud olekus ("exploded") Java veebiaplikatsiooni.

====Käsitsi juurutamine ja mahavõtmine====

Näiteaplikatsiooni juurutamiseks lae selle veebiarhiivifail alla ning kopeeri oma konteineri juurutamiskataloogi 'webapps':
<pre>wget http://tomcat.apache.org/tomcat-8.0-doc/appdev/sample/sample.war
cp /Users/kristjanveskimae/downloads/sample.war /Library/Tomcat/webapps/sample.war</pre>

[[File:sample_app.png|400px|thumb|right|Pilt 1: Õnnestunult rakendatud näiteaplikatsioon]]

Kui konfiguratsioonifailis $CATALINA_BASE/conf/server.xml on märgendi "Host" atribuudi "autoDeploy" väärtus "true", installeerib ja uuendab Tomcat aplikatsioone dünaamiliselt töötamise ajal. Kui väärtuseks on "false", käib installeerimine staatiliselt ning serverisse juurutamiseks tuleb teha konteineri taaskäivitus. [http://tomcat.apache.org/tomcat-8.0-doc/manager-howto.html#Deploy_A_New_Application_from_a_Local_Path 1] Mõlemal juhul pakib konteiner arhiveeritud faili ise lahti samasse kausta $CATALINA_BASE/webapps ning ka juurutab selle. Tekkiv aplikatsioon on lokaalsest masinast seejärel kättesaadav aadressil http://localhost:8080/sample/ . Kui rakendamine õnnestub, siis peaks olema brauserist nähtav sarnane lehekülg nagu pildil 1.

Veebirakenduse käsitsi mahavõtmiseks tuleb kustutada talle vastav dokumendipõhja kataloog "webapps" kataloogist. Samuti tuleks kustutada .war-fail olemaks kindel, et Tomcat ei rakenda uuel käivitamisel veebiaplikatsiooni veebiarhiivifailist. Veelgi lihtsam on mahavõtmine brauseriga haldusrakenduse kaudu.

Rakenduste baaskataloogi "webapps" asukohta saab muuta failis $CATALINA_BASE/conf/server.xml peremehepõhiselt määratava atribuudiga "appBase", sealjuures Tomcati vaikimisi peremees ehk "Host" on "localhost".

====Tomcati vahendid juurutamiseks====

Veebiaplikatsioonide juurutamine ja mahajuurutamine on võimalik ka kaughalduse teel tänu Tomcati internetipõhisele haldusrakendusele. Näiteks saab veebibrauserit kasutades teha serveri põhitoiminguid Tomcati enda HTML-põhise rakendusega "Tomcat Manager". Veebipõhine haldusrakendus töötab ka käsupõhise veebiteenusena, millele on valmis ehitatud Anti ja Maveni integratsioonid. Samuti eksisteerib käsurea kliendirakendus TCD (Tomcat Client Deployer). TCD ei kuulu Tomcati baaskoosseisu, kuid pakub peale serveri administreerimise tavatoimingute ka lisafunktsionaalsust nagu veebirakenduse kokkukompileerimine ja pakendamine. [http://tomcat.apache.org/tomcat-8.0-doc/manager-howto.html#Configuring_Manager_Application_Access 1]

====Haldurakendus "Tomcat Manager"====

Tomcati haldusrakendus "Tomcat Manager" (antud alamjaotuses lihtsalt haldusrakendus) on Tomcati enda veebiaplikatioon Tomcati brauseripõhiseks kaughalduseks, võimaldades muu hulgas järgnevat [http://tomcat.apache.org/tomcat-8.0-doc/manager-howto.html#Introduction 1]:
* Rakendada uue veebiaplikatsiooni war-faili üleslaadimisega;
* Näha kõiki rakendatud veebiaplikatsioone koos aktiivsete sessioonidega;
* Taasrakendada veebirakendust, näiteks veebiarhiivi pakitud klassifailide /WEB-INF/classes või teekide /WEB-INF/lib uuendamisel, kinnijooksmisel jms.;
* Peatada veebirakendust ilma serverist eemaldamata, samuti koos serverist eemaldamisega;
* Vaadata operatsioonisüsteemi ja Java parameetrite väärtusi;
* Näha kõiki saadaolevaid JNDI ressursse, k.a. andmebaasiühendusi, mis aitavad rakenduste programmeerijail defineerida <ResourceLink> elemendid web.xml konfiguratsioonifailis.

Tomcati installatsioon sisaldab haldusrakendust juba vaikimisi. Haldusrakenduse töölepanemiseks tuleb peremeesmasina konfiguratsioonikataloogi $CATALINA_BASE/conf/[enginename]/[hostname] lisada ka fail manager.xml. Vaikimisi valmiskonfigureeritud testrakendusel on see fail juba olemas asukohas $CATALINA_BASE/conf/Catalina/localhost/manager.xml . Rakendus asub vaikimisi aadressil http://[host]/manager/ , vaikimisi konfiguratsioone kasutades lahendub see asukohaks http://localhost:8080/manager/ . [http://tomcat.apache.org/tomcat-8.0-doc/manager-howto.html#Configuring_Manager_Application_Access 1]

====="Tomcat Manager" ligipääsu konfigureerimine=====

Vaikimisi on turvalisuspõhjustel ligipääs haldusrakendusele maha keeratud. Mismoodi täpselt kasutajatel ligipääsu võimaldada sõltub kasutatavast valdusest (realm). Vaikimisi defineerib $CATALINA_BASE/conf/server.xml valduseks "MemoryRealm". Vaikimisi loeb valdus "MemoryRealm" kasutajad failist $CATALINA_BASE/conf/tomcat-users.xml. Antud failis tuleb iga kasutaja defineerida omaette märgendiga <user>, mis näeb välja umbes järgmine [http://tomcat.apache.org/tomcat-8.0-doc/manager-howto.html#Configuring_Manager_Application_Access 1]:
<pre>
<user name="craig" password="secret" roles="manager-gui,manager-script" />
</pre>

Antud kasutajale on defineeritud korraga kaks rolli. Ligipääsu võimaldamiseks tulebki lihtsamal juhul kasutajatefailis $CATALINA_BASE/conf/tomcat-users.xml defineerida enda kasutaja. Kasutaja rolliks võib määrata näiteks "manager-gui", mis võimaldab ligipääsu kogu HTML liidese funktsionaalsusele.

Teised valdused on "JDBCRealm", mille puhul hoitakse kasutajatega seonduvat infot andmebaasis ja JNDIRealm, mille puhul kasutatakse lihtsustatud kataloogisirvimise protokolli (LDAP).
Lisaks saab haldusrakendusele keelata ligipääsu mujalt kui kindlaksmääratud IP-aadressidelt, lisades filtri "RemoteAddrValve" või "RemoteHostValve" konfigureerimisfaili manager.xml näiteks järgmiselt [http://tomcat.apache.org/tomcat-8.0-doc/manager-howto.html#Introduction 1]:
<pre>
<Context privileged="true">
<Valve className="org.apache.catalina.valves.RemoteAddrValve"
allow="127\.0\.0\.1"/>
</Context>
</pre>

=====Juurutamine ja mahavõtmine haldusrakendusega "Tomcat Manager"=====

Juurutamiseks lae kõigepealt veebiarhiivifail üles, kasutades esilehel asuvat sektsiooni "WAR file to deploy". Veebiarhiivi üleslaadimise liides on kujutatud plidil 2.

[[File:tomcat_manager_war_upload.png|600px|thumb|right|Pilt 2: Veebiarhiivi üleslaadimise nupp]]

Rakendus kuvatakse seejärel hallatavate rakenduste nimekirjas. Kui konteiner pole seadistatud üleslaetud aplikatsiooni kohe ka ise rakendama, tuleb vajutada "Start". Rakenduse peatamiseks kasuta "Stop", uuesti rakendamiseks "Redeploy" ja serverist eemaldamiseks "Undeploy". Nupud on näha ka pildil 3 olevas rakenduste nimekirjas.


[[File:tomcat_manager_apps_list.png|1000px|thumb|Pilt 3: Rakenduste nimekiri]]

==Näpunäiteid Tomcati reaalseks kasutamiseks==

===Juurutamise järjekord===

Tomcati käivitumisel juurutatakse aplikatsioonid sellises järjekorras [http://www.mulesoft.com/tomcat-deploy-procedures 2]:
# Konteinerisse kopeeritud kontekstikirjelduste järgi $CATALINA_BASE/conf/[EngineName]/[HostName]/[ApplicationName].xml ;
# Lahtipakitud rakendused "webapps" kataloogis;
# Pakitud rakenduste veebiarhiivid "webapps" kataloogis.

Seetõttu peaks käsitsi taasjuurutamisel kindluse mõttes eelnevalt kustutama rakenduse lahtipakitud dokumendipõhja kataloogi "webapps" kataloogist. Kontekstikirjelduse muutumisel tuleb jälgida, kas kirjeldus on juba kopeeritud serverisse ning vajadusel eelmise versiooni ümber muuta või kustutada.

===Reaalsele domeenile konfigureerimine===

Järgnevalt eeldame, et domeen ''www.minukodukas.ee'' on juba serverimasinaga seostatud. Et Tomcat hakkaks ka reaalselt Internetist tulevatele päringutele vastama, tuleb muuta failis $CATALINA_BASE/conf/server.xml konteinerile ''Catalina'' vastava teenusemärgendi sisu sarnaselt järgnevaga:

<pre>
<Service name="Catalina">
<Connector port="80" protocol="HTTP/1.1" connectionTimeout="20000" URIEncoding="UTF-8" redirectPort="8443" />
<Engine name="Catalina" defaultHost="www.minukodukas.ee">
<Host name="www.minukodukas.ee" appBase="webapps" unpackWARs="true" autoDeploy="false" deployOnStartup="false" xmlValidation="false" xmlNamespaceAware="false">
<Context path="" docBase="kodukas" debug="0" reloadable="true" />
</Host>
</Engine>
</Service>
</pre>

Ülal defineerime põhiliselt selle, et Tomcat kuulaks domeeni ''www.minukodukas.ee'' ja kasutaks HTTP päringute jaoks porti 80. Ühtlasti otsib Tomcat juurutatavat rakendust failist $CATALINA_BASE/webapps/kodukas.war. Kuna rajalisandiks on määratud tühi sõne (path=""), siis juurutataksegi aplikatsioon aadressile ''www.minukodukas.ee'' ilma rajalisandita (a'la ''www.minukodukas.ee/wiki''). Seetõttu pakitakse ka veebiarhiiv tegelikult lahti kataloogi $CATALINA_BASE/webapps/ROOT mitte kataloogi $CATALINA_BASE/webapps/kodukas nagu võiks eeldada.

===Käigultvahetus===

Võimaldamaks käigultvahetust (hot deployment) peab konteineri konfiguratsioonifailis $CATALINA_BASE/conf/server.xml olema peremehepõhise märgendi "Host" atribuudi "autoDeploy" väärtus "true". Sel juhul installeerib ja uuendab Tomcat aplikatsioone dünaamiliselt töötamise ajal. Kui väärtuseks on "false", käib installeerimine staatiliselt ning serverisse juurutamiseks tuleb teha konteineri taaskäivitus. Käigultvahetust saab määrata ka peremehe defineerimisel "Host Manager" rakendusega, mis on kättesaadav aadressil http://localhost:8080/host-manager/html . Kasutamiseks tuleb lisada oma kasutajale rolli "admin-gui" (vt. alajaotus ""Tomcat Manager" ligipääsu konfigureerimine").

[[File:host_manager_app.png]]

Käigultvahetust päästikuks on vaikimisi uuendatud veebiarhiivifaili või lahtipakitud veebirakenduse paigutamine "webapps" kataloogi. Käigultvahetuse päästikutele võib failis $CATALINA_BASE/conf/server.xml ka ise lisada kuulatavaid ressursse nagu web.xml muutmine või mõne teegifaili vahetamine (märgendis "Host").

===Klassiteekide väljatõstmine veebiarhiivifailist===

Kõik konteksti poolt kasutatavad Java klassiteegid võib pakendada veebiarhiivi sisse kataloogi "lib", kuid nii võib osutuda veebiarhiivi üleslaadimine ajakulukaks, eriti arenduskeskkonnas. Kui ei teki ohtu, et erinevad rakendused kasutavad sama teegi erinevaid versioone, siis on vahel parem lisada osa teeke konteineri kataloogi $CATALINA_BASE/libs, kust need tehakse siis konteineri poolt kättesaadavaks kõigile konteineris jooksutatavatele kontekstidele. Nii võib vähendada veebiarhiivi faili suurust märgatavalt, mis tõstab kokkuvõttes juurutamiskiirust ja ühes sellega programmeerijate tööviljakust.

===Mälukasutus===

Konteineri poolt kasutatavat mälu saab vaadata haldusrakendusest vajutades lingile "Server Status". Mälukasutus on toodud jaotuses "JVM", kus näidatakse nii maksimaalselt kättesaadavat mälu kui ka parasjagu reserveeritud mälu.

<pre>Free memory: 41.16 MB Total memory: 123.37 MB Max memory: 1027.56 MB</pre>

Mälu suurendamiseks võib näiteks defineerida skriptis $CATALINA_BASE/bin/catalina.sh muutuja "JAVA_OPTS" ning määrata Java mälukasutuse miinimum- ja maksimumväärtused sarnaselt järgnevatega [http://www.mkyong.com/tomcat/tomcat-javalangoutofmemoryerror-permgen-space/ 3]:
<pre>
JAVA_OPTS="-Xms1536m -Xmx1536m -XX:NewSize=256m -XX:MaxNewSize=256m -XX:PermSize=256m -XX:MaxPermSize=256m"
</pre>

===Logifailid===

Vaikimisi defineerib Tomcat failiga $CATALINA_BASE/conf/logging.properties viis logerit, mis tekitavad viis eraldi logifaili.

{| style="background:#cccc99;color:black;width:80%;" border="1" cellpadding="5" cellspacing="0" align="center"
|+ Tomcati tekitatavad logifailid "logs" kataloogis
!Fail !! Kasutus
|- style="background:white; color:black"
| style="width:300px" |catalina.out
| Tomcati käivitus- ja peatamisskriptide väljund, samuti juurutatud rakenduste prindilaused System.out ja veaväljundid System.err
|- style="background:white; color:black"
| style="width:300px" |catalina.[yyyy]-[mm]-[dd].log
| Pööratud (rotated) logifail catalina.out
|- style="background:white; color:black"
| style="width:300px" |host-manager.[yyyy]-[mm]-[dd].log
| Logi peremehehalduse rakendusele (rakendus on kättesaadav kohalikust masinast aadressil http://localhost:8080/host-manager/html )
|- style="background:white; color:black"
| style="width:300px" |localhost.[yyyy]-[mm]-[dd].log
| Peremehe "localhost" logi; mitme virtuaalse peremehe korral tekitatakse igale peremehele oma logi
|- style="background:white; color:black"
| style="width:300px" |localhost_access_log.[yyyy]-[mm]-[dd].txt
| Konteinerisse Internetist saabunud päringute logi
|- style="background:white; color:black"
| style="width:300px" |manager.[yyyy]-[mm]-[dd].log
| Haldusrakenduse tegevuste logi
|}

===Viiteid===

Palju vajalikku võib leida [http://tomcat.apache.org/tomcat-8.0-doc/index.html Tomcat 8 dokumentatsioonist]

Lisaks üks viide põhjalikule Tomcati versioon seitsme ülevaatele: http://www.ntu.edu.sg/home/ehchua/programming/howto/Tomcat_More.html

= Kasutatud materjalid =

#http://tomcat.apache.org/tomcat-8.0-doc/index.html
#http://www.mulesoft.com/tomcat-deploy-procedures
#http://www.mkyong.com/tomcat/tomcat-javalangoutofmemoryerror-permgen-space/

[[Category: Operatsioonisüsteemide administreerimine ja sidumine]]

Tomcat

2014-01-02T22:13:13Z

Kveskima: /* Juurutamine ja mahavõtmine haldusrakendusega "Tomcat Manager" */

==Autor==

Kristjan Veskimäe D32

2013

==Sissejuhatus==

Tomcat on vabalt kättesaadav server Java veebirakendustele. Põhimõtteliselt on tegemist Servlet/JSP spetsifikatsiooni toetava konteineriga. Kiire käivitumise ning rakenduste käigultvahetuse tõttu on Tomcat hea valik väiksemate ning keskmise suurusega Java veebirakenduste käitamiseks.

Antud töö kirjeldab Tomcati 8. versiooni. Põhiosa on üldiselt samasugune võrreldes paari eelmise versiooniga. Suuremad erinevused on versioonispetsiifilistes probleemides ja nende lahendamises, mida käesolev töö ei vaatle.

Töö vaatleb Tomcati paigaldamist ja seadistamist Unix-laadsesse keskkonda ning eeldab lugejalt algteadmisi sarnastes süsteemides. Tomcati on võimalik paigaldada ka Windows-keskkonda, kuid antud veebiserver eeldab kasutaja poolt käsureal töötamist ning Tomcati failihierarhias orienteerumist. Põhimõtteliselt on Java veebirakenduste arendamiseks IDE-abil võimalik siiski ka kasutada IDE-sse integreeritud Tomcati serverit - näiteks pakuvad sellist võimalust Eclipse EE ja NetBeans - kuid seda käesolev töö ei vaatle.

==Mõisted==

* '''Kontekst''' (context) - Tomcati mõistes üks konkreetne veebiaplikatsioon
* '''Konteiner''' (container) - veebiserver Tomcat ise
* '''Kontekstikirjeldus''' (context descriptor) - Tomcati-spetsiifiline konteksti konfiguratsioonimääratlus; peremehepõhine osa loetakse failist $CATALINA_HOME/conf/[enginename]/[hostname]/context.xml ja sellele lisatakse kontekstispetsiifilised täpsustused failist $CATALINA_BASE/conf/[enginename]/[hostname]/[webappname].xml; kontekstikirjeldus määrab näiteks nimed ressurssidele, sessioonihalduse parameetrid jmt. (olgu märgitud, et Tomcati varasemates versioonides sisaldusid kontekstikirjeldused põhikonfiguratsioonifailis server.xml)
* '''Dokumendipõhi''' (docBase) - kontekstile vastav kataloog Tomcati "webapps" kataloogis, mis tekib veebiaplikatsiooni serverisse rakendamisel
* '''Veebiarhiiv''' (Web application ARchive, war-file) - Java veebiaplikatsiooni jagatakse hea tava kohaselt selle üheainsa veebiarhiivi failina, mille laienditüübiks on "war". Tegemist on zip-protokolliga kokkupakitud kataloogiga, millel on Java veebirakenduste spetsifikatsioonile vastav ülesehitus. Siiski võib veebiaplikatsioon olla juurutamisel ka lahtipakendatud olekus (inglisekeelne termin on "war is exploded").

==Ülesehitus==

{| class="wikitable"
|+Kataloogid
|-
|style="color: green;" | $CATALINA_HOME
|baaskataloog, kuhu on Tomcat paigutatud
|-
|style="color: green;" | $CATALINA_BASE
|parasjagu töösoleva Tomcati eksemplari baaskataloog, mille alusel lahendatakse teed ülejäänud kataloogide ja failideni; ainult ühe kasutusel oleva Tomcati eksemplari puhul on see sama, mis $CATALINA_HOME

|-
|style="color: green;" | $CATALINA_BASE/bin
|serveri käivitus- ja abiskriptid
|-
|style="color: green;" | $CATALINA_BASE/conf
|konfiguratsioonifailid
|-
|style="color: green;" | $CATALINA_BASE/lib
|Tomcatile vaikimisi kättesaadavad Java klassiteegid (class libraries) ehk .jar-failid kuhu on Java kompileeritud kood kokku pakendatud
|-
|style="color: green;" | $CATALINA_BASE/logs
|logifailid paigutatakse vaikimisi siia
|-
|style="color: green;" | $CATALINA_BASE/webapps
|kataloog, kuhu paigutatakse serverisse juurutatavad veebiaplikatsioonid

|}

{| class="wikitable"
|+Mõned olulisemad failid
|-
|style="color: green;" | $CATALINA_BASE/bin/startup.sh
|serveri käivitusskript
|-
|style="color: green;" | $CATALINA_BASE/bin/shutdown.sh
|serveri peatusskript

|-
|style="color: green;" | $CATALINA_BASE/conf/server.xml
| konteineri peamine konfiguratsioonifail
|-
|style="color: green;" | $CATALINA_BASE/conf/[enginename]/[hostname]/[webappname].xml
|serveri administraatori jaoks konteinerisse endasse ümber kopeeritud rakendusepõhine kontekstikirjelduse konfiguratsioon failist $CATALINA_BASE/webapps/[ApplicationName]/META-INF/context.xml
|-
|style="color: green;" | $CATALINA_BASE/conf/[enginename]/[hostname]/context.xml
| fail, mis aitab administraatoril konteksti kohta käivat infot kirjeldada peremeesmasina-põhiselt ja halduseks mõeldud automaat-tööriistadel (näiteks Tomcat Manager ja TCD) oma tööd teha
|-
|style="color: green;" | $CATALINA_BASE/$CATALINA_BASE/conf/[enginename]/[hostname]/manager.xml
|fail, mis võimaldab lisada rakendustele ligipääsufiltreid
|-
|style="color: green;" | $CATALINA_BASE/webapps/[webappname]/META-INF/context.xml
|kontekstikirjeldusfail, mille veebirakenduse programmeerija on pakendanud oma aplikatsiooniga kaasa ning millega ta saab võimaluse kontekstikirjeldust omalt poolt mõjutada; kirjutatakse rakenduse uuestijuurutamisel üle, mistõttu administraator peaks muutma selle asemel konteinerisse ümber kopeeritud püsieksemplari $CATALINA_BASE/conf/[enginename]/[hostname]/context.xml
|-
|style="color: green;" | $CATALINA_BASE/webapps/[webappname]/WEB-INF/web.xml
|ka üks oluline Java veebiaplikatsiooni konfiguratsioonifail, mille pakendatakse koos veebiarhiiviga; enamasti muudab seda ainult programeerija; määrab muu hulgas millised aplikatsiooni osad vajavad autentimist või kui kiiresti veebisessioon aegub
|}

==Installeerimine==

===Installeerimine paketihalduriga===

<pre>
apt-cache search tomcat
apt-get install tomcat[version]-webapps
apt-get install tomcat[version]-admin
apt-get install tomcat[version]
</pre>

===Installeerimine käsitsi===

Paketihalduriga installeerides ei pruugi viimane Tomcati versioon olla kättesaadav ja see pakub ka vähem võimalusi kataloogide määramiseks jms. Käsitsi installeerimiseks tuleb laadida Tomcat kodulehelt alla. Lahtipakkimisel tekib kataloog, milles sisalduv fail "RUNNING.txt" on kõige kindlam allikas installeerimisel tekkivate probleemide vältimiseks ning lahendamiseks.

Vajaliku versiooni installeerimisfaili asukoha saab vaadata Tomcati kodulehelt sektsioonist "Download". Järgnevas näites installeerime Tomcati kõige uuema ebastabiilse kandidaatversiooni, mida näitab nimes sisalduv RC ehk "release candidate". Produktsioonikeskkonda tuleks siiski valida stabiilse versiooni. Käsitsi installeerimine on sarnane järgmisega:
<pre>
wget http://mirror.nexcess.net/apache/tomcat/tomcat-8/v8.0.0-RC5/bin/apache-tomcat-8.0.0-RC5.tar.gz
tar -zxvf apache-tomcat-8.0.0-RC5.tar.gz
mv /Users/kristjanveskimae/downloads/apache-tomcat-8.0.0-RC5 /usr/local/apache-tomcat-8.0.0-RC5
rm -f /Library/Tomcat
ln -s /usr/local/apache-tomcat-8.0.0-RC5/ /Library/Tomcat
chown -R kristjanveskimae /Library/Tomcat
chmod +x /Library/Tomcat/bin/*.sh
</pre>

==Käivitamine ja aplikatsiooni juurutamine==

===Konteineri käivitamine===

Tomcati käivitamise eelduseks on Java paigaldamine masinasse ning keskkonnamuutujate "JAVA_HOME" ja "JRE_HOME" defineerimine. Peale installeerimist võib kasutada skripte kataloogist $CATALINA_BASE/bin . Järgneb üks võimalik käivitamise ja peatamise näide, mis on kasutatav eelnevalt kirjeldatud käsitsi installeerimise juhul:
<pre>
/Library/Tomcat/bin/startup.sh
</pre>
ja peatamiseks
<pre>
/Library/Tomcat/bin/shutdown.sh
</pre>

===Näiteaplikatsiooni juurutamine===

Java veebiaplikatsiooni jagatakse hea tava kohaselt üheainsa veebiarhiivi failina. Siiski võib Tomcati juurutada ka lahtipakendatud olekus ("exploded") Java veebiaplikatsiooni.

====Käsitsi juurutamine ja mahavõtmine====

Näiteaplikatsiooni juurutamiseks lae selle veebiarhiivifail alla ning kopeeri oma konteineri juurutamiskataloogi 'webapps':
<pre>wget http://tomcat.apache.org/tomcat-8.0-doc/appdev/sample/sample.war
cp /Users/kristjanveskimae/downloads/sample.war /Library/Tomcat/webapps/sample.war</pre>

[[File:sample_app.png|400px|thumb|right|Pilt 1: Õnnestunult rakendatud näiteaplikatsioon]]

Kui konfiguratsioonifailis $CATALINA_BASE/conf/server.xml on märgendi "Host" atribuudi "autoDeploy" väärtus "true", installeerib ja uuendab Tomcat aplikatsioone dünaamiliselt töötamise ajal. Kui väärtuseks on "false", käib installeerimine staatiliselt ning serverisse juurutamiseks tuleb teha konteineri taaskäivitus. [http://tomcat.apache.org/tomcat-8.0-doc/manager-howto.html#Deploy_A_New_Application_from_a_Local_Path 1] Mõlemal juhul pakib konteiner arhiveeritud faili ise lahti samasse kausta $CATALINA_BASE/webapps ning ka juurutab selle. Tekkiv aplikatsioon on lokaalsest masinast seejärel kättesaadav aadressil http://localhost:8080/sample/ . Kui rakendamine õnnestub, siis peaks olema brauserist nähtav sarnane lehekülg nagu pildil 1.

Veebirakenduse käsitsi mahavõtmiseks tuleb kustutada talle vastav dokumendipõhja kataloog "webapps" kataloogist. Samuti tuleks kustutada .war-fail olemaks kindel, et Tomcat ei rakenda uuel käivitamisel veebiaplikatsiooni veebiarhiivifailist. Veelgi lihtsam on mahavõtmine brauseriga haldusrakenduse kaudu.

Rakenduste baaskataloogi "webapps" asukohta saab muuta failis $CATALINA_BASE/conf/server.xml peremehepõhiselt määratava atribuudiga "appBase", sealjuures Tomcati vaikimisi peremees ehk "Host" on "localhost".

====Tomcati vahendid juurutamiseks====

Veebiaplikatsioonide juurutamine ja mahajuurutamine on võimalik ka kaughalduse teel tänu Tomcati internetipõhisele haldusrakendusele. Näiteks saab veebibrauserit kasutades teha serveri põhitoiminguid Tomcati enda HTML-põhise rakendusega "Tomcat Manager". Veebipõhine haldusrakendus töötab ka käsupõhise veebiteenusena, millele on valmis ehitatud Anti ja Maveni integratsioonid. Samuti eksisteerib käsurea kliendirakendus TCD (Tomcat Client Deployer). TCD ei kuulu Tomcati baaskoosseisu, kuid pakub peale serveri administreerimise tavatoimingute ka lisafunktsionaalsust nagu veebirakenduse kokkukompileerimine ja pakendamine. [http://tomcat.apache.org/tomcat-8.0-doc/manager-howto.html#Configuring_Manager_Application_Access 1]

====Haldurakendus "Tomcat Manager"====

Tomcati haldusrakendus "Tomcat Manager" (antud alamjaotuses lihtsalt haldusrakendus) on Tomcati enda veebiaplikatioon Tomcati brauseripõhiseks kaughalduseks, võimaldades muu hulgas järgnevat [http://tomcat.apache.org/tomcat-8.0-doc/manager-howto.html#Introduction 1]:
* Rakendada uue veebiaplikatsiooni war-faili üleslaadimisega;
* Näha kõiki rakendatud veebiaplikatsioone koos aktiivsete sessioonidega;
* Taasrakendada veebirakendust, näiteks veebiarhiivi pakitud klassifailide /WEB-INF/classes või teekide /WEB-INF/lib uuendamisel, kinnijooksmisel jms.;
* Peatada veebirakendust ilma serverist eemaldamata, samuti koos serverist eemaldamisega;
* Vaadata operatsioonisüsteemi ja Java parameetrite väärtusi;
* Näha kõiki saadaolevaid JNDI ressursse, k.a. andmebaasiühendusi, mis aitavad rakenduste programmeerijail defineerida <ResourceLink> elemendid web.xml konfiguratsioonifailis.

Tomcati installatsioon sisaldab haldusrakendust juba vaikimisi. Haldusrakenduse töölepanemiseks tuleb peremeesmasina konfiguratsioonikataloogi $CATALINA_BASE/conf/[enginename]/[hostname] lisada ka fail manager.xml. Vaikimisi valmiskonfigureeritud testrakendusel on see fail juba olemas asukohas $CATALINA_BASE/conf/Catalina/localhost/manager.xml . Rakendus asub vaikimisi aadressil http://[host]/manager/ , vaikimisi konfiguratsioone kasutades lahendub see asukohaks http://localhost:8080/manager/ . [http://tomcat.apache.org/tomcat-8.0-doc/manager-howto.html#Configuring_Manager_Application_Access 1]

====="Tomcat Manager" ligipääsu konfigureerimine=====

Vaikimisi on turvalisuspõhjustel ligipääs haldusrakendusele maha keeratud. Mismoodi täpselt kasutajatel ligipääsu võimaldada sõltub kasutatavast valdusest (realm). Vaikimisi defineerib $CATALINA_BASE/conf/server.xml valduseks "MemoryRealm". Vaikimisi loeb valdus "MemoryRealm" kasutajad failist $CATALINA_BASE/conf/tomcat-users.xml. Antud failis tuleb iga kasutaja defineerida omaette märgendiga <user>, mis näeb välja umbes järgmine [http://tomcat.apache.org/tomcat-8.0-doc/manager-howto.html#Configuring_Manager_Application_Access 1]:
<pre>
<user name="craig" password="secret" roles="manager-gui,manager-script" />
</pre>

Antud kasutajale on defineeritud korraga kaks rolli. Ligipääsu võimaldamiseks tulebki lihtsamal juhul kasutajatefailis $CATALINA_BASE/conf/tomcat-users.xml defineerida enda kasutaja. Kasutaja rolliks võib määrata näiteks "manager-gui", mis võimaldab ligipääsu kogu HTML liidese funktsionaalsusele.

Teised valdused on "JDBCRealm", mille puhul hoitakse kasutajatega seonduvat infot andmebaasis ja JNDIRealm, mille puhul kasutatakse lihtsustatud kataloogisirvimise protokolli (LDAP).
Lisaks saab haldusrakendusele keelata ligipääsu mujalt kui kindlaksmääratud IP-aadressidelt, lisades filtri "RemoteAddrValve" või "RemoteHostValve" konfigureerimisfaili manager.xml näiteks järgmiselt [http://tomcat.apache.org/tomcat-8.0-doc/manager-howto.html#Introduction 1]:
<pre>
<Context privileged="true">
<Valve className="org.apache.catalina.valves.RemoteAddrValve"
allow="127\.0\.0\.1"/>
</Context>
</pre>

=====Juurutamine ja mahavõtmine haldusrakendusega "Tomcat Manager"=====

Juurutamiseks lae kõigepealt veebiarhiivifail üles, kasutades esilehel asuvat sektsiooni "WAR file to deploy". Veebiarhiivi üleslaadimise liides on kujutatud plidil 2.

[[File:tomcat_manager_war_upload.png|300px|thumb|right|Pilt 2: Veebiarhiivi üleslaadimise nupp]]

Rakendus kuvatakse seejärel hallatavate rakenduste nimekirjas. Kui konteiner pole seadistatud üleslaetud aplikatsiooni kohe ka ise rakendama, tuleb vajutada "Start". Rakenduse peatamiseks kasuta "Stop", uuesti rakendamiseks "Redeploy" ja serverist eemaldamiseks "Undeploy". Nupud on näha ka pildil 3 olevas rakenduste nimekirjas.


[[File:tomcat_manager_apps_list.png|800px|thumb|Pilt 3: Rakenduste nimekiri]]

==Näpunäiteid Tomcati reaalseks kasutamiseks==

===Juurutamise järjekord===

Tomcati käivitumisel juurutatakse aplikatsioonid sellises järjekorras [http://www.mulesoft.com/tomcat-deploy-procedures 2]:
# Konteinerisse kopeeritud kontekstikirjelduste järgi $CATALINA_BASE/conf/[EngineName]/[HostName]/[ApplicationName].xml ;
# Lahtipakitud rakendused "webapps" kataloogis;
# Pakitud rakenduste veebiarhiivid "webapps" kataloogis.

Seetõttu peaks käsitsi taasjuurutamisel kindluse mõttes eelnevalt kustutama rakenduse lahtipakitud dokumendipõhja kataloogi "webapps" kataloogist. Kontekstikirjelduse muutumisel tuleb jälgida, kas kirjeldus on juba kopeeritud serverisse ning vajadusel eelmise versiooni ümber muuta või kustutada.

===Reaalsele domeenile konfigureerimine===

Järgnevalt eeldame, et domeen ''www.minukodukas.ee'' on juba serverimasinaga seostatud. Et Tomcat hakkaks ka reaalselt Internetist tulevatele päringutele vastama, tuleb muuta failis $CATALINA_BASE/conf/server.xml konteinerile ''Catalina'' vastava teenusemärgendi sisu sarnaselt järgnevaga:

<pre>
<Service name="Catalina">
<Connector port="80" protocol="HTTP/1.1" connectionTimeout="20000" URIEncoding="UTF-8" redirectPort="8443" />
<Engine name="Catalina" defaultHost="www.minukodukas.ee">
<Host name="www.minukodukas.ee" appBase="webapps" unpackWARs="true" autoDeploy="false" deployOnStartup="false" xmlValidation="false" xmlNamespaceAware="false">
<Context path="" docBase="kodukas" debug="0" reloadable="true" />
</Host>
</Engine>
</Service>
</pre>

Ülal defineerime põhiliselt selle, et Tomcat kuulaks domeeni ''www.minukodukas.ee'' ja kasutaks HTTP päringute jaoks porti 80. Ühtlasti otsib Tomcat juurutatavat rakendust failist $CATALINA_BASE/webapps/kodukas.war. Kuna rajalisandiks on määratud tühi sõne (path=""), siis juurutataksegi aplikatsioon aadressile ''www.minukodukas.ee'' ilma rajalisandita (a'la ''www.minukodukas.ee/wiki''). Seetõttu pakitakse ka veebiarhiiv tegelikult lahti kataloogi $CATALINA_BASE/webapps/ROOT mitte kataloogi $CATALINA_BASE/webapps/kodukas nagu võiks eeldada.

===Käigultvahetus===

Võimaldamaks käigultvahetust (hot deployment) peab konteineri konfiguratsioonifailis $CATALINA_BASE/conf/server.xml olema peremehepõhise märgendi "Host" atribuudi "autoDeploy" väärtus "true". Sel juhul installeerib ja uuendab Tomcat aplikatsioone dünaamiliselt töötamise ajal. Kui väärtuseks on "false", käib installeerimine staatiliselt ning serverisse juurutamiseks tuleb teha konteineri taaskäivitus. Käigultvahetust saab määrata ka peremehe defineerimisel "Host Manager" rakendusega, mis on kättesaadav aadressil http://localhost:8080/host-manager/html . Kasutamiseks tuleb lisada oma kasutajale rolli "admin-gui" (vt. alajaotus ""Tomcat Manager" ligipääsu konfigureerimine").

[[File:host_manager_app.png]]

Käigultvahetust päästikuks on vaikimisi uuendatud veebiarhiivifaili või lahtipakitud veebirakenduse paigutamine "webapps" kataloogi. Käigultvahetuse päästikutele võib failis $CATALINA_BASE/conf/server.xml ka ise lisada kuulatavaid ressursse nagu web.xml muutmine või mõne teegifaili vahetamine (märgendis "Host").

===Klassiteekide väljatõstmine veebiarhiivifailist===

Kõik konteksti poolt kasutatavad Java klassiteegid võib pakendada veebiarhiivi sisse kataloogi "lib", kuid nii võib osutuda veebiarhiivi üleslaadimine ajakulukaks, eriti arenduskeskkonnas. Kui ei teki ohtu, et erinevad rakendused kasutavad sama teegi erinevaid versioone, siis on vahel parem lisada osa teeke konteineri kataloogi $CATALINA_BASE/libs, kust need tehakse siis konteineri poolt kättesaadavaks kõigile konteineris jooksutatavatele kontekstidele. Nii võib vähendada veebiarhiivi faili suurust märgatavalt, mis tõstab kokkuvõttes juurutamiskiirust ja ühes sellega programmeerijate tööviljakust.

===Mälukasutus===

Konteineri poolt kasutatavat mälu saab vaadata haldusrakendusest vajutades lingile "Server Status". Mälukasutus on toodud jaotuses "JVM", kus näidatakse nii maksimaalselt kättesaadavat mälu kui ka parasjagu reserveeritud mälu.

<pre>Free memory: 41.16 MB Total memory: 123.37 MB Max memory: 1027.56 MB</pre>

Mälu suurendamiseks võib näiteks defineerida skriptis $CATALINA_BASE/bin/catalina.sh muutuja "JAVA_OPTS" ning määrata Java mälukasutuse miinimum- ja maksimumväärtused sarnaselt järgnevatega [http://www.mkyong.com/tomcat/tomcat-javalangoutofmemoryerror-permgen-space/ 3]:
<pre>
JAVA_OPTS="-Xms1536m -Xmx1536m -XX:NewSize=256m -XX:MaxNewSize=256m -XX:PermSize=256m -XX:MaxPermSize=256m"
</pre>

===Logifailid===

Vaikimisi defineerib Tomcat failiga $CATALINA_BASE/conf/logging.properties viis logerit, mis tekitavad viis eraldi logifaili.

{| style="background:#cccc99;color:black;width:80%;" border="1" cellpadding="5" cellspacing="0" align="center"
|+ Tomcati tekitatavad logifailid "logs" kataloogis
!Fail !! Kasutus
|- style="background:white; color:black"
| style="width:300px" |catalina.out
| Tomcati käivitus- ja peatamisskriptide väljund, samuti juurutatud rakenduste prindilaused System.out ja veaväljundid System.err
|- style="background:white; color:black"
| style="width:300px" |catalina.[yyyy]-[mm]-[dd].log
| Pööratud (rotated) logifail catalina.out
|- style="background:white; color:black"
| style="width:300px" |host-manager.[yyyy]-[mm]-[dd].log
| Logi peremehehalduse rakendusele (rakendus on kättesaadav kohalikust masinast aadressil http://localhost:8080/host-manager/html )
|- style="background:white; color:black"
| style="width:300px" |localhost.[yyyy]-[mm]-[dd].log
| Peremehe "localhost" logi; mitme virtuaalse peremehe korral tekitatakse igale peremehele oma logi
|- style="background:white; color:black"
| style="width:300px" |localhost_access_log.[yyyy]-[mm]-[dd].txt
| Konteinerisse Internetist saabunud päringute logi
|- style="background:white; color:black"
| style="width:300px" |manager.[yyyy]-[mm]-[dd].log
| Haldusrakenduse tegevuste logi
|}

===Viiteid===

Palju vajalikku võib leida [http://tomcat.apache.org/tomcat-8.0-doc/index.html Tomcat 8 dokumentatsioonist]

Lisaks üks viide põhjalikule Tomcati versioon seitsme ülevaatele: http://www.ntu.edu.sg/home/ehchua/programming/howto/Tomcat_More.html

= Kasutatud materjalid =

#http://tomcat.apache.org/tomcat-8.0-doc/index.html
#http://www.mulesoft.com/tomcat-deploy-procedures
#http://www.mkyong.com/tomcat/tomcat-javalangoutofmemoryerror-permgen-space/

[[Category: Operatsioonisüsteemide administreerimine ja sidumine]]

Tomcat

2014-01-02T22:12:50Z

Kveskima: /* Juurutamine ja mahavõtmine haldusrakendusega "Tomcat Manager" */

==Autor==

Kristjan Veskimäe D32

2013

==Sissejuhatus==

Tomcat on vabalt kättesaadav server Java veebirakendustele. Põhimõtteliselt on tegemist Servlet/JSP spetsifikatsiooni toetava konteineriga. Kiire käivitumise ning rakenduste käigultvahetuse tõttu on Tomcat hea valik väiksemate ning keskmise suurusega Java veebirakenduste käitamiseks.

Antud töö kirjeldab Tomcati 8. versiooni. Põhiosa on üldiselt samasugune võrreldes paari eelmise versiooniga. Suuremad erinevused on versioonispetsiifilistes probleemides ja nende lahendamises, mida käesolev töö ei vaatle.

Töö vaatleb Tomcati paigaldamist ja seadistamist Unix-laadsesse keskkonda ning eeldab lugejalt algteadmisi sarnastes süsteemides. Tomcati on võimalik paigaldada ka Windows-keskkonda, kuid antud veebiserver eeldab kasutaja poolt käsureal töötamist ning Tomcati failihierarhias orienteerumist. Põhimõtteliselt on Java veebirakenduste arendamiseks IDE-abil võimalik siiski ka kasutada IDE-sse integreeritud Tomcati serverit - näiteks pakuvad sellist võimalust Eclipse EE ja NetBeans - kuid seda käesolev töö ei vaatle.

==Mõisted==

* '''Kontekst''' (context) - Tomcati mõistes üks konkreetne veebiaplikatsioon
* '''Konteiner''' (container) - veebiserver Tomcat ise
* '''Kontekstikirjeldus''' (context descriptor) - Tomcati-spetsiifiline konteksti konfiguratsioonimääratlus; peremehepõhine osa loetakse failist $CATALINA_HOME/conf/[enginename]/[hostname]/context.xml ja sellele lisatakse kontekstispetsiifilised täpsustused failist $CATALINA_BASE/conf/[enginename]/[hostname]/[webappname].xml; kontekstikirjeldus määrab näiteks nimed ressurssidele, sessioonihalduse parameetrid jmt. (olgu märgitud, et Tomcati varasemates versioonides sisaldusid kontekstikirjeldused põhikonfiguratsioonifailis server.xml)
* '''Dokumendipõhi''' (docBase) - kontekstile vastav kataloog Tomcati "webapps" kataloogis, mis tekib veebiaplikatsiooni serverisse rakendamisel
* '''Veebiarhiiv''' (Web application ARchive, war-file) - Java veebiaplikatsiooni jagatakse hea tava kohaselt selle üheainsa veebiarhiivi failina, mille laienditüübiks on "war". Tegemist on zip-protokolliga kokkupakitud kataloogiga, millel on Java veebirakenduste spetsifikatsioonile vastav ülesehitus. Siiski võib veebiaplikatsioon olla juurutamisel ka lahtipakendatud olekus (inglisekeelne termin on "war is exploded").

==Ülesehitus==

{| class="wikitable"
|+Kataloogid
|-
|style="color: green;" | $CATALINA_HOME
|baaskataloog, kuhu on Tomcat paigutatud
|-
|style="color: green;" | $CATALINA_BASE
|parasjagu töösoleva Tomcati eksemplari baaskataloog, mille alusel lahendatakse teed ülejäänud kataloogide ja failideni; ainult ühe kasutusel oleva Tomcati eksemplari puhul on see sama, mis $CATALINA_HOME

|-
|style="color: green;" | $CATALINA_BASE/bin
|serveri käivitus- ja abiskriptid
|-
|style="color: green;" | $CATALINA_BASE/conf
|konfiguratsioonifailid
|-
|style="color: green;" | $CATALINA_BASE/lib
|Tomcatile vaikimisi kättesaadavad Java klassiteegid (class libraries) ehk .jar-failid kuhu on Java kompileeritud kood kokku pakendatud
|-
|style="color: green;" | $CATALINA_BASE/logs
|logifailid paigutatakse vaikimisi siia
|-
|style="color: green;" | $CATALINA_BASE/webapps
|kataloog, kuhu paigutatakse serverisse juurutatavad veebiaplikatsioonid

|}

{| class="wikitable"
|+Mõned olulisemad failid
|-
|style="color: green;" | $CATALINA_BASE/bin/startup.sh
|serveri käivitusskript
|-
|style="color: green;" | $CATALINA_BASE/bin/shutdown.sh
|serveri peatusskript

|-
|style="color: green;" | $CATALINA_BASE/conf/server.xml
| konteineri peamine konfiguratsioonifail
|-
|style="color: green;" | $CATALINA_BASE/conf/[enginename]/[hostname]/[webappname].xml
|serveri administraatori jaoks konteinerisse endasse ümber kopeeritud rakendusepõhine kontekstikirjelduse konfiguratsioon failist $CATALINA_BASE/webapps/[ApplicationName]/META-INF/context.xml
|-
|style="color: green;" | $CATALINA_BASE/conf/[enginename]/[hostname]/context.xml
| fail, mis aitab administraatoril konteksti kohta käivat infot kirjeldada peremeesmasina-põhiselt ja halduseks mõeldud automaat-tööriistadel (näiteks Tomcat Manager ja TCD) oma tööd teha
|-
|style="color: green;" | $CATALINA_BASE/$CATALINA_BASE/conf/[enginename]/[hostname]/manager.xml
|fail, mis võimaldab lisada rakendustele ligipääsufiltreid
|-
|style="color: green;" | $CATALINA_BASE/webapps/[webappname]/META-INF/context.xml
|kontekstikirjeldusfail, mille veebirakenduse programmeerija on pakendanud oma aplikatsiooniga kaasa ning millega ta saab võimaluse kontekstikirjeldust omalt poolt mõjutada; kirjutatakse rakenduse uuestijuurutamisel üle, mistõttu administraator peaks muutma selle asemel konteinerisse ümber kopeeritud püsieksemplari $CATALINA_BASE/conf/[enginename]/[hostname]/context.xml
|-
|style="color: green;" | $CATALINA_BASE/webapps/[webappname]/WEB-INF/web.xml
|ka üks oluline Java veebiaplikatsiooni konfiguratsioonifail, mille pakendatakse koos veebiarhiiviga; enamasti muudab seda ainult programeerija; määrab muu hulgas millised aplikatsiooni osad vajavad autentimist või kui kiiresti veebisessioon aegub
|}

==Installeerimine==

===Installeerimine paketihalduriga===

<pre>
apt-cache search tomcat
apt-get install tomcat[version]-webapps
apt-get install tomcat[version]-admin
apt-get install tomcat[version]
</pre>

===Installeerimine käsitsi===

Paketihalduriga installeerides ei pruugi viimane Tomcati versioon olla kättesaadav ja see pakub ka vähem võimalusi kataloogide määramiseks jms. Käsitsi installeerimiseks tuleb laadida Tomcat kodulehelt alla. Lahtipakkimisel tekib kataloog, milles sisalduv fail "RUNNING.txt" on kõige kindlam allikas installeerimisel tekkivate probleemide vältimiseks ning lahendamiseks.

Vajaliku versiooni installeerimisfaili asukoha saab vaadata Tomcati kodulehelt sektsioonist "Download". Järgnevas näites installeerime Tomcati kõige uuema ebastabiilse kandidaatversiooni, mida näitab nimes sisalduv RC ehk "release candidate". Produktsioonikeskkonda tuleks siiski valida stabiilse versiooni. Käsitsi installeerimine on sarnane järgmisega:
<pre>
wget http://mirror.nexcess.net/apache/tomcat/tomcat-8/v8.0.0-RC5/bin/apache-tomcat-8.0.0-RC5.tar.gz
tar -zxvf apache-tomcat-8.0.0-RC5.tar.gz
mv /Users/kristjanveskimae/downloads/apache-tomcat-8.0.0-RC5 /usr/local/apache-tomcat-8.0.0-RC5
rm -f /Library/Tomcat
ln -s /usr/local/apache-tomcat-8.0.0-RC5/ /Library/Tomcat
chown -R kristjanveskimae /Library/Tomcat
chmod +x /Library/Tomcat/bin/*.sh
</pre>

==Käivitamine ja aplikatsiooni juurutamine==

===Konteineri käivitamine===

Tomcati käivitamise eelduseks on Java paigaldamine masinasse ning keskkonnamuutujate "JAVA_HOME" ja "JRE_HOME" defineerimine. Peale installeerimist võib kasutada skripte kataloogist $CATALINA_BASE/bin . Järgneb üks võimalik käivitamise ja peatamise näide, mis on kasutatav eelnevalt kirjeldatud käsitsi installeerimise juhul:
<pre>
/Library/Tomcat/bin/startup.sh
</pre>
ja peatamiseks
<pre>
/Library/Tomcat/bin/shutdown.sh
</pre>

===Näiteaplikatsiooni juurutamine===

Java veebiaplikatsiooni jagatakse hea tava kohaselt üheainsa veebiarhiivi failina. Siiski võib Tomcati juurutada ka lahtipakendatud olekus ("exploded") Java veebiaplikatsiooni.

====Käsitsi juurutamine ja mahavõtmine====

Näiteaplikatsiooni juurutamiseks lae selle veebiarhiivifail alla ning kopeeri oma konteineri juurutamiskataloogi 'webapps':
<pre>wget http://tomcat.apache.org/tomcat-8.0-doc/appdev/sample/sample.war
cp /Users/kristjanveskimae/downloads/sample.war /Library/Tomcat/webapps/sample.war</pre>

[[File:sample_app.png|400px|thumb|right|Pilt 1: Õnnestunult rakendatud näiteaplikatsioon]]

Kui konfiguratsioonifailis $CATALINA_BASE/conf/server.xml on märgendi "Host" atribuudi "autoDeploy" väärtus "true", installeerib ja uuendab Tomcat aplikatsioone dünaamiliselt töötamise ajal. Kui väärtuseks on "false", käib installeerimine staatiliselt ning serverisse juurutamiseks tuleb teha konteineri taaskäivitus. [http://tomcat.apache.org/tomcat-8.0-doc/manager-howto.html#Deploy_A_New_Application_from_a_Local_Path 1] Mõlemal juhul pakib konteiner arhiveeritud faili ise lahti samasse kausta $CATALINA_BASE/webapps ning ka juurutab selle. Tekkiv aplikatsioon on lokaalsest masinast seejärel kättesaadav aadressil http://localhost:8080/sample/ . Kui rakendamine õnnestub, siis peaks olema brauserist nähtav sarnane lehekülg nagu pildil 1.

Veebirakenduse käsitsi mahavõtmiseks tuleb kustutada talle vastav dokumendipõhja kataloog "webapps" kataloogist. Samuti tuleks kustutada .war-fail olemaks kindel, et Tomcat ei rakenda uuel käivitamisel veebiaplikatsiooni veebiarhiivifailist. Veelgi lihtsam on mahavõtmine brauseriga haldusrakenduse kaudu.

Rakenduste baaskataloogi "webapps" asukohta saab muuta failis $CATALINA_BASE/conf/server.xml peremehepõhiselt määratava atribuudiga "appBase", sealjuures Tomcati vaikimisi peremees ehk "Host" on "localhost".

====Tomcati vahendid juurutamiseks====

Veebiaplikatsioonide juurutamine ja mahajuurutamine on võimalik ka kaughalduse teel tänu Tomcati internetipõhisele haldusrakendusele. Näiteks saab veebibrauserit kasutades teha serveri põhitoiminguid Tomcati enda HTML-põhise rakendusega "Tomcat Manager". Veebipõhine haldusrakendus töötab ka käsupõhise veebiteenusena, millele on valmis ehitatud Anti ja Maveni integratsioonid. Samuti eksisteerib käsurea kliendirakendus TCD (Tomcat Client Deployer). TCD ei kuulu Tomcati baaskoosseisu, kuid pakub peale serveri administreerimise tavatoimingute ka lisafunktsionaalsust nagu veebirakenduse kokkukompileerimine ja pakendamine. [http://tomcat.apache.org/tomcat-8.0-doc/manager-howto.html#Configuring_Manager_Application_Access 1]

====Haldurakendus "Tomcat Manager"====

Tomcati haldusrakendus "Tomcat Manager" (antud alamjaotuses lihtsalt haldusrakendus) on Tomcati enda veebiaplikatioon Tomcati brauseripõhiseks kaughalduseks, võimaldades muu hulgas järgnevat [http://tomcat.apache.org/tomcat-8.0-doc/manager-howto.html#Introduction 1]:
* Rakendada uue veebiaplikatsiooni war-faili üleslaadimisega;
* Näha kõiki rakendatud veebiaplikatsioone koos aktiivsete sessioonidega;
* Taasrakendada veebirakendust, näiteks veebiarhiivi pakitud klassifailide /WEB-INF/classes või teekide /WEB-INF/lib uuendamisel, kinnijooksmisel jms.;
* Peatada veebirakendust ilma serverist eemaldamata, samuti koos serverist eemaldamisega;
* Vaadata operatsioonisüsteemi ja Java parameetrite väärtusi;
* Näha kõiki saadaolevaid JNDI ressursse, k.a. andmebaasiühendusi, mis aitavad rakenduste programmeerijail defineerida <ResourceLink> elemendid web.xml konfiguratsioonifailis.

Tomcati installatsioon sisaldab haldusrakendust juba vaikimisi. Haldusrakenduse töölepanemiseks tuleb peremeesmasina konfiguratsioonikataloogi $CATALINA_BASE/conf/[enginename]/[hostname] lisada ka fail manager.xml. Vaikimisi valmiskonfigureeritud testrakendusel on see fail juba olemas asukohas $CATALINA_BASE/conf/Catalina/localhost/manager.xml . Rakendus asub vaikimisi aadressil http://[host]/manager/ , vaikimisi konfiguratsioone kasutades lahendub see asukohaks http://localhost:8080/manager/ . [http://tomcat.apache.org/tomcat-8.0-doc/manager-howto.html#Configuring_Manager_Application_Access 1]

====="Tomcat Manager" ligipääsu konfigureerimine=====

Vaikimisi on turvalisuspõhjustel ligipääs haldusrakendusele maha keeratud. Mismoodi täpselt kasutajatel ligipääsu võimaldada sõltub kasutatavast valdusest (realm). Vaikimisi defineerib $CATALINA_BASE/conf/server.xml valduseks "MemoryRealm". Vaikimisi loeb valdus "MemoryRealm" kasutajad failist $CATALINA_BASE/conf/tomcat-users.xml. Antud failis tuleb iga kasutaja defineerida omaette märgendiga <user>, mis näeb välja umbes järgmine [http://tomcat.apache.org/tomcat-8.0-doc/manager-howto.html#Configuring_Manager_Application_Access 1]:
<pre>
<user name="craig" password="secret" roles="manager-gui,manager-script" />
</pre>

Antud kasutajale on defineeritud korraga kaks rolli. Ligipääsu võimaldamiseks tulebki lihtsamal juhul kasutajatefailis $CATALINA_BASE/conf/tomcat-users.xml defineerida enda kasutaja. Kasutaja rolliks võib määrata näiteks "manager-gui", mis võimaldab ligipääsu kogu HTML liidese funktsionaalsusele.

Teised valdused on "JDBCRealm", mille puhul hoitakse kasutajatega seonduvat infot andmebaasis ja JNDIRealm, mille puhul kasutatakse lihtsustatud kataloogisirvimise protokolli (LDAP).
Lisaks saab haldusrakendusele keelata ligipääsu mujalt kui kindlaksmääratud IP-aadressidelt, lisades filtri "RemoteAddrValve" või "RemoteHostValve" konfigureerimisfaili manager.xml näiteks järgmiselt [http://tomcat.apache.org/tomcat-8.0-doc/manager-howto.html#Introduction 1]:
<pre>
<Context privileged="true">
<Valve className="org.apache.catalina.valves.RemoteAddrValve"
allow="127\.0\.0\.1"/>
</Context>
</pre>

=====Juurutamine ja mahavõtmine haldusrakendusega "Tomcat Manager"=====

Juurutamiseks lae kõigepealt veebiarhiivifail üles, kasutades esilehel asuvat sektsiooni "WAR file to deploy". Veebiarhiivi üleslaadimise liides on kujutatud plidil 2.

[[File:tomcat_manager_war_upload.png|800px|thumb|right|Pilt 2: Veebiarhiivi üleslaadimise nupp]]

Rakendus kuvatakse seejärel hallatavate rakenduste nimekirjas. Kui konteiner pole seadistatud üleslaetud aplikatsiooni kohe ka ise rakendama, tuleb vajutada "Start". Rakenduse peatamiseks kasuta "Stop", uuesti rakendamiseks "Redeploy" ja serverist eemaldamiseks "Undeploy". Nupud on näha ka pildil 3 olevas rakenduste nimekirjas.


[[File:tomcat_manager_apps_list.png|300px|thumb|Pilt 3: Rakenduste nimekiri]]

==Näpunäiteid Tomcati reaalseks kasutamiseks==

===Juurutamise järjekord===

Tomcati käivitumisel juurutatakse aplikatsioonid sellises järjekorras [http://www.mulesoft.com/tomcat-deploy-procedures 2]:
# Konteinerisse kopeeritud kontekstikirjelduste järgi $CATALINA_BASE/conf/[EngineName]/[HostName]/[ApplicationName].xml ;
# Lahtipakitud rakendused "webapps" kataloogis;
# Pakitud rakenduste veebiarhiivid "webapps" kataloogis.

Seetõttu peaks käsitsi taasjuurutamisel kindluse mõttes eelnevalt kustutama rakenduse lahtipakitud dokumendipõhja kataloogi "webapps" kataloogist. Kontekstikirjelduse muutumisel tuleb jälgida, kas kirjeldus on juba kopeeritud serverisse ning vajadusel eelmise versiooni ümber muuta või kustutada.

===Reaalsele domeenile konfigureerimine===

Järgnevalt eeldame, et domeen ''www.minukodukas.ee'' on juba serverimasinaga seostatud. Et Tomcat hakkaks ka reaalselt Internetist tulevatele päringutele vastama, tuleb muuta failis $CATALINA_BASE/conf/server.xml konteinerile ''Catalina'' vastava teenusemärgendi sisu sarnaselt järgnevaga:

<pre>
<Service name="Catalina">
<Connector port="80" protocol="HTTP/1.1" connectionTimeout="20000" URIEncoding="UTF-8" redirectPort="8443" />
<Engine name="Catalina" defaultHost="www.minukodukas.ee">
<Host name="www.minukodukas.ee" appBase="webapps" unpackWARs="true" autoDeploy="false" deployOnStartup="false" xmlValidation="false" xmlNamespaceAware="false">
<Context path="" docBase="kodukas" debug="0" reloadable="true" />
</Host>
</Engine>
</Service>
</pre>

Ülal defineerime põhiliselt selle, et Tomcat kuulaks domeeni ''www.minukodukas.ee'' ja kasutaks HTTP päringute jaoks porti 80. Ühtlasti otsib Tomcat juurutatavat rakendust failist $CATALINA_BASE/webapps/kodukas.war. Kuna rajalisandiks on määratud tühi sõne (path=""), siis juurutataksegi aplikatsioon aadressile ''www.minukodukas.ee'' ilma rajalisandita (a'la ''www.minukodukas.ee/wiki''). Seetõttu pakitakse ka veebiarhiiv tegelikult lahti kataloogi $CATALINA_BASE/webapps/ROOT mitte kataloogi $CATALINA_BASE/webapps/kodukas nagu võiks eeldada.

===Käigultvahetus===

Võimaldamaks käigultvahetust (hot deployment) peab konteineri konfiguratsioonifailis $CATALINA_BASE/conf/server.xml olema peremehepõhise märgendi "Host" atribuudi "autoDeploy" väärtus "true". Sel juhul installeerib ja uuendab Tomcat aplikatsioone dünaamiliselt töötamise ajal. Kui väärtuseks on "false", käib installeerimine staatiliselt ning serverisse juurutamiseks tuleb teha konteineri taaskäivitus. Käigultvahetust saab määrata ka peremehe defineerimisel "Host Manager" rakendusega, mis on kättesaadav aadressil http://localhost:8080/host-manager/html . Kasutamiseks tuleb lisada oma kasutajale rolli "admin-gui" (vt. alajaotus ""Tomcat Manager" ligipääsu konfigureerimine").

[[File:host_manager_app.png]]

Käigultvahetust päästikuks on vaikimisi uuendatud veebiarhiivifaili või lahtipakitud veebirakenduse paigutamine "webapps" kataloogi. Käigultvahetuse päästikutele võib failis $CATALINA_BASE/conf/server.xml ka ise lisada kuulatavaid ressursse nagu web.xml muutmine või mõne teegifaili vahetamine (märgendis "Host").

===Klassiteekide väljatõstmine veebiarhiivifailist===

Kõik konteksti poolt kasutatavad Java klassiteegid võib pakendada veebiarhiivi sisse kataloogi "lib", kuid nii võib osutuda veebiarhiivi üleslaadimine ajakulukaks, eriti arenduskeskkonnas. Kui ei teki ohtu, et erinevad rakendused kasutavad sama teegi erinevaid versioone, siis on vahel parem lisada osa teeke konteineri kataloogi $CATALINA_BASE/libs, kust need tehakse siis konteineri poolt kättesaadavaks kõigile konteineris jooksutatavatele kontekstidele. Nii võib vähendada veebiarhiivi faili suurust märgatavalt, mis tõstab kokkuvõttes juurutamiskiirust ja ühes sellega programmeerijate tööviljakust.

===Mälukasutus===

Konteineri poolt kasutatavat mälu saab vaadata haldusrakendusest vajutades lingile "Server Status". Mälukasutus on toodud jaotuses "JVM", kus näidatakse nii maksimaalselt kättesaadavat mälu kui ka parasjagu reserveeritud mälu.

<pre>Free memory: 41.16 MB Total memory: 123.37 MB Max memory: 1027.56 MB</pre>

Mälu suurendamiseks võib näiteks defineerida skriptis $CATALINA_BASE/bin/catalina.sh muutuja "JAVA_OPTS" ning määrata Java mälukasutuse miinimum- ja maksimumväärtused sarnaselt järgnevatega [http://www.mkyong.com/tomcat/tomcat-javalangoutofmemoryerror-permgen-space/ 3]:
<pre>
JAVA_OPTS="-Xms1536m -Xmx1536m -XX:NewSize=256m -XX:MaxNewSize=256m -XX:PermSize=256m -XX:MaxPermSize=256m"
</pre>

===Logifailid===

Vaikimisi defineerib Tomcat failiga $CATALINA_BASE/conf/logging.properties viis logerit, mis tekitavad viis eraldi logifaili.

{| style="background:#cccc99;color:black;width:80%;" border="1" cellpadding="5" cellspacing="0" align="center"
|+ Tomcati tekitatavad logifailid "logs" kataloogis
!Fail !! Kasutus
|- style="background:white; color:black"
| style="width:300px" |catalina.out
| Tomcati käivitus- ja peatamisskriptide väljund, samuti juurutatud rakenduste prindilaused System.out ja veaväljundid System.err
|- style="background:white; color:black"
| style="width:300px" |catalina.[yyyy]-[mm]-[dd].log
| Pööratud (rotated) logifail catalina.out
|- style="background:white; color:black"
| style="width:300px" |host-manager.[yyyy]-[mm]-[dd].log
| Logi peremehehalduse rakendusele (rakendus on kättesaadav kohalikust masinast aadressil http://localhost:8080/host-manager/html )
|- style="background:white; color:black"
| style="width:300px" |localhost.[yyyy]-[mm]-[dd].log
| Peremehe "localhost" logi; mitme virtuaalse peremehe korral tekitatakse igale peremehele oma logi
|- style="background:white; color:black"
| style="width:300px" |localhost_access_log.[yyyy]-[mm]-[dd].txt
| Konteinerisse Internetist saabunud päringute logi
|- style="background:white; color:black"
| style="width:300px" |manager.[yyyy]-[mm]-[dd].log
| Haldusrakenduse tegevuste logi
|}

===Viiteid===

Palju vajalikku võib leida [http://tomcat.apache.org/tomcat-8.0-doc/index.html Tomcat 8 dokumentatsioonist]

Lisaks üks viide põhjalikule Tomcati versioon seitsme ülevaatele: http://www.ntu.edu.sg/home/ehchua/programming/howto/Tomcat_More.html

= Kasutatud materjalid =

#http://tomcat.apache.org/tomcat-8.0-doc/index.html
#http://www.mulesoft.com/tomcat-deploy-procedures
#http://www.mkyong.com/tomcat/tomcat-javalangoutofmemoryerror-permgen-space/

[[Category: Operatsioonisüsteemide administreerimine ja sidumine]]

Tomcat

2014-01-02T22:11:18Z

Kveskima: /* Juurutamine ja mahavõtmine haldusrakendusega "Tomcat Manager" */

==Autor==

Kristjan Veskimäe D32

2013

==Sissejuhatus==

Tomcat on vabalt kättesaadav server Java veebirakendustele. Põhimõtteliselt on tegemist Servlet/JSP spetsifikatsiooni toetava konteineriga. Kiire käivitumise ning rakenduste käigultvahetuse tõttu on Tomcat hea valik väiksemate ning keskmise suurusega Java veebirakenduste käitamiseks.

Antud töö kirjeldab Tomcati 8. versiooni. Põhiosa on üldiselt samasugune võrreldes paari eelmise versiooniga. Suuremad erinevused on versioonispetsiifilistes probleemides ja nende lahendamises, mida käesolev töö ei vaatle.

Töö vaatleb Tomcati paigaldamist ja seadistamist Unix-laadsesse keskkonda ning eeldab lugejalt algteadmisi sarnastes süsteemides. Tomcati on võimalik paigaldada ka Windows-keskkonda, kuid antud veebiserver eeldab kasutaja poolt käsureal töötamist ning Tomcati failihierarhias orienteerumist. Põhimõtteliselt on Java veebirakenduste arendamiseks IDE-abil võimalik siiski ka kasutada IDE-sse integreeritud Tomcati serverit - näiteks pakuvad sellist võimalust Eclipse EE ja NetBeans - kuid seda käesolev töö ei vaatle.

==Mõisted==

* '''Kontekst''' (context) - Tomcati mõistes üks konkreetne veebiaplikatsioon
* '''Konteiner''' (container) - veebiserver Tomcat ise
* '''Kontekstikirjeldus''' (context descriptor) - Tomcati-spetsiifiline konteksti konfiguratsioonimääratlus; peremehepõhine osa loetakse failist $CATALINA_HOME/conf/[enginename]/[hostname]/context.xml ja sellele lisatakse kontekstispetsiifilised täpsustused failist $CATALINA_BASE/conf/[enginename]/[hostname]/[webappname].xml; kontekstikirjeldus määrab näiteks nimed ressurssidele, sessioonihalduse parameetrid jmt. (olgu märgitud, et Tomcati varasemates versioonides sisaldusid kontekstikirjeldused põhikonfiguratsioonifailis server.xml)
* '''Dokumendipõhi''' (docBase) - kontekstile vastav kataloog Tomcati "webapps" kataloogis, mis tekib veebiaplikatsiooni serverisse rakendamisel
* '''Veebiarhiiv''' (Web application ARchive, war-file) - Java veebiaplikatsiooni jagatakse hea tava kohaselt selle üheainsa veebiarhiivi failina, mille laienditüübiks on "war". Tegemist on zip-protokolliga kokkupakitud kataloogiga, millel on Java veebirakenduste spetsifikatsioonile vastav ülesehitus. Siiski võib veebiaplikatsioon olla juurutamisel ka lahtipakendatud olekus (inglisekeelne termin on "war is exploded").

==Ülesehitus==

{| class="wikitable"
|+Kataloogid
|-
|style="color: green;" | $CATALINA_HOME
|baaskataloog, kuhu on Tomcat paigutatud
|-
|style="color: green;" | $CATALINA_BASE
|parasjagu töösoleva Tomcati eksemplari baaskataloog, mille alusel lahendatakse teed ülejäänud kataloogide ja failideni; ainult ühe kasutusel oleva Tomcati eksemplari puhul on see sama, mis $CATALINA_HOME

|-
|style="color: green;" | $CATALINA_BASE/bin
|serveri käivitus- ja abiskriptid
|-
|style="color: green;" | $CATALINA_BASE/conf
|konfiguratsioonifailid
|-
|style="color: green;" | $CATALINA_BASE/lib
|Tomcatile vaikimisi kättesaadavad Java klassiteegid (class libraries) ehk .jar-failid kuhu on Java kompileeritud kood kokku pakendatud
|-
|style="color: green;" | $CATALINA_BASE/logs
|logifailid paigutatakse vaikimisi siia
|-
|style="color: green;" | $CATALINA_BASE/webapps
|kataloog, kuhu paigutatakse serverisse juurutatavad veebiaplikatsioonid

|}

{| class="wikitable"
|+Mõned olulisemad failid
|-
|style="color: green;" | $CATALINA_BASE/bin/startup.sh
|serveri käivitusskript
|-
|style="color: green;" | $CATALINA_BASE/bin/shutdown.sh
|serveri peatusskript

|-
|style="color: green;" | $CATALINA_BASE/conf/server.xml
| konteineri peamine konfiguratsioonifail
|-
|style="color: green;" | $CATALINA_BASE/conf/[enginename]/[hostname]/[webappname].xml
|serveri administraatori jaoks konteinerisse endasse ümber kopeeritud rakendusepõhine kontekstikirjelduse konfiguratsioon failist $CATALINA_BASE/webapps/[ApplicationName]/META-INF/context.xml
|-
|style="color: green;" | $CATALINA_BASE/conf/[enginename]/[hostname]/context.xml
| fail, mis aitab administraatoril konteksti kohta käivat infot kirjeldada peremeesmasina-põhiselt ja halduseks mõeldud automaat-tööriistadel (näiteks Tomcat Manager ja TCD) oma tööd teha
|-
|style="color: green;" | $CATALINA_BASE/$CATALINA_BASE/conf/[enginename]/[hostname]/manager.xml
|fail, mis võimaldab lisada rakendustele ligipääsufiltreid
|-
|style="color: green;" | $CATALINA_BASE/webapps/[webappname]/META-INF/context.xml
|kontekstikirjeldusfail, mille veebirakenduse programmeerija on pakendanud oma aplikatsiooniga kaasa ning millega ta saab võimaluse kontekstikirjeldust omalt poolt mõjutada; kirjutatakse rakenduse uuestijuurutamisel üle, mistõttu administraator peaks muutma selle asemel konteinerisse ümber kopeeritud püsieksemplari $CATALINA_BASE/conf/[enginename]/[hostname]/context.xml
|-
|style="color: green;" | $CATALINA_BASE/webapps/[webappname]/WEB-INF/web.xml
|ka üks oluline Java veebiaplikatsiooni konfiguratsioonifail, mille pakendatakse koos veebiarhiiviga; enamasti muudab seda ainult programeerija; määrab muu hulgas millised aplikatsiooni osad vajavad autentimist või kui kiiresti veebisessioon aegub
|}

==Installeerimine==

===Installeerimine paketihalduriga===

<pre>
apt-cache search tomcat
apt-get install tomcat[version]-webapps
apt-get install tomcat[version]-admin
apt-get install tomcat[version]
</pre>

===Installeerimine käsitsi===

Paketihalduriga installeerides ei pruugi viimane Tomcati versioon olla kättesaadav ja see pakub ka vähem võimalusi kataloogide määramiseks jms. Käsitsi installeerimiseks tuleb laadida Tomcat kodulehelt alla. Lahtipakkimisel tekib kataloog, milles sisalduv fail "RUNNING.txt" on kõige kindlam allikas installeerimisel tekkivate probleemide vältimiseks ning lahendamiseks.

Vajaliku versiooni installeerimisfaili asukoha saab vaadata Tomcati kodulehelt sektsioonist "Download". Järgnevas näites installeerime Tomcati kõige uuema ebastabiilse kandidaatversiooni, mida näitab nimes sisalduv RC ehk "release candidate". Produktsioonikeskkonda tuleks siiski valida stabiilse versiooni. Käsitsi installeerimine on sarnane järgmisega:
<pre>
wget http://mirror.nexcess.net/apache/tomcat/tomcat-8/v8.0.0-RC5/bin/apache-tomcat-8.0.0-RC5.tar.gz
tar -zxvf apache-tomcat-8.0.0-RC5.tar.gz
mv /Users/kristjanveskimae/downloads/apache-tomcat-8.0.0-RC5 /usr/local/apache-tomcat-8.0.0-RC5
rm -f /Library/Tomcat
ln -s /usr/local/apache-tomcat-8.0.0-RC5/ /Library/Tomcat
chown -R kristjanveskimae /Library/Tomcat
chmod +x /Library/Tomcat/bin/*.sh
</pre>

==Käivitamine ja aplikatsiooni juurutamine==

===Konteineri käivitamine===

Tomcati käivitamise eelduseks on Java paigaldamine masinasse ning keskkonnamuutujate "JAVA_HOME" ja "JRE_HOME" defineerimine. Peale installeerimist võib kasutada skripte kataloogist $CATALINA_BASE/bin . Järgneb üks võimalik käivitamise ja peatamise näide, mis on kasutatav eelnevalt kirjeldatud käsitsi installeerimise juhul:
<pre>
/Library/Tomcat/bin/startup.sh
</pre>
ja peatamiseks
<pre>
/Library/Tomcat/bin/shutdown.sh
</pre>

===Näiteaplikatsiooni juurutamine===

Java veebiaplikatsiooni jagatakse hea tava kohaselt üheainsa veebiarhiivi failina. Siiski võib Tomcati juurutada ka lahtipakendatud olekus ("exploded") Java veebiaplikatsiooni.

====Käsitsi juurutamine ja mahavõtmine====

Näiteaplikatsiooni juurutamiseks lae selle veebiarhiivifail alla ning kopeeri oma konteineri juurutamiskataloogi 'webapps':
<pre>wget http://tomcat.apache.org/tomcat-8.0-doc/appdev/sample/sample.war
cp /Users/kristjanveskimae/downloads/sample.war /Library/Tomcat/webapps/sample.war</pre>

[[File:sample_app.png|400px|thumb|right|Pilt 1: Õnnestunult rakendatud näiteaplikatsioon]]

Kui konfiguratsioonifailis $CATALINA_BASE/conf/server.xml on märgendi "Host" atribuudi "autoDeploy" väärtus "true", installeerib ja uuendab Tomcat aplikatsioone dünaamiliselt töötamise ajal. Kui väärtuseks on "false", käib installeerimine staatiliselt ning serverisse juurutamiseks tuleb teha konteineri taaskäivitus. [http://tomcat.apache.org/tomcat-8.0-doc/manager-howto.html#Deploy_A_New_Application_from_a_Local_Path 1] Mõlemal juhul pakib konteiner arhiveeritud faili ise lahti samasse kausta $CATALINA_BASE/webapps ning ka juurutab selle. Tekkiv aplikatsioon on lokaalsest masinast seejärel kättesaadav aadressil http://localhost:8080/sample/ . Kui rakendamine õnnestub, siis peaks olema brauserist nähtav sarnane lehekülg nagu pildil 1.

Veebirakenduse käsitsi mahavõtmiseks tuleb kustutada talle vastav dokumendipõhja kataloog "webapps" kataloogist. Samuti tuleks kustutada .war-fail olemaks kindel, et Tomcat ei rakenda uuel käivitamisel veebiaplikatsiooni veebiarhiivifailist. Veelgi lihtsam on mahavõtmine brauseriga haldusrakenduse kaudu.

Rakenduste baaskataloogi "webapps" asukohta saab muuta failis $CATALINA_BASE/conf/server.xml peremehepõhiselt määratava atribuudiga "appBase", sealjuures Tomcati vaikimisi peremees ehk "Host" on "localhost".

====Tomcati vahendid juurutamiseks====

Veebiaplikatsioonide juurutamine ja mahajuurutamine on võimalik ka kaughalduse teel tänu Tomcati internetipõhisele haldusrakendusele. Näiteks saab veebibrauserit kasutades teha serveri põhitoiminguid Tomcati enda HTML-põhise rakendusega "Tomcat Manager". Veebipõhine haldusrakendus töötab ka käsupõhise veebiteenusena, millele on valmis ehitatud Anti ja Maveni integratsioonid. Samuti eksisteerib käsurea kliendirakendus TCD (Tomcat Client Deployer). TCD ei kuulu Tomcati baaskoosseisu, kuid pakub peale serveri administreerimise tavatoimingute ka lisafunktsionaalsust nagu veebirakenduse kokkukompileerimine ja pakendamine. [http://tomcat.apache.org/tomcat-8.0-doc/manager-howto.html#Configuring_Manager_Application_Access 1]

====Haldurakendus "Tomcat Manager"====

Tomcati haldusrakendus "Tomcat Manager" (antud alamjaotuses lihtsalt haldusrakendus) on Tomcati enda veebiaplikatioon Tomcati brauseripõhiseks kaughalduseks, võimaldades muu hulgas järgnevat [http://tomcat.apache.org/tomcat-8.0-doc/manager-howto.html#Introduction 1]:
* Rakendada uue veebiaplikatsiooni war-faili üleslaadimisega;
* Näha kõiki rakendatud veebiaplikatsioone koos aktiivsete sessioonidega;
* Taasrakendada veebirakendust, näiteks veebiarhiivi pakitud klassifailide /WEB-INF/classes või teekide /WEB-INF/lib uuendamisel, kinnijooksmisel jms.;
* Peatada veebirakendust ilma serverist eemaldamata, samuti koos serverist eemaldamisega;
* Vaadata operatsioonisüsteemi ja Java parameetrite väärtusi;
* Näha kõiki saadaolevaid JNDI ressursse, k.a. andmebaasiühendusi, mis aitavad rakenduste programmeerijail defineerida <ResourceLink> elemendid web.xml konfiguratsioonifailis.

Tomcati installatsioon sisaldab haldusrakendust juba vaikimisi. Haldusrakenduse töölepanemiseks tuleb peremeesmasina konfiguratsioonikataloogi $CATALINA_BASE/conf/[enginename]/[hostname] lisada ka fail manager.xml. Vaikimisi valmiskonfigureeritud testrakendusel on see fail juba olemas asukohas $CATALINA_BASE/conf/Catalina/localhost/manager.xml . Rakendus asub vaikimisi aadressil http://[host]/manager/ , vaikimisi konfiguratsioone kasutades lahendub see asukohaks http://localhost:8080/manager/ . [http://tomcat.apache.org/tomcat-8.0-doc/manager-howto.html#Configuring_Manager_Application_Access 1]

====="Tomcat Manager" ligipääsu konfigureerimine=====

Vaikimisi on turvalisuspõhjustel ligipääs haldusrakendusele maha keeratud. Mismoodi täpselt kasutajatel ligipääsu võimaldada sõltub kasutatavast valdusest (realm). Vaikimisi defineerib $CATALINA_BASE/conf/server.xml valduseks "MemoryRealm". Vaikimisi loeb valdus "MemoryRealm" kasutajad failist $CATALINA_BASE/conf/tomcat-users.xml. Antud failis tuleb iga kasutaja defineerida omaette märgendiga <user>, mis näeb välja umbes järgmine [http://tomcat.apache.org/tomcat-8.0-doc/manager-howto.html#Configuring_Manager_Application_Access 1]:
<pre>
<user name="craig" password="secret" roles="manager-gui,manager-script" />
</pre>

Antud kasutajale on defineeritud korraga kaks rolli. Ligipääsu võimaldamiseks tulebki lihtsamal juhul kasutajatefailis $CATALINA_BASE/conf/tomcat-users.xml defineerida enda kasutaja. Kasutaja rolliks võib määrata näiteks "manager-gui", mis võimaldab ligipääsu kogu HTML liidese funktsionaalsusele.

Teised valdused on "JDBCRealm", mille puhul hoitakse kasutajatega seonduvat infot andmebaasis ja JNDIRealm, mille puhul kasutatakse lihtsustatud kataloogisirvimise protokolli (LDAP).
Lisaks saab haldusrakendusele keelata ligipääsu mujalt kui kindlaksmääratud IP-aadressidelt, lisades filtri "RemoteAddrValve" või "RemoteHostValve" konfigureerimisfaili manager.xml näiteks järgmiselt [http://tomcat.apache.org/tomcat-8.0-doc/manager-howto.html#Introduction 1]:
<pre>
<Context privileged="true">
<Valve className="org.apache.catalina.valves.RemoteAddrValve"
allow="127\.0\.0\.1"/>
</Context>
</pre>

=====Juurutamine ja mahavõtmine haldusrakendusega "Tomcat Manager"=====

Juurutamiseks lae kõigepealt veebiarhiivifail üles, kasutades esilehel asuvat sektsiooni "WAR file to deploy".

[[File:tomcat_manager_war_upload.png|800px|thumb|right|Pilt 2: Veebiarhiivi üleslaadimise nupp]]

Rakendus kuvatakse seejärel hallatavate rakenduste nimekirjas. Kui konteiner pole seadistatud üleslaetud aplikatsiooni kohe ka ise rakendama, tuleb vajutada "Start". Rakenduse peatamiseks kasuta "Stop", uuesti rakendamiseks "Redeploy" ja serverist eemaldamiseks "Undeploy".


[[File:tomcat_manager_apps_list.png|300px|thumb|Pilt 3: Rakenduste nimekiri]]

==Näpunäiteid Tomcati reaalseks kasutamiseks==

===Juurutamise järjekord===

Tomcati käivitumisel juurutatakse aplikatsioonid sellises järjekorras [http://www.mulesoft.com/tomcat-deploy-procedures 2]:
# Konteinerisse kopeeritud kontekstikirjelduste järgi $CATALINA_BASE/conf/[EngineName]/[HostName]/[ApplicationName].xml ;
# Lahtipakitud rakendused "webapps" kataloogis;
# Pakitud rakenduste veebiarhiivid "webapps" kataloogis.

Seetõttu peaks käsitsi taasjuurutamisel kindluse mõttes eelnevalt kustutama rakenduse lahtipakitud dokumendipõhja kataloogi "webapps" kataloogist. Kontekstikirjelduse muutumisel tuleb jälgida, kas kirjeldus on juba kopeeritud serverisse ning vajadusel eelmise versiooni ümber muuta või kustutada.

===Reaalsele domeenile konfigureerimine===

Järgnevalt eeldame, et domeen ''www.minukodukas.ee'' on juba serverimasinaga seostatud. Et Tomcat hakkaks ka reaalselt Internetist tulevatele päringutele vastama, tuleb muuta failis $CATALINA_BASE/conf/server.xml konteinerile ''Catalina'' vastava teenusemärgendi sisu sarnaselt järgnevaga:

<pre>
<Service name="Catalina">
<Connector port="80" protocol="HTTP/1.1" connectionTimeout="20000" URIEncoding="UTF-8" redirectPort="8443" />
<Engine name="Catalina" defaultHost="www.minukodukas.ee">
<Host name="www.minukodukas.ee" appBase="webapps" unpackWARs="true" autoDeploy="false" deployOnStartup="false" xmlValidation="false" xmlNamespaceAware="false">
<Context path="" docBase="kodukas" debug="0" reloadable="true" />
</Host>
</Engine>
</Service>
</pre>

Ülal defineerime põhiliselt selle, et Tomcat kuulaks domeeni ''www.minukodukas.ee'' ja kasutaks HTTP päringute jaoks porti 80. Ühtlasti otsib Tomcat juurutatavat rakendust failist $CATALINA_BASE/webapps/kodukas.war. Kuna rajalisandiks on määratud tühi sõne (path=""), siis juurutataksegi aplikatsioon aadressile ''www.minukodukas.ee'' ilma rajalisandita (a'la ''www.minukodukas.ee/wiki''). Seetõttu pakitakse ka veebiarhiiv tegelikult lahti kataloogi $CATALINA_BASE/webapps/ROOT mitte kataloogi $CATALINA_BASE/webapps/kodukas nagu võiks eeldada.

===Käigultvahetus===

Võimaldamaks käigultvahetust (hot deployment) peab konteineri konfiguratsioonifailis $CATALINA_BASE/conf/server.xml olema peremehepõhise märgendi "Host" atribuudi "autoDeploy" väärtus "true". Sel juhul installeerib ja uuendab Tomcat aplikatsioone dünaamiliselt töötamise ajal. Kui väärtuseks on "false", käib installeerimine staatiliselt ning serverisse juurutamiseks tuleb teha konteineri taaskäivitus. Käigultvahetust saab määrata ka peremehe defineerimisel "Host Manager" rakendusega, mis on kättesaadav aadressil http://localhost:8080/host-manager/html . Kasutamiseks tuleb lisada oma kasutajale rolli "admin-gui" (vt. alajaotus ""Tomcat Manager" ligipääsu konfigureerimine").

[[File:host_manager_app.png]]

Käigultvahetust päästikuks on vaikimisi uuendatud veebiarhiivifaili või lahtipakitud veebirakenduse paigutamine "webapps" kataloogi. Käigultvahetuse päästikutele võib failis $CATALINA_BASE/conf/server.xml ka ise lisada kuulatavaid ressursse nagu web.xml muutmine või mõne teegifaili vahetamine (märgendis "Host").

===Klassiteekide väljatõstmine veebiarhiivifailist===

Kõik konteksti poolt kasutatavad Java klassiteegid võib pakendada veebiarhiivi sisse kataloogi "lib", kuid nii võib osutuda veebiarhiivi üleslaadimine ajakulukaks, eriti arenduskeskkonnas. Kui ei teki ohtu, et erinevad rakendused kasutavad sama teegi erinevaid versioone, siis on vahel parem lisada osa teeke konteineri kataloogi $CATALINA_BASE/libs, kust need tehakse siis konteineri poolt kättesaadavaks kõigile konteineris jooksutatavatele kontekstidele. Nii võib vähendada veebiarhiivi faili suurust märgatavalt, mis tõstab kokkuvõttes juurutamiskiirust ja ühes sellega programmeerijate tööviljakust.

===Mälukasutus===

Konteineri poolt kasutatavat mälu saab vaadata haldusrakendusest vajutades lingile "Server Status". Mälukasutus on toodud jaotuses "JVM", kus näidatakse nii maksimaalselt kättesaadavat mälu kui ka parasjagu reserveeritud mälu.

<pre>Free memory: 41.16 MB Total memory: 123.37 MB Max memory: 1027.56 MB</pre>

Mälu suurendamiseks võib näiteks defineerida skriptis $CATALINA_BASE/bin/catalina.sh muutuja "JAVA_OPTS" ning määrata Java mälukasutuse miinimum- ja maksimumväärtused sarnaselt järgnevatega [http://www.mkyong.com/tomcat/tomcat-javalangoutofmemoryerror-permgen-space/ 3]:
<pre>
JAVA_OPTS="-Xms1536m -Xmx1536m -XX:NewSize=256m -XX:MaxNewSize=256m -XX:PermSize=256m -XX:MaxPermSize=256m"
</pre>

===Logifailid===

Vaikimisi defineerib Tomcat failiga $CATALINA_BASE/conf/logging.properties viis logerit, mis tekitavad viis eraldi logifaili.

{| style="background:#cccc99;color:black;width:80%;" border="1" cellpadding="5" cellspacing="0" align="center"
|+ Tomcati tekitatavad logifailid "logs" kataloogis
!Fail !! Kasutus
|- style="background:white; color:black"
| style="width:300px" |catalina.out
| Tomcati käivitus- ja peatamisskriptide väljund, samuti juurutatud rakenduste prindilaused System.out ja veaväljundid System.err
|- style="background:white; color:black"
| style="width:300px" |catalina.[yyyy]-[mm]-[dd].log
| Pööratud (rotated) logifail catalina.out
|- style="background:white; color:black"
| style="width:300px" |host-manager.[yyyy]-[mm]-[dd].log
| Logi peremehehalduse rakendusele (rakendus on kättesaadav kohalikust masinast aadressil http://localhost:8080/host-manager/html )
|- style="background:white; color:black"
| style="width:300px" |localhost.[yyyy]-[mm]-[dd].log
| Peremehe "localhost" logi; mitme virtuaalse peremehe korral tekitatakse igale peremehele oma logi
|- style="background:white; color:black"
| style="width:300px" |localhost_access_log.[yyyy]-[mm]-[dd].txt
| Konteinerisse Internetist saabunud päringute logi
|- style="background:white; color:black"
| style="width:300px" |manager.[yyyy]-[mm]-[dd].log
| Haldusrakenduse tegevuste logi
|}

===Viiteid===

Palju vajalikku võib leida [http://tomcat.apache.org/tomcat-8.0-doc/index.html Tomcat 8 dokumentatsioonist]

Lisaks üks viide põhjalikule Tomcati versioon seitsme ülevaatele: http://www.ntu.edu.sg/home/ehchua/programming/howto/Tomcat_More.html

= Kasutatud materjalid =

#http://tomcat.apache.org/tomcat-8.0-doc/index.html
#http://www.mulesoft.com/tomcat-deploy-procedures
#http://www.mkyong.com/tomcat/tomcat-javalangoutofmemoryerror-permgen-space/

[[Category: Operatsioonisüsteemide administreerimine ja sidumine]]

Tomcat

2014-01-02T22:10:50Z

Kveskima: /* Juurutamine ja mahavõtmine haldusrakendusega "Tomcat Manager" */

==Autor==

Kristjan Veskimäe D32

2013

==Sissejuhatus==

Tomcat on vabalt kättesaadav server Java veebirakendustele. Põhimõtteliselt on tegemist Servlet/JSP spetsifikatsiooni toetava konteineriga. Kiire käivitumise ning rakenduste käigultvahetuse tõttu on Tomcat hea valik väiksemate ning keskmise suurusega Java veebirakenduste käitamiseks.

Antud töö kirjeldab Tomcati 8. versiooni. Põhiosa on üldiselt samasugune võrreldes paari eelmise versiooniga. Suuremad erinevused on versioonispetsiifilistes probleemides ja nende lahendamises, mida käesolev töö ei vaatle.

Töö vaatleb Tomcati paigaldamist ja seadistamist Unix-laadsesse keskkonda ning eeldab lugejalt algteadmisi sarnastes süsteemides. Tomcati on võimalik paigaldada ka Windows-keskkonda, kuid antud veebiserver eeldab kasutaja poolt käsureal töötamist ning Tomcati failihierarhias orienteerumist. Põhimõtteliselt on Java veebirakenduste arendamiseks IDE-abil võimalik siiski ka kasutada IDE-sse integreeritud Tomcati serverit - näiteks pakuvad sellist võimalust Eclipse EE ja NetBeans - kuid seda käesolev töö ei vaatle.

==Mõisted==

* '''Kontekst''' (context) - Tomcati mõistes üks konkreetne veebiaplikatsioon
* '''Konteiner''' (container) - veebiserver Tomcat ise
* '''Kontekstikirjeldus''' (context descriptor) - Tomcati-spetsiifiline konteksti konfiguratsioonimääratlus; peremehepõhine osa loetakse failist $CATALINA_HOME/conf/[enginename]/[hostname]/context.xml ja sellele lisatakse kontekstispetsiifilised täpsustused failist $CATALINA_BASE/conf/[enginename]/[hostname]/[webappname].xml; kontekstikirjeldus määrab näiteks nimed ressurssidele, sessioonihalduse parameetrid jmt. (olgu märgitud, et Tomcati varasemates versioonides sisaldusid kontekstikirjeldused põhikonfiguratsioonifailis server.xml)
* '''Dokumendipõhi''' (docBase) - kontekstile vastav kataloog Tomcati "webapps" kataloogis, mis tekib veebiaplikatsiooni serverisse rakendamisel
* '''Veebiarhiiv''' (Web application ARchive, war-file) - Java veebiaplikatsiooni jagatakse hea tava kohaselt selle üheainsa veebiarhiivi failina, mille laienditüübiks on "war". Tegemist on zip-protokolliga kokkupakitud kataloogiga, millel on Java veebirakenduste spetsifikatsioonile vastav ülesehitus. Siiski võib veebiaplikatsioon olla juurutamisel ka lahtipakendatud olekus (inglisekeelne termin on "war is exploded").

==Ülesehitus==

{| class="wikitable"
|+Kataloogid
|-
|style="color: green;" | $CATALINA_HOME
|baaskataloog, kuhu on Tomcat paigutatud
|-
|style="color: green;" | $CATALINA_BASE
|parasjagu töösoleva Tomcati eksemplari baaskataloog, mille alusel lahendatakse teed ülejäänud kataloogide ja failideni; ainult ühe kasutusel oleva Tomcati eksemplari puhul on see sama, mis $CATALINA_HOME

|-
|style="color: green;" | $CATALINA_BASE/bin
|serveri käivitus- ja abiskriptid
|-
|style="color: green;" | $CATALINA_BASE/conf
|konfiguratsioonifailid
|-
|style="color: green;" | $CATALINA_BASE/lib
|Tomcatile vaikimisi kättesaadavad Java klassiteegid (class libraries) ehk .jar-failid kuhu on Java kompileeritud kood kokku pakendatud
|-
|style="color: green;" | $CATALINA_BASE/logs
|logifailid paigutatakse vaikimisi siia
|-
|style="color: green;" | $CATALINA_BASE/webapps
|kataloog, kuhu paigutatakse serverisse juurutatavad veebiaplikatsioonid

|}

{| class="wikitable"
|+Mõned olulisemad failid
|-
|style="color: green;" | $CATALINA_BASE/bin/startup.sh
|serveri käivitusskript
|-
|style="color: green;" | $CATALINA_BASE/bin/shutdown.sh
|serveri peatusskript

|-
|style="color: green;" | $CATALINA_BASE/conf/server.xml
| konteineri peamine konfiguratsioonifail
|-
|style="color: green;" | $CATALINA_BASE/conf/[enginename]/[hostname]/[webappname].xml
|serveri administraatori jaoks konteinerisse endasse ümber kopeeritud rakendusepõhine kontekstikirjelduse konfiguratsioon failist $CATALINA_BASE/webapps/[ApplicationName]/META-INF/context.xml
|-
|style="color: green;" | $CATALINA_BASE/conf/[enginename]/[hostname]/context.xml
| fail, mis aitab administraatoril konteksti kohta käivat infot kirjeldada peremeesmasina-põhiselt ja halduseks mõeldud automaat-tööriistadel (näiteks Tomcat Manager ja TCD) oma tööd teha
|-
|style="color: green;" | $CATALINA_BASE/$CATALINA_BASE/conf/[enginename]/[hostname]/manager.xml
|fail, mis võimaldab lisada rakendustele ligipääsufiltreid
|-
|style="color: green;" | $CATALINA_BASE/webapps/[webappname]/META-INF/context.xml
|kontekstikirjeldusfail, mille veebirakenduse programmeerija on pakendanud oma aplikatsiooniga kaasa ning millega ta saab võimaluse kontekstikirjeldust omalt poolt mõjutada; kirjutatakse rakenduse uuestijuurutamisel üle, mistõttu administraator peaks muutma selle asemel konteinerisse ümber kopeeritud püsieksemplari $CATALINA_BASE/conf/[enginename]/[hostname]/context.xml
|-
|style="color: green;" | $CATALINA_BASE/webapps/[webappname]/WEB-INF/web.xml
|ka üks oluline Java veebiaplikatsiooni konfiguratsioonifail, mille pakendatakse koos veebiarhiiviga; enamasti muudab seda ainult programeerija; määrab muu hulgas millised aplikatsiooni osad vajavad autentimist või kui kiiresti veebisessioon aegub
|}

==Installeerimine==

===Installeerimine paketihalduriga===

<pre>
apt-cache search tomcat
apt-get install tomcat[version]-webapps
apt-get install tomcat[version]-admin
apt-get install tomcat[version]
</pre>

===Installeerimine käsitsi===

Paketihalduriga installeerides ei pruugi viimane Tomcati versioon olla kättesaadav ja see pakub ka vähem võimalusi kataloogide määramiseks jms. Käsitsi installeerimiseks tuleb laadida Tomcat kodulehelt alla. Lahtipakkimisel tekib kataloog, milles sisalduv fail "RUNNING.txt" on kõige kindlam allikas installeerimisel tekkivate probleemide vältimiseks ning lahendamiseks.

Vajaliku versiooni installeerimisfaili asukoha saab vaadata Tomcati kodulehelt sektsioonist "Download". Järgnevas näites installeerime Tomcati kõige uuema ebastabiilse kandidaatversiooni, mida näitab nimes sisalduv RC ehk "release candidate". Produktsioonikeskkonda tuleks siiski valida stabiilse versiooni. Käsitsi installeerimine on sarnane järgmisega:
<pre>
wget http://mirror.nexcess.net/apache/tomcat/tomcat-8/v8.0.0-RC5/bin/apache-tomcat-8.0.0-RC5.tar.gz
tar -zxvf apache-tomcat-8.0.0-RC5.tar.gz
mv /Users/kristjanveskimae/downloads/apache-tomcat-8.0.0-RC5 /usr/local/apache-tomcat-8.0.0-RC5
rm -f /Library/Tomcat
ln -s /usr/local/apache-tomcat-8.0.0-RC5/ /Library/Tomcat
chown -R kristjanveskimae /Library/Tomcat
chmod +x /Library/Tomcat/bin/*.sh
</pre>

==Käivitamine ja aplikatsiooni juurutamine==

===Konteineri käivitamine===

Tomcati käivitamise eelduseks on Java paigaldamine masinasse ning keskkonnamuutujate "JAVA_HOME" ja "JRE_HOME" defineerimine. Peale installeerimist võib kasutada skripte kataloogist $CATALINA_BASE/bin . Järgneb üks võimalik käivitamise ja peatamise näide, mis on kasutatav eelnevalt kirjeldatud käsitsi installeerimise juhul:
<pre>
/Library/Tomcat/bin/startup.sh
</pre>
ja peatamiseks
<pre>
/Library/Tomcat/bin/shutdown.sh
</pre>

===Näiteaplikatsiooni juurutamine===

Java veebiaplikatsiooni jagatakse hea tava kohaselt üheainsa veebiarhiivi failina. Siiski võib Tomcati juurutada ka lahtipakendatud olekus ("exploded") Java veebiaplikatsiooni.

====Käsitsi juurutamine ja mahavõtmine====

Näiteaplikatsiooni juurutamiseks lae selle veebiarhiivifail alla ning kopeeri oma konteineri juurutamiskataloogi 'webapps':
<pre>wget http://tomcat.apache.org/tomcat-8.0-doc/appdev/sample/sample.war
cp /Users/kristjanveskimae/downloads/sample.war /Library/Tomcat/webapps/sample.war</pre>

[[File:sample_app.png|400px|thumb|right|Pilt 1: Õnnestunult rakendatud näiteaplikatsioon]]

Kui konfiguratsioonifailis $CATALINA_BASE/conf/server.xml on märgendi "Host" atribuudi "autoDeploy" väärtus "true", installeerib ja uuendab Tomcat aplikatsioone dünaamiliselt töötamise ajal. Kui väärtuseks on "false", käib installeerimine staatiliselt ning serverisse juurutamiseks tuleb teha konteineri taaskäivitus. [http://tomcat.apache.org/tomcat-8.0-doc/manager-howto.html#Deploy_A_New_Application_from_a_Local_Path 1] Mõlemal juhul pakib konteiner arhiveeritud faili ise lahti samasse kausta $CATALINA_BASE/webapps ning ka juurutab selle. Tekkiv aplikatsioon on lokaalsest masinast seejärel kättesaadav aadressil http://localhost:8080/sample/ . Kui rakendamine õnnestub, siis peaks olema brauserist nähtav sarnane lehekülg nagu pildil 1.

Veebirakenduse käsitsi mahavõtmiseks tuleb kustutada talle vastav dokumendipõhja kataloog "webapps" kataloogist. Samuti tuleks kustutada .war-fail olemaks kindel, et Tomcat ei rakenda uuel käivitamisel veebiaplikatsiooni veebiarhiivifailist. Veelgi lihtsam on mahavõtmine brauseriga haldusrakenduse kaudu.

Rakenduste baaskataloogi "webapps" asukohta saab muuta failis $CATALINA_BASE/conf/server.xml peremehepõhiselt määratava atribuudiga "appBase", sealjuures Tomcati vaikimisi peremees ehk "Host" on "localhost".

====Tomcati vahendid juurutamiseks====

Veebiaplikatsioonide juurutamine ja mahajuurutamine on võimalik ka kaughalduse teel tänu Tomcati internetipõhisele haldusrakendusele. Näiteks saab veebibrauserit kasutades teha serveri põhitoiminguid Tomcati enda HTML-põhise rakendusega "Tomcat Manager". Veebipõhine haldusrakendus töötab ka käsupõhise veebiteenusena, millele on valmis ehitatud Anti ja Maveni integratsioonid. Samuti eksisteerib käsurea kliendirakendus TCD (Tomcat Client Deployer). TCD ei kuulu Tomcati baaskoosseisu, kuid pakub peale serveri administreerimise tavatoimingute ka lisafunktsionaalsust nagu veebirakenduse kokkukompileerimine ja pakendamine. [http://tomcat.apache.org/tomcat-8.0-doc/manager-howto.html#Configuring_Manager_Application_Access 1]

====Haldurakendus "Tomcat Manager"====

Tomcati haldusrakendus "Tomcat Manager" (antud alamjaotuses lihtsalt haldusrakendus) on Tomcati enda veebiaplikatioon Tomcati brauseripõhiseks kaughalduseks, võimaldades muu hulgas järgnevat [http://tomcat.apache.org/tomcat-8.0-doc/manager-howto.html#Introduction 1]:
* Rakendada uue veebiaplikatsiooni war-faili üleslaadimisega;
* Näha kõiki rakendatud veebiaplikatsioone koos aktiivsete sessioonidega;
* Taasrakendada veebirakendust, näiteks veebiarhiivi pakitud klassifailide /WEB-INF/classes või teekide /WEB-INF/lib uuendamisel, kinnijooksmisel jms.;
* Peatada veebirakendust ilma serverist eemaldamata, samuti koos serverist eemaldamisega;
* Vaadata operatsioonisüsteemi ja Java parameetrite väärtusi;
* Näha kõiki saadaolevaid JNDI ressursse, k.a. andmebaasiühendusi, mis aitavad rakenduste programmeerijail defineerida <ResourceLink> elemendid web.xml konfiguratsioonifailis.

Tomcati installatsioon sisaldab haldusrakendust juba vaikimisi. Haldusrakenduse töölepanemiseks tuleb peremeesmasina konfiguratsioonikataloogi $CATALINA_BASE/conf/[enginename]/[hostname] lisada ka fail manager.xml. Vaikimisi valmiskonfigureeritud testrakendusel on see fail juba olemas asukohas $CATALINA_BASE/conf/Catalina/localhost/manager.xml . Rakendus asub vaikimisi aadressil http://[host]/manager/ , vaikimisi konfiguratsioone kasutades lahendub see asukohaks http://localhost:8080/manager/ . [http://tomcat.apache.org/tomcat-8.0-doc/manager-howto.html#Configuring_Manager_Application_Access 1]

====="Tomcat Manager" ligipääsu konfigureerimine=====

Vaikimisi on turvalisuspõhjustel ligipääs haldusrakendusele maha keeratud. Mismoodi täpselt kasutajatel ligipääsu võimaldada sõltub kasutatavast valdusest (realm). Vaikimisi defineerib $CATALINA_BASE/conf/server.xml valduseks "MemoryRealm". Vaikimisi loeb valdus "MemoryRealm" kasutajad failist $CATALINA_BASE/conf/tomcat-users.xml. Antud failis tuleb iga kasutaja defineerida omaette märgendiga <user>, mis näeb välja umbes järgmine [http://tomcat.apache.org/tomcat-8.0-doc/manager-howto.html#Configuring_Manager_Application_Access 1]:
<pre>
<user name="craig" password="secret" roles="manager-gui,manager-script" />
</pre>

Antud kasutajale on defineeritud korraga kaks rolli. Ligipääsu võimaldamiseks tulebki lihtsamal juhul kasutajatefailis $CATALINA_BASE/conf/tomcat-users.xml defineerida enda kasutaja. Kasutaja rolliks võib määrata näiteks "manager-gui", mis võimaldab ligipääsu kogu HTML liidese funktsionaalsusele.

Teised valdused on "JDBCRealm", mille puhul hoitakse kasutajatega seonduvat infot andmebaasis ja JNDIRealm, mille puhul kasutatakse lihtsustatud kataloogisirvimise protokolli (LDAP).
Lisaks saab haldusrakendusele keelata ligipääsu mujalt kui kindlaksmääratud IP-aadressidelt, lisades filtri "RemoteAddrValve" või "RemoteHostValve" konfigureerimisfaili manager.xml näiteks järgmiselt [http://tomcat.apache.org/tomcat-8.0-doc/manager-howto.html#Introduction 1]:
<pre>
<Context privileged="true">
<Valve className="org.apache.catalina.valves.RemoteAddrValve"
allow="127\.0\.0\.1"/>
</Context>
</pre>

=====Juurutamine ja mahavõtmine haldusrakendusega "Tomcat Manager"=====

Juurutamiseks lae kõigepealt veebiarhiivifail üles, kasutades esilehel asuvat sektsiooni "WAR file to deploy".

[[File:tomcat_manager_war_upload.png|800px|thumb|right|Pilt 2: Veebiarhiivi üleslaadimise nupp]]

Rakendus kuvatakse seejärel hallatavate rakenduste nimekirjas. Kui konteiner pole seadistatud üleslaetud aplikatsiooni kohe ka ise rakendama, tuleb vajutada "Start". Rakenduse peatamiseks kasuta "Stop", uuesti rakendamiseks "Redeploy" ja serverist eemaldamiseks "Undeploy".


[[File:tomcat_manager_apps_list.png|frame|300px|Pilt 3: Rakenduste nimekiri]]

==Näpunäiteid Tomcati reaalseks kasutamiseks==

===Juurutamise järjekord===

Tomcati käivitumisel juurutatakse aplikatsioonid sellises järjekorras [http://www.mulesoft.com/tomcat-deploy-procedures 2]:
# Konteinerisse kopeeritud kontekstikirjelduste järgi $CATALINA_BASE/conf/[EngineName]/[HostName]/[ApplicationName].xml ;
# Lahtipakitud rakendused "webapps" kataloogis;
# Pakitud rakenduste veebiarhiivid "webapps" kataloogis.

Seetõttu peaks käsitsi taasjuurutamisel kindluse mõttes eelnevalt kustutama rakenduse lahtipakitud dokumendipõhja kataloogi "webapps" kataloogist. Kontekstikirjelduse muutumisel tuleb jälgida, kas kirjeldus on juba kopeeritud serverisse ning vajadusel eelmise versiooni ümber muuta või kustutada.

===Reaalsele domeenile konfigureerimine===

Järgnevalt eeldame, et domeen ''www.minukodukas.ee'' on juba serverimasinaga seostatud. Et Tomcat hakkaks ka reaalselt Internetist tulevatele päringutele vastama, tuleb muuta failis $CATALINA_BASE/conf/server.xml konteinerile ''Catalina'' vastava teenusemärgendi sisu sarnaselt järgnevaga:

<pre>
<Service name="Catalina">
<Connector port="80" protocol="HTTP/1.1" connectionTimeout="20000" URIEncoding="UTF-8" redirectPort="8443" />
<Engine name="Catalina" defaultHost="www.minukodukas.ee">
<Host name="www.minukodukas.ee" appBase="webapps" unpackWARs="true" autoDeploy="false" deployOnStartup="false" xmlValidation="false" xmlNamespaceAware="false">
<Context path="" docBase="kodukas" debug="0" reloadable="true" />
</Host>
</Engine>
</Service>
</pre>

Ülal defineerime põhiliselt selle, et Tomcat kuulaks domeeni ''www.minukodukas.ee'' ja kasutaks HTTP päringute jaoks porti 80. Ühtlasti otsib Tomcat juurutatavat rakendust failist $CATALINA_BASE/webapps/kodukas.war. Kuna rajalisandiks on määratud tühi sõne (path=""), siis juurutataksegi aplikatsioon aadressile ''www.minukodukas.ee'' ilma rajalisandita (a'la ''www.minukodukas.ee/wiki''). Seetõttu pakitakse ka veebiarhiiv tegelikult lahti kataloogi $CATALINA_BASE/webapps/ROOT mitte kataloogi $CATALINA_BASE/webapps/kodukas nagu võiks eeldada.

===Käigultvahetus===

Võimaldamaks käigultvahetust (hot deployment) peab konteineri konfiguratsioonifailis $CATALINA_BASE/conf/server.xml olema peremehepõhise märgendi "Host" atribuudi "autoDeploy" väärtus "true". Sel juhul installeerib ja uuendab Tomcat aplikatsioone dünaamiliselt töötamise ajal. Kui väärtuseks on "false", käib installeerimine staatiliselt ning serverisse juurutamiseks tuleb teha konteineri taaskäivitus. Käigultvahetust saab määrata ka peremehe defineerimisel "Host Manager" rakendusega, mis on kättesaadav aadressil http://localhost:8080/host-manager/html . Kasutamiseks tuleb lisada oma kasutajale rolli "admin-gui" (vt. alajaotus ""Tomcat Manager" ligipääsu konfigureerimine").

[[File:host_manager_app.png]]

Käigultvahetust päästikuks on vaikimisi uuendatud veebiarhiivifaili või lahtipakitud veebirakenduse paigutamine "webapps" kataloogi. Käigultvahetuse päästikutele võib failis $CATALINA_BASE/conf/server.xml ka ise lisada kuulatavaid ressursse nagu web.xml muutmine või mõne teegifaili vahetamine (märgendis "Host").

===Klassiteekide väljatõstmine veebiarhiivifailist===

Kõik konteksti poolt kasutatavad Java klassiteegid võib pakendada veebiarhiivi sisse kataloogi "lib", kuid nii võib osutuda veebiarhiivi üleslaadimine ajakulukaks, eriti arenduskeskkonnas. Kui ei teki ohtu, et erinevad rakendused kasutavad sama teegi erinevaid versioone, siis on vahel parem lisada osa teeke konteineri kataloogi $CATALINA_BASE/libs, kust need tehakse siis konteineri poolt kättesaadavaks kõigile konteineris jooksutatavatele kontekstidele. Nii võib vähendada veebiarhiivi faili suurust märgatavalt, mis tõstab kokkuvõttes juurutamiskiirust ja ühes sellega programmeerijate tööviljakust.

===Mälukasutus===

Konteineri poolt kasutatavat mälu saab vaadata haldusrakendusest vajutades lingile "Server Status". Mälukasutus on toodud jaotuses "JVM", kus näidatakse nii maksimaalselt kättesaadavat mälu kui ka parasjagu reserveeritud mälu.

<pre>Free memory: 41.16 MB Total memory: 123.37 MB Max memory: 1027.56 MB</pre>

Mälu suurendamiseks võib näiteks defineerida skriptis $CATALINA_BASE/bin/catalina.sh muutuja "JAVA_OPTS" ning määrata Java mälukasutuse miinimum- ja maksimumväärtused sarnaselt järgnevatega [http://www.mkyong.com/tomcat/tomcat-javalangoutofmemoryerror-permgen-space/ 3]:
<pre>
JAVA_OPTS="-Xms1536m -Xmx1536m -XX:NewSize=256m -XX:MaxNewSize=256m -XX:PermSize=256m -XX:MaxPermSize=256m"
</pre>

===Logifailid===

Vaikimisi defineerib Tomcat failiga $CATALINA_BASE/conf/logging.properties viis logerit, mis tekitavad viis eraldi logifaili.

{| style="background:#cccc99;color:black;width:80%;" border="1" cellpadding="5" cellspacing="0" align="center"
|+ Tomcati tekitatavad logifailid "logs" kataloogis
!Fail !! Kasutus
|- style="background:white; color:black"
| style="width:300px" |catalina.out
| Tomcati käivitus- ja peatamisskriptide väljund, samuti juurutatud rakenduste prindilaused System.out ja veaväljundid System.err
|- style="background:white; color:black"
| style="width:300px" |catalina.[yyyy]-[mm]-[dd].log
| Pööratud (rotated) logifail catalina.out
|- style="background:white; color:black"
| style="width:300px" |host-manager.[yyyy]-[mm]-[dd].log
| Logi peremehehalduse rakendusele (rakendus on kättesaadav kohalikust masinast aadressil http://localhost:8080/host-manager/html )
|- style="background:white; color:black"
| style="width:300px" |localhost.[yyyy]-[mm]-[dd].log
| Peremehe "localhost" logi; mitme virtuaalse peremehe korral tekitatakse igale peremehele oma logi
|- style="background:white; color:black"
| style="width:300px" |localhost_access_log.[yyyy]-[mm]-[dd].txt
| Konteinerisse Internetist saabunud päringute logi
|- style="background:white; color:black"
| style="width:300px" |manager.[yyyy]-[mm]-[dd].log
| Haldusrakenduse tegevuste logi
|}

===Viiteid===

Palju vajalikku võib leida [http://tomcat.apache.org/tomcat-8.0-doc/index.html Tomcat 8 dokumentatsioonist]

Lisaks üks viide põhjalikule Tomcati versioon seitsme ülevaatele: http://www.ntu.edu.sg/home/ehchua/programming/howto/Tomcat_More.html

= Kasutatud materjalid =

#http://tomcat.apache.org/tomcat-8.0-doc/index.html
#http://www.mulesoft.com/tomcat-deploy-procedures
#http://www.mkyong.com/tomcat/tomcat-javalangoutofmemoryerror-permgen-space/

[[Category: Operatsioonisüsteemide administreerimine ja sidumine]]

Tomcat

2014-01-02T22:09:37Z

Kveskima: /* Juurutamine ja mahavõtmine haldusrakendusega "Tomcat Manager" */

==Autor==

Kristjan Veskimäe D32

2013

==Sissejuhatus==

Tomcat on vabalt kättesaadav server Java veebirakendustele. Põhimõtteliselt on tegemist Servlet/JSP spetsifikatsiooni toetava konteineriga. Kiire käivitumise ning rakenduste käigultvahetuse tõttu on Tomcat hea valik väiksemate ning keskmise suurusega Java veebirakenduste käitamiseks.

Antud töö kirjeldab Tomcati 8. versiooni. Põhiosa on üldiselt samasugune võrreldes paari eelmise versiooniga. Suuremad erinevused on versioonispetsiifilistes probleemides ja nende lahendamises, mida käesolev töö ei vaatle.

Töö vaatleb Tomcati paigaldamist ja seadistamist Unix-laadsesse keskkonda ning eeldab lugejalt algteadmisi sarnastes süsteemides. Tomcati on võimalik paigaldada ka Windows-keskkonda, kuid antud veebiserver eeldab kasutaja poolt käsureal töötamist ning Tomcati failihierarhias orienteerumist. Põhimõtteliselt on Java veebirakenduste arendamiseks IDE-abil võimalik siiski ka kasutada IDE-sse integreeritud Tomcati serverit - näiteks pakuvad sellist võimalust Eclipse EE ja NetBeans - kuid seda käesolev töö ei vaatle.

==Mõisted==

* '''Kontekst''' (context) - Tomcati mõistes üks konkreetne veebiaplikatsioon
* '''Konteiner''' (container) - veebiserver Tomcat ise
* '''Kontekstikirjeldus''' (context descriptor) - Tomcati-spetsiifiline konteksti konfiguratsioonimääratlus; peremehepõhine osa loetakse failist $CATALINA_HOME/conf/[enginename]/[hostname]/context.xml ja sellele lisatakse kontekstispetsiifilised täpsustused failist $CATALINA_BASE/conf/[enginename]/[hostname]/[webappname].xml; kontekstikirjeldus määrab näiteks nimed ressurssidele, sessioonihalduse parameetrid jmt. (olgu märgitud, et Tomcati varasemates versioonides sisaldusid kontekstikirjeldused põhikonfiguratsioonifailis server.xml)
* '''Dokumendipõhi''' (docBase) - kontekstile vastav kataloog Tomcati "webapps" kataloogis, mis tekib veebiaplikatsiooni serverisse rakendamisel
* '''Veebiarhiiv''' (Web application ARchive, war-file) - Java veebiaplikatsiooni jagatakse hea tava kohaselt selle üheainsa veebiarhiivi failina, mille laienditüübiks on "war". Tegemist on zip-protokolliga kokkupakitud kataloogiga, millel on Java veebirakenduste spetsifikatsioonile vastav ülesehitus. Siiski võib veebiaplikatsioon olla juurutamisel ka lahtipakendatud olekus (inglisekeelne termin on "war is exploded").

==Ülesehitus==

{| class="wikitable"
|+Kataloogid
|-
|style="color: green;" | $CATALINA_HOME
|baaskataloog, kuhu on Tomcat paigutatud
|-
|style="color: green;" | $CATALINA_BASE
|parasjagu töösoleva Tomcati eksemplari baaskataloog, mille alusel lahendatakse teed ülejäänud kataloogide ja failideni; ainult ühe kasutusel oleva Tomcati eksemplari puhul on see sama, mis $CATALINA_HOME

|-
|style="color: green;" | $CATALINA_BASE/bin
|serveri käivitus- ja abiskriptid
|-
|style="color: green;" | $CATALINA_BASE/conf
|konfiguratsioonifailid
|-
|style="color: green;" | $CATALINA_BASE/lib
|Tomcatile vaikimisi kättesaadavad Java klassiteegid (class libraries) ehk .jar-failid kuhu on Java kompileeritud kood kokku pakendatud
|-
|style="color: green;" | $CATALINA_BASE/logs
|logifailid paigutatakse vaikimisi siia
|-
|style="color: green;" | $CATALINA_BASE/webapps
|kataloog, kuhu paigutatakse serverisse juurutatavad veebiaplikatsioonid

|}

{| class="wikitable"
|+Mõned olulisemad failid
|-
|style="color: green;" | $CATALINA_BASE/bin/startup.sh
|serveri käivitusskript
|-
|style="color: green;" | $CATALINA_BASE/bin/shutdown.sh
|serveri peatusskript

|-
|style="color: green;" | $CATALINA_BASE/conf/server.xml
| konteineri peamine konfiguratsioonifail
|-
|style="color: green;" | $CATALINA_BASE/conf/[enginename]/[hostname]/[webappname].xml
|serveri administraatori jaoks konteinerisse endasse ümber kopeeritud rakendusepõhine kontekstikirjelduse konfiguratsioon failist $CATALINA_BASE/webapps/[ApplicationName]/META-INF/context.xml
|-
|style="color: green;" | $CATALINA_BASE/conf/[enginename]/[hostname]/context.xml
| fail, mis aitab administraatoril konteksti kohta käivat infot kirjeldada peremeesmasina-põhiselt ja halduseks mõeldud automaat-tööriistadel (näiteks Tomcat Manager ja TCD) oma tööd teha
|-
|style="color: green;" | $CATALINA_BASE/$CATALINA_BASE/conf/[enginename]/[hostname]/manager.xml
|fail, mis võimaldab lisada rakendustele ligipääsufiltreid
|-
|style="color: green;" | $CATALINA_BASE/webapps/[webappname]/META-INF/context.xml
|kontekstikirjeldusfail, mille veebirakenduse programmeerija on pakendanud oma aplikatsiooniga kaasa ning millega ta saab võimaluse kontekstikirjeldust omalt poolt mõjutada; kirjutatakse rakenduse uuestijuurutamisel üle, mistõttu administraator peaks muutma selle asemel konteinerisse ümber kopeeritud püsieksemplari $CATALINA_BASE/conf/[enginename]/[hostname]/context.xml
|-
|style="color: green;" | $CATALINA_BASE/webapps/[webappname]/WEB-INF/web.xml
|ka üks oluline Java veebiaplikatsiooni konfiguratsioonifail, mille pakendatakse koos veebiarhiiviga; enamasti muudab seda ainult programeerija; määrab muu hulgas millised aplikatsiooni osad vajavad autentimist või kui kiiresti veebisessioon aegub
|}

==Installeerimine==

===Installeerimine paketihalduriga===

<pre>
apt-cache search tomcat
apt-get install tomcat[version]-webapps
apt-get install tomcat[version]-admin
apt-get install tomcat[version]
</pre>

===Installeerimine käsitsi===

Paketihalduriga installeerides ei pruugi viimane Tomcati versioon olla kättesaadav ja see pakub ka vähem võimalusi kataloogide määramiseks jms. Käsitsi installeerimiseks tuleb laadida Tomcat kodulehelt alla. Lahtipakkimisel tekib kataloog, milles sisalduv fail "RUNNING.txt" on kõige kindlam allikas installeerimisel tekkivate probleemide vältimiseks ning lahendamiseks.

Vajaliku versiooni installeerimisfaili asukoha saab vaadata Tomcati kodulehelt sektsioonist "Download". Järgnevas näites installeerime Tomcati kõige uuema ebastabiilse kandidaatversiooni, mida näitab nimes sisalduv RC ehk "release candidate". Produktsioonikeskkonda tuleks siiski valida stabiilse versiooni. Käsitsi installeerimine on sarnane järgmisega:
<pre>
wget http://mirror.nexcess.net/apache/tomcat/tomcat-8/v8.0.0-RC5/bin/apache-tomcat-8.0.0-RC5.tar.gz
tar -zxvf apache-tomcat-8.0.0-RC5.tar.gz
mv /Users/kristjanveskimae/downloads/apache-tomcat-8.0.0-RC5 /usr/local/apache-tomcat-8.0.0-RC5
rm -f /Library/Tomcat
ln -s /usr/local/apache-tomcat-8.0.0-RC5/ /Library/Tomcat
chown -R kristjanveskimae /Library/Tomcat
chmod +x /Library/Tomcat/bin/*.sh
</pre>

==Käivitamine ja aplikatsiooni juurutamine==

===Konteineri käivitamine===

Tomcati käivitamise eelduseks on Java paigaldamine masinasse ning keskkonnamuutujate "JAVA_HOME" ja "JRE_HOME" defineerimine. Peale installeerimist võib kasutada skripte kataloogist $CATALINA_BASE/bin . Järgneb üks võimalik käivitamise ja peatamise näide, mis on kasutatav eelnevalt kirjeldatud käsitsi installeerimise juhul:
<pre>
/Library/Tomcat/bin/startup.sh
</pre>
ja peatamiseks
<pre>
/Library/Tomcat/bin/shutdown.sh
</pre>

===Näiteaplikatsiooni juurutamine===

Java veebiaplikatsiooni jagatakse hea tava kohaselt üheainsa veebiarhiivi failina. Siiski võib Tomcati juurutada ka lahtipakendatud olekus ("exploded") Java veebiaplikatsiooni.

====Käsitsi juurutamine ja mahavõtmine====

Näiteaplikatsiooni juurutamiseks lae selle veebiarhiivifail alla ning kopeeri oma konteineri juurutamiskataloogi 'webapps':
<pre>wget http://tomcat.apache.org/tomcat-8.0-doc/appdev/sample/sample.war
cp /Users/kristjanveskimae/downloads/sample.war /Library/Tomcat/webapps/sample.war</pre>

[[File:sample_app.png|400px|thumb|right|Pilt 1: Õnnestunult rakendatud näiteaplikatsioon]]

Kui konfiguratsioonifailis $CATALINA_BASE/conf/server.xml on märgendi "Host" atribuudi "autoDeploy" väärtus "true", installeerib ja uuendab Tomcat aplikatsioone dünaamiliselt töötamise ajal. Kui väärtuseks on "false", käib installeerimine staatiliselt ning serverisse juurutamiseks tuleb teha konteineri taaskäivitus. [http://tomcat.apache.org/tomcat-8.0-doc/manager-howto.html#Deploy_A_New_Application_from_a_Local_Path 1] Mõlemal juhul pakib konteiner arhiveeritud faili ise lahti samasse kausta $CATALINA_BASE/webapps ning ka juurutab selle. Tekkiv aplikatsioon on lokaalsest masinast seejärel kättesaadav aadressil http://localhost:8080/sample/ . Kui rakendamine õnnestub, siis peaks olema brauserist nähtav sarnane lehekülg nagu pildil 1.

Veebirakenduse käsitsi mahavõtmiseks tuleb kustutada talle vastav dokumendipõhja kataloog "webapps" kataloogist. Samuti tuleks kustutada .war-fail olemaks kindel, et Tomcat ei rakenda uuel käivitamisel veebiaplikatsiooni veebiarhiivifailist. Veelgi lihtsam on mahavõtmine brauseriga haldusrakenduse kaudu.

Rakenduste baaskataloogi "webapps" asukohta saab muuta failis $CATALINA_BASE/conf/server.xml peremehepõhiselt määratava atribuudiga "appBase", sealjuures Tomcati vaikimisi peremees ehk "Host" on "localhost".

====Tomcati vahendid juurutamiseks====

Veebiaplikatsioonide juurutamine ja mahajuurutamine on võimalik ka kaughalduse teel tänu Tomcati internetipõhisele haldusrakendusele. Näiteks saab veebibrauserit kasutades teha serveri põhitoiminguid Tomcati enda HTML-põhise rakendusega "Tomcat Manager". Veebipõhine haldusrakendus töötab ka käsupõhise veebiteenusena, millele on valmis ehitatud Anti ja Maveni integratsioonid. Samuti eksisteerib käsurea kliendirakendus TCD (Tomcat Client Deployer). TCD ei kuulu Tomcati baaskoosseisu, kuid pakub peale serveri administreerimise tavatoimingute ka lisafunktsionaalsust nagu veebirakenduse kokkukompileerimine ja pakendamine. [http://tomcat.apache.org/tomcat-8.0-doc/manager-howto.html#Configuring_Manager_Application_Access 1]

====Haldurakendus "Tomcat Manager"====

Tomcati haldusrakendus "Tomcat Manager" (antud alamjaotuses lihtsalt haldusrakendus) on Tomcati enda veebiaplikatioon Tomcati brauseripõhiseks kaughalduseks, võimaldades muu hulgas järgnevat [http://tomcat.apache.org/tomcat-8.0-doc/manager-howto.html#Introduction 1]:
* Rakendada uue veebiaplikatsiooni war-faili üleslaadimisega;
* Näha kõiki rakendatud veebiaplikatsioone koos aktiivsete sessioonidega;
* Taasrakendada veebirakendust, näiteks veebiarhiivi pakitud klassifailide /WEB-INF/classes või teekide /WEB-INF/lib uuendamisel, kinnijooksmisel jms.;
* Peatada veebirakendust ilma serverist eemaldamata, samuti koos serverist eemaldamisega;
* Vaadata operatsioonisüsteemi ja Java parameetrite väärtusi;
* Näha kõiki saadaolevaid JNDI ressursse, k.a. andmebaasiühendusi, mis aitavad rakenduste programmeerijail defineerida <ResourceLink> elemendid web.xml konfiguratsioonifailis.

Tomcati installatsioon sisaldab haldusrakendust juba vaikimisi. Haldusrakenduse töölepanemiseks tuleb peremeesmasina konfiguratsioonikataloogi $CATALINA_BASE/conf/[enginename]/[hostname] lisada ka fail manager.xml. Vaikimisi valmiskonfigureeritud testrakendusel on see fail juba olemas asukohas $CATALINA_BASE/conf/Catalina/localhost/manager.xml . Rakendus asub vaikimisi aadressil http://[host]/manager/ , vaikimisi konfiguratsioone kasutades lahendub see asukohaks http://localhost:8080/manager/ . [http://tomcat.apache.org/tomcat-8.0-doc/manager-howto.html#Configuring_Manager_Application_Access 1]

====="Tomcat Manager" ligipääsu konfigureerimine=====

Vaikimisi on turvalisuspõhjustel ligipääs haldusrakendusele maha keeratud. Mismoodi täpselt kasutajatel ligipääsu võimaldada sõltub kasutatavast valdusest (realm). Vaikimisi defineerib $CATALINA_BASE/conf/server.xml valduseks "MemoryRealm". Vaikimisi loeb valdus "MemoryRealm" kasutajad failist $CATALINA_BASE/conf/tomcat-users.xml. Antud failis tuleb iga kasutaja defineerida omaette märgendiga <user>, mis näeb välja umbes järgmine [http://tomcat.apache.org/tomcat-8.0-doc/manager-howto.html#Configuring_Manager_Application_Access 1]:
<pre>
<user name="craig" password="secret" roles="manager-gui,manager-script" />
</pre>

Antud kasutajale on defineeritud korraga kaks rolli. Ligipääsu võimaldamiseks tulebki lihtsamal juhul kasutajatefailis $CATALINA_BASE/conf/tomcat-users.xml defineerida enda kasutaja. Kasutaja rolliks võib määrata näiteks "manager-gui", mis võimaldab ligipääsu kogu HTML liidese funktsionaalsusele.

Teised valdused on "JDBCRealm", mille puhul hoitakse kasutajatega seonduvat infot andmebaasis ja JNDIRealm, mille puhul kasutatakse lihtsustatud kataloogisirvimise protokolli (LDAP).
Lisaks saab haldusrakendusele keelata ligipääsu mujalt kui kindlaksmääratud IP-aadressidelt, lisades filtri "RemoteAddrValve" või "RemoteHostValve" konfigureerimisfaili manager.xml näiteks järgmiselt [http://tomcat.apache.org/tomcat-8.0-doc/manager-howto.html#Introduction 1]:
<pre>
<Context privileged="true">
<Valve className="org.apache.catalina.valves.RemoteAddrValve"
allow="127\.0\.0\.1"/>
</Context>
</pre>

=====Juurutamine ja mahavõtmine haldusrakendusega "Tomcat Manager"=====

Juurutamiseks lae kõigepealt veebiarhiivifail üles, kasutades esilehel asuvat sektsiooni "WAR file to deploy".

[[File:tomcat_manager_war_upload.png|800px|thumb|right|Pilt 2: Veebiarhiivi üleslaadimise nupp]]

Rakendus kuvatakse seejärel hallatavate rakenduste nimekirjas. Kui konteiner pole seadistatud üleslaetud aplikatsiooni kohe ka ise rakendama, tuleb vajutada "Start". Rakenduse peatamiseks kasuta "Stop", uuesti rakendamiseks "Redeploy" ja serverist eemaldamiseks "Undeploy".


[[File:tomcat_manager_apps_list.png|none|300px|Pilt 3: Rakenduste nimekiri]]

==Näpunäiteid Tomcati reaalseks kasutamiseks==

===Juurutamise järjekord===

Tomcati käivitumisel juurutatakse aplikatsioonid sellises järjekorras [http://www.mulesoft.com/tomcat-deploy-procedures 2]:
# Konteinerisse kopeeritud kontekstikirjelduste järgi $CATALINA_BASE/conf/[EngineName]/[HostName]/[ApplicationName].xml ;
# Lahtipakitud rakendused "webapps" kataloogis;
# Pakitud rakenduste veebiarhiivid "webapps" kataloogis.

Seetõttu peaks käsitsi taasjuurutamisel kindluse mõttes eelnevalt kustutama rakenduse lahtipakitud dokumendipõhja kataloogi "webapps" kataloogist. Kontekstikirjelduse muutumisel tuleb jälgida, kas kirjeldus on juba kopeeritud serverisse ning vajadusel eelmise versiooni ümber muuta või kustutada.

===Reaalsele domeenile konfigureerimine===

Järgnevalt eeldame, et domeen ''www.minukodukas.ee'' on juba serverimasinaga seostatud. Et Tomcat hakkaks ka reaalselt Internetist tulevatele päringutele vastama, tuleb muuta failis $CATALINA_BASE/conf/server.xml konteinerile ''Catalina'' vastava teenusemärgendi sisu sarnaselt järgnevaga:

<pre>
<Service name="Catalina">
<Connector port="80" protocol="HTTP/1.1" connectionTimeout="20000" URIEncoding="UTF-8" redirectPort="8443" />
<Engine name="Catalina" defaultHost="www.minukodukas.ee">
<Host name="www.minukodukas.ee" appBase="webapps" unpackWARs="true" autoDeploy="false" deployOnStartup="false" xmlValidation="false" xmlNamespaceAware="false">
<Context path="" docBase="kodukas" debug="0" reloadable="true" />
</Host>
</Engine>
</Service>
</pre>

Ülal defineerime põhiliselt selle, et Tomcat kuulaks domeeni ''www.minukodukas.ee'' ja kasutaks HTTP päringute jaoks porti 80. Ühtlasti otsib Tomcat juurutatavat rakendust failist $CATALINA_BASE/webapps/kodukas.war. Kuna rajalisandiks on määratud tühi sõne (path=""), siis juurutataksegi aplikatsioon aadressile ''www.minukodukas.ee'' ilma rajalisandita (a'la ''www.minukodukas.ee/wiki''). Seetõttu pakitakse ka veebiarhiiv tegelikult lahti kataloogi $CATALINA_BASE/webapps/ROOT mitte kataloogi $CATALINA_BASE/webapps/kodukas nagu võiks eeldada.

===Käigultvahetus===

Võimaldamaks käigultvahetust (hot deployment) peab konteineri konfiguratsioonifailis $CATALINA_BASE/conf/server.xml olema peremehepõhise märgendi "Host" atribuudi "autoDeploy" väärtus "true". Sel juhul installeerib ja uuendab Tomcat aplikatsioone dünaamiliselt töötamise ajal. Kui väärtuseks on "false", käib installeerimine staatiliselt ning serverisse juurutamiseks tuleb teha konteineri taaskäivitus. Käigultvahetust saab määrata ka peremehe defineerimisel "Host Manager" rakendusega, mis on kättesaadav aadressil http://localhost:8080/host-manager/html . Kasutamiseks tuleb lisada oma kasutajale rolli "admin-gui" (vt. alajaotus ""Tomcat Manager" ligipääsu konfigureerimine").

[[File:host_manager_app.png]]

Käigultvahetust päästikuks on vaikimisi uuendatud veebiarhiivifaili või lahtipakitud veebirakenduse paigutamine "webapps" kataloogi. Käigultvahetuse päästikutele võib failis $CATALINA_BASE/conf/server.xml ka ise lisada kuulatavaid ressursse nagu web.xml muutmine või mõne teegifaili vahetamine (märgendis "Host").

===Klassiteekide väljatõstmine veebiarhiivifailist===

Kõik konteksti poolt kasutatavad Java klassiteegid võib pakendada veebiarhiivi sisse kataloogi "lib", kuid nii võib osutuda veebiarhiivi üleslaadimine ajakulukaks, eriti arenduskeskkonnas. Kui ei teki ohtu, et erinevad rakendused kasutavad sama teegi erinevaid versioone, siis on vahel parem lisada osa teeke konteineri kataloogi $CATALINA_BASE/libs, kust need tehakse siis konteineri poolt kättesaadavaks kõigile konteineris jooksutatavatele kontekstidele. Nii võib vähendada veebiarhiivi faili suurust märgatavalt, mis tõstab kokkuvõttes juurutamiskiirust ja ühes sellega programmeerijate tööviljakust.

===Mälukasutus===

Konteineri poolt kasutatavat mälu saab vaadata haldusrakendusest vajutades lingile "Server Status". Mälukasutus on toodud jaotuses "JVM", kus näidatakse nii maksimaalselt kättesaadavat mälu kui ka parasjagu reserveeritud mälu.

<pre>Free memory: 41.16 MB Total memory: 123.37 MB Max memory: 1027.56 MB</pre>

Mälu suurendamiseks võib näiteks defineerida skriptis $CATALINA_BASE/bin/catalina.sh muutuja "JAVA_OPTS" ning määrata Java mälukasutuse miinimum- ja maksimumväärtused sarnaselt järgnevatega [http://www.mkyong.com/tomcat/tomcat-javalangoutofmemoryerror-permgen-space/ 3]:
<pre>
JAVA_OPTS="-Xms1536m -Xmx1536m -XX:NewSize=256m -XX:MaxNewSize=256m -XX:PermSize=256m -XX:MaxPermSize=256m"
</pre>

===Logifailid===

Vaikimisi defineerib Tomcat failiga $CATALINA_BASE/conf/logging.properties viis logerit, mis tekitavad viis eraldi logifaili.

{| style="background:#cccc99;color:black;width:80%;" border="1" cellpadding="5" cellspacing="0" align="center"
|+ Tomcati tekitatavad logifailid "logs" kataloogis
!Fail !! Kasutus
|- style="background:white; color:black"
| style="width:300px" |catalina.out
| Tomcati käivitus- ja peatamisskriptide väljund, samuti juurutatud rakenduste prindilaused System.out ja veaväljundid System.err
|- style="background:white; color:black"
| style="width:300px" |catalina.[yyyy]-[mm]-[dd].log
| Pööratud (rotated) logifail catalina.out
|- style="background:white; color:black"
| style="width:300px" |host-manager.[yyyy]-[mm]-[dd].log
| Logi peremehehalduse rakendusele (rakendus on kättesaadav kohalikust masinast aadressil http://localhost:8080/host-manager/html )
|- style="background:white; color:black"
| style="width:300px" |localhost.[yyyy]-[mm]-[dd].log
| Peremehe "localhost" logi; mitme virtuaalse peremehe korral tekitatakse igale peremehele oma logi
|- style="background:white; color:black"
| style="width:300px" |localhost_access_log.[yyyy]-[mm]-[dd].txt
| Konteinerisse Internetist saabunud päringute logi
|- style="background:white; color:black"
| style="width:300px" |manager.[yyyy]-[mm]-[dd].log
| Haldusrakenduse tegevuste logi
|}

===Viiteid===

Palju vajalikku võib leida [http://tomcat.apache.org/tomcat-8.0-doc/index.html Tomcat 8 dokumentatsioonist]

Lisaks üks viide põhjalikule Tomcati versioon seitsme ülevaatele: http://www.ntu.edu.sg/home/ehchua/programming/howto/Tomcat_More.html

= Kasutatud materjalid =

#http://tomcat.apache.org/tomcat-8.0-doc/index.html
#http://www.mulesoft.com/tomcat-deploy-procedures
#http://www.mkyong.com/tomcat/tomcat-javalangoutofmemoryerror-permgen-space/

[[Category: Operatsioonisüsteemide administreerimine ja sidumine]]

Tomcat

2014-01-02T22:07:49Z

Kveskima: /* Juurutamine ja mahavõtmine haldusrakendusega "Tomcat Manager" */

==Autor==

Kristjan Veskimäe D32

2013

==Sissejuhatus==

Tomcat on vabalt kättesaadav server Java veebirakendustele. Põhimõtteliselt on tegemist Servlet/JSP spetsifikatsiooni toetava konteineriga. Kiire käivitumise ning rakenduste käigultvahetuse tõttu on Tomcat hea valik väiksemate ning keskmise suurusega Java veebirakenduste käitamiseks.

Antud töö kirjeldab Tomcati 8. versiooni. Põhiosa on üldiselt samasugune võrreldes paari eelmise versiooniga. Suuremad erinevused on versioonispetsiifilistes probleemides ja nende lahendamises, mida käesolev töö ei vaatle.

Töö vaatleb Tomcati paigaldamist ja seadistamist Unix-laadsesse keskkonda ning eeldab lugejalt algteadmisi sarnastes süsteemides. Tomcati on võimalik paigaldada ka Windows-keskkonda, kuid antud veebiserver eeldab kasutaja poolt käsureal töötamist ning Tomcati failihierarhias orienteerumist. Põhimõtteliselt on Java veebirakenduste arendamiseks IDE-abil võimalik siiski ka kasutada IDE-sse integreeritud Tomcati serverit - näiteks pakuvad sellist võimalust Eclipse EE ja NetBeans - kuid seda käesolev töö ei vaatle.

==Mõisted==

* '''Kontekst''' (context) - Tomcati mõistes üks konkreetne veebiaplikatsioon
* '''Konteiner''' (container) - veebiserver Tomcat ise
* '''Kontekstikirjeldus''' (context descriptor) - Tomcati-spetsiifiline konteksti konfiguratsioonimääratlus; peremehepõhine osa loetakse failist $CATALINA_HOME/conf/[enginename]/[hostname]/context.xml ja sellele lisatakse kontekstispetsiifilised täpsustused failist $CATALINA_BASE/conf/[enginename]/[hostname]/[webappname].xml; kontekstikirjeldus määrab näiteks nimed ressurssidele, sessioonihalduse parameetrid jmt. (olgu märgitud, et Tomcati varasemates versioonides sisaldusid kontekstikirjeldused põhikonfiguratsioonifailis server.xml)
* '''Dokumendipõhi''' (docBase) - kontekstile vastav kataloog Tomcati "webapps" kataloogis, mis tekib veebiaplikatsiooni serverisse rakendamisel
* '''Veebiarhiiv''' (Web application ARchive, war-file) - Java veebiaplikatsiooni jagatakse hea tava kohaselt selle üheainsa veebiarhiivi failina, mille laienditüübiks on "war". Tegemist on zip-protokolliga kokkupakitud kataloogiga, millel on Java veebirakenduste spetsifikatsioonile vastav ülesehitus. Siiski võib veebiaplikatsioon olla juurutamisel ka lahtipakendatud olekus (inglisekeelne termin on "war is exploded").

==Ülesehitus==

{| class="wikitable"
|+Kataloogid
|-
|style="color: green;" | $CATALINA_HOME
|baaskataloog, kuhu on Tomcat paigutatud
|-
|style="color: green;" | $CATALINA_BASE
|parasjagu töösoleva Tomcati eksemplari baaskataloog, mille alusel lahendatakse teed ülejäänud kataloogide ja failideni; ainult ühe kasutusel oleva Tomcati eksemplari puhul on see sama, mis $CATALINA_HOME

|-
|style="color: green;" | $CATALINA_BASE/bin
|serveri käivitus- ja abiskriptid
|-
|style="color: green;" | $CATALINA_BASE/conf
|konfiguratsioonifailid
|-
|style="color: green;" | $CATALINA_BASE/lib
|Tomcatile vaikimisi kättesaadavad Java klassiteegid (class libraries) ehk .jar-failid kuhu on Java kompileeritud kood kokku pakendatud
|-
|style="color: green;" | $CATALINA_BASE/logs
|logifailid paigutatakse vaikimisi siia
|-
|style="color: green;" | $CATALINA_BASE/webapps
|kataloog, kuhu paigutatakse serverisse juurutatavad veebiaplikatsioonid

|}

{| class="wikitable"
|+Mõned olulisemad failid
|-
|style="color: green;" | $CATALINA_BASE/bin/startup.sh
|serveri käivitusskript
|-
|style="color: green;" | $CATALINA_BASE/bin/shutdown.sh
|serveri peatusskript

|-
|style="color: green;" | $CATALINA_BASE/conf/server.xml
| konteineri peamine konfiguratsioonifail
|-
|style="color: green;" | $CATALINA_BASE/conf/[enginename]/[hostname]/[webappname].xml
|serveri administraatori jaoks konteinerisse endasse ümber kopeeritud rakendusepõhine kontekstikirjelduse konfiguratsioon failist $CATALINA_BASE/webapps/[ApplicationName]/META-INF/context.xml
|-
|style="color: green;" | $CATALINA_BASE/conf/[enginename]/[hostname]/context.xml
| fail, mis aitab administraatoril konteksti kohta käivat infot kirjeldada peremeesmasina-põhiselt ja halduseks mõeldud automaat-tööriistadel (näiteks Tomcat Manager ja TCD) oma tööd teha
|-
|style="color: green;" | $CATALINA_BASE/$CATALINA_BASE/conf/[enginename]/[hostname]/manager.xml
|fail, mis võimaldab lisada rakendustele ligipääsufiltreid
|-
|style="color: green;" | $CATALINA_BASE/webapps/[webappname]/META-INF/context.xml
|kontekstikirjeldusfail, mille veebirakenduse programmeerija on pakendanud oma aplikatsiooniga kaasa ning millega ta saab võimaluse kontekstikirjeldust omalt poolt mõjutada; kirjutatakse rakenduse uuestijuurutamisel üle, mistõttu administraator peaks muutma selle asemel konteinerisse ümber kopeeritud püsieksemplari $CATALINA_BASE/conf/[enginename]/[hostname]/context.xml
|-
|style="color: green;" | $CATALINA_BASE/webapps/[webappname]/WEB-INF/web.xml
|ka üks oluline Java veebiaplikatsiooni konfiguratsioonifail, mille pakendatakse koos veebiarhiiviga; enamasti muudab seda ainult programeerija; määrab muu hulgas millised aplikatsiooni osad vajavad autentimist või kui kiiresti veebisessioon aegub
|}

==Installeerimine==

===Installeerimine paketihalduriga===

<pre>
apt-cache search tomcat
apt-get install tomcat[version]-webapps
apt-get install tomcat[version]-admin
apt-get install tomcat[version]
</pre>

===Installeerimine käsitsi===

Paketihalduriga installeerides ei pruugi viimane Tomcati versioon olla kättesaadav ja see pakub ka vähem võimalusi kataloogide määramiseks jms. Käsitsi installeerimiseks tuleb laadida Tomcat kodulehelt alla. Lahtipakkimisel tekib kataloog, milles sisalduv fail "RUNNING.txt" on kõige kindlam allikas installeerimisel tekkivate probleemide vältimiseks ning lahendamiseks.

Vajaliku versiooni installeerimisfaili asukoha saab vaadata Tomcati kodulehelt sektsioonist "Download". Järgnevas näites installeerime Tomcati kõige uuema ebastabiilse kandidaatversiooni, mida näitab nimes sisalduv RC ehk "release candidate". Produktsioonikeskkonda tuleks siiski valida stabiilse versiooni. Käsitsi installeerimine on sarnane järgmisega:
<pre>
wget http://mirror.nexcess.net/apache/tomcat/tomcat-8/v8.0.0-RC5/bin/apache-tomcat-8.0.0-RC5.tar.gz
tar -zxvf apache-tomcat-8.0.0-RC5.tar.gz
mv /Users/kristjanveskimae/downloads/apache-tomcat-8.0.0-RC5 /usr/local/apache-tomcat-8.0.0-RC5
rm -f /Library/Tomcat
ln -s /usr/local/apache-tomcat-8.0.0-RC5/ /Library/Tomcat
chown -R kristjanveskimae /Library/Tomcat
chmod +x /Library/Tomcat/bin/*.sh
</pre>

==Käivitamine ja aplikatsiooni juurutamine==

===Konteineri käivitamine===

Tomcati käivitamise eelduseks on Java paigaldamine masinasse ning keskkonnamuutujate "JAVA_HOME" ja "JRE_HOME" defineerimine. Peale installeerimist võib kasutada skripte kataloogist $CATALINA_BASE/bin . Järgneb üks võimalik käivitamise ja peatamise näide, mis on kasutatav eelnevalt kirjeldatud käsitsi installeerimise juhul:
<pre>
/Library/Tomcat/bin/startup.sh
</pre>
ja peatamiseks
<pre>
/Library/Tomcat/bin/shutdown.sh
</pre>

===Näiteaplikatsiooni juurutamine===

Java veebiaplikatsiooni jagatakse hea tava kohaselt üheainsa veebiarhiivi failina. Siiski võib Tomcati juurutada ka lahtipakendatud olekus ("exploded") Java veebiaplikatsiooni.

====Käsitsi juurutamine ja mahavõtmine====

Näiteaplikatsiooni juurutamiseks lae selle veebiarhiivifail alla ning kopeeri oma konteineri juurutamiskataloogi 'webapps':
<pre>wget http://tomcat.apache.org/tomcat-8.0-doc/appdev/sample/sample.war
cp /Users/kristjanveskimae/downloads/sample.war /Library/Tomcat/webapps/sample.war</pre>

[[File:sample_app.png|400px|thumb|right|Pilt 1: Õnnestunult rakendatud näiteaplikatsioon]]

Kui konfiguratsioonifailis $CATALINA_BASE/conf/server.xml on märgendi "Host" atribuudi "autoDeploy" väärtus "true", installeerib ja uuendab Tomcat aplikatsioone dünaamiliselt töötamise ajal. Kui väärtuseks on "false", käib installeerimine staatiliselt ning serverisse juurutamiseks tuleb teha konteineri taaskäivitus. [http://tomcat.apache.org/tomcat-8.0-doc/manager-howto.html#Deploy_A_New_Application_from_a_Local_Path 1] Mõlemal juhul pakib konteiner arhiveeritud faili ise lahti samasse kausta $CATALINA_BASE/webapps ning ka juurutab selle. Tekkiv aplikatsioon on lokaalsest masinast seejärel kättesaadav aadressil http://localhost:8080/sample/ . Kui rakendamine õnnestub, siis peaks olema brauserist nähtav sarnane lehekülg nagu pildil 1.

Veebirakenduse käsitsi mahavõtmiseks tuleb kustutada talle vastav dokumendipõhja kataloog "webapps" kataloogist. Samuti tuleks kustutada .war-fail olemaks kindel, et Tomcat ei rakenda uuel käivitamisel veebiaplikatsiooni veebiarhiivifailist. Veelgi lihtsam on mahavõtmine brauseriga haldusrakenduse kaudu.

Rakenduste baaskataloogi "webapps" asukohta saab muuta failis $CATALINA_BASE/conf/server.xml peremehepõhiselt määratava atribuudiga "appBase", sealjuures Tomcati vaikimisi peremees ehk "Host" on "localhost".

====Tomcati vahendid juurutamiseks====

Veebiaplikatsioonide juurutamine ja mahajuurutamine on võimalik ka kaughalduse teel tänu Tomcati internetipõhisele haldusrakendusele. Näiteks saab veebibrauserit kasutades teha serveri põhitoiminguid Tomcati enda HTML-põhise rakendusega "Tomcat Manager". Veebipõhine haldusrakendus töötab ka käsupõhise veebiteenusena, millele on valmis ehitatud Anti ja Maveni integratsioonid. Samuti eksisteerib käsurea kliendirakendus TCD (Tomcat Client Deployer). TCD ei kuulu Tomcati baaskoosseisu, kuid pakub peale serveri administreerimise tavatoimingute ka lisafunktsionaalsust nagu veebirakenduse kokkukompileerimine ja pakendamine. [http://tomcat.apache.org/tomcat-8.0-doc/manager-howto.html#Configuring_Manager_Application_Access 1]

====Haldurakendus "Tomcat Manager"====

Tomcati haldusrakendus "Tomcat Manager" (antud alamjaotuses lihtsalt haldusrakendus) on Tomcati enda veebiaplikatioon Tomcati brauseripõhiseks kaughalduseks, võimaldades muu hulgas järgnevat [http://tomcat.apache.org/tomcat-8.0-doc/manager-howto.html#Introduction 1]:
* Rakendada uue veebiaplikatsiooni war-faili üleslaadimisega;
* Näha kõiki rakendatud veebiaplikatsioone koos aktiivsete sessioonidega;
* Taasrakendada veebirakendust, näiteks veebiarhiivi pakitud klassifailide /WEB-INF/classes või teekide /WEB-INF/lib uuendamisel, kinnijooksmisel jms.;
* Peatada veebirakendust ilma serverist eemaldamata, samuti koos serverist eemaldamisega;
* Vaadata operatsioonisüsteemi ja Java parameetrite väärtusi;
* Näha kõiki saadaolevaid JNDI ressursse, k.a. andmebaasiühendusi, mis aitavad rakenduste programmeerijail defineerida <ResourceLink> elemendid web.xml konfiguratsioonifailis.

Tomcati installatsioon sisaldab haldusrakendust juba vaikimisi. Haldusrakenduse töölepanemiseks tuleb peremeesmasina konfiguratsioonikataloogi $CATALINA_BASE/conf/[enginename]/[hostname] lisada ka fail manager.xml. Vaikimisi valmiskonfigureeritud testrakendusel on see fail juba olemas asukohas $CATALINA_BASE/conf/Catalina/localhost/manager.xml . Rakendus asub vaikimisi aadressil http://[host]/manager/ , vaikimisi konfiguratsioone kasutades lahendub see asukohaks http://localhost:8080/manager/ . [http://tomcat.apache.org/tomcat-8.0-doc/manager-howto.html#Configuring_Manager_Application_Access 1]

====="Tomcat Manager" ligipääsu konfigureerimine=====

Vaikimisi on turvalisuspõhjustel ligipääs haldusrakendusele maha keeratud. Mismoodi täpselt kasutajatel ligipääsu võimaldada sõltub kasutatavast valdusest (realm). Vaikimisi defineerib $CATALINA_BASE/conf/server.xml valduseks "MemoryRealm". Vaikimisi loeb valdus "MemoryRealm" kasutajad failist $CATALINA_BASE/conf/tomcat-users.xml. Antud failis tuleb iga kasutaja defineerida omaette märgendiga <user>, mis näeb välja umbes järgmine [http://tomcat.apache.org/tomcat-8.0-doc/manager-howto.html#Configuring_Manager_Application_Access 1]:
<pre>
<user name="craig" password="secret" roles="manager-gui,manager-script" />
</pre>

Antud kasutajale on defineeritud korraga kaks rolli. Ligipääsu võimaldamiseks tulebki lihtsamal juhul kasutajatefailis $CATALINA_BASE/conf/tomcat-users.xml defineerida enda kasutaja. Kasutaja rolliks võib määrata näiteks "manager-gui", mis võimaldab ligipääsu kogu HTML liidese funktsionaalsusele.

Teised valdused on "JDBCRealm", mille puhul hoitakse kasutajatega seonduvat infot andmebaasis ja JNDIRealm, mille puhul kasutatakse lihtsustatud kataloogisirvimise protokolli (LDAP).
Lisaks saab haldusrakendusele keelata ligipääsu mujalt kui kindlaksmääratud IP-aadressidelt, lisades filtri "RemoteAddrValve" või "RemoteHostValve" konfigureerimisfaili manager.xml näiteks järgmiselt [http://tomcat.apache.org/tomcat-8.0-doc/manager-howto.html#Introduction 1]:
<pre>
<Context privileged="true">
<Valve className="org.apache.catalina.valves.RemoteAddrValve"
allow="127\.0\.0\.1"/>
</Context>
</pre>

=====Juurutamine ja mahavõtmine haldusrakendusega "Tomcat Manager"=====

Juurutamiseks lae kõigepealt veebiarhiivifail üles, kasutades esilehel asuvat sektsiooni "WAR file to deploy".

[[File:tomcat_manager_war_upload.png|800px|thumb|right|Pilt 2: Veebiarhiivi üleslaadimise nupp]]

Rakendus kuvatakse seejärel hallatavate rakenduste nimekirjas. Kui konteiner pole seadistatud üleslaetud aplikatsiooni kohe ka ise rakendama, tuleb vajutada "Start". Rakenduse peatamiseks kasuta "Stop", uuesti rakendamiseks "Redeploy" ja serverist eemaldamiseks "Undeploy".


[[File:tomcat_manager_apps_list.png|200px|thumb|frame|Pilt 3: Rakenduste nimekiri]]

==Näpunäiteid Tomcati reaalseks kasutamiseks==

===Juurutamise järjekord===

Tomcati käivitumisel juurutatakse aplikatsioonid sellises järjekorras [http://www.mulesoft.com/tomcat-deploy-procedures 2]:
# Konteinerisse kopeeritud kontekstikirjelduste järgi $CATALINA_BASE/conf/[EngineName]/[HostName]/[ApplicationName].xml ;
# Lahtipakitud rakendused "webapps" kataloogis;
# Pakitud rakenduste veebiarhiivid "webapps" kataloogis.

Seetõttu peaks käsitsi taasjuurutamisel kindluse mõttes eelnevalt kustutama rakenduse lahtipakitud dokumendipõhja kataloogi "webapps" kataloogist. Kontekstikirjelduse muutumisel tuleb jälgida, kas kirjeldus on juba kopeeritud serverisse ning vajadusel eelmise versiooni ümber muuta või kustutada.

===Reaalsele domeenile konfigureerimine===

Järgnevalt eeldame, et domeen ''www.minukodukas.ee'' on juba serverimasinaga seostatud. Et Tomcat hakkaks ka reaalselt Internetist tulevatele päringutele vastama, tuleb muuta failis $CATALINA_BASE/conf/server.xml konteinerile ''Catalina'' vastava teenusemärgendi sisu sarnaselt järgnevaga:

<pre>
<Service name="Catalina">
<Connector port="80" protocol="HTTP/1.1" connectionTimeout="20000" URIEncoding="UTF-8" redirectPort="8443" />
<Engine name="Catalina" defaultHost="www.minukodukas.ee">
<Host name="www.minukodukas.ee" appBase="webapps" unpackWARs="true" autoDeploy="false" deployOnStartup="false" xmlValidation="false" xmlNamespaceAware="false">
<Context path="" docBase="kodukas" debug="0" reloadable="true" />
</Host>
</Engine>
</Service>
</pre>

Ülal defineerime põhiliselt selle, et Tomcat kuulaks domeeni ''www.minukodukas.ee'' ja kasutaks HTTP päringute jaoks porti 80. Ühtlasti otsib Tomcat juurutatavat rakendust failist $CATALINA_BASE/webapps/kodukas.war. Kuna rajalisandiks on määratud tühi sõne (path=""), siis juurutataksegi aplikatsioon aadressile ''www.minukodukas.ee'' ilma rajalisandita (a'la ''www.minukodukas.ee/wiki''). Seetõttu pakitakse ka veebiarhiiv tegelikult lahti kataloogi $CATALINA_BASE/webapps/ROOT mitte kataloogi $CATALINA_BASE/webapps/kodukas nagu võiks eeldada.

===Käigultvahetus===

Võimaldamaks käigultvahetust (hot deployment) peab konteineri konfiguratsioonifailis $CATALINA_BASE/conf/server.xml olema peremehepõhise märgendi "Host" atribuudi "autoDeploy" väärtus "true". Sel juhul installeerib ja uuendab Tomcat aplikatsioone dünaamiliselt töötamise ajal. Kui väärtuseks on "false", käib installeerimine staatiliselt ning serverisse juurutamiseks tuleb teha konteineri taaskäivitus. Käigultvahetust saab määrata ka peremehe defineerimisel "Host Manager" rakendusega, mis on kättesaadav aadressil http://localhost:8080/host-manager/html . Kasutamiseks tuleb lisada oma kasutajale rolli "admin-gui" (vt. alajaotus ""Tomcat Manager" ligipääsu konfigureerimine").

[[File:host_manager_app.png]]

Käigultvahetust päästikuks on vaikimisi uuendatud veebiarhiivifaili või lahtipakitud veebirakenduse paigutamine "webapps" kataloogi. Käigultvahetuse päästikutele võib failis $CATALINA_BASE/conf/server.xml ka ise lisada kuulatavaid ressursse nagu web.xml muutmine või mõne teegifaili vahetamine (märgendis "Host").

===Klassiteekide väljatõstmine veebiarhiivifailist===

Kõik konteksti poolt kasutatavad Java klassiteegid võib pakendada veebiarhiivi sisse kataloogi "lib", kuid nii võib osutuda veebiarhiivi üleslaadimine ajakulukaks, eriti arenduskeskkonnas. Kui ei teki ohtu, et erinevad rakendused kasutavad sama teegi erinevaid versioone, siis on vahel parem lisada osa teeke konteineri kataloogi $CATALINA_BASE/libs, kust need tehakse siis konteineri poolt kättesaadavaks kõigile konteineris jooksutatavatele kontekstidele. Nii võib vähendada veebiarhiivi faili suurust märgatavalt, mis tõstab kokkuvõttes juurutamiskiirust ja ühes sellega programmeerijate tööviljakust.

===Mälukasutus===

Konteineri poolt kasutatavat mälu saab vaadata haldusrakendusest vajutades lingile "Server Status". Mälukasutus on toodud jaotuses "JVM", kus näidatakse nii maksimaalselt kättesaadavat mälu kui ka parasjagu reserveeritud mälu.

<pre>Free memory: 41.16 MB Total memory: 123.37 MB Max memory: 1027.56 MB</pre>

Mälu suurendamiseks võib näiteks defineerida skriptis $CATALINA_BASE/bin/catalina.sh muutuja "JAVA_OPTS" ning määrata Java mälukasutuse miinimum- ja maksimumväärtused sarnaselt järgnevatega [http://www.mkyong.com/tomcat/tomcat-javalangoutofmemoryerror-permgen-space/ 3]:
<pre>
JAVA_OPTS="-Xms1536m -Xmx1536m -XX:NewSize=256m -XX:MaxNewSize=256m -XX:PermSize=256m -XX:MaxPermSize=256m"
</pre>

===Logifailid===

Vaikimisi defineerib Tomcat failiga $CATALINA_BASE/conf/logging.properties viis logerit, mis tekitavad viis eraldi logifaili.

{| style="background:#cccc99;color:black;width:80%;" border="1" cellpadding="5" cellspacing="0" align="center"
|+ Tomcati tekitatavad logifailid "logs" kataloogis
!Fail !! Kasutus
|- style="background:white; color:black"
| style="width:300px" |catalina.out
| Tomcati käivitus- ja peatamisskriptide väljund, samuti juurutatud rakenduste prindilaused System.out ja veaväljundid System.err
|- style="background:white; color:black"
| style="width:300px" |catalina.[yyyy]-[mm]-[dd].log
| Pööratud (rotated) logifail catalina.out
|- style="background:white; color:black"
| style="width:300px" |host-manager.[yyyy]-[mm]-[dd].log
| Logi peremehehalduse rakendusele (rakendus on kättesaadav kohalikust masinast aadressil http://localhost:8080/host-manager/html )
|- style="background:white; color:black"
| style="width:300px" |localhost.[yyyy]-[mm]-[dd].log
| Peremehe "localhost" logi; mitme virtuaalse peremehe korral tekitatakse igale peremehele oma logi
|- style="background:white; color:black"
| style="width:300px" |localhost_access_log.[yyyy]-[mm]-[dd].txt
| Konteinerisse Internetist saabunud päringute logi
|- style="background:white; color:black"
| style="width:300px" |manager.[yyyy]-[mm]-[dd].log
| Haldusrakenduse tegevuste logi
|}

===Viiteid===

Palju vajalikku võib leida [http://tomcat.apache.org/tomcat-8.0-doc/index.html Tomcat 8 dokumentatsioonist]

Lisaks üks viide põhjalikule Tomcati versioon seitsme ülevaatele: http://www.ntu.edu.sg/home/ehchua/programming/howto/Tomcat_More.html

= Kasutatud materjalid =

#http://tomcat.apache.org/tomcat-8.0-doc/index.html
#http://www.mulesoft.com/tomcat-deploy-procedures
#http://www.mkyong.com/tomcat/tomcat-javalangoutofmemoryerror-permgen-space/

[[Category: Operatsioonisüsteemide administreerimine ja sidumine]]

Tomcat

2014-01-02T22:07:36Z

Kveskima: /* Juurutamine ja mahavõtmine haldusrakendusega "Tomcat Manager" */

==Autor==

Kristjan Veskimäe D32

2013

==Sissejuhatus==

Tomcat on vabalt kättesaadav server Java veebirakendustele. Põhimõtteliselt on tegemist Servlet/JSP spetsifikatsiooni toetava konteineriga. Kiire käivitumise ning rakenduste käigultvahetuse tõttu on Tomcat hea valik väiksemate ning keskmise suurusega Java veebirakenduste käitamiseks.

Antud töö kirjeldab Tomcati 8. versiooni. Põhiosa on üldiselt samasugune võrreldes paari eelmise versiooniga. Suuremad erinevused on versioonispetsiifilistes probleemides ja nende lahendamises, mida käesolev töö ei vaatle.

Töö vaatleb Tomcati paigaldamist ja seadistamist Unix-laadsesse keskkonda ning eeldab lugejalt algteadmisi sarnastes süsteemides. Tomcati on võimalik paigaldada ka Windows-keskkonda, kuid antud veebiserver eeldab kasutaja poolt käsureal töötamist ning Tomcati failihierarhias orienteerumist. Põhimõtteliselt on Java veebirakenduste arendamiseks IDE-abil võimalik siiski ka kasutada IDE-sse integreeritud Tomcati serverit - näiteks pakuvad sellist võimalust Eclipse EE ja NetBeans - kuid seda käesolev töö ei vaatle.

==Mõisted==

* '''Kontekst''' (context) - Tomcati mõistes üks konkreetne veebiaplikatsioon
* '''Konteiner''' (container) - veebiserver Tomcat ise
* '''Kontekstikirjeldus''' (context descriptor) - Tomcati-spetsiifiline konteksti konfiguratsioonimääratlus; peremehepõhine osa loetakse failist $CATALINA_HOME/conf/[enginename]/[hostname]/context.xml ja sellele lisatakse kontekstispetsiifilised täpsustused failist $CATALINA_BASE/conf/[enginename]/[hostname]/[webappname].xml; kontekstikirjeldus määrab näiteks nimed ressurssidele, sessioonihalduse parameetrid jmt. (olgu märgitud, et Tomcati varasemates versioonides sisaldusid kontekstikirjeldused põhikonfiguratsioonifailis server.xml)
* '''Dokumendipõhi''' (docBase) - kontekstile vastav kataloog Tomcati "webapps" kataloogis, mis tekib veebiaplikatsiooni serverisse rakendamisel
* '''Veebiarhiiv''' (Web application ARchive, war-file) - Java veebiaplikatsiooni jagatakse hea tava kohaselt selle üheainsa veebiarhiivi failina, mille laienditüübiks on "war". Tegemist on zip-protokolliga kokkupakitud kataloogiga, millel on Java veebirakenduste spetsifikatsioonile vastav ülesehitus. Siiski võib veebiaplikatsioon olla juurutamisel ka lahtipakendatud olekus (inglisekeelne termin on "war is exploded").

==Ülesehitus==

{| class="wikitable"
|+Kataloogid
|-
|style="color: green;" | $CATALINA_HOME
|baaskataloog, kuhu on Tomcat paigutatud
|-
|style="color: green;" | $CATALINA_BASE
|parasjagu töösoleva Tomcati eksemplari baaskataloog, mille alusel lahendatakse teed ülejäänud kataloogide ja failideni; ainult ühe kasutusel oleva Tomcati eksemplari puhul on see sama, mis $CATALINA_HOME

|-
|style="color: green;" | $CATALINA_BASE/bin
|serveri käivitus- ja abiskriptid
|-
|style="color: green;" | $CATALINA_BASE/conf
|konfiguratsioonifailid
|-
|style="color: green;" | $CATALINA_BASE/lib
|Tomcatile vaikimisi kättesaadavad Java klassiteegid (class libraries) ehk .jar-failid kuhu on Java kompileeritud kood kokku pakendatud
|-
|style="color: green;" | $CATALINA_BASE/logs
|logifailid paigutatakse vaikimisi siia
|-
|style="color: green;" | $CATALINA_BASE/webapps
|kataloog, kuhu paigutatakse serverisse juurutatavad veebiaplikatsioonid

|}

{| class="wikitable"
|+Mõned olulisemad failid
|-
|style="color: green;" | $CATALINA_BASE/bin/startup.sh
|serveri käivitusskript
|-
|style="color: green;" | $CATALINA_BASE/bin/shutdown.sh
|serveri peatusskript

|-
|style="color: green;" | $CATALINA_BASE/conf/server.xml
| konteineri peamine konfiguratsioonifail
|-
|style="color: green;" | $CATALINA_BASE/conf/[enginename]/[hostname]/[webappname].xml
|serveri administraatori jaoks konteinerisse endasse ümber kopeeritud rakendusepõhine kontekstikirjelduse konfiguratsioon failist $CATALINA_BASE/webapps/[ApplicationName]/META-INF/context.xml
|-
|style="color: green;" | $CATALINA_BASE/conf/[enginename]/[hostname]/context.xml
| fail, mis aitab administraatoril konteksti kohta käivat infot kirjeldada peremeesmasina-põhiselt ja halduseks mõeldud automaat-tööriistadel (näiteks Tomcat Manager ja TCD) oma tööd teha
|-
|style="color: green;" | $CATALINA_BASE/$CATALINA_BASE/conf/[enginename]/[hostname]/manager.xml
|fail, mis võimaldab lisada rakendustele ligipääsufiltreid
|-
|style="color: green;" | $CATALINA_BASE/webapps/[webappname]/META-INF/context.xml
|kontekstikirjeldusfail, mille veebirakenduse programmeerija on pakendanud oma aplikatsiooniga kaasa ning millega ta saab võimaluse kontekstikirjeldust omalt poolt mõjutada; kirjutatakse rakenduse uuestijuurutamisel üle, mistõttu administraator peaks muutma selle asemel konteinerisse ümber kopeeritud püsieksemplari $CATALINA_BASE/conf/[enginename]/[hostname]/context.xml
|-
|style="color: green;" | $CATALINA_BASE/webapps/[webappname]/WEB-INF/web.xml
|ka üks oluline Java veebiaplikatsiooni konfiguratsioonifail, mille pakendatakse koos veebiarhiiviga; enamasti muudab seda ainult programeerija; määrab muu hulgas millised aplikatsiooni osad vajavad autentimist või kui kiiresti veebisessioon aegub
|}

==Installeerimine==

===Installeerimine paketihalduriga===

<pre>
apt-cache search tomcat
apt-get install tomcat[version]-webapps
apt-get install tomcat[version]-admin
apt-get install tomcat[version]
</pre>

===Installeerimine käsitsi===

Paketihalduriga installeerides ei pruugi viimane Tomcati versioon olla kättesaadav ja see pakub ka vähem võimalusi kataloogide määramiseks jms. Käsitsi installeerimiseks tuleb laadida Tomcat kodulehelt alla. Lahtipakkimisel tekib kataloog, milles sisalduv fail "RUNNING.txt" on kõige kindlam allikas installeerimisel tekkivate probleemide vältimiseks ning lahendamiseks.

Vajaliku versiooni installeerimisfaili asukoha saab vaadata Tomcati kodulehelt sektsioonist "Download". Järgnevas näites installeerime Tomcati kõige uuema ebastabiilse kandidaatversiooni, mida näitab nimes sisalduv RC ehk "release candidate". Produktsioonikeskkonda tuleks siiski valida stabiilse versiooni. Käsitsi installeerimine on sarnane järgmisega:
<pre>
wget http://mirror.nexcess.net/apache/tomcat/tomcat-8/v8.0.0-RC5/bin/apache-tomcat-8.0.0-RC5.tar.gz
tar -zxvf apache-tomcat-8.0.0-RC5.tar.gz
mv /Users/kristjanveskimae/downloads/apache-tomcat-8.0.0-RC5 /usr/local/apache-tomcat-8.0.0-RC5
rm -f /Library/Tomcat
ln -s /usr/local/apache-tomcat-8.0.0-RC5/ /Library/Tomcat
chown -R kristjanveskimae /Library/Tomcat
chmod +x /Library/Tomcat/bin/*.sh
</pre>

==Käivitamine ja aplikatsiooni juurutamine==

===Konteineri käivitamine===

Tomcati käivitamise eelduseks on Java paigaldamine masinasse ning keskkonnamuutujate "JAVA_HOME" ja "JRE_HOME" defineerimine. Peale installeerimist võib kasutada skripte kataloogist $CATALINA_BASE/bin . Järgneb üks võimalik käivitamise ja peatamise näide, mis on kasutatav eelnevalt kirjeldatud käsitsi installeerimise juhul:
<pre>
/Library/Tomcat/bin/startup.sh
</pre>
ja peatamiseks
<pre>
/Library/Tomcat/bin/shutdown.sh
</pre>

===Näiteaplikatsiooni juurutamine===

Java veebiaplikatsiooni jagatakse hea tava kohaselt üheainsa veebiarhiivi failina. Siiski võib Tomcati juurutada ka lahtipakendatud olekus ("exploded") Java veebiaplikatsiooni.

====Käsitsi juurutamine ja mahavõtmine====

Näiteaplikatsiooni juurutamiseks lae selle veebiarhiivifail alla ning kopeeri oma konteineri juurutamiskataloogi 'webapps':
<pre>wget http://tomcat.apache.org/tomcat-8.0-doc/appdev/sample/sample.war
cp /Users/kristjanveskimae/downloads/sample.war /Library/Tomcat/webapps/sample.war</pre>

[[File:sample_app.png|400px|thumb|right|Pilt 1: Õnnestunult rakendatud näiteaplikatsioon]]

Kui konfiguratsioonifailis $CATALINA_BASE/conf/server.xml on märgendi "Host" atribuudi "autoDeploy" väärtus "true", installeerib ja uuendab Tomcat aplikatsioone dünaamiliselt töötamise ajal. Kui väärtuseks on "false", käib installeerimine staatiliselt ning serverisse juurutamiseks tuleb teha konteineri taaskäivitus. [http://tomcat.apache.org/tomcat-8.0-doc/manager-howto.html#Deploy_A_New_Application_from_a_Local_Path 1] Mõlemal juhul pakib konteiner arhiveeritud faili ise lahti samasse kausta $CATALINA_BASE/webapps ning ka juurutab selle. Tekkiv aplikatsioon on lokaalsest masinast seejärel kättesaadav aadressil http://localhost:8080/sample/ . Kui rakendamine õnnestub, siis peaks olema brauserist nähtav sarnane lehekülg nagu pildil 1.

Veebirakenduse käsitsi mahavõtmiseks tuleb kustutada talle vastav dokumendipõhja kataloog "webapps" kataloogist. Samuti tuleks kustutada .war-fail olemaks kindel, et Tomcat ei rakenda uuel käivitamisel veebiaplikatsiooni veebiarhiivifailist. Veelgi lihtsam on mahavõtmine brauseriga haldusrakenduse kaudu.

Rakenduste baaskataloogi "webapps" asukohta saab muuta failis $CATALINA_BASE/conf/server.xml peremehepõhiselt määratava atribuudiga "appBase", sealjuures Tomcati vaikimisi peremees ehk "Host" on "localhost".

====Tomcati vahendid juurutamiseks====

Veebiaplikatsioonide juurutamine ja mahajuurutamine on võimalik ka kaughalduse teel tänu Tomcati internetipõhisele haldusrakendusele. Näiteks saab veebibrauserit kasutades teha serveri põhitoiminguid Tomcati enda HTML-põhise rakendusega "Tomcat Manager". Veebipõhine haldusrakendus töötab ka käsupõhise veebiteenusena, millele on valmis ehitatud Anti ja Maveni integratsioonid. Samuti eksisteerib käsurea kliendirakendus TCD (Tomcat Client Deployer). TCD ei kuulu Tomcati baaskoosseisu, kuid pakub peale serveri administreerimise tavatoimingute ka lisafunktsionaalsust nagu veebirakenduse kokkukompileerimine ja pakendamine. [http://tomcat.apache.org/tomcat-8.0-doc/manager-howto.html#Configuring_Manager_Application_Access 1]

====Haldurakendus "Tomcat Manager"====

Tomcati haldusrakendus "Tomcat Manager" (antud alamjaotuses lihtsalt haldusrakendus) on Tomcati enda veebiaplikatioon Tomcati brauseripõhiseks kaughalduseks, võimaldades muu hulgas järgnevat [http://tomcat.apache.org/tomcat-8.0-doc/manager-howto.html#Introduction 1]:
* Rakendada uue veebiaplikatsiooni war-faili üleslaadimisega;
* Näha kõiki rakendatud veebiaplikatsioone koos aktiivsete sessioonidega;
* Taasrakendada veebirakendust, näiteks veebiarhiivi pakitud klassifailide /WEB-INF/classes või teekide /WEB-INF/lib uuendamisel, kinnijooksmisel jms.;
* Peatada veebirakendust ilma serverist eemaldamata, samuti koos serverist eemaldamisega;
* Vaadata operatsioonisüsteemi ja Java parameetrite väärtusi;
* Näha kõiki saadaolevaid JNDI ressursse, k.a. andmebaasiühendusi, mis aitavad rakenduste programmeerijail defineerida <ResourceLink> elemendid web.xml konfiguratsioonifailis.

Tomcati installatsioon sisaldab haldusrakendust juba vaikimisi. Haldusrakenduse töölepanemiseks tuleb peremeesmasina konfiguratsioonikataloogi $CATALINA_BASE/conf/[enginename]/[hostname] lisada ka fail manager.xml. Vaikimisi valmiskonfigureeritud testrakendusel on see fail juba olemas asukohas $CATALINA_BASE/conf/Catalina/localhost/manager.xml . Rakendus asub vaikimisi aadressil http://[host]/manager/ , vaikimisi konfiguratsioone kasutades lahendub see asukohaks http://localhost:8080/manager/ . [http://tomcat.apache.org/tomcat-8.0-doc/manager-howto.html#Configuring_Manager_Application_Access 1]

====="Tomcat Manager" ligipääsu konfigureerimine=====

Vaikimisi on turvalisuspõhjustel ligipääs haldusrakendusele maha keeratud. Mismoodi täpselt kasutajatel ligipääsu võimaldada sõltub kasutatavast valdusest (realm). Vaikimisi defineerib $CATALINA_BASE/conf/server.xml valduseks "MemoryRealm". Vaikimisi loeb valdus "MemoryRealm" kasutajad failist $CATALINA_BASE/conf/tomcat-users.xml. Antud failis tuleb iga kasutaja defineerida omaette märgendiga <user>, mis näeb välja umbes järgmine [http://tomcat.apache.org/tomcat-8.0-doc/manager-howto.html#Configuring_Manager_Application_Access 1]:
<pre>
<user name="craig" password="secret" roles="manager-gui,manager-script" />
</pre>

Antud kasutajale on defineeritud korraga kaks rolli. Ligipääsu võimaldamiseks tulebki lihtsamal juhul kasutajatefailis $CATALINA_BASE/conf/tomcat-users.xml defineerida enda kasutaja. Kasutaja rolliks võib määrata näiteks "manager-gui", mis võimaldab ligipääsu kogu HTML liidese funktsionaalsusele.

Teised valdused on "JDBCRealm", mille puhul hoitakse kasutajatega seonduvat infot andmebaasis ja JNDIRealm, mille puhul kasutatakse lihtsustatud kataloogisirvimise protokolli (LDAP).
Lisaks saab haldusrakendusele keelata ligipääsu mujalt kui kindlaksmääratud IP-aadressidelt, lisades filtri "RemoteAddrValve" või "RemoteHostValve" konfigureerimisfaili manager.xml näiteks järgmiselt [http://tomcat.apache.org/tomcat-8.0-doc/manager-howto.html#Introduction 1]:
<pre>
<Context privileged="true">
<Valve className="org.apache.catalina.valves.RemoteAddrValve"
allow="127\.0\.0\.1"/>
</Context>
</pre>

=====Juurutamine ja mahavõtmine haldusrakendusega "Tomcat Manager"=====

Juurutamiseks lae kõigepealt veebiarhiivifail üles, kasutades esilehel asuvat sektsiooni "WAR file to deploy".

[[File:tomcat_manager_war_upload.png|800px|thumb|right|Pilt 2: Veebiarhiivi üleslaadimise nupp]]

Rakendus kuvatakse seejärel hallatavate rakenduste nimekirjas. Kui konteiner pole seadistatud üleslaetud aplikatsiooni kohe ka ise rakendama, tuleb vajutada "Start". Rakenduse peatamiseks kasuta "Stop", uuesti rakendamiseks "Redeploy" ja serverist eemaldamiseks "Undeploy".


[[File:tomcat_manager_apps_list.png|800px|thumb|frame|Pilt 3: Rakenduste nimekiri]]

==Näpunäiteid Tomcati reaalseks kasutamiseks==

===Juurutamise järjekord===

Tomcati käivitumisel juurutatakse aplikatsioonid sellises järjekorras [http://www.mulesoft.com/tomcat-deploy-procedures 2]:
# Konteinerisse kopeeritud kontekstikirjelduste järgi $CATALINA_BASE/conf/[EngineName]/[HostName]/[ApplicationName].xml ;
# Lahtipakitud rakendused "webapps" kataloogis;
# Pakitud rakenduste veebiarhiivid "webapps" kataloogis.

Seetõttu peaks käsitsi taasjuurutamisel kindluse mõttes eelnevalt kustutama rakenduse lahtipakitud dokumendipõhja kataloogi "webapps" kataloogist. Kontekstikirjelduse muutumisel tuleb jälgida, kas kirjeldus on juba kopeeritud serverisse ning vajadusel eelmise versiooni ümber muuta või kustutada.

===Reaalsele domeenile konfigureerimine===

Järgnevalt eeldame, et domeen ''www.minukodukas.ee'' on juba serverimasinaga seostatud. Et Tomcat hakkaks ka reaalselt Internetist tulevatele päringutele vastama, tuleb muuta failis $CATALINA_BASE/conf/server.xml konteinerile ''Catalina'' vastava teenusemärgendi sisu sarnaselt järgnevaga:

<pre>
<Service name="Catalina">
<Connector port="80" protocol="HTTP/1.1" connectionTimeout="20000" URIEncoding="UTF-8" redirectPort="8443" />
<Engine name="Catalina" defaultHost="www.minukodukas.ee">
<Host name="www.minukodukas.ee" appBase="webapps" unpackWARs="true" autoDeploy="false" deployOnStartup="false" xmlValidation="false" xmlNamespaceAware="false">
<Context path="" docBase="kodukas" debug="0" reloadable="true" />
</Host>
</Engine>
</Service>
</pre>

Ülal defineerime põhiliselt selle, et Tomcat kuulaks domeeni ''www.minukodukas.ee'' ja kasutaks HTTP päringute jaoks porti 80. Ühtlasti otsib Tomcat juurutatavat rakendust failist $CATALINA_BASE/webapps/kodukas.war. Kuna rajalisandiks on määratud tühi sõne (path=""), siis juurutataksegi aplikatsioon aadressile ''www.minukodukas.ee'' ilma rajalisandita (a'la ''www.minukodukas.ee/wiki''). Seetõttu pakitakse ka veebiarhiiv tegelikult lahti kataloogi $CATALINA_BASE/webapps/ROOT mitte kataloogi $CATALINA_BASE/webapps/kodukas nagu võiks eeldada.

===Käigultvahetus===

Võimaldamaks käigultvahetust (hot deployment) peab konteineri konfiguratsioonifailis $CATALINA_BASE/conf/server.xml olema peremehepõhise märgendi "Host" atribuudi "autoDeploy" väärtus "true". Sel juhul installeerib ja uuendab Tomcat aplikatsioone dünaamiliselt töötamise ajal. Kui väärtuseks on "false", käib installeerimine staatiliselt ning serverisse juurutamiseks tuleb teha konteineri taaskäivitus. Käigultvahetust saab määrata ka peremehe defineerimisel "Host Manager" rakendusega, mis on kättesaadav aadressil http://localhost:8080/host-manager/html . Kasutamiseks tuleb lisada oma kasutajale rolli "admin-gui" (vt. alajaotus ""Tomcat Manager" ligipääsu konfigureerimine").

[[File:host_manager_app.png]]

Käigultvahetust päästikuks on vaikimisi uuendatud veebiarhiivifaili või lahtipakitud veebirakenduse paigutamine "webapps" kataloogi. Käigultvahetuse päästikutele võib failis $CATALINA_BASE/conf/server.xml ka ise lisada kuulatavaid ressursse nagu web.xml muutmine või mõne teegifaili vahetamine (märgendis "Host").

===Klassiteekide väljatõstmine veebiarhiivifailist===

Kõik konteksti poolt kasutatavad Java klassiteegid võib pakendada veebiarhiivi sisse kataloogi "lib", kuid nii võib osutuda veebiarhiivi üleslaadimine ajakulukaks, eriti arenduskeskkonnas. Kui ei teki ohtu, et erinevad rakendused kasutavad sama teegi erinevaid versioone, siis on vahel parem lisada osa teeke konteineri kataloogi $CATALINA_BASE/libs, kust need tehakse siis konteineri poolt kättesaadavaks kõigile konteineris jooksutatavatele kontekstidele. Nii võib vähendada veebiarhiivi faili suurust märgatavalt, mis tõstab kokkuvõttes juurutamiskiirust ja ühes sellega programmeerijate tööviljakust.

===Mälukasutus===

Konteineri poolt kasutatavat mälu saab vaadata haldusrakendusest vajutades lingile "Server Status". Mälukasutus on toodud jaotuses "JVM", kus näidatakse nii maksimaalselt kättesaadavat mälu kui ka parasjagu reserveeritud mälu.

<pre>Free memory: 41.16 MB Total memory: 123.37 MB Max memory: 1027.56 MB</pre>

Mälu suurendamiseks võib näiteks defineerida skriptis $CATALINA_BASE/bin/catalina.sh muutuja "JAVA_OPTS" ning määrata Java mälukasutuse miinimum- ja maksimumväärtused sarnaselt järgnevatega [http://www.mkyong.com/tomcat/tomcat-javalangoutofmemoryerror-permgen-space/ 3]:
<pre>
JAVA_OPTS="-Xms1536m -Xmx1536m -XX:NewSize=256m -XX:MaxNewSize=256m -XX:PermSize=256m -XX:MaxPermSize=256m"
</pre>

===Logifailid===

Vaikimisi defineerib Tomcat failiga $CATALINA_BASE/conf/logging.properties viis logerit, mis tekitavad viis eraldi logifaili.

{| style="background:#cccc99;color:black;width:80%;" border="1" cellpadding="5" cellspacing="0" align="center"
|+ Tomcati tekitatavad logifailid "logs" kataloogis
!Fail !! Kasutus
|- style="background:white; color:black"
| style="width:300px" |catalina.out
| Tomcati käivitus- ja peatamisskriptide väljund, samuti juurutatud rakenduste prindilaused System.out ja veaväljundid System.err
|- style="background:white; color:black"
| style="width:300px" |catalina.[yyyy]-[mm]-[dd].log
| Pööratud (rotated) logifail catalina.out
|- style="background:white; color:black"
| style="width:300px" |host-manager.[yyyy]-[mm]-[dd].log
| Logi peremehehalduse rakendusele (rakendus on kättesaadav kohalikust masinast aadressil http://localhost:8080/host-manager/html )
|- style="background:white; color:black"
| style="width:300px" |localhost.[yyyy]-[mm]-[dd].log
| Peremehe "localhost" logi; mitme virtuaalse peremehe korral tekitatakse igale peremehele oma logi
|- style="background:white; color:black"
| style="width:300px" |localhost_access_log.[yyyy]-[mm]-[dd].txt
| Konteinerisse Internetist saabunud päringute logi
|- style="background:white; color:black"
| style="width:300px" |manager.[yyyy]-[mm]-[dd].log
| Haldusrakenduse tegevuste logi
|}

===Viiteid===

Palju vajalikku võib leida [http://tomcat.apache.org/tomcat-8.0-doc/index.html Tomcat 8 dokumentatsioonist]

Lisaks üks viide põhjalikule Tomcati versioon seitsme ülevaatele: http://www.ntu.edu.sg/home/ehchua/programming/howto/Tomcat_More.html

= Kasutatud materjalid =

#http://tomcat.apache.org/tomcat-8.0-doc/index.html
#http://www.mulesoft.com/tomcat-deploy-procedures
#http://www.mkyong.com/tomcat/tomcat-javalangoutofmemoryerror-permgen-space/

[[Category: Operatsioonisüsteemide administreerimine ja sidumine]]

Tomcat

2014-01-02T22:07:07Z

Kveskima: /* Juurutamine ja mahavõtmine haldusrakendusega "Tomcat Manager" */

==Autor==

Kristjan Veskimäe D32

2013

==Sissejuhatus==

Tomcat on vabalt kättesaadav server Java veebirakendustele. Põhimõtteliselt on tegemist Servlet/JSP spetsifikatsiooni toetava konteineriga. Kiire käivitumise ning rakenduste käigultvahetuse tõttu on Tomcat hea valik väiksemate ning keskmise suurusega Java veebirakenduste käitamiseks.

Antud töö kirjeldab Tomcati 8. versiooni. Põhiosa on üldiselt samasugune võrreldes paari eelmise versiooniga. Suuremad erinevused on versioonispetsiifilistes probleemides ja nende lahendamises, mida käesolev töö ei vaatle.

Töö vaatleb Tomcati paigaldamist ja seadistamist Unix-laadsesse keskkonda ning eeldab lugejalt algteadmisi sarnastes süsteemides. Tomcati on võimalik paigaldada ka Windows-keskkonda, kuid antud veebiserver eeldab kasutaja poolt käsureal töötamist ning Tomcati failihierarhias orienteerumist. Põhimõtteliselt on Java veebirakenduste arendamiseks IDE-abil võimalik siiski ka kasutada IDE-sse integreeritud Tomcati serverit - näiteks pakuvad sellist võimalust Eclipse EE ja NetBeans - kuid seda käesolev töö ei vaatle.

==Mõisted==

* '''Kontekst''' (context) - Tomcati mõistes üks konkreetne veebiaplikatsioon
* '''Konteiner''' (container) - veebiserver Tomcat ise
* '''Kontekstikirjeldus''' (context descriptor) - Tomcati-spetsiifiline konteksti konfiguratsioonimääratlus; peremehepõhine osa loetakse failist $CATALINA_HOME/conf/[enginename]/[hostname]/context.xml ja sellele lisatakse kontekstispetsiifilised täpsustused failist $CATALINA_BASE/conf/[enginename]/[hostname]/[webappname].xml; kontekstikirjeldus määrab näiteks nimed ressurssidele, sessioonihalduse parameetrid jmt. (olgu märgitud, et Tomcati varasemates versioonides sisaldusid kontekstikirjeldused põhikonfiguratsioonifailis server.xml)
* '''Dokumendipõhi''' (docBase) - kontekstile vastav kataloog Tomcati "webapps" kataloogis, mis tekib veebiaplikatsiooni serverisse rakendamisel
* '''Veebiarhiiv''' (Web application ARchive, war-file) - Java veebiaplikatsiooni jagatakse hea tava kohaselt selle üheainsa veebiarhiivi failina, mille laienditüübiks on "war". Tegemist on zip-protokolliga kokkupakitud kataloogiga, millel on Java veebirakenduste spetsifikatsioonile vastav ülesehitus. Siiski võib veebiaplikatsioon olla juurutamisel ka lahtipakendatud olekus (inglisekeelne termin on "war is exploded").

==Ülesehitus==

{| class="wikitable"
|+Kataloogid
|-
|style="color: green;" | $CATALINA_HOME
|baaskataloog, kuhu on Tomcat paigutatud
|-
|style="color: green;" | $CATALINA_BASE
|parasjagu töösoleva Tomcati eksemplari baaskataloog, mille alusel lahendatakse teed ülejäänud kataloogide ja failideni; ainult ühe kasutusel oleva Tomcati eksemplari puhul on see sama, mis $CATALINA_HOME

|-
|style="color: green;" | $CATALINA_BASE/bin
|serveri käivitus- ja abiskriptid
|-
|style="color: green;" | $CATALINA_BASE/conf
|konfiguratsioonifailid
|-
|style="color: green;" | $CATALINA_BASE/lib
|Tomcatile vaikimisi kättesaadavad Java klassiteegid (class libraries) ehk .jar-failid kuhu on Java kompileeritud kood kokku pakendatud
|-
|style="color: green;" | $CATALINA_BASE/logs
|logifailid paigutatakse vaikimisi siia
|-
|style="color: green;" | $CATALINA_BASE/webapps
|kataloog, kuhu paigutatakse serverisse juurutatavad veebiaplikatsioonid

|}

{| class="wikitable"
|+Mõned olulisemad failid
|-
|style="color: green;" | $CATALINA_BASE/bin/startup.sh
|serveri käivitusskript
|-
|style="color: green;" | $CATALINA_BASE/bin/shutdown.sh
|serveri peatusskript

|-
|style="color: green;" | $CATALINA_BASE/conf/server.xml
| konteineri peamine konfiguratsioonifail
|-
|style="color: green;" | $CATALINA_BASE/conf/[enginename]/[hostname]/[webappname].xml
|serveri administraatori jaoks konteinerisse endasse ümber kopeeritud rakendusepõhine kontekstikirjelduse konfiguratsioon failist $CATALINA_BASE/webapps/[ApplicationName]/META-INF/context.xml
|-
|style="color: green;" | $CATALINA_BASE/conf/[enginename]/[hostname]/context.xml
| fail, mis aitab administraatoril konteksti kohta käivat infot kirjeldada peremeesmasina-põhiselt ja halduseks mõeldud automaat-tööriistadel (näiteks Tomcat Manager ja TCD) oma tööd teha
|-
|style="color: green;" | $CATALINA_BASE/$CATALINA_BASE/conf/[enginename]/[hostname]/manager.xml
|fail, mis võimaldab lisada rakendustele ligipääsufiltreid
|-
|style="color: green;" | $CATALINA_BASE/webapps/[webappname]/META-INF/context.xml
|kontekstikirjeldusfail, mille veebirakenduse programmeerija on pakendanud oma aplikatsiooniga kaasa ning millega ta saab võimaluse kontekstikirjeldust omalt poolt mõjutada; kirjutatakse rakenduse uuestijuurutamisel üle, mistõttu administraator peaks muutma selle asemel konteinerisse ümber kopeeritud püsieksemplari $CATALINA_BASE/conf/[enginename]/[hostname]/context.xml
|-
|style="color: green;" | $CATALINA_BASE/webapps/[webappname]/WEB-INF/web.xml
|ka üks oluline Java veebiaplikatsiooni konfiguratsioonifail, mille pakendatakse koos veebiarhiiviga; enamasti muudab seda ainult programeerija; määrab muu hulgas millised aplikatsiooni osad vajavad autentimist või kui kiiresti veebisessioon aegub
|}

==Installeerimine==

===Installeerimine paketihalduriga===

<pre>
apt-cache search tomcat
apt-get install tomcat[version]-webapps
apt-get install tomcat[version]-admin
apt-get install tomcat[version]
</pre>

===Installeerimine käsitsi===

Paketihalduriga installeerides ei pruugi viimane Tomcati versioon olla kättesaadav ja see pakub ka vähem võimalusi kataloogide määramiseks jms. Käsitsi installeerimiseks tuleb laadida Tomcat kodulehelt alla. Lahtipakkimisel tekib kataloog, milles sisalduv fail "RUNNING.txt" on kõige kindlam allikas installeerimisel tekkivate probleemide vältimiseks ning lahendamiseks.

Vajaliku versiooni installeerimisfaili asukoha saab vaadata Tomcati kodulehelt sektsioonist "Download". Järgnevas näites installeerime Tomcati kõige uuema ebastabiilse kandidaatversiooni, mida näitab nimes sisalduv RC ehk "release candidate". Produktsioonikeskkonda tuleks siiski valida stabiilse versiooni. Käsitsi installeerimine on sarnane järgmisega:
<pre>
wget http://mirror.nexcess.net/apache/tomcat/tomcat-8/v8.0.0-RC5/bin/apache-tomcat-8.0.0-RC5.tar.gz
tar -zxvf apache-tomcat-8.0.0-RC5.tar.gz
mv /Users/kristjanveskimae/downloads/apache-tomcat-8.0.0-RC5 /usr/local/apache-tomcat-8.0.0-RC5
rm -f /Library/Tomcat
ln -s /usr/local/apache-tomcat-8.0.0-RC5/ /Library/Tomcat
chown -R kristjanveskimae /Library/Tomcat
chmod +x /Library/Tomcat/bin/*.sh
</pre>

==Käivitamine ja aplikatsiooni juurutamine==

===Konteineri käivitamine===

Tomcati käivitamise eelduseks on Java paigaldamine masinasse ning keskkonnamuutujate "JAVA_HOME" ja "JRE_HOME" defineerimine. Peale installeerimist võib kasutada skripte kataloogist $CATALINA_BASE/bin . Järgneb üks võimalik käivitamise ja peatamise näide, mis on kasutatav eelnevalt kirjeldatud käsitsi installeerimise juhul:
<pre>
/Library/Tomcat/bin/startup.sh
</pre>
ja peatamiseks
<pre>
/Library/Tomcat/bin/shutdown.sh
</pre>

===Näiteaplikatsiooni juurutamine===

Java veebiaplikatsiooni jagatakse hea tava kohaselt üheainsa veebiarhiivi failina. Siiski võib Tomcati juurutada ka lahtipakendatud olekus ("exploded") Java veebiaplikatsiooni.

====Käsitsi juurutamine ja mahavõtmine====

Näiteaplikatsiooni juurutamiseks lae selle veebiarhiivifail alla ning kopeeri oma konteineri juurutamiskataloogi 'webapps':
<pre>wget http://tomcat.apache.org/tomcat-8.0-doc/appdev/sample/sample.war
cp /Users/kristjanveskimae/downloads/sample.war /Library/Tomcat/webapps/sample.war</pre>

[[File:sample_app.png|400px|thumb|right|Pilt 1: Õnnestunult rakendatud näiteaplikatsioon]]

Kui konfiguratsioonifailis $CATALINA_BASE/conf/server.xml on märgendi "Host" atribuudi "autoDeploy" väärtus "true", installeerib ja uuendab Tomcat aplikatsioone dünaamiliselt töötamise ajal. Kui väärtuseks on "false", käib installeerimine staatiliselt ning serverisse juurutamiseks tuleb teha konteineri taaskäivitus. [http://tomcat.apache.org/tomcat-8.0-doc/manager-howto.html#Deploy_A_New_Application_from_a_Local_Path 1] Mõlemal juhul pakib konteiner arhiveeritud faili ise lahti samasse kausta $CATALINA_BASE/webapps ning ka juurutab selle. Tekkiv aplikatsioon on lokaalsest masinast seejärel kättesaadav aadressil http://localhost:8080/sample/ . Kui rakendamine õnnestub, siis peaks olema brauserist nähtav sarnane lehekülg nagu pildil 1.

Veebirakenduse käsitsi mahavõtmiseks tuleb kustutada talle vastav dokumendipõhja kataloog "webapps" kataloogist. Samuti tuleks kustutada .war-fail olemaks kindel, et Tomcat ei rakenda uuel käivitamisel veebiaplikatsiooni veebiarhiivifailist. Veelgi lihtsam on mahavõtmine brauseriga haldusrakenduse kaudu.

Rakenduste baaskataloogi "webapps" asukohta saab muuta failis $CATALINA_BASE/conf/server.xml peremehepõhiselt määratava atribuudiga "appBase", sealjuures Tomcati vaikimisi peremees ehk "Host" on "localhost".

====Tomcati vahendid juurutamiseks====

Veebiaplikatsioonide juurutamine ja mahajuurutamine on võimalik ka kaughalduse teel tänu Tomcati internetipõhisele haldusrakendusele. Näiteks saab veebibrauserit kasutades teha serveri põhitoiminguid Tomcati enda HTML-põhise rakendusega "Tomcat Manager". Veebipõhine haldusrakendus töötab ka käsupõhise veebiteenusena, millele on valmis ehitatud Anti ja Maveni integratsioonid. Samuti eksisteerib käsurea kliendirakendus TCD (Tomcat Client Deployer). TCD ei kuulu Tomcati baaskoosseisu, kuid pakub peale serveri administreerimise tavatoimingute ka lisafunktsionaalsust nagu veebirakenduse kokkukompileerimine ja pakendamine. [http://tomcat.apache.org/tomcat-8.0-doc/manager-howto.html#Configuring_Manager_Application_Access 1]

====Haldurakendus "Tomcat Manager"====

Tomcati haldusrakendus "Tomcat Manager" (antud alamjaotuses lihtsalt haldusrakendus) on Tomcati enda veebiaplikatioon Tomcati brauseripõhiseks kaughalduseks, võimaldades muu hulgas järgnevat [http://tomcat.apache.org/tomcat-8.0-doc/manager-howto.html#Introduction 1]:
* Rakendada uue veebiaplikatsiooni war-faili üleslaadimisega;
* Näha kõiki rakendatud veebiaplikatsioone koos aktiivsete sessioonidega;
* Taasrakendada veebirakendust, näiteks veebiarhiivi pakitud klassifailide /WEB-INF/classes või teekide /WEB-INF/lib uuendamisel, kinnijooksmisel jms.;
* Peatada veebirakendust ilma serverist eemaldamata, samuti koos serverist eemaldamisega;
* Vaadata operatsioonisüsteemi ja Java parameetrite väärtusi;
* Näha kõiki saadaolevaid JNDI ressursse, k.a. andmebaasiühendusi, mis aitavad rakenduste programmeerijail defineerida <ResourceLink> elemendid web.xml konfiguratsioonifailis.

Tomcati installatsioon sisaldab haldusrakendust juba vaikimisi. Haldusrakenduse töölepanemiseks tuleb peremeesmasina konfiguratsioonikataloogi $CATALINA_BASE/conf/[enginename]/[hostname] lisada ka fail manager.xml. Vaikimisi valmiskonfigureeritud testrakendusel on see fail juba olemas asukohas $CATALINA_BASE/conf/Catalina/localhost/manager.xml . Rakendus asub vaikimisi aadressil http://[host]/manager/ , vaikimisi konfiguratsioone kasutades lahendub see asukohaks http://localhost:8080/manager/ . [http://tomcat.apache.org/tomcat-8.0-doc/manager-howto.html#Configuring_Manager_Application_Access 1]

====="Tomcat Manager" ligipääsu konfigureerimine=====

Vaikimisi on turvalisuspõhjustel ligipääs haldusrakendusele maha keeratud. Mismoodi täpselt kasutajatel ligipääsu võimaldada sõltub kasutatavast valdusest (realm). Vaikimisi defineerib $CATALINA_BASE/conf/server.xml valduseks "MemoryRealm". Vaikimisi loeb valdus "MemoryRealm" kasutajad failist $CATALINA_BASE/conf/tomcat-users.xml. Antud failis tuleb iga kasutaja defineerida omaette märgendiga <user>, mis näeb välja umbes järgmine [http://tomcat.apache.org/tomcat-8.0-doc/manager-howto.html#Configuring_Manager_Application_Access 1]:
<pre>
<user name="craig" password="secret" roles="manager-gui,manager-script" />
</pre>

Antud kasutajale on defineeritud korraga kaks rolli. Ligipääsu võimaldamiseks tulebki lihtsamal juhul kasutajatefailis $CATALINA_BASE/conf/tomcat-users.xml defineerida enda kasutaja. Kasutaja rolliks võib määrata näiteks "manager-gui", mis võimaldab ligipääsu kogu HTML liidese funktsionaalsusele.

Teised valdused on "JDBCRealm", mille puhul hoitakse kasutajatega seonduvat infot andmebaasis ja JNDIRealm, mille puhul kasutatakse lihtsustatud kataloogisirvimise protokolli (LDAP).
Lisaks saab haldusrakendusele keelata ligipääsu mujalt kui kindlaksmääratud IP-aadressidelt, lisades filtri "RemoteAddrValve" või "RemoteHostValve" konfigureerimisfaili manager.xml näiteks järgmiselt [http://tomcat.apache.org/tomcat-8.0-doc/manager-howto.html#Introduction 1]:
<pre>
<Context privileged="true">
<Valve className="org.apache.catalina.valves.RemoteAddrValve"
allow="127\.0\.0\.1"/>
</Context>
</pre>

=====Juurutamine ja mahavõtmine haldusrakendusega "Tomcat Manager"=====

Juurutamiseks lae kõigepealt veebiarhiivifail üles, kasutades esilehel asuvat sektsiooni "WAR file to deploy".

[[File:tomcat_manager_war_upload.png|800px|thumb|right|Pilt 2: Veebiarhiivi üleslaadimise nupp]]

Rakendus kuvatakse seejärel hallatavate rakenduste nimekirjas. Kui konteiner pole seadistatud üleslaetud aplikatsiooni kohe ka ise rakendama, tuleb vajutada "Start". Rakenduse peatamiseks kasuta "Stop", uuesti rakendamiseks "Redeploy" ja serverist eemaldamiseks "Undeploy".


[[File:tomcat_manager_apps_list.png|800px|thumb|border|Pilt 3: Rakenduste nimekiri]]

==Näpunäiteid Tomcati reaalseks kasutamiseks==

===Juurutamise järjekord===

Tomcati käivitumisel juurutatakse aplikatsioonid sellises järjekorras [http://www.mulesoft.com/tomcat-deploy-procedures 2]:
# Konteinerisse kopeeritud kontekstikirjelduste järgi $CATALINA_BASE/conf/[EngineName]/[HostName]/[ApplicationName].xml ;
# Lahtipakitud rakendused "webapps" kataloogis;
# Pakitud rakenduste veebiarhiivid "webapps" kataloogis.

Seetõttu peaks käsitsi taasjuurutamisel kindluse mõttes eelnevalt kustutama rakenduse lahtipakitud dokumendipõhja kataloogi "webapps" kataloogist. Kontekstikirjelduse muutumisel tuleb jälgida, kas kirjeldus on juba kopeeritud serverisse ning vajadusel eelmise versiooni ümber muuta või kustutada.

===Reaalsele domeenile konfigureerimine===

Järgnevalt eeldame, et domeen ''www.minukodukas.ee'' on juba serverimasinaga seostatud. Et Tomcat hakkaks ka reaalselt Internetist tulevatele päringutele vastama, tuleb muuta failis $CATALINA_BASE/conf/server.xml konteinerile ''Catalina'' vastava teenusemärgendi sisu sarnaselt järgnevaga:

<pre>
<Service name="Catalina">
<Connector port="80" protocol="HTTP/1.1" connectionTimeout="20000" URIEncoding="UTF-8" redirectPort="8443" />
<Engine name="Catalina" defaultHost="www.minukodukas.ee">
<Host name="www.minukodukas.ee" appBase="webapps" unpackWARs="true" autoDeploy="false" deployOnStartup="false" xmlValidation="false" xmlNamespaceAware="false">
<Context path="" docBase="kodukas" debug="0" reloadable="true" />
</Host>
</Engine>
</Service>
</pre>

Ülal defineerime põhiliselt selle, et Tomcat kuulaks domeeni ''www.minukodukas.ee'' ja kasutaks HTTP päringute jaoks porti 80. Ühtlasti otsib Tomcat juurutatavat rakendust failist $CATALINA_BASE/webapps/kodukas.war. Kuna rajalisandiks on määratud tühi sõne (path=""), siis juurutataksegi aplikatsioon aadressile ''www.minukodukas.ee'' ilma rajalisandita (a'la ''www.minukodukas.ee/wiki''). Seetõttu pakitakse ka veebiarhiiv tegelikult lahti kataloogi $CATALINA_BASE/webapps/ROOT mitte kataloogi $CATALINA_BASE/webapps/kodukas nagu võiks eeldada.

===Käigultvahetus===

Võimaldamaks käigultvahetust (hot deployment) peab konteineri konfiguratsioonifailis $CATALINA_BASE/conf/server.xml olema peremehepõhise märgendi "Host" atribuudi "autoDeploy" väärtus "true". Sel juhul installeerib ja uuendab Tomcat aplikatsioone dünaamiliselt töötamise ajal. Kui väärtuseks on "false", käib installeerimine staatiliselt ning serverisse juurutamiseks tuleb teha konteineri taaskäivitus. Käigultvahetust saab määrata ka peremehe defineerimisel "Host Manager" rakendusega, mis on kättesaadav aadressil http://localhost:8080/host-manager/html . Kasutamiseks tuleb lisada oma kasutajale rolli "admin-gui" (vt. alajaotus ""Tomcat Manager" ligipääsu konfigureerimine").

[[File:host_manager_app.png]]

Käigultvahetust päästikuks on vaikimisi uuendatud veebiarhiivifaili või lahtipakitud veebirakenduse paigutamine "webapps" kataloogi. Käigultvahetuse päästikutele võib failis $CATALINA_BASE/conf/server.xml ka ise lisada kuulatavaid ressursse nagu web.xml muutmine või mõne teegifaili vahetamine (märgendis "Host").

===Klassiteekide väljatõstmine veebiarhiivifailist===

Kõik konteksti poolt kasutatavad Java klassiteegid võib pakendada veebiarhiivi sisse kataloogi "lib", kuid nii võib osutuda veebiarhiivi üleslaadimine ajakulukaks, eriti arenduskeskkonnas. Kui ei teki ohtu, et erinevad rakendused kasutavad sama teegi erinevaid versioone, siis on vahel parem lisada osa teeke konteineri kataloogi $CATALINA_BASE/libs, kust need tehakse siis konteineri poolt kättesaadavaks kõigile konteineris jooksutatavatele kontekstidele. Nii võib vähendada veebiarhiivi faili suurust märgatavalt, mis tõstab kokkuvõttes juurutamiskiirust ja ühes sellega programmeerijate tööviljakust.

===Mälukasutus===

Konteineri poolt kasutatavat mälu saab vaadata haldusrakendusest vajutades lingile "Server Status". Mälukasutus on toodud jaotuses "JVM", kus näidatakse nii maksimaalselt kättesaadavat mälu kui ka parasjagu reserveeritud mälu.

<pre>Free memory: 41.16 MB Total memory: 123.37 MB Max memory: 1027.56 MB</pre>

Mälu suurendamiseks võib näiteks defineerida skriptis $CATALINA_BASE/bin/catalina.sh muutuja "JAVA_OPTS" ning määrata Java mälukasutuse miinimum- ja maksimumväärtused sarnaselt järgnevatega [http://www.mkyong.com/tomcat/tomcat-javalangoutofmemoryerror-permgen-space/ 3]:
<pre>
JAVA_OPTS="-Xms1536m -Xmx1536m -XX:NewSize=256m -XX:MaxNewSize=256m -XX:PermSize=256m -XX:MaxPermSize=256m"
</pre>

===Logifailid===

Vaikimisi defineerib Tomcat failiga $CATALINA_BASE/conf/logging.properties viis logerit, mis tekitavad viis eraldi logifaili.

{| style="background:#cccc99;color:black;width:80%;" border="1" cellpadding="5" cellspacing="0" align="center"
|+ Tomcati tekitatavad logifailid "logs" kataloogis
!Fail !! Kasutus
|- style="background:white; color:black"
| style="width:300px" |catalina.out
| Tomcati käivitus- ja peatamisskriptide väljund, samuti juurutatud rakenduste prindilaused System.out ja veaväljundid System.err
|- style="background:white; color:black"
| style="width:300px" |catalina.[yyyy]-[mm]-[dd].log
| Pööratud (rotated) logifail catalina.out
|- style="background:white; color:black"
| style="width:300px" |host-manager.[yyyy]-[mm]-[dd].log
| Logi peremehehalduse rakendusele (rakendus on kättesaadav kohalikust masinast aadressil http://localhost:8080/host-manager/html )
|- style="background:white; color:black"
| style="width:300px" |localhost.[yyyy]-[mm]-[dd].log
| Peremehe "localhost" logi; mitme virtuaalse peremehe korral tekitatakse igale peremehele oma logi
|- style="background:white; color:black"
| style="width:300px" |localhost_access_log.[yyyy]-[mm]-[dd].txt
| Konteinerisse Internetist saabunud päringute logi
|- style="background:white; color:black"
| style="width:300px" |manager.[yyyy]-[mm]-[dd].log
| Haldusrakenduse tegevuste logi
|}

===Viiteid===

Palju vajalikku võib leida [http://tomcat.apache.org/tomcat-8.0-doc/index.html Tomcat 8 dokumentatsioonist]

Lisaks üks viide põhjalikule Tomcati versioon seitsme ülevaatele: http://www.ntu.edu.sg/home/ehchua/programming/howto/Tomcat_More.html

= Kasutatud materjalid =

#http://tomcat.apache.org/tomcat-8.0-doc/index.html
#http://www.mulesoft.com/tomcat-deploy-procedures
#http://www.mkyong.com/tomcat/tomcat-javalangoutofmemoryerror-permgen-space/

[[Category: Operatsioonisüsteemide administreerimine ja sidumine]]

Tomcat

2014-01-02T22:04:33Z

Kveskima: /* Juurutamine ja mahavõtmine haldusrakendusega "Tomcat Manager" */

==Autor==

Kristjan Veskimäe D32

2013

==Sissejuhatus==

Tomcat on vabalt kättesaadav server Java veebirakendustele. Põhimõtteliselt on tegemist Servlet/JSP spetsifikatsiooni toetava konteineriga. Kiire käivitumise ning rakenduste käigultvahetuse tõttu on Tomcat hea valik väiksemate ning keskmise suurusega Java veebirakenduste käitamiseks.

Antud töö kirjeldab Tomcati 8. versiooni. Põhiosa on üldiselt samasugune võrreldes paari eelmise versiooniga. Suuremad erinevused on versioonispetsiifilistes probleemides ja nende lahendamises, mida käesolev töö ei vaatle.

Töö vaatleb Tomcati paigaldamist ja seadistamist Unix-laadsesse keskkonda ning eeldab lugejalt algteadmisi sarnastes süsteemides. Tomcati on võimalik paigaldada ka Windows-keskkonda, kuid antud veebiserver eeldab kasutaja poolt käsureal töötamist ning Tomcati failihierarhias orienteerumist. Põhimõtteliselt on Java veebirakenduste arendamiseks IDE-abil võimalik siiski ka kasutada IDE-sse integreeritud Tomcati serverit - näiteks pakuvad sellist võimalust Eclipse EE ja NetBeans - kuid seda käesolev töö ei vaatle.

==Mõisted==

* '''Kontekst''' (context) - Tomcati mõistes üks konkreetne veebiaplikatsioon
* '''Konteiner''' (container) - veebiserver Tomcat ise
* '''Kontekstikirjeldus''' (context descriptor) - Tomcati-spetsiifiline konteksti konfiguratsioonimääratlus; peremehepõhine osa loetakse failist $CATALINA_HOME/conf/[enginename]/[hostname]/context.xml ja sellele lisatakse kontekstispetsiifilised täpsustused failist $CATALINA_BASE/conf/[enginename]/[hostname]/[webappname].xml; kontekstikirjeldus määrab näiteks nimed ressurssidele, sessioonihalduse parameetrid jmt. (olgu märgitud, et Tomcati varasemates versioonides sisaldusid kontekstikirjeldused põhikonfiguratsioonifailis server.xml)
* '''Dokumendipõhi''' (docBase) - kontekstile vastav kataloog Tomcati "webapps" kataloogis, mis tekib veebiaplikatsiooni serverisse rakendamisel
* '''Veebiarhiiv''' (Web application ARchive, war-file) - Java veebiaplikatsiooni jagatakse hea tava kohaselt selle üheainsa veebiarhiivi failina, mille laienditüübiks on "war". Tegemist on zip-protokolliga kokkupakitud kataloogiga, millel on Java veebirakenduste spetsifikatsioonile vastav ülesehitus. Siiski võib veebiaplikatsioon olla juurutamisel ka lahtipakendatud olekus (inglisekeelne termin on "war is exploded").

==Ülesehitus==

{| class="wikitable"
|+Kataloogid
|-
|style="color: green;" | $CATALINA_HOME
|baaskataloog, kuhu on Tomcat paigutatud
|-
|style="color: green;" | $CATALINA_BASE
|parasjagu töösoleva Tomcati eksemplari baaskataloog, mille alusel lahendatakse teed ülejäänud kataloogide ja failideni; ainult ühe kasutusel oleva Tomcati eksemplari puhul on see sama, mis $CATALINA_HOME

|-
|style="color: green;" | $CATALINA_BASE/bin
|serveri käivitus- ja abiskriptid
|-
|style="color: green;" | $CATALINA_BASE/conf
|konfiguratsioonifailid
|-
|style="color: green;" | $CATALINA_BASE/lib
|Tomcatile vaikimisi kättesaadavad Java klassiteegid (class libraries) ehk .jar-failid kuhu on Java kompileeritud kood kokku pakendatud
|-
|style="color: green;" | $CATALINA_BASE/logs
|logifailid paigutatakse vaikimisi siia
|-
|style="color: green;" | $CATALINA_BASE/webapps
|kataloog, kuhu paigutatakse serverisse juurutatavad veebiaplikatsioonid

|}

{| class="wikitable"
|+Mõned olulisemad failid
|-
|style="color: green;" | $CATALINA_BASE/bin/startup.sh
|serveri käivitusskript
|-
|style="color: green;" | $CATALINA_BASE/bin/shutdown.sh
|serveri peatusskript

|-
|style="color: green;" | $CATALINA_BASE/conf/server.xml
| konteineri peamine konfiguratsioonifail
|-
|style="color: green;" | $CATALINA_BASE/conf/[enginename]/[hostname]/[webappname].xml
|serveri administraatori jaoks konteinerisse endasse ümber kopeeritud rakendusepõhine kontekstikirjelduse konfiguratsioon failist $CATALINA_BASE/webapps/[ApplicationName]/META-INF/context.xml
|-
|style="color: green;" | $CATALINA_BASE/conf/[enginename]/[hostname]/context.xml
| fail, mis aitab administraatoril konteksti kohta käivat infot kirjeldada peremeesmasina-põhiselt ja halduseks mõeldud automaat-tööriistadel (näiteks Tomcat Manager ja TCD) oma tööd teha
|-
|style="color: green;" | $CATALINA_BASE/$CATALINA_BASE/conf/[enginename]/[hostname]/manager.xml
|fail, mis võimaldab lisada rakendustele ligipääsufiltreid
|-
|style="color: green;" | $CATALINA_BASE/webapps/[webappname]/META-INF/context.xml
|kontekstikirjeldusfail, mille veebirakenduse programmeerija on pakendanud oma aplikatsiooniga kaasa ning millega ta saab võimaluse kontekstikirjeldust omalt poolt mõjutada; kirjutatakse rakenduse uuestijuurutamisel üle, mistõttu administraator peaks muutma selle asemel konteinerisse ümber kopeeritud püsieksemplari $CATALINA_BASE/conf/[enginename]/[hostname]/context.xml
|-
|style="color: green;" | $CATALINA_BASE/webapps/[webappname]/WEB-INF/web.xml
|ka üks oluline Java veebiaplikatsiooni konfiguratsioonifail, mille pakendatakse koos veebiarhiiviga; enamasti muudab seda ainult programeerija; määrab muu hulgas millised aplikatsiooni osad vajavad autentimist või kui kiiresti veebisessioon aegub
|}

==Installeerimine==

===Installeerimine paketihalduriga===

<pre>
apt-cache search tomcat
apt-get install tomcat[version]-webapps
apt-get install tomcat[version]-admin
apt-get install tomcat[version]
</pre>

===Installeerimine käsitsi===

Paketihalduriga installeerides ei pruugi viimane Tomcati versioon olla kättesaadav ja see pakub ka vähem võimalusi kataloogide määramiseks jms. Käsitsi installeerimiseks tuleb laadida Tomcat kodulehelt alla. Lahtipakkimisel tekib kataloog, milles sisalduv fail "RUNNING.txt" on kõige kindlam allikas installeerimisel tekkivate probleemide vältimiseks ning lahendamiseks.

Vajaliku versiooni installeerimisfaili asukoha saab vaadata Tomcati kodulehelt sektsioonist "Download". Järgnevas näites installeerime Tomcati kõige uuema ebastabiilse kandidaatversiooni, mida näitab nimes sisalduv RC ehk "release candidate". Produktsioonikeskkonda tuleks siiski valida stabiilse versiooni. Käsitsi installeerimine on sarnane järgmisega:
<pre>
wget http://mirror.nexcess.net/apache/tomcat/tomcat-8/v8.0.0-RC5/bin/apache-tomcat-8.0.0-RC5.tar.gz
tar -zxvf apache-tomcat-8.0.0-RC5.tar.gz
mv /Users/kristjanveskimae/downloads/apache-tomcat-8.0.0-RC5 /usr/local/apache-tomcat-8.0.0-RC5
rm -f /Library/Tomcat
ln -s /usr/local/apache-tomcat-8.0.0-RC5/ /Library/Tomcat
chown -R kristjanveskimae /Library/Tomcat
chmod +x /Library/Tomcat/bin/*.sh
</pre>

==Käivitamine ja aplikatsiooni juurutamine==

===Konteineri käivitamine===

Tomcati käivitamise eelduseks on Java paigaldamine masinasse ning keskkonnamuutujate "JAVA_HOME" ja "JRE_HOME" defineerimine. Peale installeerimist võib kasutada skripte kataloogist $CATALINA_BASE/bin . Järgneb üks võimalik käivitamise ja peatamise näide, mis on kasutatav eelnevalt kirjeldatud käsitsi installeerimise juhul:
<pre>
/Library/Tomcat/bin/startup.sh
</pre>
ja peatamiseks
<pre>
/Library/Tomcat/bin/shutdown.sh
</pre>

===Näiteaplikatsiooni juurutamine===

Java veebiaplikatsiooni jagatakse hea tava kohaselt üheainsa veebiarhiivi failina. Siiski võib Tomcati juurutada ka lahtipakendatud olekus ("exploded") Java veebiaplikatsiooni.

====Käsitsi juurutamine ja mahavõtmine====

Näiteaplikatsiooni juurutamiseks lae selle veebiarhiivifail alla ning kopeeri oma konteineri juurutamiskataloogi 'webapps':
<pre>wget http://tomcat.apache.org/tomcat-8.0-doc/appdev/sample/sample.war
cp /Users/kristjanveskimae/downloads/sample.war /Library/Tomcat/webapps/sample.war</pre>

[[File:sample_app.png|400px|thumb|right|Pilt 1: Õnnestunult rakendatud näiteaplikatsioon]]

Kui konfiguratsioonifailis $CATALINA_BASE/conf/server.xml on märgendi "Host" atribuudi "autoDeploy" väärtus "true", installeerib ja uuendab Tomcat aplikatsioone dünaamiliselt töötamise ajal. Kui väärtuseks on "false", käib installeerimine staatiliselt ning serverisse juurutamiseks tuleb teha konteineri taaskäivitus. [http://tomcat.apache.org/tomcat-8.0-doc/manager-howto.html#Deploy_A_New_Application_from_a_Local_Path 1] Mõlemal juhul pakib konteiner arhiveeritud faili ise lahti samasse kausta $CATALINA_BASE/webapps ning ka juurutab selle. Tekkiv aplikatsioon on lokaalsest masinast seejärel kättesaadav aadressil http://localhost:8080/sample/ . Kui rakendamine õnnestub, siis peaks olema brauserist nähtav sarnane lehekülg nagu pildil 1.

Veebirakenduse käsitsi mahavõtmiseks tuleb kustutada talle vastav dokumendipõhja kataloog "webapps" kataloogist. Samuti tuleks kustutada .war-fail olemaks kindel, et Tomcat ei rakenda uuel käivitamisel veebiaplikatsiooni veebiarhiivifailist. Veelgi lihtsam on mahavõtmine brauseriga haldusrakenduse kaudu.

Rakenduste baaskataloogi "webapps" asukohta saab muuta failis $CATALINA_BASE/conf/server.xml peremehepõhiselt määratava atribuudiga "appBase", sealjuures Tomcati vaikimisi peremees ehk "Host" on "localhost".

====Tomcati vahendid juurutamiseks====

Veebiaplikatsioonide juurutamine ja mahajuurutamine on võimalik ka kaughalduse teel tänu Tomcati internetipõhisele haldusrakendusele. Näiteks saab veebibrauserit kasutades teha serveri põhitoiminguid Tomcati enda HTML-põhise rakendusega "Tomcat Manager". Veebipõhine haldusrakendus töötab ka käsupõhise veebiteenusena, millele on valmis ehitatud Anti ja Maveni integratsioonid. Samuti eksisteerib käsurea kliendirakendus TCD (Tomcat Client Deployer). TCD ei kuulu Tomcati baaskoosseisu, kuid pakub peale serveri administreerimise tavatoimingute ka lisafunktsionaalsust nagu veebirakenduse kokkukompileerimine ja pakendamine. [http://tomcat.apache.org/tomcat-8.0-doc/manager-howto.html#Configuring_Manager_Application_Access 1]

====Haldurakendus "Tomcat Manager"====

Tomcati haldusrakendus "Tomcat Manager" (antud alamjaotuses lihtsalt haldusrakendus) on Tomcati enda veebiaplikatioon Tomcati brauseripõhiseks kaughalduseks, võimaldades muu hulgas järgnevat [http://tomcat.apache.org/tomcat-8.0-doc/manager-howto.html#Introduction 1]:
* Rakendada uue veebiaplikatsiooni war-faili üleslaadimisega;
* Näha kõiki rakendatud veebiaplikatsioone koos aktiivsete sessioonidega;
* Taasrakendada veebirakendust, näiteks veebiarhiivi pakitud klassifailide /WEB-INF/classes või teekide /WEB-INF/lib uuendamisel, kinnijooksmisel jms.;
* Peatada veebirakendust ilma serverist eemaldamata, samuti koos serverist eemaldamisega;
* Vaadata operatsioonisüsteemi ja Java parameetrite väärtusi;
* Näha kõiki saadaolevaid JNDI ressursse, k.a. andmebaasiühendusi, mis aitavad rakenduste programmeerijail defineerida <ResourceLink> elemendid web.xml konfiguratsioonifailis.

Tomcati installatsioon sisaldab haldusrakendust juba vaikimisi. Haldusrakenduse töölepanemiseks tuleb peremeesmasina konfiguratsioonikataloogi $CATALINA_BASE/conf/[enginename]/[hostname] lisada ka fail manager.xml. Vaikimisi valmiskonfigureeritud testrakendusel on see fail juba olemas asukohas $CATALINA_BASE/conf/Catalina/localhost/manager.xml . Rakendus asub vaikimisi aadressil http://[host]/manager/ , vaikimisi konfiguratsioone kasutades lahendub see asukohaks http://localhost:8080/manager/ . [http://tomcat.apache.org/tomcat-8.0-doc/manager-howto.html#Configuring_Manager_Application_Access 1]

====="Tomcat Manager" ligipääsu konfigureerimine=====

Vaikimisi on turvalisuspõhjustel ligipääs haldusrakendusele maha keeratud. Mismoodi täpselt kasutajatel ligipääsu võimaldada sõltub kasutatavast valdusest (realm). Vaikimisi defineerib $CATALINA_BASE/conf/server.xml valduseks "MemoryRealm". Vaikimisi loeb valdus "MemoryRealm" kasutajad failist $CATALINA_BASE/conf/tomcat-users.xml. Antud failis tuleb iga kasutaja defineerida omaette märgendiga <user>, mis näeb välja umbes järgmine [http://tomcat.apache.org/tomcat-8.0-doc/manager-howto.html#Configuring_Manager_Application_Access 1]:
<pre>
<user name="craig" password="secret" roles="manager-gui,manager-script" />
</pre>

Antud kasutajale on defineeritud korraga kaks rolli. Ligipääsu võimaldamiseks tulebki lihtsamal juhul kasutajatefailis $CATALINA_BASE/conf/tomcat-users.xml defineerida enda kasutaja. Kasutaja rolliks võib määrata näiteks "manager-gui", mis võimaldab ligipääsu kogu HTML liidese funktsionaalsusele.

Teised valdused on "JDBCRealm", mille puhul hoitakse kasutajatega seonduvat infot andmebaasis ja JNDIRealm, mille puhul kasutatakse lihtsustatud kataloogisirvimise protokolli (LDAP).
Lisaks saab haldusrakendusele keelata ligipääsu mujalt kui kindlaksmääratud IP-aadressidelt, lisades filtri "RemoteAddrValve" või "RemoteHostValve" konfigureerimisfaili manager.xml näiteks järgmiselt [http://tomcat.apache.org/tomcat-8.0-doc/manager-howto.html#Introduction 1]:
<pre>
<Context privileged="true">
<Valve className="org.apache.catalina.valves.RemoteAddrValve"
allow="127\.0\.0\.1"/>
</Context>
</pre>

=====Juurutamine ja mahavõtmine haldusrakendusega "Tomcat Manager"=====

Juurutamiseks lae kõigepealt veebiarhiivifail üles, kasutades esilehel asuvat sektsiooni "WAR file to deploy".

[[File:tomcat_manager_war_upload.png|800px|thumb|right|Pilt 2: Veebiarhiivi üleslaadimise nupp]]

Rakendus kuvatakse seejärel hallatavate rakenduste nimekirjas. Kui konteiner pole seadistatud üleslaetud aplikatsiooni kohe ka ise rakendama, tuleb vajutada "Start". Rakenduse peatamiseks kasuta "Stop", uuesti rakendamiseks "Redeploy" ja serverist eemaldamiseks "Undeploy".


[[File:tomcat_manager_apps_list.png|800px|thumb|right|Pilt 3: Rakenduste nimekiri]]

==Näpunäiteid Tomcati reaalseks kasutamiseks==

===Juurutamise järjekord===

Tomcati käivitumisel juurutatakse aplikatsioonid sellises järjekorras [http://www.mulesoft.com/tomcat-deploy-procedures 2]:
# Konteinerisse kopeeritud kontekstikirjelduste järgi $CATALINA_BASE/conf/[EngineName]/[HostName]/[ApplicationName].xml ;
# Lahtipakitud rakendused "webapps" kataloogis;
# Pakitud rakenduste veebiarhiivid "webapps" kataloogis.

Seetõttu peaks käsitsi taasjuurutamisel kindluse mõttes eelnevalt kustutama rakenduse lahtipakitud dokumendipõhja kataloogi "webapps" kataloogist. Kontekstikirjelduse muutumisel tuleb jälgida, kas kirjeldus on juba kopeeritud serverisse ning vajadusel eelmise versiooni ümber muuta või kustutada.

===Reaalsele domeenile konfigureerimine===

Järgnevalt eeldame, et domeen ''www.minukodukas.ee'' on juba serverimasinaga seostatud. Et Tomcat hakkaks ka reaalselt Internetist tulevatele päringutele vastama, tuleb muuta failis $CATALINA_BASE/conf/server.xml konteinerile ''Catalina'' vastava teenusemärgendi sisu sarnaselt järgnevaga:

<pre>
<Service name="Catalina">
<Connector port="80" protocol="HTTP/1.1" connectionTimeout="20000" URIEncoding="UTF-8" redirectPort="8443" />
<Engine name="Catalina" defaultHost="www.minukodukas.ee">
<Host name="www.minukodukas.ee" appBase="webapps" unpackWARs="true" autoDeploy="false" deployOnStartup="false" xmlValidation="false" xmlNamespaceAware="false">
<Context path="" docBase="kodukas" debug="0" reloadable="true" />
</Host>
</Engine>
</Service>
</pre>

Ülal defineerime põhiliselt selle, et Tomcat kuulaks domeeni ''www.minukodukas.ee'' ja kasutaks HTTP päringute jaoks porti 80. Ühtlasti otsib Tomcat juurutatavat rakendust failist $CATALINA_BASE/webapps/kodukas.war. Kuna rajalisandiks on määratud tühi sõne (path=""), siis juurutataksegi aplikatsioon aadressile ''www.minukodukas.ee'' ilma rajalisandita (a'la ''www.minukodukas.ee/wiki''). Seetõttu pakitakse ka veebiarhiiv tegelikult lahti kataloogi $CATALINA_BASE/webapps/ROOT mitte kataloogi $CATALINA_BASE/webapps/kodukas nagu võiks eeldada.

===Käigultvahetus===

Võimaldamaks käigultvahetust (hot deployment) peab konteineri konfiguratsioonifailis $CATALINA_BASE/conf/server.xml olema peremehepõhise märgendi "Host" atribuudi "autoDeploy" väärtus "true". Sel juhul installeerib ja uuendab Tomcat aplikatsioone dünaamiliselt töötamise ajal. Kui väärtuseks on "false", käib installeerimine staatiliselt ning serverisse juurutamiseks tuleb teha konteineri taaskäivitus. Käigultvahetust saab määrata ka peremehe defineerimisel "Host Manager" rakendusega, mis on kättesaadav aadressil http://localhost:8080/host-manager/html . Kasutamiseks tuleb lisada oma kasutajale rolli "admin-gui" (vt. alajaotus ""Tomcat Manager" ligipääsu konfigureerimine").

[[File:host_manager_app.png]]

Käigultvahetust päästikuks on vaikimisi uuendatud veebiarhiivifaili või lahtipakitud veebirakenduse paigutamine "webapps" kataloogi. Käigultvahetuse päästikutele võib failis $CATALINA_BASE/conf/server.xml ka ise lisada kuulatavaid ressursse nagu web.xml muutmine või mõne teegifaili vahetamine (märgendis "Host").

===Klassiteekide väljatõstmine veebiarhiivifailist===

Kõik konteksti poolt kasutatavad Java klassiteegid võib pakendada veebiarhiivi sisse kataloogi "lib", kuid nii võib osutuda veebiarhiivi üleslaadimine ajakulukaks, eriti arenduskeskkonnas. Kui ei teki ohtu, et erinevad rakendused kasutavad sama teegi erinevaid versioone, siis on vahel parem lisada osa teeke konteineri kataloogi $CATALINA_BASE/libs, kust need tehakse siis konteineri poolt kättesaadavaks kõigile konteineris jooksutatavatele kontekstidele. Nii võib vähendada veebiarhiivi faili suurust märgatavalt, mis tõstab kokkuvõttes juurutamiskiirust ja ühes sellega programmeerijate tööviljakust.

===Mälukasutus===

Konteineri poolt kasutatavat mälu saab vaadata haldusrakendusest vajutades lingile "Server Status". Mälukasutus on toodud jaotuses "JVM", kus näidatakse nii maksimaalselt kättesaadavat mälu kui ka parasjagu reserveeritud mälu.

<pre>Free memory: 41.16 MB Total memory: 123.37 MB Max memory: 1027.56 MB</pre>

Mälu suurendamiseks võib näiteks defineerida skriptis $CATALINA_BASE/bin/catalina.sh muutuja "JAVA_OPTS" ning määrata Java mälukasutuse miinimum- ja maksimumväärtused sarnaselt järgnevatega [http://www.mkyong.com/tomcat/tomcat-javalangoutofmemoryerror-permgen-space/ 3]:
<pre>
JAVA_OPTS="-Xms1536m -Xmx1536m -XX:NewSize=256m -XX:MaxNewSize=256m -XX:PermSize=256m -XX:MaxPermSize=256m"
</pre>

===Logifailid===

Vaikimisi defineerib Tomcat failiga $CATALINA_BASE/conf/logging.properties viis logerit, mis tekitavad viis eraldi logifaili.

{| style="background:#cccc99;color:black;width:80%;" border="1" cellpadding="5" cellspacing="0" align="center"
|+ Tomcati tekitatavad logifailid "logs" kataloogis
!Fail !! Kasutus
|- style="background:white; color:black"
| style="width:300px" |catalina.out
| Tomcati käivitus- ja peatamisskriptide väljund, samuti juurutatud rakenduste prindilaused System.out ja veaväljundid System.err
|- style="background:white; color:black"
| style="width:300px" |catalina.[yyyy]-[mm]-[dd].log
| Pööratud (rotated) logifail catalina.out
|- style="background:white; color:black"
| style="width:300px" |host-manager.[yyyy]-[mm]-[dd].log
| Logi peremehehalduse rakendusele (rakendus on kättesaadav kohalikust masinast aadressil http://localhost:8080/host-manager/html )
|- style="background:white; color:black"
| style="width:300px" |localhost.[yyyy]-[mm]-[dd].log
| Peremehe "localhost" logi; mitme virtuaalse peremehe korral tekitatakse igale peremehele oma logi
|- style="background:white; color:black"
| style="width:300px" |localhost_access_log.[yyyy]-[mm]-[dd].txt
| Konteinerisse Internetist saabunud päringute logi
|- style="background:white; color:black"
| style="width:300px" |manager.[yyyy]-[mm]-[dd].log
| Haldusrakenduse tegevuste logi
|}

===Viiteid===

Palju vajalikku võib leida [http://tomcat.apache.org/tomcat-8.0-doc/index.html Tomcat 8 dokumentatsioonist]

Lisaks üks viide põhjalikule Tomcati versioon seitsme ülevaatele: http://www.ntu.edu.sg/home/ehchua/programming/howto/Tomcat_More.html

= Kasutatud materjalid =

#http://tomcat.apache.org/tomcat-8.0-doc/index.html
#http://www.mulesoft.com/tomcat-deploy-procedures
#http://www.mkyong.com/tomcat/tomcat-javalangoutofmemoryerror-permgen-space/

[[Category: Operatsioonisüsteemide administreerimine ja sidumine]]

Tomcat

2014-01-02T22:04:00Z

Kveskima: /* Juurutamine ja mahavõtmine haldusrakendusega "Tomcat Manager" */

==Autor==

Kristjan Veskimäe D32

2013

==Sissejuhatus==

Tomcat on vabalt kättesaadav server Java veebirakendustele. Põhimõtteliselt on tegemist Servlet/JSP spetsifikatsiooni toetava konteineriga. Kiire käivitumise ning rakenduste käigultvahetuse tõttu on Tomcat hea valik väiksemate ning keskmise suurusega Java veebirakenduste käitamiseks.

Antud töö kirjeldab Tomcati 8. versiooni. Põhiosa on üldiselt samasugune võrreldes paari eelmise versiooniga. Suuremad erinevused on versioonispetsiifilistes probleemides ja nende lahendamises, mida käesolev töö ei vaatle.

Töö vaatleb Tomcati paigaldamist ja seadistamist Unix-laadsesse keskkonda ning eeldab lugejalt algteadmisi sarnastes süsteemides. Tomcati on võimalik paigaldada ka Windows-keskkonda, kuid antud veebiserver eeldab kasutaja poolt käsureal töötamist ning Tomcati failihierarhias orienteerumist. Põhimõtteliselt on Java veebirakenduste arendamiseks IDE-abil võimalik siiski ka kasutada IDE-sse integreeritud Tomcati serverit - näiteks pakuvad sellist võimalust Eclipse EE ja NetBeans - kuid seda käesolev töö ei vaatle.

==Mõisted==

* '''Kontekst''' (context) - Tomcati mõistes üks konkreetne veebiaplikatsioon
* '''Konteiner''' (container) - veebiserver Tomcat ise
* '''Kontekstikirjeldus''' (context descriptor) - Tomcati-spetsiifiline konteksti konfiguratsioonimääratlus; peremehepõhine osa loetakse failist $CATALINA_HOME/conf/[enginename]/[hostname]/context.xml ja sellele lisatakse kontekstispetsiifilised täpsustused failist $CATALINA_BASE/conf/[enginename]/[hostname]/[webappname].xml; kontekstikirjeldus määrab näiteks nimed ressurssidele, sessioonihalduse parameetrid jmt. (olgu märgitud, et Tomcati varasemates versioonides sisaldusid kontekstikirjeldused põhikonfiguratsioonifailis server.xml)
* '''Dokumendipõhi''' (docBase) - kontekstile vastav kataloog Tomcati "webapps" kataloogis, mis tekib veebiaplikatsiooni serverisse rakendamisel
* '''Veebiarhiiv''' (Web application ARchive, war-file) - Java veebiaplikatsiooni jagatakse hea tava kohaselt selle üheainsa veebiarhiivi failina, mille laienditüübiks on "war". Tegemist on zip-protokolliga kokkupakitud kataloogiga, millel on Java veebirakenduste spetsifikatsioonile vastav ülesehitus. Siiski võib veebiaplikatsioon olla juurutamisel ka lahtipakendatud olekus (inglisekeelne termin on "war is exploded").

==Ülesehitus==

{| class="wikitable"
|+Kataloogid
|-
|style="color: green;" | $CATALINA_HOME
|baaskataloog, kuhu on Tomcat paigutatud
|-
|style="color: green;" | $CATALINA_BASE
|parasjagu töösoleva Tomcati eksemplari baaskataloog, mille alusel lahendatakse teed ülejäänud kataloogide ja failideni; ainult ühe kasutusel oleva Tomcati eksemplari puhul on see sama, mis $CATALINA_HOME

|-
|style="color: green;" | $CATALINA_BASE/bin
|serveri käivitus- ja abiskriptid
|-
|style="color: green;" | $CATALINA_BASE/conf
|konfiguratsioonifailid
|-
|style="color: green;" | $CATALINA_BASE/lib
|Tomcatile vaikimisi kättesaadavad Java klassiteegid (class libraries) ehk .jar-failid kuhu on Java kompileeritud kood kokku pakendatud
|-
|style="color: green;" | $CATALINA_BASE/logs
|logifailid paigutatakse vaikimisi siia
|-
|style="color: green;" | $CATALINA_BASE/webapps
|kataloog, kuhu paigutatakse serverisse juurutatavad veebiaplikatsioonid

|}

{| class="wikitable"
|+Mõned olulisemad failid
|-
|style="color: green;" | $CATALINA_BASE/bin/startup.sh
|serveri käivitusskript
|-
|style="color: green;" | $CATALINA_BASE/bin/shutdown.sh
|serveri peatusskript

|-
|style="color: green;" | $CATALINA_BASE/conf/server.xml
| konteineri peamine konfiguratsioonifail
|-
|style="color: green;" | $CATALINA_BASE/conf/[enginename]/[hostname]/[webappname].xml
|serveri administraatori jaoks konteinerisse endasse ümber kopeeritud rakendusepõhine kontekstikirjelduse konfiguratsioon failist $CATALINA_BASE/webapps/[ApplicationName]/META-INF/context.xml
|-
|style="color: green;" | $CATALINA_BASE/conf/[enginename]/[hostname]/context.xml
| fail, mis aitab administraatoril konteksti kohta käivat infot kirjeldada peremeesmasina-põhiselt ja halduseks mõeldud automaat-tööriistadel (näiteks Tomcat Manager ja TCD) oma tööd teha
|-
|style="color: green;" | $CATALINA_BASE/$CATALINA_BASE/conf/[enginename]/[hostname]/manager.xml
|fail, mis võimaldab lisada rakendustele ligipääsufiltreid
|-
|style="color: green;" | $CATALINA_BASE/webapps/[webappname]/META-INF/context.xml
|kontekstikirjeldusfail, mille veebirakenduse programmeerija on pakendanud oma aplikatsiooniga kaasa ning millega ta saab võimaluse kontekstikirjeldust omalt poolt mõjutada; kirjutatakse rakenduse uuestijuurutamisel üle, mistõttu administraator peaks muutma selle asemel konteinerisse ümber kopeeritud püsieksemplari $CATALINA_BASE/conf/[enginename]/[hostname]/context.xml
|-
|style="color: green;" | $CATALINA_BASE/webapps/[webappname]/WEB-INF/web.xml
|ka üks oluline Java veebiaplikatsiooni konfiguratsioonifail, mille pakendatakse koos veebiarhiiviga; enamasti muudab seda ainult programeerija; määrab muu hulgas millised aplikatsiooni osad vajavad autentimist või kui kiiresti veebisessioon aegub
|}

==Installeerimine==

===Installeerimine paketihalduriga===

<pre>
apt-cache search tomcat
apt-get install tomcat[version]-webapps
apt-get install tomcat[version]-admin
apt-get install tomcat[version]
</pre>

===Installeerimine käsitsi===

Paketihalduriga installeerides ei pruugi viimane Tomcati versioon olla kättesaadav ja see pakub ka vähem võimalusi kataloogide määramiseks jms. Käsitsi installeerimiseks tuleb laadida Tomcat kodulehelt alla. Lahtipakkimisel tekib kataloog, milles sisalduv fail "RUNNING.txt" on kõige kindlam allikas installeerimisel tekkivate probleemide vältimiseks ning lahendamiseks.

Vajaliku versiooni installeerimisfaili asukoha saab vaadata Tomcati kodulehelt sektsioonist "Download". Järgnevas näites installeerime Tomcati kõige uuema ebastabiilse kandidaatversiooni, mida näitab nimes sisalduv RC ehk "release candidate". Produktsioonikeskkonda tuleks siiski valida stabiilse versiooni. Käsitsi installeerimine on sarnane järgmisega:
<pre>
wget http://mirror.nexcess.net/apache/tomcat/tomcat-8/v8.0.0-RC5/bin/apache-tomcat-8.0.0-RC5.tar.gz
tar -zxvf apache-tomcat-8.0.0-RC5.tar.gz
mv /Users/kristjanveskimae/downloads/apache-tomcat-8.0.0-RC5 /usr/local/apache-tomcat-8.0.0-RC5
rm -f /Library/Tomcat
ln -s /usr/local/apache-tomcat-8.0.0-RC5/ /Library/Tomcat
chown -R kristjanveskimae /Library/Tomcat
chmod +x /Library/Tomcat/bin/*.sh
</pre>

==Käivitamine ja aplikatsiooni juurutamine==

===Konteineri käivitamine===

Tomcati käivitamise eelduseks on Java paigaldamine masinasse ning keskkonnamuutujate "JAVA_HOME" ja "JRE_HOME" defineerimine. Peale installeerimist võib kasutada skripte kataloogist $CATALINA_BASE/bin . Järgneb üks võimalik käivitamise ja peatamise näide, mis on kasutatav eelnevalt kirjeldatud käsitsi installeerimise juhul:
<pre>
/Library/Tomcat/bin/startup.sh
</pre>
ja peatamiseks
<pre>
/Library/Tomcat/bin/shutdown.sh
</pre>

===Näiteaplikatsiooni juurutamine===

Java veebiaplikatsiooni jagatakse hea tava kohaselt üheainsa veebiarhiivi failina. Siiski võib Tomcati juurutada ka lahtipakendatud olekus ("exploded") Java veebiaplikatsiooni.

====Käsitsi juurutamine ja mahavõtmine====

Näiteaplikatsiooni juurutamiseks lae selle veebiarhiivifail alla ning kopeeri oma konteineri juurutamiskataloogi 'webapps':
<pre>wget http://tomcat.apache.org/tomcat-8.0-doc/appdev/sample/sample.war
cp /Users/kristjanveskimae/downloads/sample.war /Library/Tomcat/webapps/sample.war</pre>

[[File:sample_app.png|400px|thumb|right|Pilt 1: Õnnestunult rakendatud näiteaplikatsioon]]

Kui konfiguratsioonifailis $CATALINA_BASE/conf/server.xml on märgendi "Host" atribuudi "autoDeploy" väärtus "true", installeerib ja uuendab Tomcat aplikatsioone dünaamiliselt töötamise ajal. Kui väärtuseks on "false", käib installeerimine staatiliselt ning serverisse juurutamiseks tuleb teha konteineri taaskäivitus. [http://tomcat.apache.org/tomcat-8.0-doc/manager-howto.html#Deploy_A_New_Application_from_a_Local_Path 1] Mõlemal juhul pakib konteiner arhiveeritud faili ise lahti samasse kausta $CATALINA_BASE/webapps ning ka juurutab selle. Tekkiv aplikatsioon on lokaalsest masinast seejärel kättesaadav aadressil http://localhost:8080/sample/ . Kui rakendamine õnnestub, siis peaks olema brauserist nähtav sarnane lehekülg nagu pildil 1.

Veebirakenduse käsitsi mahavõtmiseks tuleb kustutada talle vastav dokumendipõhja kataloog "webapps" kataloogist. Samuti tuleks kustutada .war-fail olemaks kindel, et Tomcat ei rakenda uuel käivitamisel veebiaplikatsiooni veebiarhiivifailist. Veelgi lihtsam on mahavõtmine brauseriga haldusrakenduse kaudu.

Rakenduste baaskataloogi "webapps" asukohta saab muuta failis $CATALINA_BASE/conf/server.xml peremehepõhiselt määratava atribuudiga "appBase", sealjuures Tomcati vaikimisi peremees ehk "Host" on "localhost".

====Tomcati vahendid juurutamiseks====

Veebiaplikatsioonide juurutamine ja mahajuurutamine on võimalik ka kaughalduse teel tänu Tomcati internetipõhisele haldusrakendusele. Näiteks saab veebibrauserit kasutades teha serveri põhitoiminguid Tomcati enda HTML-põhise rakendusega "Tomcat Manager". Veebipõhine haldusrakendus töötab ka käsupõhise veebiteenusena, millele on valmis ehitatud Anti ja Maveni integratsioonid. Samuti eksisteerib käsurea kliendirakendus TCD (Tomcat Client Deployer). TCD ei kuulu Tomcati baaskoosseisu, kuid pakub peale serveri administreerimise tavatoimingute ka lisafunktsionaalsust nagu veebirakenduse kokkukompileerimine ja pakendamine. [http://tomcat.apache.org/tomcat-8.0-doc/manager-howto.html#Configuring_Manager_Application_Access 1]

====Haldurakendus "Tomcat Manager"====

Tomcati haldusrakendus "Tomcat Manager" (antud alamjaotuses lihtsalt haldusrakendus) on Tomcati enda veebiaplikatioon Tomcati brauseripõhiseks kaughalduseks, võimaldades muu hulgas järgnevat [http://tomcat.apache.org/tomcat-8.0-doc/manager-howto.html#Introduction 1]:
* Rakendada uue veebiaplikatsiooni war-faili üleslaadimisega;
* Näha kõiki rakendatud veebiaplikatsioone koos aktiivsete sessioonidega;
* Taasrakendada veebirakendust, näiteks veebiarhiivi pakitud klassifailide /WEB-INF/classes või teekide /WEB-INF/lib uuendamisel, kinnijooksmisel jms.;
* Peatada veebirakendust ilma serverist eemaldamata, samuti koos serverist eemaldamisega;
* Vaadata operatsioonisüsteemi ja Java parameetrite väärtusi;
* Näha kõiki saadaolevaid JNDI ressursse, k.a. andmebaasiühendusi, mis aitavad rakenduste programmeerijail defineerida <ResourceLink> elemendid web.xml konfiguratsioonifailis.

Tomcati installatsioon sisaldab haldusrakendust juba vaikimisi. Haldusrakenduse töölepanemiseks tuleb peremeesmasina konfiguratsioonikataloogi $CATALINA_BASE/conf/[enginename]/[hostname] lisada ka fail manager.xml. Vaikimisi valmiskonfigureeritud testrakendusel on see fail juba olemas asukohas $CATALINA_BASE/conf/Catalina/localhost/manager.xml . Rakendus asub vaikimisi aadressil http://[host]/manager/ , vaikimisi konfiguratsioone kasutades lahendub see asukohaks http://localhost:8080/manager/ . [http://tomcat.apache.org/tomcat-8.0-doc/manager-howto.html#Configuring_Manager_Application_Access 1]

====="Tomcat Manager" ligipääsu konfigureerimine=====

Vaikimisi on turvalisuspõhjustel ligipääs haldusrakendusele maha keeratud. Mismoodi täpselt kasutajatel ligipääsu võimaldada sõltub kasutatavast valdusest (realm). Vaikimisi defineerib $CATALINA_BASE/conf/server.xml valduseks "MemoryRealm". Vaikimisi loeb valdus "MemoryRealm" kasutajad failist $CATALINA_BASE/conf/tomcat-users.xml. Antud failis tuleb iga kasutaja defineerida omaette märgendiga <user>, mis näeb välja umbes järgmine [http://tomcat.apache.org/tomcat-8.0-doc/manager-howto.html#Configuring_Manager_Application_Access 1]:
<pre>
<user name="craig" password="secret" roles="manager-gui,manager-script" />
</pre>

Antud kasutajale on defineeritud korraga kaks rolli. Ligipääsu võimaldamiseks tulebki lihtsamal juhul kasutajatefailis $CATALINA_BASE/conf/tomcat-users.xml defineerida enda kasutaja. Kasutaja rolliks võib määrata näiteks "manager-gui", mis võimaldab ligipääsu kogu HTML liidese funktsionaalsusele.

Teised valdused on "JDBCRealm", mille puhul hoitakse kasutajatega seonduvat infot andmebaasis ja JNDIRealm, mille puhul kasutatakse lihtsustatud kataloogisirvimise protokolli (LDAP).
Lisaks saab haldusrakendusele keelata ligipääsu mujalt kui kindlaksmääratud IP-aadressidelt, lisades filtri "RemoteAddrValve" või "RemoteHostValve" konfigureerimisfaili manager.xml näiteks järgmiselt [http://tomcat.apache.org/tomcat-8.0-doc/manager-howto.html#Introduction 1]:
<pre>
<Context privileged="true">
<Valve className="org.apache.catalina.valves.RemoteAddrValve"
allow="127\.0\.0\.1"/>
</Context>
</pre>

=====Juurutamine ja mahavõtmine haldusrakendusega "Tomcat Manager"=====

Juurutamiseks lae kõigepealt veebiarhiivifail üles, kasutades esilehel asuvat sektsiooni "WAR file to deploy".

[[File:tomcat_manager_war_upload.png|800px|thumb|right|Pilt 2: Veebiarhiivi üleslaadimise nupp]]

Rakendus kuvatakse seejärel hallatavate rakenduste nimekirjas. Kui konteiner pole seadistatud üleslaetud aplikatsiooni kohe ka ise rakendama, tuleb vajutada "Start". Rakenduse peatamiseks kasuta "Stop", uuesti rakendamiseks "Redeploy" ja serverist eemaldamiseks "Undeploy".


[[File:tomcat_manager_apps_list.png|800px|Pilt 3: Rakenduste nimekiri]]

==Näpunäiteid Tomcati reaalseks kasutamiseks==

===Juurutamise järjekord===

Tomcati käivitumisel juurutatakse aplikatsioonid sellises järjekorras [http://www.mulesoft.com/tomcat-deploy-procedures 2]:
# Konteinerisse kopeeritud kontekstikirjelduste järgi $CATALINA_BASE/conf/[EngineName]/[HostName]/[ApplicationName].xml ;
# Lahtipakitud rakendused "webapps" kataloogis;
# Pakitud rakenduste veebiarhiivid "webapps" kataloogis.

Seetõttu peaks käsitsi taasjuurutamisel kindluse mõttes eelnevalt kustutama rakenduse lahtipakitud dokumendipõhja kataloogi "webapps" kataloogist. Kontekstikirjelduse muutumisel tuleb jälgida, kas kirjeldus on juba kopeeritud serverisse ning vajadusel eelmise versiooni ümber muuta või kustutada.

===Reaalsele domeenile konfigureerimine===

Järgnevalt eeldame, et domeen ''www.minukodukas.ee'' on juba serverimasinaga seostatud. Et Tomcat hakkaks ka reaalselt Internetist tulevatele päringutele vastama, tuleb muuta failis $CATALINA_BASE/conf/server.xml konteinerile ''Catalina'' vastava teenusemärgendi sisu sarnaselt järgnevaga:

<pre>
<Service name="Catalina">
<Connector port="80" protocol="HTTP/1.1" connectionTimeout="20000" URIEncoding="UTF-8" redirectPort="8443" />
<Engine name="Catalina" defaultHost="www.minukodukas.ee">
<Host name="www.minukodukas.ee" appBase="webapps" unpackWARs="true" autoDeploy="false" deployOnStartup="false" xmlValidation="false" xmlNamespaceAware="false">
<Context path="" docBase="kodukas" debug="0" reloadable="true" />
</Host>
</Engine>
</Service>
</pre>

Ülal defineerime põhiliselt selle, et Tomcat kuulaks domeeni ''www.minukodukas.ee'' ja kasutaks HTTP päringute jaoks porti 80. Ühtlasti otsib Tomcat juurutatavat rakendust failist $CATALINA_BASE/webapps/kodukas.war. Kuna rajalisandiks on määratud tühi sõne (path=""), siis juurutataksegi aplikatsioon aadressile ''www.minukodukas.ee'' ilma rajalisandita (a'la ''www.minukodukas.ee/wiki''). Seetõttu pakitakse ka veebiarhiiv tegelikult lahti kataloogi $CATALINA_BASE/webapps/ROOT mitte kataloogi $CATALINA_BASE/webapps/kodukas nagu võiks eeldada.

===Käigultvahetus===

Võimaldamaks käigultvahetust (hot deployment) peab konteineri konfiguratsioonifailis $CATALINA_BASE/conf/server.xml olema peremehepõhise märgendi "Host" atribuudi "autoDeploy" väärtus "true". Sel juhul installeerib ja uuendab Tomcat aplikatsioone dünaamiliselt töötamise ajal. Kui väärtuseks on "false", käib installeerimine staatiliselt ning serverisse juurutamiseks tuleb teha konteineri taaskäivitus. Käigultvahetust saab määrata ka peremehe defineerimisel "Host Manager" rakendusega, mis on kättesaadav aadressil http://localhost:8080/host-manager/html . Kasutamiseks tuleb lisada oma kasutajale rolli "admin-gui" (vt. alajaotus ""Tomcat Manager" ligipääsu konfigureerimine").

[[File:host_manager_app.png]]

Käigultvahetust päästikuks on vaikimisi uuendatud veebiarhiivifaili või lahtipakitud veebirakenduse paigutamine "webapps" kataloogi. Käigultvahetuse päästikutele võib failis $CATALINA_BASE/conf/server.xml ka ise lisada kuulatavaid ressursse nagu web.xml muutmine või mõne teegifaili vahetamine (märgendis "Host").

===Klassiteekide väljatõstmine veebiarhiivifailist===

Kõik konteksti poolt kasutatavad Java klassiteegid võib pakendada veebiarhiivi sisse kataloogi "lib", kuid nii võib osutuda veebiarhiivi üleslaadimine ajakulukaks, eriti arenduskeskkonnas. Kui ei teki ohtu, et erinevad rakendused kasutavad sama teegi erinevaid versioone, siis on vahel parem lisada osa teeke konteineri kataloogi $CATALINA_BASE/libs, kust need tehakse siis konteineri poolt kättesaadavaks kõigile konteineris jooksutatavatele kontekstidele. Nii võib vähendada veebiarhiivi faili suurust märgatavalt, mis tõstab kokkuvõttes juurutamiskiirust ja ühes sellega programmeerijate tööviljakust.

===Mälukasutus===

Konteineri poolt kasutatavat mälu saab vaadata haldusrakendusest vajutades lingile "Server Status". Mälukasutus on toodud jaotuses "JVM", kus näidatakse nii maksimaalselt kättesaadavat mälu kui ka parasjagu reserveeritud mälu.

<pre>Free memory: 41.16 MB Total memory: 123.37 MB Max memory: 1027.56 MB</pre>

Mälu suurendamiseks võib näiteks defineerida skriptis $CATALINA_BASE/bin/catalina.sh muutuja "JAVA_OPTS" ning määrata Java mälukasutuse miinimum- ja maksimumväärtused sarnaselt järgnevatega [http://www.mkyong.com/tomcat/tomcat-javalangoutofmemoryerror-permgen-space/ 3]:
<pre>
JAVA_OPTS="-Xms1536m -Xmx1536m -XX:NewSize=256m -XX:MaxNewSize=256m -XX:PermSize=256m -XX:MaxPermSize=256m"
</pre>

===Logifailid===

Vaikimisi defineerib Tomcat failiga $CATALINA_BASE/conf/logging.properties viis logerit, mis tekitavad viis eraldi logifaili.

{| style="background:#cccc99;color:black;width:80%;" border="1" cellpadding="5" cellspacing="0" align="center"
|+ Tomcati tekitatavad logifailid "logs" kataloogis
!Fail !! Kasutus
|- style="background:white; color:black"
| style="width:300px" |catalina.out
| Tomcati käivitus- ja peatamisskriptide väljund, samuti juurutatud rakenduste prindilaused System.out ja veaväljundid System.err
|- style="background:white; color:black"
| style="width:300px" |catalina.[yyyy]-[mm]-[dd].log
| Pööratud (rotated) logifail catalina.out
|- style="background:white; color:black"
| style="width:300px" |host-manager.[yyyy]-[mm]-[dd].log
| Logi peremehehalduse rakendusele (rakendus on kättesaadav kohalikust masinast aadressil http://localhost:8080/host-manager/html )
|- style="background:white; color:black"
| style="width:300px" |localhost.[yyyy]-[mm]-[dd].log
| Peremehe "localhost" logi; mitme virtuaalse peremehe korral tekitatakse igale peremehele oma logi
|- style="background:white; color:black"
| style="width:300px" |localhost_access_log.[yyyy]-[mm]-[dd].txt
| Konteinerisse Internetist saabunud päringute logi
|- style="background:white; color:black"
| style="width:300px" |manager.[yyyy]-[mm]-[dd].log
| Haldusrakenduse tegevuste logi
|}

===Viiteid===

Palju vajalikku võib leida [http://tomcat.apache.org/tomcat-8.0-doc/index.html Tomcat 8 dokumentatsioonist]

Lisaks üks viide põhjalikule Tomcati versioon seitsme ülevaatele: http://www.ntu.edu.sg/home/ehchua/programming/howto/Tomcat_More.html

= Kasutatud materjalid =

#http://tomcat.apache.org/tomcat-8.0-doc/index.html
#http://www.mulesoft.com/tomcat-deploy-procedures
#http://www.mkyong.com/tomcat/tomcat-javalangoutofmemoryerror-permgen-space/

[[Category: Operatsioonisüsteemide administreerimine ja sidumine]]

Tomcat

2014-01-02T22:03:33Z

Kveskima: /* Käsitsi juurutamine ja mahavõtmine */

==Autor==

Kristjan Veskimäe D32

2013

==Sissejuhatus==

Tomcat on vabalt kättesaadav server Java veebirakendustele. Põhimõtteliselt on tegemist Servlet/JSP spetsifikatsiooni toetava konteineriga. Kiire käivitumise ning rakenduste käigultvahetuse tõttu on Tomcat hea valik väiksemate ning keskmise suurusega Java veebirakenduste käitamiseks.

Antud töö kirjeldab Tomcati 8. versiooni. Põhiosa on üldiselt samasugune võrreldes paari eelmise versiooniga. Suuremad erinevused on versioonispetsiifilistes probleemides ja nende lahendamises, mida käesolev töö ei vaatle.

Töö vaatleb Tomcati paigaldamist ja seadistamist Unix-laadsesse keskkonda ning eeldab lugejalt algteadmisi sarnastes süsteemides. Tomcati on võimalik paigaldada ka Windows-keskkonda, kuid antud veebiserver eeldab kasutaja poolt käsureal töötamist ning Tomcati failihierarhias orienteerumist. Põhimõtteliselt on Java veebirakenduste arendamiseks IDE-abil võimalik siiski ka kasutada IDE-sse integreeritud Tomcati serverit - näiteks pakuvad sellist võimalust Eclipse EE ja NetBeans - kuid seda käesolev töö ei vaatle.

==Mõisted==

* '''Kontekst''' (context) - Tomcati mõistes üks konkreetne veebiaplikatsioon
* '''Konteiner''' (container) - veebiserver Tomcat ise
* '''Kontekstikirjeldus''' (context descriptor) - Tomcati-spetsiifiline konteksti konfiguratsioonimääratlus; peremehepõhine osa loetakse failist $CATALINA_HOME/conf/[enginename]/[hostname]/context.xml ja sellele lisatakse kontekstispetsiifilised täpsustused failist $CATALINA_BASE/conf/[enginename]/[hostname]/[webappname].xml; kontekstikirjeldus määrab näiteks nimed ressurssidele, sessioonihalduse parameetrid jmt. (olgu märgitud, et Tomcati varasemates versioonides sisaldusid kontekstikirjeldused põhikonfiguratsioonifailis server.xml)
* '''Dokumendipõhi''' (docBase) - kontekstile vastav kataloog Tomcati "webapps" kataloogis, mis tekib veebiaplikatsiooni serverisse rakendamisel
* '''Veebiarhiiv''' (Web application ARchive, war-file) - Java veebiaplikatsiooni jagatakse hea tava kohaselt selle üheainsa veebiarhiivi failina, mille laienditüübiks on "war". Tegemist on zip-protokolliga kokkupakitud kataloogiga, millel on Java veebirakenduste spetsifikatsioonile vastav ülesehitus. Siiski võib veebiaplikatsioon olla juurutamisel ka lahtipakendatud olekus (inglisekeelne termin on "war is exploded").

==Ülesehitus==

{| class="wikitable"
|+Kataloogid
|-
|style="color: green;" | $CATALINA_HOME
|baaskataloog, kuhu on Tomcat paigutatud
|-
|style="color: green;" | $CATALINA_BASE
|parasjagu töösoleva Tomcati eksemplari baaskataloog, mille alusel lahendatakse teed ülejäänud kataloogide ja failideni; ainult ühe kasutusel oleva Tomcati eksemplari puhul on see sama, mis $CATALINA_HOME

|-
|style="color: green;" | $CATALINA_BASE/bin
|serveri käivitus- ja abiskriptid
|-
|style="color: green;" | $CATALINA_BASE/conf
|konfiguratsioonifailid
|-
|style="color: green;" | $CATALINA_BASE/lib
|Tomcatile vaikimisi kättesaadavad Java klassiteegid (class libraries) ehk .jar-failid kuhu on Java kompileeritud kood kokku pakendatud
|-
|style="color: green;" | $CATALINA_BASE/logs
|logifailid paigutatakse vaikimisi siia
|-
|style="color: green;" | $CATALINA_BASE/webapps
|kataloog, kuhu paigutatakse serverisse juurutatavad veebiaplikatsioonid

|}

{| class="wikitable"
|+Mõned olulisemad failid
|-
|style="color: green;" | $CATALINA_BASE/bin/startup.sh
|serveri käivitusskript
|-
|style="color: green;" | $CATALINA_BASE/bin/shutdown.sh
|serveri peatusskript

|-
|style="color: green;" | $CATALINA_BASE/conf/server.xml
| konteineri peamine konfiguratsioonifail
|-
|style="color: green;" | $CATALINA_BASE/conf/[enginename]/[hostname]/[webappname].xml
|serveri administraatori jaoks konteinerisse endasse ümber kopeeritud rakendusepõhine kontekstikirjelduse konfiguratsioon failist $CATALINA_BASE/webapps/[ApplicationName]/META-INF/context.xml
|-
|style="color: green;" | $CATALINA_BASE/conf/[enginename]/[hostname]/context.xml
| fail, mis aitab administraatoril konteksti kohta käivat infot kirjeldada peremeesmasina-põhiselt ja halduseks mõeldud automaat-tööriistadel (näiteks Tomcat Manager ja TCD) oma tööd teha
|-
|style="color: green;" | $CATALINA_BASE/$CATALINA_BASE/conf/[enginename]/[hostname]/manager.xml
|fail, mis võimaldab lisada rakendustele ligipääsufiltreid
|-
|style="color: green;" | $CATALINA_BASE/webapps/[webappname]/META-INF/context.xml
|kontekstikirjeldusfail, mille veebirakenduse programmeerija on pakendanud oma aplikatsiooniga kaasa ning millega ta saab võimaluse kontekstikirjeldust omalt poolt mõjutada; kirjutatakse rakenduse uuestijuurutamisel üle, mistõttu administraator peaks muutma selle asemel konteinerisse ümber kopeeritud püsieksemplari $CATALINA_BASE/conf/[enginename]/[hostname]/context.xml
|-
|style="color: green;" | $CATALINA_BASE/webapps/[webappname]/WEB-INF/web.xml
|ka üks oluline Java veebiaplikatsiooni konfiguratsioonifail, mille pakendatakse koos veebiarhiiviga; enamasti muudab seda ainult programeerija; määrab muu hulgas millised aplikatsiooni osad vajavad autentimist või kui kiiresti veebisessioon aegub
|}

==Installeerimine==

===Installeerimine paketihalduriga===

<pre>
apt-cache search tomcat
apt-get install tomcat[version]-webapps
apt-get install tomcat[version]-admin
apt-get install tomcat[version]
</pre>

===Installeerimine käsitsi===

Paketihalduriga installeerides ei pruugi viimane Tomcati versioon olla kättesaadav ja see pakub ka vähem võimalusi kataloogide määramiseks jms. Käsitsi installeerimiseks tuleb laadida Tomcat kodulehelt alla. Lahtipakkimisel tekib kataloog, milles sisalduv fail "RUNNING.txt" on kõige kindlam allikas installeerimisel tekkivate probleemide vältimiseks ning lahendamiseks.

Vajaliku versiooni installeerimisfaili asukoha saab vaadata Tomcati kodulehelt sektsioonist "Download". Järgnevas näites installeerime Tomcati kõige uuema ebastabiilse kandidaatversiooni, mida näitab nimes sisalduv RC ehk "release candidate". Produktsioonikeskkonda tuleks siiski valida stabiilse versiooni. Käsitsi installeerimine on sarnane järgmisega:
<pre>
wget http://mirror.nexcess.net/apache/tomcat/tomcat-8/v8.0.0-RC5/bin/apache-tomcat-8.0.0-RC5.tar.gz
tar -zxvf apache-tomcat-8.0.0-RC5.tar.gz
mv /Users/kristjanveskimae/downloads/apache-tomcat-8.0.0-RC5 /usr/local/apache-tomcat-8.0.0-RC5
rm -f /Library/Tomcat
ln -s /usr/local/apache-tomcat-8.0.0-RC5/ /Library/Tomcat
chown -R kristjanveskimae /Library/Tomcat
chmod +x /Library/Tomcat/bin/*.sh
</pre>

==Käivitamine ja aplikatsiooni juurutamine==

===Konteineri käivitamine===

Tomcati käivitamise eelduseks on Java paigaldamine masinasse ning keskkonnamuutujate "JAVA_HOME" ja "JRE_HOME" defineerimine. Peale installeerimist võib kasutada skripte kataloogist $CATALINA_BASE/bin . Järgneb üks võimalik käivitamise ja peatamise näide, mis on kasutatav eelnevalt kirjeldatud käsitsi installeerimise juhul:
<pre>
/Library/Tomcat/bin/startup.sh
</pre>
ja peatamiseks
<pre>
/Library/Tomcat/bin/shutdown.sh
</pre>

===Näiteaplikatsiooni juurutamine===

Java veebiaplikatsiooni jagatakse hea tava kohaselt üheainsa veebiarhiivi failina. Siiski võib Tomcati juurutada ka lahtipakendatud olekus ("exploded") Java veebiaplikatsiooni.

====Käsitsi juurutamine ja mahavõtmine====

Näiteaplikatsiooni juurutamiseks lae selle veebiarhiivifail alla ning kopeeri oma konteineri juurutamiskataloogi 'webapps':
<pre>wget http://tomcat.apache.org/tomcat-8.0-doc/appdev/sample/sample.war
cp /Users/kristjanveskimae/downloads/sample.war /Library/Tomcat/webapps/sample.war</pre>

[[File:sample_app.png|400px|thumb|right|Pilt 1: Õnnestunult rakendatud näiteaplikatsioon]]

Kui konfiguratsioonifailis $CATALINA_BASE/conf/server.xml on märgendi "Host" atribuudi "autoDeploy" väärtus "true", installeerib ja uuendab Tomcat aplikatsioone dünaamiliselt töötamise ajal. Kui väärtuseks on "false", käib installeerimine staatiliselt ning serverisse juurutamiseks tuleb teha konteineri taaskäivitus. [http://tomcat.apache.org/tomcat-8.0-doc/manager-howto.html#Deploy_A_New_Application_from_a_Local_Path 1] Mõlemal juhul pakib konteiner arhiveeritud faili ise lahti samasse kausta $CATALINA_BASE/webapps ning ka juurutab selle. Tekkiv aplikatsioon on lokaalsest masinast seejärel kättesaadav aadressil http://localhost:8080/sample/ . Kui rakendamine õnnestub, siis peaks olema brauserist nähtav sarnane lehekülg nagu pildil 1.

Veebirakenduse käsitsi mahavõtmiseks tuleb kustutada talle vastav dokumendipõhja kataloog "webapps" kataloogist. Samuti tuleks kustutada .war-fail olemaks kindel, et Tomcat ei rakenda uuel käivitamisel veebiaplikatsiooni veebiarhiivifailist. Veelgi lihtsam on mahavõtmine brauseriga haldusrakenduse kaudu.

Rakenduste baaskataloogi "webapps" asukohta saab muuta failis $CATALINA_BASE/conf/server.xml peremehepõhiselt määratava atribuudiga "appBase", sealjuures Tomcati vaikimisi peremees ehk "Host" on "localhost".

====Tomcati vahendid juurutamiseks====

Veebiaplikatsioonide juurutamine ja mahajuurutamine on võimalik ka kaughalduse teel tänu Tomcati internetipõhisele haldusrakendusele. Näiteks saab veebibrauserit kasutades teha serveri põhitoiminguid Tomcati enda HTML-põhise rakendusega "Tomcat Manager". Veebipõhine haldusrakendus töötab ka käsupõhise veebiteenusena, millele on valmis ehitatud Anti ja Maveni integratsioonid. Samuti eksisteerib käsurea kliendirakendus TCD (Tomcat Client Deployer). TCD ei kuulu Tomcati baaskoosseisu, kuid pakub peale serveri administreerimise tavatoimingute ka lisafunktsionaalsust nagu veebirakenduse kokkukompileerimine ja pakendamine. [http://tomcat.apache.org/tomcat-8.0-doc/manager-howto.html#Configuring_Manager_Application_Access 1]

====Haldurakendus "Tomcat Manager"====

Tomcati haldusrakendus "Tomcat Manager" (antud alamjaotuses lihtsalt haldusrakendus) on Tomcati enda veebiaplikatioon Tomcati brauseripõhiseks kaughalduseks, võimaldades muu hulgas järgnevat [http://tomcat.apache.org/tomcat-8.0-doc/manager-howto.html#Introduction 1]:
* Rakendada uue veebiaplikatsiooni war-faili üleslaadimisega;
* Näha kõiki rakendatud veebiaplikatsioone koos aktiivsete sessioonidega;
* Taasrakendada veebirakendust, näiteks veebiarhiivi pakitud klassifailide /WEB-INF/classes või teekide /WEB-INF/lib uuendamisel, kinnijooksmisel jms.;
* Peatada veebirakendust ilma serverist eemaldamata, samuti koos serverist eemaldamisega;
* Vaadata operatsioonisüsteemi ja Java parameetrite väärtusi;
* Näha kõiki saadaolevaid JNDI ressursse, k.a. andmebaasiühendusi, mis aitavad rakenduste programmeerijail defineerida <ResourceLink> elemendid web.xml konfiguratsioonifailis.

Tomcati installatsioon sisaldab haldusrakendust juba vaikimisi. Haldusrakenduse töölepanemiseks tuleb peremeesmasina konfiguratsioonikataloogi $CATALINA_BASE/conf/[enginename]/[hostname] lisada ka fail manager.xml. Vaikimisi valmiskonfigureeritud testrakendusel on see fail juba olemas asukohas $CATALINA_BASE/conf/Catalina/localhost/manager.xml . Rakendus asub vaikimisi aadressil http://[host]/manager/ , vaikimisi konfiguratsioone kasutades lahendub see asukohaks http://localhost:8080/manager/ . [http://tomcat.apache.org/tomcat-8.0-doc/manager-howto.html#Configuring_Manager_Application_Access 1]

====="Tomcat Manager" ligipääsu konfigureerimine=====

Vaikimisi on turvalisuspõhjustel ligipääs haldusrakendusele maha keeratud. Mismoodi täpselt kasutajatel ligipääsu võimaldada sõltub kasutatavast valdusest (realm). Vaikimisi defineerib $CATALINA_BASE/conf/server.xml valduseks "MemoryRealm". Vaikimisi loeb valdus "MemoryRealm" kasutajad failist $CATALINA_BASE/conf/tomcat-users.xml. Antud failis tuleb iga kasutaja defineerida omaette märgendiga <user>, mis näeb välja umbes järgmine [http://tomcat.apache.org/tomcat-8.0-doc/manager-howto.html#Configuring_Manager_Application_Access 1]:
<pre>
<user name="craig" password="secret" roles="manager-gui,manager-script" />
</pre>

Antud kasutajale on defineeritud korraga kaks rolli. Ligipääsu võimaldamiseks tulebki lihtsamal juhul kasutajatefailis $CATALINA_BASE/conf/tomcat-users.xml defineerida enda kasutaja. Kasutaja rolliks võib määrata näiteks "manager-gui", mis võimaldab ligipääsu kogu HTML liidese funktsionaalsusele.

Teised valdused on "JDBCRealm", mille puhul hoitakse kasutajatega seonduvat infot andmebaasis ja JNDIRealm, mille puhul kasutatakse lihtsustatud kataloogisirvimise protokolli (LDAP).
Lisaks saab haldusrakendusele keelata ligipääsu mujalt kui kindlaksmääratud IP-aadressidelt, lisades filtri "RemoteAddrValve" või "RemoteHostValve" konfigureerimisfaili manager.xml näiteks järgmiselt [http://tomcat.apache.org/tomcat-8.0-doc/manager-howto.html#Introduction 1]:
<pre>
<Context privileged="true">
<Valve className="org.apache.catalina.valves.RemoteAddrValve"
allow="127\.0\.0\.1"/>
</Context>
</pre>

=====Juurutamine ja mahavõtmine haldusrakendusega "Tomcat Manager"=====

Juurutamiseks lae kõigepealt veebiarhiivifail üles, kasutades esilehel asuvat sektsiooni "WAR file to deploy".

[[File:tomcat_manager_war_upload.png|800px|thumb|right|Veebiarhiivi üleslaadimise nupp]]

Rakendus kuvatakse seejärel hallatavate rakenduste nimekirjas. Kui konteiner pole seadistatud üleslaetud aplikatsiooni kohe ka ise rakendama, tuleb vajutada "Start". Rakenduse peatamiseks kasuta "Stop", uuesti rakendamiseks "Redeploy" ja serverist eemaldamiseks "Undeploy".


[[File:tomcat_manager_apps_list.png|800px|Rakenduste nimekiri]]

==Näpunäiteid Tomcati reaalseks kasutamiseks==

===Juurutamise järjekord===

Tomcati käivitumisel juurutatakse aplikatsioonid sellises järjekorras [http://www.mulesoft.com/tomcat-deploy-procedures 2]:
# Konteinerisse kopeeritud kontekstikirjelduste järgi $CATALINA_BASE/conf/[EngineName]/[HostName]/[ApplicationName].xml ;
# Lahtipakitud rakendused "webapps" kataloogis;
# Pakitud rakenduste veebiarhiivid "webapps" kataloogis.

Seetõttu peaks käsitsi taasjuurutamisel kindluse mõttes eelnevalt kustutama rakenduse lahtipakitud dokumendipõhja kataloogi "webapps" kataloogist. Kontekstikirjelduse muutumisel tuleb jälgida, kas kirjeldus on juba kopeeritud serverisse ning vajadusel eelmise versiooni ümber muuta või kustutada.

===Reaalsele domeenile konfigureerimine===

Järgnevalt eeldame, et domeen ''www.minukodukas.ee'' on juba serverimasinaga seostatud. Et Tomcat hakkaks ka reaalselt Internetist tulevatele päringutele vastama, tuleb muuta failis $CATALINA_BASE/conf/server.xml konteinerile ''Catalina'' vastava teenusemärgendi sisu sarnaselt järgnevaga:

<pre>
<Service name="Catalina">
<Connector port="80" protocol="HTTP/1.1" connectionTimeout="20000" URIEncoding="UTF-8" redirectPort="8443" />
<Engine name="Catalina" defaultHost="www.minukodukas.ee">
<Host name="www.minukodukas.ee" appBase="webapps" unpackWARs="true" autoDeploy="false" deployOnStartup="false" xmlValidation="false" xmlNamespaceAware="false">
<Context path="" docBase="kodukas" debug="0" reloadable="true" />
</Host>
</Engine>
</Service>
</pre>

Ülal defineerime põhiliselt selle, et Tomcat kuulaks domeeni ''www.minukodukas.ee'' ja kasutaks HTTP päringute jaoks porti 80. Ühtlasti otsib Tomcat juurutatavat rakendust failist $CATALINA_BASE/webapps/kodukas.war. Kuna rajalisandiks on määratud tühi sõne (path=""), siis juurutataksegi aplikatsioon aadressile ''www.minukodukas.ee'' ilma rajalisandita (a'la ''www.minukodukas.ee/wiki''). Seetõttu pakitakse ka veebiarhiiv tegelikult lahti kataloogi $CATALINA_BASE/webapps/ROOT mitte kataloogi $CATALINA_BASE/webapps/kodukas nagu võiks eeldada.

===Käigultvahetus===

Võimaldamaks käigultvahetust (hot deployment) peab konteineri konfiguratsioonifailis $CATALINA_BASE/conf/server.xml olema peremehepõhise märgendi "Host" atribuudi "autoDeploy" väärtus "true". Sel juhul installeerib ja uuendab Tomcat aplikatsioone dünaamiliselt töötamise ajal. Kui väärtuseks on "false", käib installeerimine staatiliselt ning serverisse juurutamiseks tuleb teha konteineri taaskäivitus. Käigultvahetust saab määrata ka peremehe defineerimisel "Host Manager" rakendusega, mis on kättesaadav aadressil http://localhost:8080/host-manager/html . Kasutamiseks tuleb lisada oma kasutajale rolli "admin-gui" (vt. alajaotus ""Tomcat Manager" ligipääsu konfigureerimine").

[[File:host_manager_app.png]]

Käigultvahetust päästikuks on vaikimisi uuendatud veebiarhiivifaili või lahtipakitud veebirakenduse paigutamine "webapps" kataloogi. Käigultvahetuse päästikutele võib failis $CATALINA_BASE/conf/server.xml ka ise lisada kuulatavaid ressursse nagu web.xml muutmine või mõne teegifaili vahetamine (märgendis "Host").

===Klassiteekide väljatõstmine veebiarhiivifailist===

Kõik konteksti poolt kasutatavad Java klassiteegid võib pakendada veebiarhiivi sisse kataloogi "lib", kuid nii võib osutuda veebiarhiivi üleslaadimine ajakulukaks, eriti arenduskeskkonnas. Kui ei teki ohtu, et erinevad rakendused kasutavad sama teegi erinevaid versioone, siis on vahel parem lisada osa teeke konteineri kataloogi $CATALINA_BASE/libs, kust need tehakse siis konteineri poolt kättesaadavaks kõigile konteineris jooksutatavatele kontekstidele. Nii võib vähendada veebiarhiivi faili suurust märgatavalt, mis tõstab kokkuvõttes juurutamiskiirust ja ühes sellega programmeerijate tööviljakust.

===Mälukasutus===

Konteineri poolt kasutatavat mälu saab vaadata haldusrakendusest vajutades lingile "Server Status". Mälukasutus on toodud jaotuses "JVM", kus näidatakse nii maksimaalselt kättesaadavat mälu kui ka parasjagu reserveeritud mälu.

<pre>Free memory: 41.16 MB Total memory: 123.37 MB Max memory: 1027.56 MB</pre>

Mälu suurendamiseks võib näiteks defineerida skriptis $CATALINA_BASE/bin/catalina.sh muutuja "JAVA_OPTS" ning määrata Java mälukasutuse miinimum- ja maksimumväärtused sarnaselt järgnevatega [http://www.mkyong.com/tomcat/tomcat-javalangoutofmemoryerror-permgen-space/ 3]:
<pre>
JAVA_OPTS="-Xms1536m -Xmx1536m -XX:NewSize=256m -XX:MaxNewSize=256m -XX:PermSize=256m -XX:MaxPermSize=256m"
</pre>

===Logifailid===

Vaikimisi defineerib Tomcat failiga $CATALINA_BASE/conf/logging.properties viis logerit, mis tekitavad viis eraldi logifaili.

{| style="background:#cccc99;color:black;width:80%;" border="1" cellpadding="5" cellspacing="0" align="center"
|+ Tomcati tekitatavad logifailid "logs" kataloogis
!Fail !! Kasutus
|- style="background:white; color:black"
| style="width:300px" |catalina.out
| Tomcati käivitus- ja peatamisskriptide väljund, samuti juurutatud rakenduste prindilaused System.out ja veaväljundid System.err
|- style="background:white; color:black"
| style="width:300px" |catalina.[yyyy]-[mm]-[dd].log
| Pööratud (rotated) logifail catalina.out
|- style="background:white; color:black"
| style="width:300px" |host-manager.[yyyy]-[mm]-[dd].log
| Logi peremehehalduse rakendusele (rakendus on kättesaadav kohalikust masinast aadressil http://localhost:8080/host-manager/html )
|- style="background:white; color:black"
| style="width:300px" |localhost.[yyyy]-[mm]-[dd].log
| Peremehe "localhost" logi; mitme virtuaalse peremehe korral tekitatakse igale peremehele oma logi
|- style="background:white; color:black"
| style="width:300px" |localhost_access_log.[yyyy]-[mm]-[dd].txt
| Konteinerisse Internetist saabunud päringute logi
|- style="background:white; color:black"
| style="width:300px" |manager.[yyyy]-[mm]-[dd].log
| Haldusrakenduse tegevuste logi
|}

===Viiteid===

Palju vajalikku võib leida [http://tomcat.apache.org/tomcat-8.0-doc/index.html Tomcat 8 dokumentatsioonist]

Lisaks üks viide põhjalikule Tomcati versioon seitsme ülevaatele: http://www.ntu.edu.sg/home/ehchua/programming/howto/Tomcat_More.html

= Kasutatud materjalid =

#http://tomcat.apache.org/tomcat-8.0-doc/index.html
#http://www.mulesoft.com/tomcat-deploy-procedures
#http://www.mkyong.com/tomcat/tomcat-javalangoutofmemoryerror-permgen-space/

[[Category: Operatsioonisüsteemide administreerimine ja sidumine]]

Tomcat

2014-01-02T22:03:05Z

Kveskima: /* Käsitsi juurutamine ja mahavõtmine */

==Autor==

Kristjan Veskimäe D32

2013

==Sissejuhatus==

Tomcat on vabalt kättesaadav server Java veebirakendustele. Põhimõtteliselt on tegemist Servlet/JSP spetsifikatsiooni toetava konteineriga. Kiire käivitumise ning rakenduste käigultvahetuse tõttu on Tomcat hea valik väiksemate ning keskmise suurusega Java veebirakenduste käitamiseks.

Antud töö kirjeldab Tomcati 8. versiooni. Põhiosa on üldiselt samasugune võrreldes paari eelmise versiooniga. Suuremad erinevused on versioonispetsiifilistes probleemides ja nende lahendamises, mida käesolev töö ei vaatle.

Töö vaatleb Tomcati paigaldamist ja seadistamist Unix-laadsesse keskkonda ning eeldab lugejalt algteadmisi sarnastes süsteemides. Tomcati on võimalik paigaldada ka Windows-keskkonda, kuid antud veebiserver eeldab kasutaja poolt käsureal töötamist ning Tomcati failihierarhias orienteerumist. Põhimõtteliselt on Java veebirakenduste arendamiseks IDE-abil võimalik siiski ka kasutada IDE-sse integreeritud Tomcati serverit - näiteks pakuvad sellist võimalust Eclipse EE ja NetBeans - kuid seda käesolev töö ei vaatle.

==Mõisted==

* '''Kontekst''' (context) - Tomcati mõistes üks konkreetne veebiaplikatsioon
* '''Konteiner''' (container) - veebiserver Tomcat ise
* '''Kontekstikirjeldus''' (context descriptor) - Tomcati-spetsiifiline konteksti konfiguratsioonimääratlus; peremehepõhine osa loetakse failist $CATALINA_HOME/conf/[enginename]/[hostname]/context.xml ja sellele lisatakse kontekstispetsiifilised täpsustused failist $CATALINA_BASE/conf/[enginename]/[hostname]/[webappname].xml; kontekstikirjeldus määrab näiteks nimed ressurssidele, sessioonihalduse parameetrid jmt. (olgu märgitud, et Tomcati varasemates versioonides sisaldusid kontekstikirjeldused põhikonfiguratsioonifailis server.xml)
* '''Dokumendipõhi''' (docBase) - kontekstile vastav kataloog Tomcati "webapps" kataloogis, mis tekib veebiaplikatsiooni serverisse rakendamisel
* '''Veebiarhiiv''' (Web application ARchive, war-file) - Java veebiaplikatsiooni jagatakse hea tava kohaselt selle üheainsa veebiarhiivi failina, mille laienditüübiks on "war". Tegemist on zip-protokolliga kokkupakitud kataloogiga, millel on Java veebirakenduste spetsifikatsioonile vastav ülesehitus. Siiski võib veebiaplikatsioon olla juurutamisel ka lahtipakendatud olekus (inglisekeelne termin on "war is exploded").

==Ülesehitus==

{| class="wikitable"
|+Kataloogid
|-
|style="color: green;" | $CATALINA_HOME
|baaskataloog, kuhu on Tomcat paigutatud
|-
|style="color: green;" | $CATALINA_BASE
|parasjagu töösoleva Tomcati eksemplari baaskataloog, mille alusel lahendatakse teed ülejäänud kataloogide ja failideni; ainult ühe kasutusel oleva Tomcati eksemplari puhul on see sama, mis $CATALINA_HOME

|-
|style="color: green;" | $CATALINA_BASE/bin
|serveri käivitus- ja abiskriptid
|-
|style="color: green;" | $CATALINA_BASE/conf
|konfiguratsioonifailid
|-
|style="color: green;" | $CATALINA_BASE/lib
|Tomcatile vaikimisi kättesaadavad Java klassiteegid (class libraries) ehk .jar-failid kuhu on Java kompileeritud kood kokku pakendatud
|-
|style="color: green;" | $CATALINA_BASE/logs
|logifailid paigutatakse vaikimisi siia
|-
|style="color: green;" | $CATALINA_BASE/webapps
|kataloog, kuhu paigutatakse serverisse juurutatavad veebiaplikatsioonid

|}

{| class="wikitable"
|+Mõned olulisemad failid
|-
|style="color: green;" | $CATALINA_BASE/bin/startup.sh
|serveri käivitusskript
|-
|style="color: green;" | $CATALINA_BASE/bin/shutdown.sh
|serveri peatusskript

|-
|style="color: green;" | $CATALINA_BASE/conf/server.xml
| konteineri peamine konfiguratsioonifail
|-
|style="color: green;" | $CATALINA_BASE/conf/[enginename]/[hostname]/[webappname].xml
|serveri administraatori jaoks konteinerisse endasse ümber kopeeritud rakendusepõhine kontekstikirjelduse konfiguratsioon failist $CATALINA_BASE/webapps/[ApplicationName]/META-INF/context.xml
|-
|style="color: green;" | $CATALINA_BASE/conf/[enginename]/[hostname]/context.xml
| fail, mis aitab administraatoril konteksti kohta käivat infot kirjeldada peremeesmasina-põhiselt ja halduseks mõeldud automaat-tööriistadel (näiteks Tomcat Manager ja TCD) oma tööd teha
|-
|style="color: green;" | $CATALINA_BASE/$CATALINA_BASE/conf/[enginename]/[hostname]/manager.xml
|fail, mis võimaldab lisada rakendustele ligipääsufiltreid
|-
|style="color: green;" | $CATALINA_BASE/webapps/[webappname]/META-INF/context.xml
|kontekstikirjeldusfail, mille veebirakenduse programmeerija on pakendanud oma aplikatsiooniga kaasa ning millega ta saab võimaluse kontekstikirjeldust omalt poolt mõjutada; kirjutatakse rakenduse uuestijuurutamisel üle, mistõttu administraator peaks muutma selle asemel konteinerisse ümber kopeeritud püsieksemplari $CATALINA_BASE/conf/[enginename]/[hostname]/context.xml
|-
|style="color: green;" | $CATALINA_BASE/webapps/[webappname]/WEB-INF/web.xml
|ka üks oluline Java veebiaplikatsiooni konfiguratsioonifail, mille pakendatakse koos veebiarhiiviga; enamasti muudab seda ainult programeerija; määrab muu hulgas millised aplikatsiooni osad vajavad autentimist või kui kiiresti veebisessioon aegub
|}

==Installeerimine==

===Installeerimine paketihalduriga===

<pre>
apt-cache search tomcat
apt-get install tomcat[version]-webapps
apt-get install tomcat[version]-admin
apt-get install tomcat[version]
</pre>

===Installeerimine käsitsi===

Paketihalduriga installeerides ei pruugi viimane Tomcati versioon olla kättesaadav ja see pakub ka vähem võimalusi kataloogide määramiseks jms. Käsitsi installeerimiseks tuleb laadida Tomcat kodulehelt alla. Lahtipakkimisel tekib kataloog, milles sisalduv fail "RUNNING.txt" on kõige kindlam allikas installeerimisel tekkivate probleemide vältimiseks ning lahendamiseks.

Vajaliku versiooni installeerimisfaili asukoha saab vaadata Tomcati kodulehelt sektsioonist "Download". Järgnevas näites installeerime Tomcati kõige uuema ebastabiilse kandidaatversiooni, mida näitab nimes sisalduv RC ehk "release candidate". Produktsioonikeskkonda tuleks siiski valida stabiilse versiooni. Käsitsi installeerimine on sarnane järgmisega:
<pre>
wget http://mirror.nexcess.net/apache/tomcat/tomcat-8/v8.0.0-RC5/bin/apache-tomcat-8.0.0-RC5.tar.gz
tar -zxvf apache-tomcat-8.0.0-RC5.tar.gz
mv /Users/kristjanveskimae/downloads/apache-tomcat-8.0.0-RC5 /usr/local/apache-tomcat-8.0.0-RC5
rm -f /Library/Tomcat
ln -s /usr/local/apache-tomcat-8.0.0-RC5/ /Library/Tomcat
chown -R kristjanveskimae /Library/Tomcat
chmod +x /Library/Tomcat/bin/*.sh
</pre>

==Käivitamine ja aplikatsiooni juurutamine==

===Konteineri käivitamine===

Tomcati käivitamise eelduseks on Java paigaldamine masinasse ning keskkonnamuutujate "JAVA_HOME" ja "JRE_HOME" defineerimine. Peale installeerimist võib kasutada skripte kataloogist $CATALINA_BASE/bin . Järgneb üks võimalik käivitamise ja peatamise näide, mis on kasutatav eelnevalt kirjeldatud käsitsi installeerimise juhul:
<pre>
/Library/Tomcat/bin/startup.sh
</pre>
ja peatamiseks
<pre>
/Library/Tomcat/bin/shutdown.sh
</pre>

===Näiteaplikatsiooni juurutamine===

Java veebiaplikatsiooni jagatakse hea tava kohaselt üheainsa veebiarhiivi failina. Siiski võib Tomcati juurutada ka lahtipakendatud olekus ("exploded") Java veebiaplikatsiooni.

====Käsitsi juurutamine ja mahavõtmine====

Näiteaplikatsiooni juurutamiseks lae selle veebiarhiivifail alla ning kopeeri oma konteineri juurutamiskataloogi 'webapps':
<pre>wget http://tomcat.apache.org/tomcat-8.0-doc/appdev/sample/sample.war
cp /Users/kristjanveskimae/downloads/sample.war /Library/Tomcat/webapps/sample.war</pre>

[[File:sample_app.png|400px|thumb|right|Joonis 1: Õnnestunult rakendatud näiteaplikatsioon]]

Kui konfiguratsioonifailis $CATALINA_BASE/conf/server.xml on märgendi "Host" atribuudi "autoDeploy" väärtus "true", installeerib ja uuendab Tomcat aplikatsioone dünaamiliselt töötamise ajal. Kui väärtuseks on "false", käib installeerimine staatiliselt ning serverisse juurutamiseks tuleb teha konteineri taaskäivitus. [http://tomcat.apache.org/tomcat-8.0-doc/manager-howto.html#Deploy_A_New_Application_from_a_Local_Path 1] Mõlemal juhul pakib konteiner arhiveeritud faili ise lahti samasse kausta $CATALINA_BASE/webapps ning ka juurutab selle. Tekkiv aplikatsioon on lokaalsest masinast seejärel kättesaadav aadressil http://localhost:8080/sample/ . Kui rakendamine õnnestub, siis peaks olema brauserist nähtav sarnane lehekülg nagu pildil 1.

Veebirakenduse käsitsi mahavõtmiseks tuleb kustutada talle vastav dokumendipõhja kataloog "webapps" kataloogist. Samuti tuleks kustutada .war-fail olemaks kindel, et Tomcat ei rakenda uuel käivitamisel veebiaplikatsiooni veebiarhiivifailist. Veelgi lihtsam on mahavõtmine brauseriga haldusrakenduse kaudu.

Rakenduste baaskataloogi "webapps" asukohta saab muuta failis $CATALINA_BASE/conf/server.xml peremehepõhiselt määratava atribuudiga "appBase", sealjuures Tomcati vaikimisi peremees ehk "Host" on "localhost".

====Tomcati vahendid juurutamiseks====

Veebiaplikatsioonide juurutamine ja mahajuurutamine on võimalik ka kaughalduse teel tänu Tomcati internetipõhisele haldusrakendusele. Näiteks saab veebibrauserit kasutades teha serveri põhitoiminguid Tomcati enda HTML-põhise rakendusega "Tomcat Manager". Veebipõhine haldusrakendus töötab ka käsupõhise veebiteenusena, millele on valmis ehitatud Anti ja Maveni integratsioonid. Samuti eksisteerib käsurea kliendirakendus TCD (Tomcat Client Deployer). TCD ei kuulu Tomcati baaskoosseisu, kuid pakub peale serveri administreerimise tavatoimingute ka lisafunktsionaalsust nagu veebirakenduse kokkukompileerimine ja pakendamine. [http://tomcat.apache.org/tomcat-8.0-doc/manager-howto.html#Configuring_Manager_Application_Access 1]

====Haldurakendus "Tomcat Manager"====

Tomcati haldusrakendus "Tomcat Manager" (antud alamjaotuses lihtsalt haldusrakendus) on Tomcati enda veebiaplikatioon Tomcati brauseripõhiseks kaughalduseks, võimaldades muu hulgas järgnevat [http://tomcat.apache.org/tomcat-8.0-doc/manager-howto.html#Introduction 1]:
* Rakendada uue veebiaplikatsiooni war-faili üleslaadimisega;
* Näha kõiki rakendatud veebiaplikatsioone koos aktiivsete sessioonidega;
* Taasrakendada veebirakendust, näiteks veebiarhiivi pakitud klassifailide /WEB-INF/classes või teekide /WEB-INF/lib uuendamisel, kinnijooksmisel jms.;
* Peatada veebirakendust ilma serverist eemaldamata, samuti koos serverist eemaldamisega;
* Vaadata operatsioonisüsteemi ja Java parameetrite väärtusi;
* Näha kõiki saadaolevaid JNDI ressursse, k.a. andmebaasiühendusi, mis aitavad rakenduste programmeerijail defineerida <ResourceLink> elemendid web.xml konfiguratsioonifailis.

Tomcati installatsioon sisaldab haldusrakendust juba vaikimisi. Haldusrakenduse töölepanemiseks tuleb peremeesmasina konfiguratsioonikataloogi $CATALINA_BASE/conf/[enginename]/[hostname] lisada ka fail manager.xml. Vaikimisi valmiskonfigureeritud testrakendusel on see fail juba olemas asukohas $CATALINA_BASE/conf/Catalina/localhost/manager.xml . Rakendus asub vaikimisi aadressil http://[host]/manager/ , vaikimisi konfiguratsioone kasutades lahendub see asukohaks http://localhost:8080/manager/ . [http://tomcat.apache.org/tomcat-8.0-doc/manager-howto.html#Configuring_Manager_Application_Access 1]

====="Tomcat Manager" ligipääsu konfigureerimine=====

Vaikimisi on turvalisuspõhjustel ligipääs haldusrakendusele maha keeratud. Mismoodi täpselt kasutajatel ligipääsu võimaldada sõltub kasutatavast valdusest (realm). Vaikimisi defineerib $CATALINA_BASE/conf/server.xml valduseks "MemoryRealm". Vaikimisi loeb valdus "MemoryRealm" kasutajad failist $CATALINA_BASE/conf/tomcat-users.xml. Antud failis tuleb iga kasutaja defineerida omaette märgendiga <user>, mis näeb välja umbes järgmine [http://tomcat.apache.org/tomcat-8.0-doc/manager-howto.html#Configuring_Manager_Application_Access 1]:
<pre>
<user name="craig" password="secret" roles="manager-gui,manager-script" />
</pre>

Antud kasutajale on defineeritud korraga kaks rolli. Ligipääsu võimaldamiseks tulebki lihtsamal juhul kasutajatefailis $CATALINA_BASE/conf/tomcat-users.xml defineerida enda kasutaja. Kasutaja rolliks võib määrata näiteks "manager-gui", mis võimaldab ligipääsu kogu HTML liidese funktsionaalsusele.

Teised valdused on "JDBCRealm", mille puhul hoitakse kasutajatega seonduvat infot andmebaasis ja JNDIRealm, mille puhul kasutatakse lihtsustatud kataloogisirvimise protokolli (LDAP).
Lisaks saab haldusrakendusele keelata ligipääsu mujalt kui kindlaksmääratud IP-aadressidelt, lisades filtri "RemoteAddrValve" või "RemoteHostValve" konfigureerimisfaili manager.xml näiteks järgmiselt [http://tomcat.apache.org/tomcat-8.0-doc/manager-howto.html#Introduction 1]:
<pre>
<Context privileged="true">
<Valve className="org.apache.catalina.valves.RemoteAddrValve"
allow="127\.0\.0\.1"/>
</Context>
</pre>

=====Juurutamine ja mahavõtmine haldusrakendusega "Tomcat Manager"=====

Juurutamiseks lae kõigepealt veebiarhiivifail üles, kasutades esilehel asuvat sektsiooni "WAR file to deploy".

[[File:tomcat_manager_war_upload.png|800px|thumb|right|Veebiarhiivi üleslaadimise nupp]]

Rakendus kuvatakse seejärel hallatavate rakenduste nimekirjas. Kui konteiner pole seadistatud üleslaetud aplikatsiooni kohe ka ise rakendama, tuleb vajutada "Start". Rakenduse peatamiseks kasuta "Stop", uuesti rakendamiseks "Redeploy" ja serverist eemaldamiseks "Undeploy".


[[File:tomcat_manager_apps_list.png|800px|Rakenduste nimekiri]]

==Näpunäiteid Tomcati reaalseks kasutamiseks==

===Juurutamise järjekord===

Tomcati käivitumisel juurutatakse aplikatsioonid sellises järjekorras [http://www.mulesoft.com/tomcat-deploy-procedures 2]:
# Konteinerisse kopeeritud kontekstikirjelduste järgi $CATALINA_BASE/conf/[EngineName]/[HostName]/[ApplicationName].xml ;
# Lahtipakitud rakendused "webapps" kataloogis;
# Pakitud rakenduste veebiarhiivid "webapps" kataloogis.

Seetõttu peaks käsitsi taasjuurutamisel kindluse mõttes eelnevalt kustutama rakenduse lahtipakitud dokumendipõhja kataloogi "webapps" kataloogist. Kontekstikirjelduse muutumisel tuleb jälgida, kas kirjeldus on juba kopeeritud serverisse ning vajadusel eelmise versiooni ümber muuta või kustutada.

===Reaalsele domeenile konfigureerimine===

Järgnevalt eeldame, et domeen ''www.minukodukas.ee'' on juba serverimasinaga seostatud. Et Tomcat hakkaks ka reaalselt Internetist tulevatele päringutele vastama, tuleb muuta failis $CATALINA_BASE/conf/server.xml konteinerile ''Catalina'' vastava teenusemärgendi sisu sarnaselt järgnevaga:

<pre>
<Service name="Catalina">
<Connector port="80" protocol="HTTP/1.1" connectionTimeout="20000" URIEncoding="UTF-8" redirectPort="8443" />
<Engine name="Catalina" defaultHost="www.minukodukas.ee">
<Host name="www.minukodukas.ee" appBase="webapps" unpackWARs="true" autoDeploy="false" deployOnStartup="false" xmlValidation="false" xmlNamespaceAware="false">
<Context path="" docBase="kodukas" debug="0" reloadable="true" />
</Host>
</Engine>
</Service>
</pre>

Ülal defineerime põhiliselt selle, et Tomcat kuulaks domeeni ''www.minukodukas.ee'' ja kasutaks HTTP päringute jaoks porti 80. Ühtlasti otsib Tomcat juurutatavat rakendust failist $CATALINA_BASE/webapps/kodukas.war. Kuna rajalisandiks on määratud tühi sõne (path=""), siis juurutataksegi aplikatsioon aadressile ''www.minukodukas.ee'' ilma rajalisandita (a'la ''www.minukodukas.ee/wiki''). Seetõttu pakitakse ka veebiarhiiv tegelikult lahti kataloogi $CATALINA_BASE/webapps/ROOT mitte kataloogi $CATALINA_BASE/webapps/kodukas nagu võiks eeldada.

===Käigultvahetus===

Võimaldamaks käigultvahetust (hot deployment) peab konteineri konfiguratsioonifailis $CATALINA_BASE/conf/server.xml olema peremehepõhise märgendi "Host" atribuudi "autoDeploy" väärtus "true". Sel juhul installeerib ja uuendab Tomcat aplikatsioone dünaamiliselt töötamise ajal. Kui väärtuseks on "false", käib installeerimine staatiliselt ning serverisse juurutamiseks tuleb teha konteineri taaskäivitus. Käigultvahetust saab määrata ka peremehe defineerimisel "Host Manager" rakendusega, mis on kättesaadav aadressil http://localhost:8080/host-manager/html . Kasutamiseks tuleb lisada oma kasutajale rolli "admin-gui" (vt. alajaotus ""Tomcat Manager" ligipääsu konfigureerimine").

[[File:host_manager_app.png]]

Käigultvahetust päästikuks on vaikimisi uuendatud veebiarhiivifaili või lahtipakitud veebirakenduse paigutamine "webapps" kataloogi. Käigultvahetuse päästikutele võib failis $CATALINA_BASE/conf/server.xml ka ise lisada kuulatavaid ressursse nagu web.xml muutmine või mõne teegifaili vahetamine (märgendis "Host").

===Klassiteekide väljatõstmine veebiarhiivifailist===

Kõik konteksti poolt kasutatavad Java klassiteegid võib pakendada veebiarhiivi sisse kataloogi "lib", kuid nii võib osutuda veebiarhiivi üleslaadimine ajakulukaks, eriti arenduskeskkonnas. Kui ei teki ohtu, et erinevad rakendused kasutavad sama teegi erinevaid versioone, siis on vahel parem lisada osa teeke konteineri kataloogi $CATALINA_BASE/libs, kust need tehakse siis konteineri poolt kättesaadavaks kõigile konteineris jooksutatavatele kontekstidele. Nii võib vähendada veebiarhiivi faili suurust märgatavalt, mis tõstab kokkuvõttes juurutamiskiirust ja ühes sellega programmeerijate tööviljakust.

===Mälukasutus===

Konteineri poolt kasutatavat mälu saab vaadata haldusrakendusest vajutades lingile "Server Status". Mälukasutus on toodud jaotuses "JVM", kus näidatakse nii maksimaalselt kättesaadavat mälu kui ka parasjagu reserveeritud mälu.

<pre>Free memory: 41.16 MB Total memory: 123.37 MB Max memory: 1027.56 MB</pre>

Mälu suurendamiseks võib näiteks defineerida skriptis $CATALINA_BASE/bin/catalina.sh muutuja "JAVA_OPTS" ning määrata Java mälukasutuse miinimum- ja maksimumväärtused sarnaselt järgnevatega [http://www.mkyong.com/tomcat/tomcat-javalangoutofmemoryerror-permgen-space/ 3]:
<pre>
JAVA_OPTS="-Xms1536m -Xmx1536m -XX:NewSize=256m -XX:MaxNewSize=256m -XX:PermSize=256m -XX:MaxPermSize=256m"
</pre>

===Logifailid===

Vaikimisi defineerib Tomcat failiga $CATALINA_BASE/conf/logging.properties viis logerit, mis tekitavad viis eraldi logifaili.

{| style="background:#cccc99;color:black;width:80%;" border="1" cellpadding="5" cellspacing="0" align="center"
|+ Tomcati tekitatavad logifailid "logs" kataloogis
!Fail !! Kasutus
|- style="background:white; color:black"
| style="width:300px" |catalina.out
| Tomcati käivitus- ja peatamisskriptide väljund, samuti juurutatud rakenduste prindilaused System.out ja veaväljundid System.err
|- style="background:white; color:black"
| style="width:300px" |catalina.[yyyy]-[mm]-[dd].log
| Pööratud (rotated) logifail catalina.out
|- style="background:white; color:black"
| style="width:300px" |host-manager.[yyyy]-[mm]-[dd].log
| Logi peremehehalduse rakendusele (rakendus on kättesaadav kohalikust masinast aadressil http://localhost:8080/host-manager/html )
|- style="background:white; color:black"
| style="width:300px" |localhost.[yyyy]-[mm]-[dd].log
| Peremehe "localhost" logi; mitme virtuaalse peremehe korral tekitatakse igale peremehele oma logi
|- style="background:white; color:black"
| style="width:300px" |localhost_access_log.[yyyy]-[mm]-[dd].txt
| Konteinerisse Internetist saabunud päringute logi
|- style="background:white; color:black"
| style="width:300px" |manager.[yyyy]-[mm]-[dd].log
| Haldusrakenduse tegevuste logi
|}

===Viiteid===

Palju vajalikku võib leida [http://tomcat.apache.org/tomcat-8.0-doc/index.html Tomcat 8 dokumentatsioonist]

Lisaks üks viide põhjalikule Tomcati versioon seitsme ülevaatele: http://www.ntu.edu.sg/home/ehchua/programming/howto/Tomcat_More.html

= Kasutatud materjalid =

#http://tomcat.apache.org/tomcat-8.0-doc/index.html
#http://www.mulesoft.com/tomcat-deploy-procedures
#http://www.mkyong.com/tomcat/tomcat-javalangoutofmemoryerror-permgen-space/

[[Category: Operatsioonisüsteemide administreerimine ja sidumine]]

Tomcat

2014-01-02T22:02:21Z

Kveskima: /* Käsitsi juurutamine ja mahavõtmine */

==Autor==

Kristjan Veskimäe D32

2013

==Sissejuhatus==

Tomcat on vabalt kättesaadav server Java veebirakendustele. Põhimõtteliselt on tegemist Servlet/JSP spetsifikatsiooni toetava konteineriga. Kiire käivitumise ning rakenduste käigultvahetuse tõttu on Tomcat hea valik väiksemate ning keskmise suurusega Java veebirakenduste käitamiseks.

Antud töö kirjeldab Tomcati 8. versiooni. Põhiosa on üldiselt samasugune võrreldes paari eelmise versiooniga. Suuremad erinevused on versioonispetsiifilistes probleemides ja nende lahendamises, mida käesolev töö ei vaatle.

Töö vaatleb Tomcati paigaldamist ja seadistamist Unix-laadsesse keskkonda ning eeldab lugejalt algteadmisi sarnastes süsteemides. Tomcati on võimalik paigaldada ka Windows-keskkonda, kuid antud veebiserver eeldab kasutaja poolt käsureal töötamist ning Tomcati failihierarhias orienteerumist. Põhimõtteliselt on Java veebirakenduste arendamiseks IDE-abil võimalik siiski ka kasutada IDE-sse integreeritud Tomcati serverit - näiteks pakuvad sellist võimalust Eclipse EE ja NetBeans - kuid seda käesolev töö ei vaatle.

==Mõisted==

* '''Kontekst''' (context) - Tomcati mõistes üks konkreetne veebiaplikatsioon
* '''Konteiner''' (container) - veebiserver Tomcat ise
* '''Kontekstikirjeldus''' (context descriptor) - Tomcati-spetsiifiline konteksti konfiguratsioonimääratlus; peremehepõhine osa loetakse failist $CATALINA_HOME/conf/[enginename]/[hostname]/context.xml ja sellele lisatakse kontekstispetsiifilised täpsustused failist $CATALINA_BASE/conf/[enginename]/[hostname]/[webappname].xml; kontekstikirjeldus määrab näiteks nimed ressurssidele, sessioonihalduse parameetrid jmt. (olgu märgitud, et Tomcati varasemates versioonides sisaldusid kontekstikirjeldused põhikonfiguratsioonifailis server.xml)
* '''Dokumendipõhi''' (docBase) - kontekstile vastav kataloog Tomcati "webapps" kataloogis, mis tekib veebiaplikatsiooni serverisse rakendamisel
* '''Veebiarhiiv''' (Web application ARchive, war-file) - Java veebiaplikatsiooni jagatakse hea tava kohaselt selle üheainsa veebiarhiivi failina, mille laienditüübiks on "war". Tegemist on zip-protokolliga kokkupakitud kataloogiga, millel on Java veebirakenduste spetsifikatsioonile vastav ülesehitus. Siiski võib veebiaplikatsioon olla juurutamisel ka lahtipakendatud olekus (inglisekeelne termin on "war is exploded").

==Ülesehitus==

{| class="wikitable"
|+Kataloogid
|-
|style="color: green;" | $CATALINA_HOME
|baaskataloog, kuhu on Tomcat paigutatud
|-
|style="color: green;" | $CATALINA_BASE
|parasjagu töösoleva Tomcati eksemplari baaskataloog, mille alusel lahendatakse teed ülejäänud kataloogide ja failideni; ainult ühe kasutusel oleva Tomcati eksemplari puhul on see sama, mis $CATALINA_HOME

|-
|style="color: green;" | $CATALINA_BASE/bin
|serveri käivitus- ja abiskriptid
|-
|style="color: green;" | $CATALINA_BASE/conf
|konfiguratsioonifailid
|-
|style="color: green;" | $CATALINA_BASE/lib
|Tomcatile vaikimisi kättesaadavad Java klassiteegid (class libraries) ehk .jar-failid kuhu on Java kompileeritud kood kokku pakendatud
|-
|style="color: green;" | $CATALINA_BASE/logs
|logifailid paigutatakse vaikimisi siia
|-
|style="color: green;" | $CATALINA_BASE/webapps
|kataloog, kuhu paigutatakse serverisse juurutatavad veebiaplikatsioonid

|}

{| class="wikitable"
|+Mõned olulisemad failid
|-
|style="color: green;" | $CATALINA_BASE/bin/startup.sh
|serveri käivitusskript
|-
|style="color: green;" | $CATALINA_BASE/bin/shutdown.sh
|serveri peatusskript

|-
|style="color: green;" | $CATALINA_BASE/conf/server.xml
| konteineri peamine konfiguratsioonifail
|-
|style="color: green;" | $CATALINA_BASE/conf/[enginename]/[hostname]/[webappname].xml
|serveri administraatori jaoks konteinerisse endasse ümber kopeeritud rakendusepõhine kontekstikirjelduse konfiguratsioon failist $CATALINA_BASE/webapps/[ApplicationName]/META-INF/context.xml
|-
|style="color: green;" | $CATALINA_BASE/conf/[enginename]/[hostname]/context.xml
| fail, mis aitab administraatoril konteksti kohta käivat infot kirjeldada peremeesmasina-põhiselt ja halduseks mõeldud automaat-tööriistadel (näiteks Tomcat Manager ja TCD) oma tööd teha
|-
|style="color: green;" | $CATALINA_BASE/$CATALINA_BASE/conf/[enginename]/[hostname]/manager.xml
|fail, mis võimaldab lisada rakendustele ligipääsufiltreid
|-
|style="color: green;" | $CATALINA_BASE/webapps/[webappname]/META-INF/context.xml
|kontekstikirjeldusfail, mille veebirakenduse programmeerija on pakendanud oma aplikatsiooniga kaasa ning millega ta saab võimaluse kontekstikirjeldust omalt poolt mõjutada; kirjutatakse rakenduse uuestijuurutamisel üle, mistõttu administraator peaks muutma selle asemel konteinerisse ümber kopeeritud püsieksemplari $CATALINA_BASE/conf/[enginename]/[hostname]/context.xml
|-
|style="color: green;" | $CATALINA_BASE/webapps/[webappname]/WEB-INF/web.xml
|ka üks oluline Java veebiaplikatsiooni konfiguratsioonifail, mille pakendatakse koos veebiarhiiviga; enamasti muudab seda ainult programeerija; määrab muu hulgas millised aplikatsiooni osad vajavad autentimist või kui kiiresti veebisessioon aegub
|}

==Installeerimine==

===Installeerimine paketihalduriga===

<pre>
apt-cache search tomcat
apt-get install tomcat[version]-webapps
apt-get install tomcat[version]-admin
apt-get install tomcat[version]
</pre>

===Installeerimine käsitsi===

Paketihalduriga installeerides ei pruugi viimane Tomcati versioon olla kättesaadav ja see pakub ka vähem võimalusi kataloogide määramiseks jms. Käsitsi installeerimiseks tuleb laadida Tomcat kodulehelt alla. Lahtipakkimisel tekib kataloog, milles sisalduv fail "RUNNING.txt" on kõige kindlam allikas installeerimisel tekkivate probleemide vältimiseks ning lahendamiseks.

Vajaliku versiooni installeerimisfaili asukoha saab vaadata Tomcati kodulehelt sektsioonist "Download". Järgnevas näites installeerime Tomcati kõige uuema ebastabiilse kandidaatversiooni, mida näitab nimes sisalduv RC ehk "release candidate". Produktsioonikeskkonda tuleks siiski valida stabiilse versiooni. Käsitsi installeerimine on sarnane järgmisega:
<pre>
wget http://mirror.nexcess.net/apache/tomcat/tomcat-8/v8.0.0-RC5/bin/apache-tomcat-8.0.0-RC5.tar.gz
tar -zxvf apache-tomcat-8.0.0-RC5.tar.gz
mv /Users/kristjanveskimae/downloads/apache-tomcat-8.0.0-RC5 /usr/local/apache-tomcat-8.0.0-RC5
rm -f /Library/Tomcat
ln -s /usr/local/apache-tomcat-8.0.0-RC5/ /Library/Tomcat
chown -R kristjanveskimae /Library/Tomcat
chmod +x /Library/Tomcat/bin/*.sh
</pre>

==Käivitamine ja aplikatsiooni juurutamine==

===Konteineri käivitamine===

Tomcati käivitamise eelduseks on Java paigaldamine masinasse ning keskkonnamuutujate "JAVA_HOME" ja "JRE_HOME" defineerimine. Peale installeerimist võib kasutada skripte kataloogist $CATALINA_BASE/bin . Järgneb üks võimalik käivitamise ja peatamise näide, mis on kasutatav eelnevalt kirjeldatud käsitsi installeerimise juhul:
<pre>
/Library/Tomcat/bin/startup.sh
</pre>
ja peatamiseks
<pre>
/Library/Tomcat/bin/shutdown.sh
</pre>

===Näiteaplikatsiooni juurutamine===

Java veebiaplikatsiooni jagatakse hea tava kohaselt üheainsa veebiarhiivi failina. Siiski võib Tomcati juurutada ka lahtipakendatud olekus ("exploded") Java veebiaplikatsiooni.

====Käsitsi juurutamine ja mahavõtmine====

Näiteaplikatsiooni juurutamiseks lae selle veebiarhiivifail alla ning kopeeri oma konteineri juurutamiskataloogi 'webapps':
<pre>wget http://tomcat.apache.org/tomcat-8.0-doc/appdev/sample/sample.war
cp /Users/kristjanveskimae/downloads/sample.war /Library/Tomcat/webapps/sample.war</pre>

[[File:sample_app.png|400px|thumb|right|Joonis 1: Õnnestunult rakendatud näiteaplikatsioon]]

Kui konfiguratsioonifailis $CATALINA_BASE/conf/server.xml on märgendi "Host" atribuudi "autoDeploy" väärtus "true", installeerib ja uuendab Tomcat aplikatsioone dünaamiliselt töötamise ajal. Kui väärtuseks on "false", käib installeerimine staatiliselt ning serverisse juurutamiseks tuleb teha konteineri taaskäivitus. [http://tomcat.apache.org/tomcat-8.0-doc/manager-howto.html#Deploy_A_New_Application_from_a_Local_Path 1] Mõlemal juhul pakib konteiner arhiveeritud faili ise lahti samasse kausta $CATALINA_BASE/webapps ning ka juurutab selle. Tekkiv aplikatsioon on lokaalsest masinast seejärel kättesaadav aadressil http://localhost:8080/sample/ .

Veebirakenduse käsitsi mahavõtmiseks tuleb kustutada talle vastav dokumendipõhja kataloog "webapps" kataloogist. Samuti tuleks kustutada .war-fail olemaks kindel, et Tomcat ei rakenda uuel käivitamisel veebiaplikatsiooni veebiarhiivifailist. Veelgi lihtsam on mahavõtmine brauseriga haldusrakenduse kaudu.

Rakenduste baaskataloogi "webapps" asukohta saab muuta failis $CATALINA_BASE/conf/server.xml peremehepõhiselt määratava atribuudiga "appBase", sealjuures Tomcati vaikimisi peremees ehk "Host" on "localhost".

====Tomcati vahendid juurutamiseks====

Veebiaplikatsioonide juurutamine ja mahajuurutamine on võimalik ka kaughalduse teel tänu Tomcati internetipõhisele haldusrakendusele. Näiteks saab veebibrauserit kasutades teha serveri põhitoiminguid Tomcati enda HTML-põhise rakendusega "Tomcat Manager". Veebipõhine haldusrakendus töötab ka käsupõhise veebiteenusena, millele on valmis ehitatud Anti ja Maveni integratsioonid. Samuti eksisteerib käsurea kliendirakendus TCD (Tomcat Client Deployer). TCD ei kuulu Tomcati baaskoosseisu, kuid pakub peale serveri administreerimise tavatoimingute ka lisafunktsionaalsust nagu veebirakenduse kokkukompileerimine ja pakendamine. [http://tomcat.apache.org/tomcat-8.0-doc/manager-howto.html#Configuring_Manager_Application_Access 1]

====Haldurakendus "Tomcat Manager"====

Tomcati haldusrakendus "Tomcat Manager" (antud alamjaotuses lihtsalt haldusrakendus) on Tomcati enda veebiaplikatioon Tomcati brauseripõhiseks kaughalduseks, võimaldades muu hulgas järgnevat [http://tomcat.apache.org/tomcat-8.0-doc/manager-howto.html#Introduction 1]:
* Rakendada uue veebiaplikatsiooni war-faili üleslaadimisega;
* Näha kõiki rakendatud veebiaplikatsioone koos aktiivsete sessioonidega;
* Taasrakendada veebirakendust, näiteks veebiarhiivi pakitud klassifailide /WEB-INF/classes või teekide /WEB-INF/lib uuendamisel, kinnijooksmisel jms.;
* Peatada veebirakendust ilma serverist eemaldamata, samuti koos serverist eemaldamisega;
* Vaadata operatsioonisüsteemi ja Java parameetrite väärtusi;
* Näha kõiki saadaolevaid JNDI ressursse, k.a. andmebaasiühendusi, mis aitavad rakenduste programmeerijail defineerida <ResourceLink> elemendid web.xml konfiguratsioonifailis.

Tomcati installatsioon sisaldab haldusrakendust juba vaikimisi. Haldusrakenduse töölepanemiseks tuleb peremeesmasina konfiguratsioonikataloogi $CATALINA_BASE/conf/[enginename]/[hostname] lisada ka fail manager.xml. Vaikimisi valmiskonfigureeritud testrakendusel on see fail juba olemas asukohas $CATALINA_BASE/conf/Catalina/localhost/manager.xml . Rakendus asub vaikimisi aadressil http://[host]/manager/ , vaikimisi konfiguratsioone kasutades lahendub see asukohaks http://localhost:8080/manager/ . [http://tomcat.apache.org/tomcat-8.0-doc/manager-howto.html#Configuring_Manager_Application_Access 1]

====="Tomcat Manager" ligipääsu konfigureerimine=====

Vaikimisi on turvalisuspõhjustel ligipääs haldusrakendusele maha keeratud. Mismoodi täpselt kasutajatel ligipääsu võimaldada sõltub kasutatavast valdusest (realm). Vaikimisi defineerib $CATALINA_BASE/conf/server.xml valduseks "MemoryRealm". Vaikimisi loeb valdus "MemoryRealm" kasutajad failist $CATALINA_BASE/conf/tomcat-users.xml. Antud failis tuleb iga kasutaja defineerida omaette märgendiga <user>, mis näeb välja umbes järgmine [http://tomcat.apache.org/tomcat-8.0-doc/manager-howto.html#Configuring_Manager_Application_Access 1]:
<pre>
<user name="craig" password="secret" roles="manager-gui,manager-script" />
</pre>

Antud kasutajale on defineeritud korraga kaks rolli. Ligipääsu võimaldamiseks tulebki lihtsamal juhul kasutajatefailis $CATALINA_BASE/conf/tomcat-users.xml defineerida enda kasutaja. Kasutaja rolliks võib määrata näiteks "manager-gui", mis võimaldab ligipääsu kogu HTML liidese funktsionaalsusele.

Teised valdused on "JDBCRealm", mille puhul hoitakse kasutajatega seonduvat infot andmebaasis ja JNDIRealm, mille puhul kasutatakse lihtsustatud kataloogisirvimise protokolli (LDAP).
Lisaks saab haldusrakendusele keelata ligipääsu mujalt kui kindlaksmääratud IP-aadressidelt, lisades filtri "RemoteAddrValve" või "RemoteHostValve" konfigureerimisfaili manager.xml näiteks järgmiselt [http://tomcat.apache.org/tomcat-8.0-doc/manager-howto.html#Introduction 1]:
<pre>
<Context privileged="true">
<Valve className="org.apache.catalina.valves.RemoteAddrValve"
allow="127\.0\.0\.1"/>
</Context>
</pre>

=====Juurutamine ja mahavõtmine haldusrakendusega "Tomcat Manager"=====

Juurutamiseks lae kõigepealt veebiarhiivifail üles, kasutades esilehel asuvat sektsiooni "WAR file to deploy".

[[File:tomcat_manager_war_upload.png|800px|thumb|right|Veebiarhiivi üleslaadimise nupp]]

Rakendus kuvatakse seejärel hallatavate rakenduste nimekirjas. Kui konteiner pole seadistatud üleslaetud aplikatsiooni kohe ka ise rakendama, tuleb vajutada "Start". Rakenduse peatamiseks kasuta "Stop", uuesti rakendamiseks "Redeploy" ja serverist eemaldamiseks "Undeploy".


[[File:tomcat_manager_apps_list.png|800px|Rakenduste nimekiri]]

==Näpunäiteid Tomcati reaalseks kasutamiseks==

===Juurutamise järjekord===

Tomcati käivitumisel juurutatakse aplikatsioonid sellises järjekorras [http://www.mulesoft.com/tomcat-deploy-procedures 2]:
# Konteinerisse kopeeritud kontekstikirjelduste järgi $CATALINA_BASE/conf/[EngineName]/[HostName]/[ApplicationName].xml ;
# Lahtipakitud rakendused "webapps" kataloogis;
# Pakitud rakenduste veebiarhiivid "webapps" kataloogis.

Seetõttu peaks käsitsi taasjuurutamisel kindluse mõttes eelnevalt kustutama rakenduse lahtipakitud dokumendipõhja kataloogi "webapps" kataloogist. Kontekstikirjelduse muutumisel tuleb jälgida, kas kirjeldus on juba kopeeritud serverisse ning vajadusel eelmise versiooni ümber muuta või kustutada.

===Reaalsele domeenile konfigureerimine===

Järgnevalt eeldame, et domeen ''www.minukodukas.ee'' on juba serverimasinaga seostatud. Et Tomcat hakkaks ka reaalselt Internetist tulevatele päringutele vastama, tuleb muuta failis $CATALINA_BASE/conf/server.xml konteinerile ''Catalina'' vastava teenusemärgendi sisu sarnaselt järgnevaga:

<pre>
<Service name="Catalina">
<Connector port="80" protocol="HTTP/1.1" connectionTimeout="20000" URIEncoding="UTF-8" redirectPort="8443" />
<Engine name="Catalina" defaultHost="www.minukodukas.ee">
<Host name="www.minukodukas.ee" appBase="webapps" unpackWARs="true" autoDeploy="false" deployOnStartup="false" xmlValidation="false" xmlNamespaceAware="false">
<Context path="" docBase="kodukas" debug="0" reloadable="true" />
</Host>
</Engine>
</Service>
</pre>

Ülal defineerime põhiliselt selle, et Tomcat kuulaks domeeni ''www.minukodukas.ee'' ja kasutaks HTTP päringute jaoks porti 80. Ühtlasti otsib Tomcat juurutatavat rakendust failist $CATALINA_BASE/webapps/kodukas.war. Kuna rajalisandiks on määratud tühi sõne (path=""), siis juurutataksegi aplikatsioon aadressile ''www.minukodukas.ee'' ilma rajalisandita (a'la ''www.minukodukas.ee/wiki''). Seetõttu pakitakse ka veebiarhiiv tegelikult lahti kataloogi $CATALINA_BASE/webapps/ROOT mitte kataloogi $CATALINA_BASE/webapps/kodukas nagu võiks eeldada.

===Käigultvahetus===

Võimaldamaks käigultvahetust (hot deployment) peab konteineri konfiguratsioonifailis $CATALINA_BASE/conf/server.xml olema peremehepõhise märgendi "Host" atribuudi "autoDeploy" väärtus "true". Sel juhul installeerib ja uuendab Tomcat aplikatsioone dünaamiliselt töötamise ajal. Kui väärtuseks on "false", käib installeerimine staatiliselt ning serverisse juurutamiseks tuleb teha konteineri taaskäivitus. Käigultvahetust saab määrata ka peremehe defineerimisel "Host Manager" rakendusega, mis on kättesaadav aadressil http://localhost:8080/host-manager/html . Kasutamiseks tuleb lisada oma kasutajale rolli "admin-gui" (vt. alajaotus ""Tomcat Manager" ligipääsu konfigureerimine").

[[File:host_manager_app.png]]

Käigultvahetust päästikuks on vaikimisi uuendatud veebiarhiivifaili või lahtipakitud veebirakenduse paigutamine "webapps" kataloogi. Käigultvahetuse päästikutele võib failis $CATALINA_BASE/conf/server.xml ka ise lisada kuulatavaid ressursse nagu web.xml muutmine või mõne teegifaili vahetamine (märgendis "Host").

===Klassiteekide väljatõstmine veebiarhiivifailist===

Kõik konteksti poolt kasutatavad Java klassiteegid võib pakendada veebiarhiivi sisse kataloogi "lib", kuid nii võib osutuda veebiarhiivi üleslaadimine ajakulukaks, eriti arenduskeskkonnas. Kui ei teki ohtu, et erinevad rakendused kasutavad sama teegi erinevaid versioone, siis on vahel parem lisada osa teeke konteineri kataloogi $CATALINA_BASE/libs, kust need tehakse siis konteineri poolt kättesaadavaks kõigile konteineris jooksutatavatele kontekstidele. Nii võib vähendada veebiarhiivi faili suurust märgatavalt, mis tõstab kokkuvõttes juurutamiskiirust ja ühes sellega programmeerijate tööviljakust.

===Mälukasutus===

Konteineri poolt kasutatavat mälu saab vaadata haldusrakendusest vajutades lingile "Server Status". Mälukasutus on toodud jaotuses "JVM", kus näidatakse nii maksimaalselt kättesaadavat mälu kui ka parasjagu reserveeritud mälu.

<pre>Free memory: 41.16 MB Total memory: 123.37 MB Max memory: 1027.56 MB</pre>

Mälu suurendamiseks võib näiteks defineerida skriptis $CATALINA_BASE/bin/catalina.sh muutuja "JAVA_OPTS" ning määrata Java mälukasutuse miinimum- ja maksimumväärtused sarnaselt järgnevatega [http://www.mkyong.com/tomcat/tomcat-javalangoutofmemoryerror-permgen-space/ 3]:
<pre>
JAVA_OPTS="-Xms1536m -Xmx1536m -XX:NewSize=256m -XX:MaxNewSize=256m -XX:PermSize=256m -XX:MaxPermSize=256m"
</pre>

===Logifailid===

Vaikimisi defineerib Tomcat failiga $CATALINA_BASE/conf/logging.properties viis logerit, mis tekitavad viis eraldi logifaili.

{| style="background:#cccc99;color:black;width:80%;" border="1" cellpadding="5" cellspacing="0" align="center"
|+ Tomcati tekitatavad logifailid "logs" kataloogis
!Fail !! Kasutus
|- style="background:white; color:black"
| style="width:300px" |catalina.out
| Tomcati käivitus- ja peatamisskriptide väljund, samuti juurutatud rakenduste prindilaused System.out ja veaväljundid System.err
|- style="background:white; color:black"
| style="width:300px" |catalina.[yyyy]-[mm]-[dd].log
| Pööratud (rotated) logifail catalina.out
|- style="background:white; color:black"
| style="width:300px" |host-manager.[yyyy]-[mm]-[dd].log
| Logi peremehehalduse rakendusele (rakendus on kättesaadav kohalikust masinast aadressil http://localhost:8080/host-manager/html )
|- style="background:white; color:black"
| style="width:300px" |localhost.[yyyy]-[mm]-[dd].log
| Peremehe "localhost" logi; mitme virtuaalse peremehe korral tekitatakse igale peremehele oma logi
|- style="background:white; color:black"
| style="width:300px" |localhost_access_log.[yyyy]-[mm]-[dd].txt
| Konteinerisse Internetist saabunud päringute logi
|- style="background:white; color:black"
| style="width:300px" |manager.[yyyy]-[mm]-[dd].log
| Haldusrakenduse tegevuste logi
|}

===Viiteid===

Palju vajalikku võib leida [http://tomcat.apache.org/tomcat-8.0-doc/index.html Tomcat 8 dokumentatsioonist]

Lisaks üks viide põhjalikule Tomcati versioon seitsme ülevaatele: http://www.ntu.edu.sg/home/ehchua/programming/howto/Tomcat_More.html

= Kasutatud materjalid =

#http://tomcat.apache.org/tomcat-8.0-doc/index.html
#http://www.mulesoft.com/tomcat-deploy-procedures
#http://www.mkyong.com/tomcat/tomcat-javalangoutofmemoryerror-permgen-space/

[[Category: Operatsioonisüsteemide administreerimine ja sidumine]]

Tomcat

2014-01-02T22:01:31Z

Kveskima: /* Juurutamine ja mahavõtmine haldusrakendusega "Tomcat Manager" */

==Autor==

Kristjan Veskimäe D32

2013

==Sissejuhatus==

Tomcat on vabalt kättesaadav server Java veebirakendustele. Põhimõtteliselt on tegemist Servlet/JSP spetsifikatsiooni toetava konteineriga. Kiire käivitumise ning rakenduste käigultvahetuse tõttu on Tomcat hea valik väiksemate ning keskmise suurusega Java veebirakenduste käitamiseks.

Antud töö kirjeldab Tomcati 8. versiooni. Põhiosa on üldiselt samasugune võrreldes paari eelmise versiooniga. Suuremad erinevused on versioonispetsiifilistes probleemides ja nende lahendamises, mida käesolev töö ei vaatle.

Töö vaatleb Tomcati paigaldamist ja seadistamist Unix-laadsesse keskkonda ning eeldab lugejalt algteadmisi sarnastes süsteemides. Tomcati on võimalik paigaldada ka Windows-keskkonda, kuid antud veebiserver eeldab kasutaja poolt käsureal töötamist ning Tomcati failihierarhias orienteerumist. Põhimõtteliselt on Java veebirakenduste arendamiseks IDE-abil võimalik siiski ka kasutada IDE-sse integreeritud Tomcati serverit - näiteks pakuvad sellist võimalust Eclipse EE ja NetBeans - kuid seda käesolev töö ei vaatle.

==Mõisted==

* '''Kontekst''' (context) - Tomcati mõistes üks konkreetne veebiaplikatsioon
* '''Konteiner''' (container) - veebiserver Tomcat ise
* '''Kontekstikirjeldus''' (context descriptor) - Tomcati-spetsiifiline konteksti konfiguratsioonimääratlus; peremehepõhine osa loetakse failist $CATALINA_HOME/conf/[enginename]/[hostname]/context.xml ja sellele lisatakse kontekstispetsiifilised täpsustused failist $CATALINA_BASE/conf/[enginename]/[hostname]/[webappname].xml; kontekstikirjeldus määrab näiteks nimed ressurssidele, sessioonihalduse parameetrid jmt. (olgu märgitud, et Tomcati varasemates versioonides sisaldusid kontekstikirjeldused põhikonfiguratsioonifailis server.xml)
* '''Dokumendipõhi''' (docBase) - kontekstile vastav kataloog Tomcati "webapps" kataloogis, mis tekib veebiaplikatsiooni serverisse rakendamisel
* '''Veebiarhiiv''' (Web application ARchive, war-file) - Java veebiaplikatsiooni jagatakse hea tava kohaselt selle üheainsa veebiarhiivi failina, mille laienditüübiks on "war". Tegemist on zip-protokolliga kokkupakitud kataloogiga, millel on Java veebirakenduste spetsifikatsioonile vastav ülesehitus. Siiski võib veebiaplikatsioon olla juurutamisel ka lahtipakendatud olekus (inglisekeelne termin on "war is exploded").

==Ülesehitus==

{| class="wikitable"
|+Kataloogid
|-
|style="color: green;" | $CATALINA_HOME
|baaskataloog, kuhu on Tomcat paigutatud
|-
|style="color: green;" | $CATALINA_BASE
|parasjagu töösoleva Tomcati eksemplari baaskataloog, mille alusel lahendatakse teed ülejäänud kataloogide ja failideni; ainult ühe kasutusel oleva Tomcati eksemplari puhul on see sama, mis $CATALINA_HOME

|-
|style="color: green;" | $CATALINA_BASE/bin
|serveri käivitus- ja abiskriptid
|-
|style="color: green;" | $CATALINA_BASE/conf
|konfiguratsioonifailid
|-
|style="color: green;" | $CATALINA_BASE/lib
|Tomcatile vaikimisi kättesaadavad Java klassiteegid (class libraries) ehk .jar-failid kuhu on Java kompileeritud kood kokku pakendatud
|-
|style="color: green;" | $CATALINA_BASE/logs
|logifailid paigutatakse vaikimisi siia
|-
|style="color: green;" | $CATALINA_BASE/webapps
|kataloog, kuhu paigutatakse serverisse juurutatavad veebiaplikatsioonid

|}

{| class="wikitable"
|+Mõned olulisemad failid
|-
|style="color: green;" | $CATALINA_BASE/bin/startup.sh
|serveri käivitusskript
|-
|style="color: green;" | $CATALINA_BASE/bin/shutdown.sh
|serveri peatusskript

|-
|style="color: green;" | $CATALINA_BASE/conf/server.xml
| konteineri peamine konfiguratsioonifail
|-
|style="color: green;" | $CATALINA_BASE/conf/[enginename]/[hostname]/[webappname].xml
|serveri administraatori jaoks konteinerisse endasse ümber kopeeritud rakendusepõhine kontekstikirjelduse konfiguratsioon failist $CATALINA_BASE/webapps/[ApplicationName]/META-INF/context.xml
|-
|style="color: green;" | $CATALINA_BASE/conf/[enginename]/[hostname]/context.xml
| fail, mis aitab administraatoril konteksti kohta käivat infot kirjeldada peremeesmasina-põhiselt ja halduseks mõeldud automaat-tööriistadel (näiteks Tomcat Manager ja TCD) oma tööd teha
|-
|style="color: green;" | $CATALINA_BASE/$CATALINA_BASE/conf/[enginename]/[hostname]/manager.xml
|fail, mis võimaldab lisada rakendustele ligipääsufiltreid
|-
|style="color: green;" | $CATALINA_BASE/webapps/[webappname]/META-INF/context.xml
|kontekstikirjeldusfail, mille veebirakenduse programmeerija on pakendanud oma aplikatsiooniga kaasa ning millega ta saab võimaluse kontekstikirjeldust omalt poolt mõjutada; kirjutatakse rakenduse uuestijuurutamisel üle, mistõttu administraator peaks muutma selle asemel konteinerisse ümber kopeeritud püsieksemplari $CATALINA_BASE/conf/[enginename]/[hostname]/context.xml
|-
|style="color: green;" | $CATALINA_BASE/webapps/[webappname]/WEB-INF/web.xml
|ka üks oluline Java veebiaplikatsiooni konfiguratsioonifail, mille pakendatakse koos veebiarhiiviga; enamasti muudab seda ainult programeerija; määrab muu hulgas millised aplikatsiooni osad vajavad autentimist või kui kiiresti veebisessioon aegub
|}

==Installeerimine==

===Installeerimine paketihalduriga===

<pre>
apt-cache search tomcat
apt-get install tomcat[version]-webapps
apt-get install tomcat[version]-admin
apt-get install tomcat[version]
</pre>

===Installeerimine käsitsi===

Paketihalduriga installeerides ei pruugi viimane Tomcati versioon olla kättesaadav ja see pakub ka vähem võimalusi kataloogide määramiseks jms. Käsitsi installeerimiseks tuleb laadida Tomcat kodulehelt alla. Lahtipakkimisel tekib kataloog, milles sisalduv fail "RUNNING.txt" on kõige kindlam allikas installeerimisel tekkivate probleemide vältimiseks ning lahendamiseks.

Vajaliku versiooni installeerimisfaili asukoha saab vaadata Tomcati kodulehelt sektsioonist "Download". Järgnevas näites installeerime Tomcati kõige uuema ebastabiilse kandidaatversiooni, mida näitab nimes sisalduv RC ehk "release candidate". Produktsioonikeskkonda tuleks siiski valida stabiilse versiooni. Käsitsi installeerimine on sarnane järgmisega:
<pre>
wget http://mirror.nexcess.net/apache/tomcat/tomcat-8/v8.0.0-RC5/bin/apache-tomcat-8.0.0-RC5.tar.gz
tar -zxvf apache-tomcat-8.0.0-RC5.tar.gz
mv /Users/kristjanveskimae/downloads/apache-tomcat-8.0.0-RC5 /usr/local/apache-tomcat-8.0.0-RC5
rm -f /Library/Tomcat
ln -s /usr/local/apache-tomcat-8.0.0-RC5/ /Library/Tomcat
chown -R kristjanveskimae /Library/Tomcat
chmod +x /Library/Tomcat/bin/*.sh
</pre>

==Käivitamine ja aplikatsiooni juurutamine==

===Konteineri käivitamine===

Tomcati käivitamise eelduseks on Java paigaldamine masinasse ning keskkonnamuutujate "JAVA_HOME" ja "JRE_HOME" defineerimine. Peale installeerimist võib kasutada skripte kataloogist $CATALINA_BASE/bin . Järgneb üks võimalik käivitamise ja peatamise näide, mis on kasutatav eelnevalt kirjeldatud käsitsi installeerimise juhul:
<pre>
/Library/Tomcat/bin/startup.sh
</pre>
ja peatamiseks
<pre>
/Library/Tomcat/bin/shutdown.sh
</pre>

===Näiteaplikatsiooni juurutamine===

Java veebiaplikatsiooni jagatakse hea tava kohaselt üheainsa veebiarhiivi failina. Siiski võib Tomcati juurutada ka lahtipakendatud olekus ("exploded") Java veebiaplikatsiooni.

====Käsitsi juurutamine ja mahavõtmine====

Näiteaplikatsiooni juurutamiseks lae selle veebiarhiivifail alla ning kopeeri oma konteineri juurutamiskataloogi 'webapps':
<pre>wget http://tomcat.apache.org/tomcat-8.0-doc/appdev/sample/sample.war
cp /Users/kristjanveskimae/downloads/sample.war /Library/Tomcat/webapps/sample.war</pre>

[[File:sample_app.png|400px|thumb|right|Õnnestunult rakendatud näiteaplikatsioon[http://localhost:8080/sample/]]]

Kui konfiguratsioonifailis $CATALINA_BASE/conf/server.xml on märgendi "Host" atribuudi "autoDeploy" väärtus "true", installeerib ja uuendab Tomcat aplikatsioone dünaamiliselt töötamise ajal. Kui väärtuseks on "false", käib installeerimine staatiliselt ning serverisse juurutamiseks tuleb teha konteineri taaskäivitus. [http://tomcat.apache.org/tomcat-8.0-doc/manager-howto.html#Deploy_A_New_Application_from_a_Local_Path 1] Mõlemal juhul pakib konteiner arhiveeritud faili ise lahti samasse kausta $CATALINA_BASE/webapps ning ka juurutab selle. Tekkiv aplikatsioon on lokaalsest masinast seejärel kättesaadav aadressil http://localhost:8080/sample/ .

Veebirakenduse käsitsi mahavõtmiseks tuleb kustutada talle vastav dokumendipõhja kataloog "webapps" kataloogist. Samuti tuleks kustutada .war-fail olemaks kindel, et Tomcat ei rakenda uuel käivitamisel veebiaplikatsiooni veebiarhiivifailist. Veelgi lihtsam on mahavõtmine brauseriga haldusrakenduse kaudu.

Rakenduste baaskataloogi "webapps" asukohta saab muuta failis $CATALINA_BASE/conf/server.xml peremehepõhiselt määratava atribuudiga "appBase", sealjuures Tomcati vaikimisi peremees ehk "Host" on "localhost".

====Tomcati vahendid juurutamiseks====

Veebiaplikatsioonide juurutamine ja mahajuurutamine on võimalik ka kaughalduse teel tänu Tomcati internetipõhisele haldusrakendusele. Näiteks saab veebibrauserit kasutades teha serveri põhitoiminguid Tomcati enda HTML-põhise rakendusega "Tomcat Manager". Veebipõhine haldusrakendus töötab ka käsupõhise veebiteenusena, millele on valmis ehitatud Anti ja Maveni integratsioonid. Samuti eksisteerib käsurea kliendirakendus TCD (Tomcat Client Deployer). TCD ei kuulu Tomcati baaskoosseisu, kuid pakub peale serveri administreerimise tavatoimingute ka lisafunktsionaalsust nagu veebirakenduse kokkukompileerimine ja pakendamine. [http://tomcat.apache.org/tomcat-8.0-doc/manager-howto.html#Configuring_Manager_Application_Access 1]

====Haldurakendus "Tomcat Manager"====

Tomcati haldusrakendus "Tomcat Manager" (antud alamjaotuses lihtsalt haldusrakendus) on Tomcati enda veebiaplikatioon Tomcati brauseripõhiseks kaughalduseks, võimaldades muu hulgas järgnevat [http://tomcat.apache.org/tomcat-8.0-doc/manager-howto.html#Introduction 1]:
* Rakendada uue veebiaplikatsiooni war-faili üleslaadimisega;
* Näha kõiki rakendatud veebiaplikatsioone koos aktiivsete sessioonidega;
* Taasrakendada veebirakendust, näiteks veebiarhiivi pakitud klassifailide /WEB-INF/classes või teekide /WEB-INF/lib uuendamisel, kinnijooksmisel jms.;
* Peatada veebirakendust ilma serverist eemaldamata, samuti koos serverist eemaldamisega;
* Vaadata operatsioonisüsteemi ja Java parameetrite väärtusi;
* Näha kõiki saadaolevaid JNDI ressursse, k.a. andmebaasiühendusi, mis aitavad rakenduste programmeerijail defineerida <ResourceLink> elemendid web.xml konfiguratsioonifailis.

Tomcati installatsioon sisaldab haldusrakendust juba vaikimisi. Haldusrakenduse töölepanemiseks tuleb peremeesmasina konfiguratsioonikataloogi $CATALINA_BASE/conf/[enginename]/[hostname] lisada ka fail manager.xml. Vaikimisi valmiskonfigureeritud testrakendusel on see fail juba olemas asukohas $CATALINA_BASE/conf/Catalina/localhost/manager.xml . Rakendus asub vaikimisi aadressil http://[host]/manager/ , vaikimisi konfiguratsioone kasutades lahendub see asukohaks http://localhost:8080/manager/ . [http://tomcat.apache.org/tomcat-8.0-doc/manager-howto.html#Configuring_Manager_Application_Access 1]

====="Tomcat Manager" ligipääsu konfigureerimine=====

Vaikimisi on turvalisuspõhjustel ligipääs haldusrakendusele maha keeratud. Mismoodi täpselt kasutajatel ligipääsu võimaldada sõltub kasutatavast valdusest (realm). Vaikimisi defineerib $CATALINA_BASE/conf/server.xml valduseks "MemoryRealm". Vaikimisi loeb valdus "MemoryRealm" kasutajad failist $CATALINA_BASE/conf/tomcat-users.xml. Antud failis tuleb iga kasutaja defineerida omaette märgendiga <user>, mis näeb välja umbes järgmine [http://tomcat.apache.org/tomcat-8.0-doc/manager-howto.html#Configuring_Manager_Application_Access 1]:
<pre>
<user name="craig" password="secret" roles="manager-gui,manager-script" />
</pre>

Antud kasutajale on defineeritud korraga kaks rolli. Ligipääsu võimaldamiseks tulebki lihtsamal juhul kasutajatefailis $CATALINA_BASE/conf/tomcat-users.xml defineerida enda kasutaja. Kasutaja rolliks võib määrata näiteks "manager-gui", mis võimaldab ligipääsu kogu HTML liidese funktsionaalsusele.

Teised valdused on "JDBCRealm", mille puhul hoitakse kasutajatega seonduvat infot andmebaasis ja JNDIRealm, mille puhul kasutatakse lihtsustatud kataloogisirvimise protokolli (LDAP).
Lisaks saab haldusrakendusele keelata ligipääsu mujalt kui kindlaksmääratud IP-aadressidelt, lisades filtri "RemoteAddrValve" või "RemoteHostValve" konfigureerimisfaili manager.xml näiteks järgmiselt [http://tomcat.apache.org/tomcat-8.0-doc/manager-howto.html#Introduction 1]:
<pre>
<Context privileged="true">
<Valve className="org.apache.catalina.valves.RemoteAddrValve"
allow="127\.0\.0\.1"/>
</Context>
</pre>

=====Juurutamine ja mahavõtmine haldusrakendusega "Tomcat Manager"=====

Juurutamiseks lae kõigepealt veebiarhiivifail üles, kasutades esilehel asuvat sektsiooni "WAR file to deploy".

[[File:tomcat_manager_war_upload.png|800px|thumb|right|Veebiarhiivi üleslaadimise nupp]]

Rakendus kuvatakse seejärel hallatavate rakenduste nimekirjas. Kui konteiner pole seadistatud üleslaetud aplikatsiooni kohe ka ise rakendama, tuleb vajutada "Start". Rakenduse peatamiseks kasuta "Stop", uuesti rakendamiseks "Redeploy" ja serverist eemaldamiseks "Undeploy".


[[File:tomcat_manager_apps_list.png|800px|Rakenduste nimekiri]]

==Näpunäiteid Tomcati reaalseks kasutamiseks==

===Juurutamise järjekord===

Tomcati käivitumisel juurutatakse aplikatsioonid sellises järjekorras [http://www.mulesoft.com/tomcat-deploy-procedures 2]:
# Konteinerisse kopeeritud kontekstikirjelduste järgi $CATALINA_BASE/conf/[EngineName]/[HostName]/[ApplicationName].xml ;
# Lahtipakitud rakendused "webapps" kataloogis;
# Pakitud rakenduste veebiarhiivid "webapps" kataloogis.

Seetõttu peaks käsitsi taasjuurutamisel kindluse mõttes eelnevalt kustutama rakenduse lahtipakitud dokumendipõhja kataloogi "webapps" kataloogist. Kontekstikirjelduse muutumisel tuleb jälgida, kas kirjeldus on juba kopeeritud serverisse ning vajadusel eelmise versiooni ümber muuta või kustutada.

===Reaalsele domeenile konfigureerimine===

Järgnevalt eeldame, et domeen ''www.minukodukas.ee'' on juba serverimasinaga seostatud. Et Tomcat hakkaks ka reaalselt Internetist tulevatele päringutele vastama, tuleb muuta failis $CATALINA_BASE/conf/server.xml konteinerile ''Catalina'' vastava teenusemärgendi sisu sarnaselt järgnevaga:

<pre>
<Service name="Catalina">
<Connector port="80" protocol="HTTP/1.1" connectionTimeout="20000" URIEncoding="UTF-8" redirectPort="8443" />
<Engine name="Catalina" defaultHost="www.minukodukas.ee">
<Host name="www.minukodukas.ee" appBase="webapps" unpackWARs="true" autoDeploy="false" deployOnStartup="false" xmlValidation="false" xmlNamespaceAware="false">
<Context path="" docBase="kodukas" debug="0" reloadable="true" />
</Host>
</Engine>
</Service>
</pre>

Ülal defineerime põhiliselt selle, et Tomcat kuulaks domeeni ''www.minukodukas.ee'' ja kasutaks HTTP päringute jaoks porti 80. Ühtlasti otsib Tomcat juurutatavat rakendust failist $CATALINA_BASE/webapps/kodukas.war. Kuna rajalisandiks on määratud tühi sõne (path=""), siis juurutataksegi aplikatsioon aadressile ''www.minukodukas.ee'' ilma rajalisandita (a'la ''www.minukodukas.ee/wiki''). Seetõttu pakitakse ka veebiarhiiv tegelikult lahti kataloogi $CATALINA_BASE/webapps/ROOT mitte kataloogi $CATALINA_BASE/webapps/kodukas nagu võiks eeldada.

===Käigultvahetus===

Võimaldamaks käigultvahetust (hot deployment) peab konteineri konfiguratsioonifailis $CATALINA_BASE/conf/server.xml olema peremehepõhise märgendi "Host" atribuudi "autoDeploy" väärtus "true". Sel juhul installeerib ja uuendab Tomcat aplikatsioone dünaamiliselt töötamise ajal. Kui väärtuseks on "false", käib installeerimine staatiliselt ning serverisse juurutamiseks tuleb teha konteineri taaskäivitus. Käigultvahetust saab määrata ka peremehe defineerimisel "Host Manager" rakendusega, mis on kättesaadav aadressil http://localhost:8080/host-manager/html . Kasutamiseks tuleb lisada oma kasutajale rolli "admin-gui" (vt. alajaotus ""Tomcat Manager" ligipääsu konfigureerimine").

[[File:host_manager_app.png]]

Käigultvahetust päästikuks on vaikimisi uuendatud veebiarhiivifaili või lahtipakitud veebirakenduse paigutamine "webapps" kataloogi. Käigultvahetuse päästikutele võib failis $CATALINA_BASE/conf/server.xml ka ise lisada kuulatavaid ressursse nagu web.xml muutmine või mõne teegifaili vahetamine (märgendis "Host").

===Klassiteekide väljatõstmine veebiarhiivifailist===

Kõik konteksti poolt kasutatavad Java klassiteegid võib pakendada veebiarhiivi sisse kataloogi "lib", kuid nii võib osutuda veebiarhiivi üleslaadimine ajakulukaks, eriti arenduskeskkonnas. Kui ei teki ohtu, et erinevad rakendused kasutavad sama teegi erinevaid versioone, siis on vahel parem lisada osa teeke konteineri kataloogi $CATALINA_BASE/libs, kust need tehakse siis konteineri poolt kättesaadavaks kõigile konteineris jooksutatavatele kontekstidele. Nii võib vähendada veebiarhiivi faili suurust märgatavalt, mis tõstab kokkuvõttes juurutamiskiirust ja ühes sellega programmeerijate tööviljakust.

===Mälukasutus===

Konteineri poolt kasutatavat mälu saab vaadata haldusrakendusest vajutades lingile "Server Status". Mälukasutus on toodud jaotuses "JVM", kus näidatakse nii maksimaalselt kättesaadavat mälu kui ka parasjagu reserveeritud mälu.

<pre>Free memory: 41.16 MB Total memory: 123.37 MB Max memory: 1027.56 MB</pre>

Mälu suurendamiseks võib näiteks defineerida skriptis $CATALINA_BASE/bin/catalina.sh muutuja "JAVA_OPTS" ning määrata Java mälukasutuse miinimum- ja maksimumväärtused sarnaselt järgnevatega [http://www.mkyong.com/tomcat/tomcat-javalangoutofmemoryerror-permgen-space/ 3]:
<pre>
JAVA_OPTS="-Xms1536m -Xmx1536m -XX:NewSize=256m -XX:MaxNewSize=256m -XX:PermSize=256m -XX:MaxPermSize=256m"
</pre>

===Logifailid===

Vaikimisi defineerib Tomcat failiga $CATALINA_BASE/conf/logging.properties viis logerit, mis tekitavad viis eraldi logifaili.

{| style="background:#cccc99;color:black;width:80%;" border="1" cellpadding="5" cellspacing="0" align="center"
|+ Tomcati tekitatavad logifailid "logs" kataloogis
!Fail !! Kasutus
|- style="background:white; color:black"
| style="width:300px" |catalina.out
| Tomcati käivitus- ja peatamisskriptide väljund, samuti juurutatud rakenduste prindilaused System.out ja veaväljundid System.err
|- style="background:white; color:black"
| style="width:300px" |catalina.[yyyy]-[mm]-[dd].log
| Pööratud (rotated) logifail catalina.out
|- style="background:white; color:black"
| style="width:300px" |host-manager.[yyyy]-[mm]-[dd].log
| Logi peremehehalduse rakendusele (rakendus on kättesaadav kohalikust masinast aadressil http://localhost:8080/host-manager/html )
|- style="background:white; color:black"
| style="width:300px" |localhost.[yyyy]-[mm]-[dd].log
| Peremehe "localhost" logi; mitme virtuaalse peremehe korral tekitatakse igale peremehele oma logi
|- style="background:white; color:black"
| style="width:300px" |localhost_access_log.[yyyy]-[mm]-[dd].txt
| Konteinerisse Internetist saabunud päringute logi
|- style="background:white; color:black"
| style="width:300px" |manager.[yyyy]-[mm]-[dd].log
| Haldusrakenduse tegevuste logi
|}

===Viiteid===

Palju vajalikku võib leida [http://tomcat.apache.org/tomcat-8.0-doc/index.html Tomcat 8 dokumentatsioonist]

Lisaks üks viide põhjalikule Tomcati versioon seitsme ülevaatele: http://www.ntu.edu.sg/home/ehchua/programming/howto/Tomcat_More.html

= Kasutatud materjalid =

#http://tomcat.apache.org/tomcat-8.0-doc/index.html
#http://www.mulesoft.com/tomcat-deploy-procedures
#http://www.mkyong.com/tomcat/tomcat-javalangoutofmemoryerror-permgen-space/

[[Category: Operatsioonisüsteemide administreerimine ja sidumine]]

Tomcat

2014-01-02T22:00:50Z

Kveskima: /* Juurutamine ja mahavõtmine haldusrakendusega "Tomcat Manager" */

==Autor==

Kristjan Veskimäe D32

2013

==Sissejuhatus==

Tomcat on vabalt kättesaadav server Java veebirakendustele. Põhimõtteliselt on tegemist Servlet/JSP spetsifikatsiooni toetava konteineriga. Kiire käivitumise ning rakenduste käigultvahetuse tõttu on Tomcat hea valik väiksemate ning keskmise suurusega Java veebirakenduste käitamiseks.

Antud töö kirjeldab Tomcati 8. versiooni. Põhiosa on üldiselt samasugune võrreldes paari eelmise versiooniga. Suuremad erinevused on versioonispetsiifilistes probleemides ja nende lahendamises, mida käesolev töö ei vaatle.

Töö vaatleb Tomcati paigaldamist ja seadistamist Unix-laadsesse keskkonda ning eeldab lugejalt algteadmisi sarnastes süsteemides. Tomcati on võimalik paigaldada ka Windows-keskkonda, kuid antud veebiserver eeldab kasutaja poolt käsureal töötamist ning Tomcati failihierarhias orienteerumist. Põhimõtteliselt on Java veebirakenduste arendamiseks IDE-abil võimalik siiski ka kasutada IDE-sse integreeritud Tomcati serverit - näiteks pakuvad sellist võimalust Eclipse EE ja NetBeans - kuid seda käesolev töö ei vaatle.

==Mõisted==

* '''Kontekst''' (context) - Tomcati mõistes üks konkreetne veebiaplikatsioon
* '''Konteiner''' (container) - veebiserver Tomcat ise
* '''Kontekstikirjeldus''' (context descriptor) - Tomcati-spetsiifiline konteksti konfiguratsioonimääratlus; peremehepõhine osa loetakse failist $CATALINA_HOME/conf/[enginename]/[hostname]/context.xml ja sellele lisatakse kontekstispetsiifilised täpsustused failist $CATALINA_BASE/conf/[enginename]/[hostname]/[webappname].xml; kontekstikirjeldus määrab näiteks nimed ressurssidele, sessioonihalduse parameetrid jmt. (olgu märgitud, et Tomcati varasemates versioonides sisaldusid kontekstikirjeldused põhikonfiguratsioonifailis server.xml)
* '''Dokumendipõhi''' (docBase) - kontekstile vastav kataloog Tomcati "webapps" kataloogis, mis tekib veebiaplikatsiooni serverisse rakendamisel
* '''Veebiarhiiv''' (Web application ARchive, war-file) - Java veebiaplikatsiooni jagatakse hea tava kohaselt selle üheainsa veebiarhiivi failina, mille laienditüübiks on "war". Tegemist on zip-protokolliga kokkupakitud kataloogiga, millel on Java veebirakenduste spetsifikatsioonile vastav ülesehitus. Siiski võib veebiaplikatsioon olla juurutamisel ka lahtipakendatud olekus (inglisekeelne termin on "war is exploded").

==Ülesehitus==

{| class="wikitable"
|+Kataloogid
|-
|style="color: green;" | $CATALINA_HOME
|baaskataloog, kuhu on Tomcat paigutatud
|-
|style="color: green;" | $CATALINA_BASE
|parasjagu töösoleva Tomcati eksemplari baaskataloog, mille alusel lahendatakse teed ülejäänud kataloogide ja failideni; ainult ühe kasutusel oleva Tomcati eksemplari puhul on see sama, mis $CATALINA_HOME

|-
|style="color: green;" | $CATALINA_BASE/bin
|serveri käivitus- ja abiskriptid
|-
|style="color: green;" | $CATALINA_BASE/conf
|konfiguratsioonifailid
|-
|style="color: green;" | $CATALINA_BASE/lib
|Tomcatile vaikimisi kättesaadavad Java klassiteegid (class libraries) ehk .jar-failid kuhu on Java kompileeritud kood kokku pakendatud
|-
|style="color: green;" | $CATALINA_BASE/logs
|logifailid paigutatakse vaikimisi siia
|-
|style="color: green;" | $CATALINA_BASE/webapps
|kataloog, kuhu paigutatakse serverisse juurutatavad veebiaplikatsioonid

|}

{| class="wikitable"
|+Mõned olulisemad failid
|-
|style="color: green;" | $CATALINA_BASE/bin/startup.sh
|serveri käivitusskript
|-
|style="color: green;" | $CATALINA_BASE/bin/shutdown.sh
|serveri peatusskript

|-
|style="color: green;" | $CATALINA_BASE/conf/server.xml
| konteineri peamine konfiguratsioonifail
|-
|style="color: green;" | $CATALINA_BASE/conf/[enginename]/[hostname]/[webappname].xml
|serveri administraatori jaoks konteinerisse endasse ümber kopeeritud rakendusepõhine kontekstikirjelduse konfiguratsioon failist $CATALINA_BASE/webapps/[ApplicationName]/META-INF/context.xml
|-
|style="color: green;" | $CATALINA_BASE/conf/[enginename]/[hostname]/context.xml
| fail, mis aitab administraatoril konteksti kohta käivat infot kirjeldada peremeesmasina-põhiselt ja halduseks mõeldud automaat-tööriistadel (näiteks Tomcat Manager ja TCD) oma tööd teha
|-
|style="color: green;" | $CATALINA_BASE/$CATALINA_BASE/conf/[enginename]/[hostname]/manager.xml
|fail, mis võimaldab lisada rakendustele ligipääsufiltreid
|-
|style="color: green;" | $CATALINA_BASE/webapps/[webappname]/META-INF/context.xml
|kontekstikirjeldusfail, mille veebirakenduse programmeerija on pakendanud oma aplikatsiooniga kaasa ning millega ta saab võimaluse kontekstikirjeldust omalt poolt mõjutada; kirjutatakse rakenduse uuestijuurutamisel üle, mistõttu administraator peaks muutma selle asemel konteinerisse ümber kopeeritud püsieksemplari $CATALINA_BASE/conf/[enginename]/[hostname]/context.xml
|-
|style="color: green;" | $CATALINA_BASE/webapps/[webappname]/WEB-INF/web.xml
|ka üks oluline Java veebiaplikatsiooni konfiguratsioonifail, mille pakendatakse koos veebiarhiiviga; enamasti muudab seda ainult programeerija; määrab muu hulgas millised aplikatsiooni osad vajavad autentimist või kui kiiresti veebisessioon aegub
|}

==Installeerimine==

===Installeerimine paketihalduriga===

<pre>
apt-cache search tomcat
apt-get install tomcat[version]-webapps
apt-get install tomcat[version]-admin
apt-get install tomcat[version]
</pre>

===Installeerimine käsitsi===

Paketihalduriga installeerides ei pruugi viimane Tomcati versioon olla kättesaadav ja see pakub ka vähem võimalusi kataloogide määramiseks jms. Käsitsi installeerimiseks tuleb laadida Tomcat kodulehelt alla. Lahtipakkimisel tekib kataloog, milles sisalduv fail "RUNNING.txt" on kõige kindlam allikas installeerimisel tekkivate probleemide vältimiseks ning lahendamiseks.

Vajaliku versiooni installeerimisfaili asukoha saab vaadata Tomcati kodulehelt sektsioonist "Download". Järgnevas näites installeerime Tomcati kõige uuema ebastabiilse kandidaatversiooni, mida näitab nimes sisalduv RC ehk "release candidate". Produktsioonikeskkonda tuleks siiski valida stabiilse versiooni. Käsitsi installeerimine on sarnane järgmisega:
<pre>
wget http://mirror.nexcess.net/apache/tomcat/tomcat-8/v8.0.0-RC5/bin/apache-tomcat-8.0.0-RC5.tar.gz
tar -zxvf apache-tomcat-8.0.0-RC5.tar.gz
mv /Users/kristjanveskimae/downloads/apache-tomcat-8.0.0-RC5 /usr/local/apache-tomcat-8.0.0-RC5
rm -f /Library/Tomcat
ln -s /usr/local/apache-tomcat-8.0.0-RC5/ /Library/Tomcat
chown -R kristjanveskimae /Library/Tomcat
chmod +x /Library/Tomcat/bin/*.sh
</pre>

==Käivitamine ja aplikatsiooni juurutamine==

===Konteineri käivitamine===

Tomcati käivitamise eelduseks on Java paigaldamine masinasse ning keskkonnamuutujate "JAVA_HOME" ja "JRE_HOME" defineerimine. Peale installeerimist võib kasutada skripte kataloogist $CATALINA_BASE/bin . Järgneb üks võimalik käivitamise ja peatamise näide, mis on kasutatav eelnevalt kirjeldatud käsitsi installeerimise juhul:
<pre>
/Library/Tomcat/bin/startup.sh
</pre>
ja peatamiseks
<pre>
/Library/Tomcat/bin/shutdown.sh
</pre>

===Näiteaplikatsiooni juurutamine===

Java veebiaplikatsiooni jagatakse hea tava kohaselt üheainsa veebiarhiivi failina. Siiski võib Tomcati juurutada ka lahtipakendatud olekus ("exploded") Java veebiaplikatsiooni.

====Käsitsi juurutamine ja mahavõtmine====

Näiteaplikatsiooni juurutamiseks lae selle veebiarhiivifail alla ning kopeeri oma konteineri juurutamiskataloogi 'webapps':
<pre>wget http://tomcat.apache.org/tomcat-8.0-doc/appdev/sample/sample.war
cp /Users/kristjanveskimae/downloads/sample.war /Library/Tomcat/webapps/sample.war</pre>

[[File:sample_app.png|400px|thumb|right|Õnnestunult rakendatud näiteaplikatsioon[http://localhost:8080/sample/]]]

Kui konfiguratsioonifailis $CATALINA_BASE/conf/server.xml on märgendi "Host" atribuudi "autoDeploy" väärtus "true", installeerib ja uuendab Tomcat aplikatsioone dünaamiliselt töötamise ajal. Kui väärtuseks on "false", käib installeerimine staatiliselt ning serverisse juurutamiseks tuleb teha konteineri taaskäivitus. [http://tomcat.apache.org/tomcat-8.0-doc/manager-howto.html#Deploy_A_New_Application_from_a_Local_Path 1] Mõlemal juhul pakib konteiner arhiveeritud faili ise lahti samasse kausta $CATALINA_BASE/webapps ning ka juurutab selle. Tekkiv aplikatsioon on lokaalsest masinast seejärel kättesaadav aadressil http://localhost:8080/sample/ .

Veebirakenduse käsitsi mahavõtmiseks tuleb kustutada talle vastav dokumendipõhja kataloog "webapps" kataloogist. Samuti tuleks kustutada .war-fail olemaks kindel, et Tomcat ei rakenda uuel käivitamisel veebiaplikatsiooni veebiarhiivifailist. Veelgi lihtsam on mahavõtmine brauseriga haldusrakenduse kaudu.

Rakenduste baaskataloogi "webapps" asukohta saab muuta failis $CATALINA_BASE/conf/server.xml peremehepõhiselt määratava atribuudiga "appBase", sealjuures Tomcati vaikimisi peremees ehk "Host" on "localhost".

====Tomcati vahendid juurutamiseks====

Veebiaplikatsioonide juurutamine ja mahajuurutamine on võimalik ka kaughalduse teel tänu Tomcati internetipõhisele haldusrakendusele. Näiteks saab veebibrauserit kasutades teha serveri põhitoiminguid Tomcati enda HTML-põhise rakendusega "Tomcat Manager". Veebipõhine haldusrakendus töötab ka käsupõhise veebiteenusena, millele on valmis ehitatud Anti ja Maveni integratsioonid. Samuti eksisteerib käsurea kliendirakendus TCD (Tomcat Client Deployer). TCD ei kuulu Tomcati baaskoosseisu, kuid pakub peale serveri administreerimise tavatoimingute ka lisafunktsionaalsust nagu veebirakenduse kokkukompileerimine ja pakendamine. [http://tomcat.apache.org/tomcat-8.0-doc/manager-howto.html#Configuring_Manager_Application_Access 1]

====Haldurakendus "Tomcat Manager"====

Tomcati haldusrakendus "Tomcat Manager" (antud alamjaotuses lihtsalt haldusrakendus) on Tomcati enda veebiaplikatioon Tomcati brauseripõhiseks kaughalduseks, võimaldades muu hulgas järgnevat [http://tomcat.apache.org/tomcat-8.0-doc/manager-howto.html#Introduction 1]:
* Rakendada uue veebiaplikatsiooni war-faili üleslaadimisega;
* Näha kõiki rakendatud veebiaplikatsioone koos aktiivsete sessioonidega;
* Taasrakendada veebirakendust, näiteks veebiarhiivi pakitud klassifailide /WEB-INF/classes või teekide /WEB-INF/lib uuendamisel, kinnijooksmisel jms.;
* Peatada veebirakendust ilma serverist eemaldamata, samuti koos serverist eemaldamisega;
* Vaadata operatsioonisüsteemi ja Java parameetrite väärtusi;
* Näha kõiki saadaolevaid JNDI ressursse, k.a. andmebaasiühendusi, mis aitavad rakenduste programmeerijail defineerida <ResourceLink> elemendid web.xml konfiguratsioonifailis.

Tomcati installatsioon sisaldab haldusrakendust juba vaikimisi. Haldusrakenduse töölepanemiseks tuleb peremeesmasina konfiguratsioonikataloogi $CATALINA_BASE/conf/[enginename]/[hostname] lisada ka fail manager.xml. Vaikimisi valmiskonfigureeritud testrakendusel on see fail juba olemas asukohas $CATALINA_BASE/conf/Catalina/localhost/manager.xml . Rakendus asub vaikimisi aadressil http://[host]/manager/ , vaikimisi konfiguratsioone kasutades lahendub see asukohaks http://localhost:8080/manager/ . [http://tomcat.apache.org/tomcat-8.0-doc/manager-howto.html#Configuring_Manager_Application_Access 1]

====="Tomcat Manager" ligipääsu konfigureerimine=====

Vaikimisi on turvalisuspõhjustel ligipääs haldusrakendusele maha keeratud. Mismoodi täpselt kasutajatel ligipääsu võimaldada sõltub kasutatavast valdusest (realm). Vaikimisi defineerib $CATALINA_BASE/conf/server.xml valduseks "MemoryRealm". Vaikimisi loeb valdus "MemoryRealm" kasutajad failist $CATALINA_BASE/conf/tomcat-users.xml. Antud failis tuleb iga kasutaja defineerida omaette märgendiga <user>, mis näeb välja umbes järgmine [http://tomcat.apache.org/tomcat-8.0-doc/manager-howto.html#Configuring_Manager_Application_Access 1]:
<pre>
<user name="craig" password="secret" roles="manager-gui,manager-script" />
</pre>

Antud kasutajale on defineeritud korraga kaks rolli. Ligipääsu võimaldamiseks tulebki lihtsamal juhul kasutajatefailis $CATALINA_BASE/conf/tomcat-users.xml defineerida enda kasutaja. Kasutaja rolliks võib määrata näiteks "manager-gui", mis võimaldab ligipääsu kogu HTML liidese funktsionaalsusele.

Teised valdused on "JDBCRealm", mille puhul hoitakse kasutajatega seonduvat infot andmebaasis ja JNDIRealm, mille puhul kasutatakse lihtsustatud kataloogisirvimise protokolli (LDAP).
Lisaks saab haldusrakendusele keelata ligipääsu mujalt kui kindlaksmääratud IP-aadressidelt, lisades filtri "RemoteAddrValve" või "RemoteHostValve" konfigureerimisfaili manager.xml näiteks järgmiselt [http://tomcat.apache.org/tomcat-8.0-doc/manager-howto.html#Introduction 1]:
<pre>
<Context privileged="true">
<Valve className="org.apache.catalina.valves.RemoteAddrValve"
allow="127\.0\.0\.1"/>
</Context>
</pre>

=====Juurutamine ja mahavõtmine haldusrakendusega "Tomcat Manager"=====

Juurutamiseks lae kõigepealt veebiarhiivifail üles, kasutades esilehel asuvat sektsiooni "WAR file to deploy".

[[File:tomcat_manager_war_upload.png|400px|thumb|right|Veebiarhiivi üleslaadimise nupp]]

Rakendus kuvatakse seejärel hallatavate rakenduste nimekirjas. Kui konteiner pole seadistatud üleslaetud aplikatsiooni kohe ka ise rakendama, tuleb vajutada "Start". Rakenduse peatamiseks kasuta "Stop", uuesti rakendamiseks "Redeploy" ja serverist eemaldamiseks "Undeploy".


[[File:tomcat_manager_apps_list.png|800px|Rakenduste nimekiri]]

==Näpunäiteid Tomcati reaalseks kasutamiseks==

===Juurutamise järjekord===

Tomcati käivitumisel juurutatakse aplikatsioonid sellises järjekorras [http://www.mulesoft.com/tomcat-deploy-procedures 2]:
# Konteinerisse kopeeritud kontekstikirjelduste järgi $CATALINA_BASE/conf/[EngineName]/[HostName]/[ApplicationName].xml ;
# Lahtipakitud rakendused "webapps" kataloogis;
# Pakitud rakenduste veebiarhiivid "webapps" kataloogis.

Seetõttu peaks käsitsi taasjuurutamisel kindluse mõttes eelnevalt kustutama rakenduse lahtipakitud dokumendipõhja kataloogi "webapps" kataloogist. Kontekstikirjelduse muutumisel tuleb jälgida, kas kirjeldus on juba kopeeritud serverisse ning vajadusel eelmise versiooni ümber muuta või kustutada.

===Reaalsele domeenile konfigureerimine===

Järgnevalt eeldame, et domeen ''www.minukodukas.ee'' on juba serverimasinaga seostatud. Et Tomcat hakkaks ka reaalselt Internetist tulevatele päringutele vastama, tuleb muuta failis $CATALINA_BASE/conf/server.xml konteinerile ''Catalina'' vastava teenusemärgendi sisu sarnaselt järgnevaga:

<pre>
<Service name="Catalina">
<Connector port="80" protocol="HTTP/1.1" connectionTimeout="20000" URIEncoding="UTF-8" redirectPort="8443" />
<Engine name="Catalina" defaultHost="www.minukodukas.ee">
<Host name="www.minukodukas.ee" appBase="webapps" unpackWARs="true" autoDeploy="false" deployOnStartup="false" xmlValidation="false" xmlNamespaceAware="false">
<Context path="" docBase="kodukas" debug="0" reloadable="true" />
</Host>
</Engine>
</Service>
</pre>

Ülal defineerime põhiliselt selle, et Tomcat kuulaks domeeni ''www.minukodukas.ee'' ja kasutaks HTTP päringute jaoks porti 80. Ühtlasti otsib Tomcat juurutatavat rakendust failist $CATALINA_BASE/webapps/kodukas.war. Kuna rajalisandiks on määratud tühi sõne (path=""), siis juurutataksegi aplikatsioon aadressile ''www.minukodukas.ee'' ilma rajalisandita (a'la ''www.minukodukas.ee/wiki''). Seetõttu pakitakse ka veebiarhiiv tegelikult lahti kataloogi $CATALINA_BASE/webapps/ROOT mitte kataloogi $CATALINA_BASE/webapps/kodukas nagu võiks eeldada.

===Käigultvahetus===

Võimaldamaks käigultvahetust (hot deployment) peab konteineri konfiguratsioonifailis $CATALINA_BASE/conf/server.xml olema peremehepõhise märgendi "Host" atribuudi "autoDeploy" väärtus "true". Sel juhul installeerib ja uuendab Tomcat aplikatsioone dünaamiliselt töötamise ajal. Kui väärtuseks on "false", käib installeerimine staatiliselt ning serverisse juurutamiseks tuleb teha konteineri taaskäivitus. Käigultvahetust saab määrata ka peremehe defineerimisel "Host Manager" rakendusega, mis on kättesaadav aadressil http://localhost:8080/host-manager/html . Kasutamiseks tuleb lisada oma kasutajale rolli "admin-gui" (vt. alajaotus ""Tomcat Manager" ligipääsu konfigureerimine").

[[File:host_manager_app.png]]

Käigultvahetust päästikuks on vaikimisi uuendatud veebiarhiivifaili või lahtipakitud veebirakenduse paigutamine "webapps" kataloogi. Käigultvahetuse päästikutele võib failis $CATALINA_BASE/conf/server.xml ka ise lisada kuulatavaid ressursse nagu web.xml muutmine või mõne teegifaili vahetamine (märgendis "Host").

===Klassiteekide väljatõstmine veebiarhiivifailist===

Kõik konteksti poolt kasutatavad Java klassiteegid võib pakendada veebiarhiivi sisse kataloogi "lib", kuid nii võib osutuda veebiarhiivi üleslaadimine ajakulukaks, eriti arenduskeskkonnas. Kui ei teki ohtu, et erinevad rakendused kasutavad sama teegi erinevaid versioone, siis on vahel parem lisada osa teeke konteineri kataloogi $CATALINA_BASE/libs, kust need tehakse siis konteineri poolt kättesaadavaks kõigile konteineris jooksutatavatele kontekstidele. Nii võib vähendada veebiarhiivi faili suurust märgatavalt, mis tõstab kokkuvõttes juurutamiskiirust ja ühes sellega programmeerijate tööviljakust.

===Mälukasutus===

Konteineri poolt kasutatavat mälu saab vaadata haldusrakendusest vajutades lingile "Server Status". Mälukasutus on toodud jaotuses "JVM", kus näidatakse nii maksimaalselt kättesaadavat mälu kui ka parasjagu reserveeritud mälu.

<pre>Free memory: 41.16 MB Total memory: 123.37 MB Max memory: 1027.56 MB</pre>

Mälu suurendamiseks võib näiteks defineerida skriptis $CATALINA_BASE/bin/catalina.sh muutuja "JAVA_OPTS" ning määrata Java mälukasutuse miinimum- ja maksimumväärtused sarnaselt järgnevatega [http://www.mkyong.com/tomcat/tomcat-javalangoutofmemoryerror-permgen-space/ 3]:
<pre>
JAVA_OPTS="-Xms1536m -Xmx1536m -XX:NewSize=256m -XX:MaxNewSize=256m -XX:PermSize=256m -XX:MaxPermSize=256m"
</pre>

===Logifailid===

Vaikimisi defineerib Tomcat failiga $CATALINA_BASE/conf/logging.properties viis logerit, mis tekitavad viis eraldi logifaili.

{| style="background:#cccc99;color:black;width:80%;" border="1" cellpadding="5" cellspacing="0" align="center"
|+ Tomcati tekitatavad logifailid "logs" kataloogis
!Fail !! Kasutus
|- style="background:white; color:black"
| style="width:300px" |catalina.out
| Tomcati käivitus- ja peatamisskriptide väljund, samuti juurutatud rakenduste prindilaused System.out ja veaväljundid System.err
|- style="background:white; color:black"
| style="width:300px" |catalina.[yyyy]-[mm]-[dd].log
| Pööratud (rotated) logifail catalina.out
|- style="background:white; color:black"
| style="width:300px" |host-manager.[yyyy]-[mm]-[dd].log
| Logi peremehehalduse rakendusele (rakendus on kättesaadav kohalikust masinast aadressil http://localhost:8080/host-manager/html )
|- style="background:white; color:black"
| style="width:300px" |localhost.[yyyy]-[mm]-[dd].log
| Peremehe "localhost" logi; mitme virtuaalse peremehe korral tekitatakse igale peremehele oma logi
|- style="background:white; color:black"
| style="width:300px" |localhost_access_log.[yyyy]-[mm]-[dd].txt
| Konteinerisse Internetist saabunud päringute logi
|- style="background:white; color:black"
| style="width:300px" |manager.[yyyy]-[mm]-[dd].log
| Haldusrakenduse tegevuste logi
|}

===Viiteid===

Palju vajalikku võib leida [http://tomcat.apache.org/tomcat-8.0-doc/index.html Tomcat 8 dokumentatsioonist]

Lisaks üks viide põhjalikule Tomcati versioon seitsme ülevaatele: http://www.ntu.edu.sg/home/ehchua/programming/howto/Tomcat_More.html

= Kasutatud materjalid =

#http://tomcat.apache.org/tomcat-8.0-doc/index.html
#http://www.mulesoft.com/tomcat-deploy-procedures
#http://www.mkyong.com/tomcat/tomcat-javalangoutofmemoryerror-permgen-space/

[[Category: Operatsioonisüsteemide administreerimine ja sidumine]]

Tomcat

2014-01-02T22:00:27Z

Kveskima: /* Juurutamine ja mahavõtmine haldusrakendusega "Tomcat Manager" */

==Autor==

Kristjan Veskimäe D32

2013

==Sissejuhatus==

Tomcat on vabalt kättesaadav server Java veebirakendustele. Põhimõtteliselt on tegemist Servlet/JSP spetsifikatsiooni toetava konteineriga. Kiire käivitumise ning rakenduste käigultvahetuse tõttu on Tomcat hea valik väiksemate ning keskmise suurusega Java veebirakenduste käitamiseks.

Antud töö kirjeldab Tomcati 8. versiooni. Põhiosa on üldiselt samasugune võrreldes paari eelmise versiooniga. Suuremad erinevused on versioonispetsiifilistes probleemides ja nende lahendamises, mida käesolev töö ei vaatle.

Töö vaatleb Tomcati paigaldamist ja seadistamist Unix-laadsesse keskkonda ning eeldab lugejalt algteadmisi sarnastes süsteemides. Tomcati on võimalik paigaldada ka Windows-keskkonda, kuid antud veebiserver eeldab kasutaja poolt käsureal töötamist ning Tomcati failihierarhias orienteerumist. Põhimõtteliselt on Java veebirakenduste arendamiseks IDE-abil võimalik siiski ka kasutada IDE-sse integreeritud Tomcati serverit - näiteks pakuvad sellist võimalust Eclipse EE ja NetBeans - kuid seda käesolev töö ei vaatle.

==Mõisted==

* '''Kontekst''' (context) - Tomcati mõistes üks konkreetne veebiaplikatsioon
* '''Konteiner''' (container) - veebiserver Tomcat ise
* '''Kontekstikirjeldus''' (context descriptor) - Tomcati-spetsiifiline konteksti konfiguratsioonimääratlus; peremehepõhine osa loetakse failist $CATALINA_HOME/conf/[enginename]/[hostname]/context.xml ja sellele lisatakse kontekstispetsiifilised täpsustused failist $CATALINA_BASE/conf/[enginename]/[hostname]/[webappname].xml; kontekstikirjeldus määrab näiteks nimed ressurssidele, sessioonihalduse parameetrid jmt. (olgu märgitud, et Tomcati varasemates versioonides sisaldusid kontekstikirjeldused põhikonfiguratsioonifailis server.xml)
* '''Dokumendipõhi''' (docBase) - kontekstile vastav kataloog Tomcati "webapps" kataloogis, mis tekib veebiaplikatsiooni serverisse rakendamisel
* '''Veebiarhiiv''' (Web application ARchive, war-file) - Java veebiaplikatsiooni jagatakse hea tava kohaselt selle üheainsa veebiarhiivi failina, mille laienditüübiks on "war". Tegemist on zip-protokolliga kokkupakitud kataloogiga, millel on Java veebirakenduste spetsifikatsioonile vastav ülesehitus. Siiski võib veebiaplikatsioon olla juurutamisel ka lahtipakendatud olekus (inglisekeelne termin on "war is exploded").

==Ülesehitus==

{| class="wikitable"
|+Kataloogid
|-
|style="color: green;" | $CATALINA_HOME
|baaskataloog, kuhu on Tomcat paigutatud
|-
|style="color: green;" | $CATALINA_BASE
|parasjagu töösoleva Tomcati eksemplari baaskataloog, mille alusel lahendatakse teed ülejäänud kataloogide ja failideni; ainult ühe kasutusel oleva Tomcati eksemplari puhul on see sama, mis $CATALINA_HOME

|-
|style="color: green;" | $CATALINA_BASE/bin
|serveri käivitus- ja abiskriptid
|-
|style="color: green;" | $CATALINA_BASE/conf
|konfiguratsioonifailid
|-
|style="color: green;" | $CATALINA_BASE/lib
|Tomcatile vaikimisi kättesaadavad Java klassiteegid (class libraries) ehk .jar-failid kuhu on Java kompileeritud kood kokku pakendatud
|-
|style="color: green;" | $CATALINA_BASE/logs
|logifailid paigutatakse vaikimisi siia
|-
|style="color: green;" | $CATALINA_BASE/webapps
|kataloog, kuhu paigutatakse serverisse juurutatavad veebiaplikatsioonid

|}

{| class="wikitable"
|+Mõned olulisemad failid
|-
|style="color: green;" | $CATALINA_BASE/bin/startup.sh
|serveri käivitusskript
|-
|style="color: green;" | $CATALINA_BASE/bin/shutdown.sh
|serveri peatusskript

|-
|style="color: green;" | $CATALINA_BASE/conf/server.xml
| konteineri peamine konfiguratsioonifail
|-
|style="color: green;" | $CATALINA_BASE/conf/[enginename]/[hostname]/[webappname].xml
|serveri administraatori jaoks konteinerisse endasse ümber kopeeritud rakendusepõhine kontekstikirjelduse konfiguratsioon failist $CATALINA_BASE/webapps/[ApplicationName]/META-INF/context.xml
|-
|style="color: green;" | $CATALINA_BASE/conf/[enginename]/[hostname]/context.xml
| fail, mis aitab administraatoril konteksti kohta käivat infot kirjeldada peremeesmasina-põhiselt ja halduseks mõeldud automaat-tööriistadel (näiteks Tomcat Manager ja TCD) oma tööd teha
|-
|style="color: green;" | $CATALINA_BASE/$CATALINA_BASE/conf/[enginename]/[hostname]/manager.xml
|fail, mis võimaldab lisada rakendustele ligipääsufiltreid
|-
|style="color: green;" | $CATALINA_BASE/webapps/[webappname]/META-INF/context.xml
|kontekstikirjeldusfail, mille veebirakenduse programmeerija on pakendanud oma aplikatsiooniga kaasa ning millega ta saab võimaluse kontekstikirjeldust omalt poolt mõjutada; kirjutatakse rakenduse uuestijuurutamisel üle, mistõttu administraator peaks muutma selle asemel konteinerisse ümber kopeeritud püsieksemplari $CATALINA_BASE/conf/[enginename]/[hostname]/context.xml
|-
|style="color: green;" | $CATALINA_BASE/webapps/[webappname]/WEB-INF/web.xml
|ka üks oluline Java veebiaplikatsiooni konfiguratsioonifail, mille pakendatakse koos veebiarhiiviga; enamasti muudab seda ainult programeerija; määrab muu hulgas millised aplikatsiooni osad vajavad autentimist või kui kiiresti veebisessioon aegub
|}

==Installeerimine==

===Installeerimine paketihalduriga===

<pre>
apt-cache search tomcat
apt-get install tomcat[version]-webapps
apt-get install tomcat[version]-admin
apt-get install tomcat[version]
</pre>

===Installeerimine käsitsi===

Paketihalduriga installeerides ei pruugi viimane Tomcati versioon olla kättesaadav ja see pakub ka vähem võimalusi kataloogide määramiseks jms. Käsitsi installeerimiseks tuleb laadida Tomcat kodulehelt alla. Lahtipakkimisel tekib kataloog, milles sisalduv fail "RUNNING.txt" on kõige kindlam allikas installeerimisel tekkivate probleemide vältimiseks ning lahendamiseks.

Vajaliku versiooni installeerimisfaili asukoha saab vaadata Tomcati kodulehelt sektsioonist "Download". Järgnevas näites installeerime Tomcati kõige uuema ebastabiilse kandidaatversiooni, mida näitab nimes sisalduv RC ehk "release candidate". Produktsioonikeskkonda tuleks siiski valida stabiilse versiooni. Käsitsi installeerimine on sarnane järgmisega:
<pre>
wget http://mirror.nexcess.net/apache/tomcat/tomcat-8/v8.0.0-RC5/bin/apache-tomcat-8.0.0-RC5.tar.gz
tar -zxvf apache-tomcat-8.0.0-RC5.tar.gz
mv /Users/kristjanveskimae/downloads/apache-tomcat-8.0.0-RC5 /usr/local/apache-tomcat-8.0.0-RC5
rm -f /Library/Tomcat
ln -s /usr/local/apache-tomcat-8.0.0-RC5/ /Library/Tomcat
chown -R kristjanveskimae /Library/Tomcat
chmod +x /Library/Tomcat/bin/*.sh
</pre>

==Käivitamine ja aplikatsiooni juurutamine==

===Konteineri käivitamine===

Tomcati käivitamise eelduseks on Java paigaldamine masinasse ning keskkonnamuutujate "JAVA_HOME" ja "JRE_HOME" defineerimine. Peale installeerimist võib kasutada skripte kataloogist $CATALINA_BASE/bin . Järgneb üks võimalik käivitamise ja peatamise näide, mis on kasutatav eelnevalt kirjeldatud käsitsi installeerimise juhul:
<pre>
/Library/Tomcat/bin/startup.sh
</pre>
ja peatamiseks
<pre>
/Library/Tomcat/bin/shutdown.sh
</pre>

===Näiteaplikatsiooni juurutamine===

Java veebiaplikatsiooni jagatakse hea tava kohaselt üheainsa veebiarhiivi failina. Siiski võib Tomcati juurutada ka lahtipakendatud olekus ("exploded") Java veebiaplikatsiooni.

====Käsitsi juurutamine ja mahavõtmine====

Näiteaplikatsiooni juurutamiseks lae selle veebiarhiivifail alla ning kopeeri oma konteineri juurutamiskataloogi 'webapps':
<pre>wget http://tomcat.apache.org/tomcat-8.0-doc/appdev/sample/sample.war
cp /Users/kristjanveskimae/downloads/sample.war /Library/Tomcat/webapps/sample.war</pre>

[[File:sample_app.png|400px|thumb|right|Õnnestunult rakendatud näiteaplikatsioon[http://localhost:8080/sample/]]]

Kui konfiguratsioonifailis $CATALINA_BASE/conf/server.xml on märgendi "Host" atribuudi "autoDeploy" väärtus "true", installeerib ja uuendab Tomcat aplikatsioone dünaamiliselt töötamise ajal. Kui väärtuseks on "false", käib installeerimine staatiliselt ning serverisse juurutamiseks tuleb teha konteineri taaskäivitus. [http://tomcat.apache.org/tomcat-8.0-doc/manager-howto.html#Deploy_A_New_Application_from_a_Local_Path 1] Mõlemal juhul pakib konteiner arhiveeritud faili ise lahti samasse kausta $CATALINA_BASE/webapps ning ka juurutab selle. Tekkiv aplikatsioon on lokaalsest masinast seejärel kättesaadav aadressil http://localhost:8080/sample/ .

Veebirakenduse käsitsi mahavõtmiseks tuleb kustutada talle vastav dokumendipõhja kataloog "webapps" kataloogist. Samuti tuleks kustutada .war-fail olemaks kindel, et Tomcat ei rakenda uuel käivitamisel veebiaplikatsiooni veebiarhiivifailist. Veelgi lihtsam on mahavõtmine brauseriga haldusrakenduse kaudu.

Rakenduste baaskataloogi "webapps" asukohta saab muuta failis $CATALINA_BASE/conf/server.xml peremehepõhiselt määratava atribuudiga "appBase", sealjuures Tomcati vaikimisi peremees ehk "Host" on "localhost".

====Tomcati vahendid juurutamiseks====

Veebiaplikatsioonide juurutamine ja mahajuurutamine on võimalik ka kaughalduse teel tänu Tomcati internetipõhisele haldusrakendusele. Näiteks saab veebibrauserit kasutades teha serveri põhitoiminguid Tomcati enda HTML-põhise rakendusega "Tomcat Manager". Veebipõhine haldusrakendus töötab ka käsupõhise veebiteenusena, millele on valmis ehitatud Anti ja Maveni integratsioonid. Samuti eksisteerib käsurea kliendirakendus TCD (Tomcat Client Deployer). TCD ei kuulu Tomcati baaskoosseisu, kuid pakub peale serveri administreerimise tavatoimingute ka lisafunktsionaalsust nagu veebirakenduse kokkukompileerimine ja pakendamine. [http://tomcat.apache.org/tomcat-8.0-doc/manager-howto.html#Configuring_Manager_Application_Access 1]

====Haldurakendus "Tomcat Manager"====

Tomcati haldusrakendus "Tomcat Manager" (antud alamjaotuses lihtsalt haldusrakendus) on Tomcati enda veebiaplikatioon Tomcati brauseripõhiseks kaughalduseks, võimaldades muu hulgas järgnevat [http://tomcat.apache.org/tomcat-8.0-doc/manager-howto.html#Introduction 1]:
* Rakendada uue veebiaplikatsiooni war-faili üleslaadimisega;
* Näha kõiki rakendatud veebiaplikatsioone koos aktiivsete sessioonidega;
* Taasrakendada veebirakendust, näiteks veebiarhiivi pakitud klassifailide /WEB-INF/classes või teekide /WEB-INF/lib uuendamisel, kinnijooksmisel jms.;
* Peatada veebirakendust ilma serverist eemaldamata, samuti koos serverist eemaldamisega;
* Vaadata operatsioonisüsteemi ja Java parameetrite väärtusi;
* Näha kõiki saadaolevaid JNDI ressursse, k.a. andmebaasiühendusi, mis aitavad rakenduste programmeerijail defineerida <ResourceLink> elemendid web.xml konfiguratsioonifailis.

Tomcati installatsioon sisaldab haldusrakendust juba vaikimisi. Haldusrakenduse töölepanemiseks tuleb peremeesmasina konfiguratsioonikataloogi $CATALINA_BASE/conf/[enginename]/[hostname] lisada ka fail manager.xml. Vaikimisi valmiskonfigureeritud testrakendusel on see fail juba olemas asukohas $CATALINA_BASE/conf/Catalina/localhost/manager.xml . Rakendus asub vaikimisi aadressil http://[host]/manager/ , vaikimisi konfiguratsioone kasutades lahendub see asukohaks http://localhost:8080/manager/ . [http://tomcat.apache.org/tomcat-8.0-doc/manager-howto.html#Configuring_Manager_Application_Access 1]

====="Tomcat Manager" ligipääsu konfigureerimine=====

Vaikimisi on turvalisuspõhjustel ligipääs haldusrakendusele maha keeratud. Mismoodi täpselt kasutajatel ligipääsu võimaldada sõltub kasutatavast valdusest (realm). Vaikimisi defineerib $CATALINA_BASE/conf/server.xml valduseks "MemoryRealm". Vaikimisi loeb valdus "MemoryRealm" kasutajad failist $CATALINA_BASE/conf/tomcat-users.xml. Antud failis tuleb iga kasutaja defineerida omaette märgendiga <user>, mis näeb välja umbes järgmine [http://tomcat.apache.org/tomcat-8.0-doc/manager-howto.html#Configuring_Manager_Application_Access 1]:
<pre>
<user name="craig" password="secret" roles="manager-gui,manager-script" />
</pre>

Antud kasutajale on defineeritud korraga kaks rolli. Ligipääsu võimaldamiseks tulebki lihtsamal juhul kasutajatefailis $CATALINA_BASE/conf/tomcat-users.xml defineerida enda kasutaja. Kasutaja rolliks võib määrata näiteks "manager-gui", mis võimaldab ligipääsu kogu HTML liidese funktsionaalsusele.

Teised valdused on "JDBCRealm", mille puhul hoitakse kasutajatega seonduvat infot andmebaasis ja JNDIRealm, mille puhul kasutatakse lihtsustatud kataloogisirvimise protokolli (LDAP).
Lisaks saab haldusrakendusele keelata ligipääsu mujalt kui kindlaksmääratud IP-aadressidelt, lisades filtri "RemoteAddrValve" või "RemoteHostValve" konfigureerimisfaili manager.xml näiteks järgmiselt [http://tomcat.apache.org/tomcat-8.0-doc/manager-howto.html#Introduction 1]:
<pre>
<Context privileged="true">
<Valve className="org.apache.catalina.valves.RemoteAddrValve"
allow="127\.0\.0\.1"/>
</Context>
</pre>

=====Juurutamine ja mahavõtmine haldusrakendusega "Tomcat Manager"=====

Juurutamiseks lae kõigepealt veebiarhiivifail üles, kasutades esilehel asuvat sektsiooni "WAR file to deploy".

[[File:File:tomcat_manager_war_upload.png|400px|thumb|right|Veebiarhiivi üleslaadimise nupp]]

Rakendus kuvatakse seejärel hallatavate rakenduste nimekirjas. Kui konteiner pole seadistatud üleslaetud aplikatsiooni kohe ka ise rakendama, tuleb vajutada "Start". Rakenduse peatamiseks kasuta "Stop", uuesti rakendamiseks "Redeploy" ja serverist eemaldamiseks "Undeploy".


[[File:tomcat_manager_apps_list.png|800px|Rakenduste nimekiri]]

==Näpunäiteid Tomcati reaalseks kasutamiseks==

===Juurutamise järjekord===

Tomcati käivitumisel juurutatakse aplikatsioonid sellises järjekorras [http://www.mulesoft.com/tomcat-deploy-procedures 2]:
# Konteinerisse kopeeritud kontekstikirjelduste järgi $CATALINA_BASE/conf/[EngineName]/[HostName]/[ApplicationName].xml ;
# Lahtipakitud rakendused "webapps" kataloogis;
# Pakitud rakenduste veebiarhiivid "webapps" kataloogis.

Seetõttu peaks käsitsi taasjuurutamisel kindluse mõttes eelnevalt kustutama rakenduse lahtipakitud dokumendipõhja kataloogi "webapps" kataloogist. Kontekstikirjelduse muutumisel tuleb jälgida, kas kirjeldus on juba kopeeritud serverisse ning vajadusel eelmise versiooni ümber muuta või kustutada.

===Reaalsele domeenile konfigureerimine===

Järgnevalt eeldame, et domeen ''www.minukodukas.ee'' on juba serverimasinaga seostatud. Et Tomcat hakkaks ka reaalselt Internetist tulevatele päringutele vastama, tuleb muuta failis $CATALINA_BASE/conf/server.xml konteinerile ''Catalina'' vastava teenusemärgendi sisu sarnaselt järgnevaga:

<pre>
<Service name="Catalina">
<Connector port="80" protocol="HTTP/1.1" connectionTimeout="20000" URIEncoding="UTF-8" redirectPort="8443" />
<Engine name="Catalina" defaultHost="www.minukodukas.ee">
<Host name="www.minukodukas.ee" appBase="webapps" unpackWARs="true" autoDeploy="false" deployOnStartup="false" xmlValidation="false" xmlNamespaceAware="false">
<Context path="" docBase="kodukas" debug="0" reloadable="true" />
</Host>
</Engine>
</Service>
</pre>

Ülal defineerime põhiliselt selle, et Tomcat kuulaks domeeni ''www.minukodukas.ee'' ja kasutaks HTTP päringute jaoks porti 80. Ühtlasti otsib Tomcat juurutatavat rakendust failist $CATALINA_BASE/webapps/kodukas.war. Kuna rajalisandiks on määratud tühi sõne (path=""), siis juurutataksegi aplikatsioon aadressile ''www.minukodukas.ee'' ilma rajalisandita (a'la ''www.minukodukas.ee/wiki''). Seetõttu pakitakse ka veebiarhiiv tegelikult lahti kataloogi $CATALINA_BASE/webapps/ROOT mitte kataloogi $CATALINA_BASE/webapps/kodukas nagu võiks eeldada.

===Käigultvahetus===

Võimaldamaks käigultvahetust (hot deployment) peab konteineri konfiguratsioonifailis $CATALINA_BASE/conf/server.xml olema peremehepõhise märgendi "Host" atribuudi "autoDeploy" väärtus "true". Sel juhul installeerib ja uuendab Tomcat aplikatsioone dünaamiliselt töötamise ajal. Kui väärtuseks on "false", käib installeerimine staatiliselt ning serverisse juurutamiseks tuleb teha konteineri taaskäivitus. Käigultvahetust saab määrata ka peremehe defineerimisel "Host Manager" rakendusega, mis on kättesaadav aadressil http://localhost:8080/host-manager/html . Kasutamiseks tuleb lisada oma kasutajale rolli "admin-gui" (vt. alajaotus ""Tomcat Manager" ligipääsu konfigureerimine").

[[File:host_manager_app.png]]

Käigultvahetust päästikuks on vaikimisi uuendatud veebiarhiivifaili või lahtipakitud veebirakenduse paigutamine "webapps" kataloogi. Käigultvahetuse päästikutele võib failis $CATALINA_BASE/conf/server.xml ka ise lisada kuulatavaid ressursse nagu web.xml muutmine või mõne teegifaili vahetamine (märgendis "Host").

===Klassiteekide väljatõstmine veebiarhiivifailist===

Kõik konteksti poolt kasutatavad Java klassiteegid võib pakendada veebiarhiivi sisse kataloogi "lib", kuid nii võib osutuda veebiarhiivi üleslaadimine ajakulukaks, eriti arenduskeskkonnas. Kui ei teki ohtu, et erinevad rakendused kasutavad sama teegi erinevaid versioone, siis on vahel parem lisada osa teeke konteineri kataloogi $CATALINA_BASE/libs, kust need tehakse siis konteineri poolt kättesaadavaks kõigile konteineris jooksutatavatele kontekstidele. Nii võib vähendada veebiarhiivi faili suurust märgatavalt, mis tõstab kokkuvõttes juurutamiskiirust ja ühes sellega programmeerijate tööviljakust.

===Mälukasutus===

Konteineri poolt kasutatavat mälu saab vaadata haldusrakendusest vajutades lingile "Server Status". Mälukasutus on toodud jaotuses "JVM", kus näidatakse nii maksimaalselt kättesaadavat mälu kui ka parasjagu reserveeritud mälu.

<pre>Free memory: 41.16 MB Total memory: 123.37 MB Max memory: 1027.56 MB</pre>

Mälu suurendamiseks võib näiteks defineerida skriptis $CATALINA_BASE/bin/catalina.sh muutuja "JAVA_OPTS" ning määrata Java mälukasutuse miinimum- ja maksimumväärtused sarnaselt järgnevatega [http://www.mkyong.com/tomcat/tomcat-javalangoutofmemoryerror-permgen-space/ 3]:
<pre>
JAVA_OPTS="-Xms1536m -Xmx1536m -XX:NewSize=256m -XX:MaxNewSize=256m -XX:PermSize=256m -XX:MaxPermSize=256m"
</pre>

===Logifailid===

Vaikimisi defineerib Tomcat failiga $CATALINA_BASE/conf/logging.properties viis logerit, mis tekitavad viis eraldi logifaili.

{| style="background:#cccc99;color:black;width:80%;" border="1" cellpadding="5" cellspacing="0" align="center"
|+ Tomcati tekitatavad logifailid "logs" kataloogis
!Fail !! Kasutus
|- style="background:white; color:black"
| style="width:300px" |catalina.out
| Tomcati käivitus- ja peatamisskriptide väljund, samuti juurutatud rakenduste prindilaused System.out ja veaväljundid System.err
|- style="background:white; color:black"
| style="width:300px" |catalina.[yyyy]-[mm]-[dd].log
| Pööratud (rotated) logifail catalina.out
|- style="background:white; color:black"
| style="width:300px" |host-manager.[yyyy]-[mm]-[dd].log
| Logi peremehehalduse rakendusele (rakendus on kättesaadav kohalikust masinast aadressil http://localhost:8080/host-manager/html )
|- style="background:white; color:black"
| style="width:300px" |localhost.[yyyy]-[mm]-[dd].log
| Peremehe "localhost" logi; mitme virtuaalse peremehe korral tekitatakse igale peremehele oma logi
|- style="background:white; color:black"
| style="width:300px" |localhost_access_log.[yyyy]-[mm]-[dd].txt
| Konteinerisse Internetist saabunud päringute logi
|- style="background:white; color:black"
| style="width:300px" |manager.[yyyy]-[mm]-[dd].log
| Haldusrakenduse tegevuste logi
|}

===Viiteid===

Palju vajalikku võib leida [http://tomcat.apache.org/tomcat-8.0-doc/index.html Tomcat 8 dokumentatsioonist]

Lisaks üks viide põhjalikule Tomcati versioon seitsme ülevaatele: http://www.ntu.edu.sg/home/ehchua/programming/howto/Tomcat_More.html

= Kasutatud materjalid =

#http://tomcat.apache.org/tomcat-8.0-doc/index.html
#http://www.mulesoft.com/tomcat-deploy-procedures
#http://www.mkyong.com/tomcat/tomcat-javalangoutofmemoryerror-permgen-space/

[[Category: Operatsioonisüsteemide administreerimine ja sidumine]]

Tomcat

2014-01-02T21:56:16Z

Kveskima: /* Käsitsi juurutamine ja mahavõtmine */

==Autor==

Kristjan Veskimäe D32

2013

==Sissejuhatus==

Tomcat on vabalt kättesaadav server Java veebirakendustele. Põhimõtteliselt on tegemist Servlet/JSP spetsifikatsiooni toetava konteineriga. Kiire käivitumise ning rakenduste käigultvahetuse tõttu on Tomcat hea valik väiksemate ning keskmise suurusega Java veebirakenduste käitamiseks.

Antud töö kirjeldab Tomcati 8. versiooni. Põhiosa on üldiselt samasugune võrreldes paari eelmise versiooniga. Suuremad erinevused on versioonispetsiifilistes probleemides ja nende lahendamises, mida käesolev töö ei vaatle.

Töö vaatleb Tomcati paigaldamist ja seadistamist Unix-laadsesse keskkonda ning eeldab lugejalt algteadmisi sarnastes süsteemides. Tomcati on võimalik paigaldada ka Windows-keskkonda, kuid antud veebiserver eeldab kasutaja poolt käsureal töötamist ning Tomcati failihierarhias orienteerumist. Põhimõtteliselt on Java veebirakenduste arendamiseks IDE-abil võimalik siiski ka kasutada IDE-sse integreeritud Tomcati serverit - näiteks pakuvad sellist võimalust Eclipse EE ja NetBeans - kuid seda käesolev töö ei vaatle.

==Mõisted==

* '''Kontekst''' (context) - Tomcati mõistes üks konkreetne veebiaplikatsioon
* '''Konteiner''' (container) - veebiserver Tomcat ise
* '''Kontekstikirjeldus''' (context descriptor) - Tomcati-spetsiifiline konteksti konfiguratsioonimääratlus; peremehepõhine osa loetakse failist $CATALINA_HOME/conf/[enginename]/[hostname]/context.xml ja sellele lisatakse kontekstispetsiifilised täpsustused failist $CATALINA_BASE/conf/[enginename]/[hostname]/[webappname].xml; kontekstikirjeldus määrab näiteks nimed ressurssidele, sessioonihalduse parameetrid jmt. (olgu märgitud, et Tomcati varasemates versioonides sisaldusid kontekstikirjeldused põhikonfiguratsioonifailis server.xml)
* '''Dokumendipõhi''' (docBase) - kontekstile vastav kataloog Tomcati "webapps" kataloogis, mis tekib veebiaplikatsiooni serverisse rakendamisel
* '''Veebiarhiiv''' (Web application ARchive, war-file) - Java veebiaplikatsiooni jagatakse hea tava kohaselt selle üheainsa veebiarhiivi failina, mille laienditüübiks on "war". Tegemist on zip-protokolliga kokkupakitud kataloogiga, millel on Java veebirakenduste spetsifikatsioonile vastav ülesehitus. Siiski võib veebiaplikatsioon olla juurutamisel ka lahtipakendatud olekus (inglisekeelne termin on "war is exploded").

==Ülesehitus==

{| class="wikitable"
|+Kataloogid
|-
|style="color: green;" | $CATALINA_HOME
|baaskataloog, kuhu on Tomcat paigutatud
|-
|style="color: green;" | $CATALINA_BASE
|parasjagu töösoleva Tomcati eksemplari baaskataloog, mille alusel lahendatakse teed ülejäänud kataloogide ja failideni; ainult ühe kasutusel oleva Tomcati eksemplari puhul on see sama, mis $CATALINA_HOME

|-
|style="color: green;" | $CATALINA_BASE/bin
|serveri käivitus- ja abiskriptid
|-
|style="color: green;" | $CATALINA_BASE/conf
|konfiguratsioonifailid
|-
|style="color: green;" | $CATALINA_BASE/lib
|Tomcatile vaikimisi kättesaadavad Java klassiteegid (class libraries) ehk .jar-failid kuhu on Java kompileeritud kood kokku pakendatud
|-
|style="color: green;" | $CATALINA_BASE/logs
|logifailid paigutatakse vaikimisi siia
|-
|style="color: green;" | $CATALINA_BASE/webapps
|kataloog, kuhu paigutatakse serverisse juurutatavad veebiaplikatsioonid

|}

{| class="wikitable"
|+Mõned olulisemad failid
|-
|style="color: green;" | $CATALINA_BASE/bin/startup.sh
|serveri käivitusskript
|-
|style="color: green;" | $CATALINA_BASE/bin/shutdown.sh
|serveri peatusskript

|-
|style="color: green;" | $CATALINA_BASE/conf/server.xml
| konteineri peamine konfiguratsioonifail
|-
|style="color: green;" | $CATALINA_BASE/conf/[enginename]/[hostname]/[webappname].xml
|serveri administraatori jaoks konteinerisse endasse ümber kopeeritud rakendusepõhine kontekstikirjelduse konfiguratsioon failist $CATALINA_BASE/webapps/[ApplicationName]/META-INF/context.xml
|-
|style="color: green;" | $CATALINA_BASE/conf/[enginename]/[hostname]/context.xml
| fail, mis aitab administraatoril konteksti kohta käivat infot kirjeldada peremeesmasina-põhiselt ja halduseks mõeldud automaat-tööriistadel (näiteks Tomcat Manager ja TCD) oma tööd teha
|-
|style="color: green;" | $CATALINA_BASE/$CATALINA_BASE/conf/[enginename]/[hostname]/manager.xml
|fail, mis võimaldab lisada rakendustele ligipääsufiltreid
|-
|style="color: green;" | $CATALINA_BASE/webapps/[webappname]/META-INF/context.xml
|kontekstikirjeldusfail, mille veebirakenduse programmeerija on pakendanud oma aplikatsiooniga kaasa ning millega ta saab võimaluse kontekstikirjeldust omalt poolt mõjutada; kirjutatakse rakenduse uuestijuurutamisel üle, mistõttu administraator peaks muutma selle asemel konteinerisse ümber kopeeritud püsieksemplari $CATALINA_BASE/conf/[enginename]/[hostname]/context.xml
|-
|style="color: green;" | $CATALINA_BASE/webapps/[webappname]/WEB-INF/web.xml
|ka üks oluline Java veebiaplikatsiooni konfiguratsioonifail, mille pakendatakse koos veebiarhiiviga; enamasti muudab seda ainult programeerija; määrab muu hulgas millised aplikatsiooni osad vajavad autentimist või kui kiiresti veebisessioon aegub
|}

==Installeerimine==

===Installeerimine paketihalduriga===

<pre>
apt-cache search tomcat
apt-get install tomcat[version]-webapps
apt-get install tomcat[version]-admin
apt-get install tomcat[version]
</pre>

===Installeerimine käsitsi===

Paketihalduriga installeerides ei pruugi viimane Tomcati versioon olla kättesaadav ja see pakub ka vähem võimalusi kataloogide määramiseks jms. Käsitsi installeerimiseks tuleb laadida Tomcat kodulehelt alla. Lahtipakkimisel tekib kataloog, milles sisalduv fail "RUNNING.txt" on kõige kindlam allikas installeerimisel tekkivate probleemide vältimiseks ning lahendamiseks.

Vajaliku versiooni installeerimisfaili asukoha saab vaadata Tomcati kodulehelt sektsioonist "Download". Järgnevas näites installeerime Tomcati kõige uuema ebastabiilse kandidaatversiooni, mida näitab nimes sisalduv RC ehk "release candidate". Produktsioonikeskkonda tuleks siiski valida stabiilse versiooni. Käsitsi installeerimine on sarnane järgmisega:
<pre>
wget http://mirror.nexcess.net/apache/tomcat/tomcat-8/v8.0.0-RC5/bin/apache-tomcat-8.0.0-RC5.tar.gz
tar -zxvf apache-tomcat-8.0.0-RC5.tar.gz
mv /Users/kristjanveskimae/downloads/apache-tomcat-8.0.0-RC5 /usr/local/apache-tomcat-8.0.0-RC5
rm -f /Library/Tomcat
ln -s /usr/local/apache-tomcat-8.0.0-RC5/ /Library/Tomcat
chown -R kristjanveskimae /Library/Tomcat
chmod +x /Library/Tomcat/bin/*.sh
</pre>

==Käivitamine ja aplikatsiooni juurutamine==

===Konteineri käivitamine===

Tomcati käivitamise eelduseks on Java paigaldamine masinasse ning keskkonnamuutujate "JAVA_HOME" ja "JRE_HOME" defineerimine. Peale installeerimist võib kasutada skripte kataloogist $CATALINA_BASE/bin . Järgneb üks võimalik käivitamise ja peatamise näide, mis on kasutatav eelnevalt kirjeldatud käsitsi installeerimise juhul:
<pre>
/Library/Tomcat/bin/startup.sh
</pre>
ja peatamiseks
<pre>
/Library/Tomcat/bin/shutdown.sh
</pre>

===Näiteaplikatsiooni juurutamine===

Java veebiaplikatsiooni jagatakse hea tava kohaselt üheainsa veebiarhiivi failina. Siiski võib Tomcati juurutada ka lahtipakendatud olekus ("exploded") Java veebiaplikatsiooni.

====Käsitsi juurutamine ja mahavõtmine====

Näiteaplikatsiooni juurutamiseks lae selle veebiarhiivifail alla ning kopeeri oma konteineri juurutamiskataloogi 'webapps':
<pre>wget http://tomcat.apache.org/tomcat-8.0-doc/appdev/sample/sample.war
cp /Users/kristjanveskimae/downloads/sample.war /Library/Tomcat/webapps/sample.war</pre>

[[File:sample_app.png|400px|thumb|right|Õnnestunult rakendatud näiteaplikatsioon[http://localhost:8080/sample/]]]

Kui konfiguratsioonifailis $CATALINA_BASE/conf/server.xml on märgendi "Host" atribuudi "autoDeploy" väärtus "true", installeerib ja uuendab Tomcat aplikatsioone dünaamiliselt töötamise ajal. Kui väärtuseks on "false", käib installeerimine staatiliselt ning serverisse juurutamiseks tuleb teha konteineri taaskäivitus. [http://tomcat.apache.org/tomcat-8.0-doc/manager-howto.html#Deploy_A_New_Application_from_a_Local_Path 1] Mõlemal juhul pakib konteiner arhiveeritud faili ise lahti samasse kausta $CATALINA_BASE/webapps ning ka juurutab selle. Tekkiv aplikatsioon on lokaalsest masinast seejärel kättesaadav aadressil http://localhost:8080/sample/ .

Veebirakenduse käsitsi mahavõtmiseks tuleb kustutada talle vastav dokumendipõhja kataloog "webapps" kataloogist. Samuti tuleks kustutada .war-fail olemaks kindel, et Tomcat ei rakenda uuel käivitamisel veebiaplikatsiooni veebiarhiivifailist. Veelgi lihtsam on mahavõtmine brauseriga haldusrakenduse kaudu.

Rakenduste baaskataloogi "webapps" asukohta saab muuta failis $CATALINA_BASE/conf/server.xml peremehepõhiselt määratava atribuudiga "appBase", sealjuures Tomcati vaikimisi peremees ehk "Host" on "localhost".

====Tomcati vahendid juurutamiseks====

Veebiaplikatsioonide juurutamine ja mahajuurutamine on võimalik ka kaughalduse teel tänu Tomcati internetipõhisele haldusrakendusele. Näiteks saab veebibrauserit kasutades teha serveri põhitoiminguid Tomcati enda HTML-põhise rakendusega "Tomcat Manager". Veebipõhine haldusrakendus töötab ka käsupõhise veebiteenusena, millele on valmis ehitatud Anti ja Maveni integratsioonid. Samuti eksisteerib käsurea kliendirakendus TCD (Tomcat Client Deployer). TCD ei kuulu Tomcati baaskoosseisu, kuid pakub peale serveri administreerimise tavatoimingute ka lisafunktsionaalsust nagu veebirakenduse kokkukompileerimine ja pakendamine. [http://tomcat.apache.org/tomcat-8.0-doc/manager-howto.html#Configuring_Manager_Application_Access 1]

====Haldurakendus "Tomcat Manager"====

Tomcati haldusrakendus "Tomcat Manager" (antud alamjaotuses lihtsalt haldusrakendus) on Tomcati enda veebiaplikatioon Tomcati brauseripõhiseks kaughalduseks, võimaldades muu hulgas järgnevat [http://tomcat.apache.org/tomcat-8.0-doc/manager-howto.html#Introduction 1]:
* Rakendada uue veebiaplikatsiooni war-faili üleslaadimisega;
* Näha kõiki rakendatud veebiaplikatsioone koos aktiivsete sessioonidega;
* Taasrakendada veebirakendust, näiteks veebiarhiivi pakitud klassifailide /WEB-INF/classes või teekide /WEB-INF/lib uuendamisel, kinnijooksmisel jms.;
* Peatada veebirakendust ilma serverist eemaldamata, samuti koos serverist eemaldamisega;
* Vaadata operatsioonisüsteemi ja Java parameetrite väärtusi;
* Näha kõiki saadaolevaid JNDI ressursse, k.a. andmebaasiühendusi, mis aitavad rakenduste programmeerijail defineerida <ResourceLink> elemendid web.xml konfiguratsioonifailis.

Tomcati installatsioon sisaldab haldusrakendust juba vaikimisi. Haldusrakenduse töölepanemiseks tuleb peremeesmasina konfiguratsioonikataloogi $CATALINA_BASE/conf/[enginename]/[hostname] lisada ka fail manager.xml. Vaikimisi valmiskonfigureeritud testrakendusel on see fail juba olemas asukohas $CATALINA_BASE/conf/Catalina/localhost/manager.xml . Rakendus asub vaikimisi aadressil http://[host]/manager/ , vaikimisi konfiguratsioone kasutades lahendub see asukohaks http://localhost:8080/manager/ . [http://tomcat.apache.org/tomcat-8.0-doc/manager-howto.html#Configuring_Manager_Application_Access 1]

====="Tomcat Manager" ligipääsu konfigureerimine=====

Vaikimisi on turvalisuspõhjustel ligipääs haldusrakendusele maha keeratud. Mismoodi täpselt kasutajatel ligipääsu võimaldada sõltub kasutatavast valdusest (realm). Vaikimisi defineerib $CATALINA_BASE/conf/server.xml valduseks "MemoryRealm". Vaikimisi loeb valdus "MemoryRealm" kasutajad failist $CATALINA_BASE/conf/tomcat-users.xml. Antud failis tuleb iga kasutaja defineerida omaette märgendiga <user>, mis näeb välja umbes järgmine [http://tomcat.apache.org/tomcat-8.0-doc/manager-howto.html#Configuring_Manager_Application_Access 1]:
<pre>
<user name="craig" password="secret" roles="manager-gui,manager-script" />
</pre>

Antud kasutajale on defineeritud korraga kaks rolli. Ligipääsu võimaldamiseks tulebki lihtsamal juhul kasutajatefailis $CATALINA_BASE/conf/tomcat-users.xml defineerida enda kasutaja. Kasutaja rolliks võib määrata näiteks "manager-gui", mis võimaldab ligipääsu kogu HTML liidese funktsionaalsusele.

Teised valdused on "JDBCRealm", mille puhul hoitakse kasutajatega seonduvat infot andmebaasis ja JNDIRealm, mille puhul kasutatakse lihtsustatud kataloogisirvimise protokolli (LDAP).
Lisaks saab haldusrakendusele keelata ligipääsu mujalt kui kindlaksmääratud IP-aadressidelt, lisades filtri "RemoteAddrValve" või "RemoteHostValve" konfigureerimisfaili manager.xml näiteks järgmiselt [http://tomcat.apache.org/tomcat-8.0-doc/manager-howto.html#Introduction 1]:
<pre>
<Context privileged="true">
<Valve className="org.apache.catalina.valves.RemoteAddrValve"
allow="127\.0\.0\.1"/>
</Context>
</pre>

=====Juurutamine ja mahavõtmine haldusrakendusega "Tomcat Manager"=====

Juurutamiseks lae kõigepealt veebiarhiivifail üles, kasutades esilehel asuvat sektsiooni "WAR file to deploy".
[[File:tomcat_manager_war_upload.png]]

Rakendus kuvatakse seejärel hallatavate rakenduste nimekirjas. Kui konteiner pole seadistatud üleslaetud aplikatsiooni kohe ka ise rakendama, tuleb vajutada "Start". Rakenduse peatamiseks kasuta "Stop", uuesti rakendamiseks "Redeploy" ja serverist eemaldamiseks "Undeploy".


[[File:tomcat_manager_apps_list.png|800px|Rakenduste nimekiri]]

==Näpunäiteid Tomcati reaalseks kasutamiseks==

===Juurutamise järjekord===

Tomcati käivitumisel juurutatakse aplikatsioonid sellises järjekorras [http://www.mulesoft.com/tomcat-deploy-procedures 2]:
# Konteinerisse kopeeritud kontekstikirjelduste järgi $CATALINA_BASE/conf/[EngineName]/[HostName]/[ApplicationName].xml ;
# Lahtipakitud rakendused "webapps" kataloogis;
# Pakitud rakenduste veebiarhiivid "webapps" kataloogis.

Seetõttu peaks käsitsi taasjuurutamisel kindluse mõttes eelnevalt kustutama rakenduse lahtipakitud dokumendipõhja kataloogi "webapps" kataloogist. Kontekstikirjelduse muutumisel tuleb jälgida, kas kirjeldus on juba kopeeritud serverisse ning vajadusel eelmise versiooni ümber muuta või kustutada.

===Reaalsele domeenile konfigureerimine===

Järgnevalt eeldame, et domeen ''www.minukodukas.ee'' on juba serverimasinaga seostatud. Et Tomcat hakkaks ka reaalselt Internetist tulevatele päringutele vastama, tuleb muuta failis $CATALINA_BASE/conf/server.xml konteinerile ''Catalina'' vastava teenusemärgendi sisu sarnaselt järgnevaga:

<pre>
<Service name="Catalina">
<Connector port="80" protocol="HTTP/1.1" connectionTimeout="20000" URIEncoding="UTF-8" redirectPort="8443" />
<Engine name="Catalina" defaultHost="www.minukodukas.ee">
<Host name="www.minukodukas.ee" appBase="webapps" unpackWARs="true" autoDeploy="false" deployOnStartup="false" xmlValidation="false" xmlNamespaceAware="false">
<Context path="" docBase="kodukas" debug="0" reloadable="true" />
</Host>
</Engine>
</Service>
</pre>

Ülal defineerime põhiliselt selle, et Tomcat kuulaks domeeni ''www.minukodukas.ee'' ja kasutaks HTTP päringute jaoks porti 80. Ühtlasti otsib Tomcat juurutatavat rakendust failist $CATALINA_BASE/webapps/kodukas.war. Kuna rajalisandiks on määratud tühi sõne (path=""), siis juurutataksegi aplikatsioon aadressile ''www.minukodukas.ee'' ilma rajalisandita (a'la ''www.minukodukas.ee/wiki''). Seetõttu pakitakse ka veebiarhiiv tegelikult lahti kataloogi $CATALINA_BASE/webapps/ROOT mitte kataloogi $CATALINA_BASE/webapps/kodukas nagu võiks eeldada.

===Käigultvahetus===

Võimaldamaks käigultvahetust (hot deployment) peab konteineri konfiguratsioonifailis $CATALINA_BASE/conf/server.xml olema peremehepõhise märgendi "Host" atribuudi "autoDeploy" väärtus "true". Sel juhul installeerib ja uuendab Tomcat aplikatsioone dünaamiliselt töötamise ajal. Kui väärtuseks on "false", käib installeerimine staatiliselt ning serverisse juurutamiseks tuleb teha konteineri taaskäivitus. Käigultvahetust saab määrata ka peremehe defineerimisel "Host Manager" rakendusega, mis on kättesaadav aadressil http://localhost:8080/host-manager/html . Kasutamiseks tuleb lisada oma kasutajale rolli "admin-gui" (vt. alajaotus ""Tomcat Manager" ligipääsu konfigureerimine").

[[File:host_manager_app.png]]

Käigultvahetust päästikuks on vaikimisi uuendatud veebiarhiivifaili või lahtipakitud veebirakenduse paigutamine "webapps" kataloogi. Käigultvahetuse päästikutele võib failis $CATALINA_BASE/conf/server.xml ka ise lisada kuulatavaid ressursse nagu web.xml muutmine või mõne teegifaili vahetamine (märgendis "Host").

===Klassiteekide väljatõstmine veebiarhiivifailist===

Kõik konteksti poolt kasutatavad Java klassiteegid võib pakendada veebiarhiivi sisse kataloogi "lib", kuid nii võib osutuda veebiarhiivi üleslaadimine ajakulukaks, eriti arenduskeskkonnas. Kui ei teki ohtu, et erinevad rakendused kasutavad sama teegi erinevaid versioone, siis on vahel parem lisada osa teeke konteineri kataloogi $CATALINA_BASE/libs, kust need tehakse siis konteineri poolt kättesaadavaks kõigile konteineris jooksutatavatele kontekstidele. Nii võib vähendada veebiarhiivi faili suurust märgatavalt, mis tõstab kokkuvõttes juurutamiskiirust ja ühes sellega programmeerijate tööviljakust.

===Mälukasutus===

Konteineri poolt kasutatavat mälu saab vaadata haldusrakendusest vajutades lingile "Server Status". Mälukasutus on toodud jaotuses "JVM", kus näidatakse nii maksimaalselt kättesaadavat mälu kui ka parasjagu reserveeritud mälu.

<pre>Free memory: 41.16 MB Total memory: 123.37 MB Max memory: 1027.56 MB</pre>

Mälu suurendamiseks võib näiteks defineerida skriptis $CATALINA_BASE/bin/catalina.sh muutuja "JAVA_OPTS" ning määrata Java mälukasutuse miinimum- ja maksimumväärtused sarnaselt järgnevatega [http://www.mkyong.com/tomcat/tomcat-javalangoutofmemoryerror-permgen-space/ 3]:
<pre>
JAVA_OPTS="-Xms1536m -Xmx1536m -XX:NewSize=256m -XX:MaxNewSize=256m -XX:PermSize=256m -XX:MaxPermSize=256m"
</pre>

===Logifailid===

Vaikimisi defineerib Tomcat failiga $CATALINA_BASE/conf/logging.properties viis logerit, mis tekitavad viis eraldi logifaili.

{| style="background:#cccc99;color:black;width:80%;" border="1" cellpadding="5" cellspacing="0" align="center"
|+ Tomcati tekitatavad logifailid "logs" kataloogis
!Fail !! Kasutus
|- style="background:white; color:black"
| style="width:300px" |catalina.out
| Tomcati käivitus- ja peatamisskriptide väljund, samuti juurutatud rakenduste prindilaused System.out ja veaväljundid System.err
|- style="background:white; color:black"
| style="width:300px" |catalina.[yyyy]-[mm]-[dd].log
| Pööratud (rotated) logifail catalina.out
|- style="background:white; color:black"
| style="width:300px" |host-manager.[yyyy]-[mm]-[dd].log
| Logi peremehehalduse rakendusele (rakendus on kättesaadav kohalikust masinast aadressil http://localhost:8080/host-manager/html )
|- style="background:white; color:black"
| style="width:300px" |localhost.[yyyy]-[mm]-[dd].log
| Peremehe "localhost" logi; mitme virtuaalse peremehe korral tekitatakse igale peremehele oma logi
|- style="background:white; color:black"
| style="width:300px" |localhost_access_log.[yyyy]-[mm]-[dd].txt
| Konteinerisse Internetist saabunud päringute logi
|- style="background:white; color:black"
| style="width:300px" |manager.[yyyy]-[mm]-[dd].log
| Haldusrakenduse tegevuste logi
|}

===Viiteid===

Palju vajalikku võib leida [http://tomcat.apache.org/tomcat-8.0-doc/index.html Tomcat 8 dokumentatsioonist]

Lisaks üks viide põhjalikule Tomcati versioon seitsme ülevaatele: http://www.ntu.edu.sg/home/ehchua/programming/howto/Tomcat_More.html

= Kasutatud materjalid =

#http://tomcat.apache.org/tomcat-8.0-doc/index.html
#http://www.mulesoft.com/tomcat-deploy-procedures
#http://www.mkyong.com/tomcat/tomcat-javalangoutofmemoryerror-permgen-space/

[[Category: Operatsioonisüsteemide administreerimine ja sidumine]]

Tomcat

2014-01-02T21:52:13Z

Kveskima: /* Käsitsi juurutamine ja mahavõtmine */

==Autor==

Kristjan Veskimäe D32

2013

==Sissejuhatus==

Tomcat on vabalt kättesaadav server Java veebirakendustele. Põhimõtteliselt on tegemist Servlet/JSP spetsifikatsiooni toetava konteineriga. Kiire käivitumise ning rakenduste käigultvahetuse tõttu on Tomcat hea valik väiksemate ning keskmise suurusega Java veebirakenduste käitamiseks.

Antud töö kirjeldab Tomcati 8. versiooni. Põhiosa on üldiselt samasugune võrreldes paari eelmise versiooniga. Suuremad erinevused on versioonispetsiifilistes probleemides ja nende lahendamises, mida käesolev töö ei vaatle.

Töö vaatleb Tomcati paigaldamist ja seadistamist Unix-laadsesse keskkonda ning eeldab lugejalt algteadmisi sarnastes süsteemides. Tomcati on võimalik paigaldada ka Windows-keskkonda, kuid antud veebiserver eeldab kasutaja poolt käsureal töötamist ning Tomcati failihierarhias orienteerumist. Põhimõtteliselt on Java veebirakenduste arendamiseks IDE-abil võimalik siiski ka kasutada IDE-sse integreeritud Tomcati serverit - näiteks pakuvad sellist võimalust Eclipse EE ja NetBeans - kuid seda käesolev töö ei vaatle.

==Mõisted==

* '''Kontekst''' (context) - Tomcati mõistes üks konkreetne veebiaplikatsioon
* '''Konteiner''' (container) - veebiserver Tomcat ise
* '''Kontekstikirjeldus''' (context descriptor) - Tomcati-spetsiifiline konteksti konfiguratsioonimääratlus; peremehepõhine osa loetakse failist $CATALINA_HOME/conf/[enginename]/[hostname]/context.xml ja sellele lisatakse kontekstispetsiifilised täpsustused failist $CATALINA_BASE/conf/[enginename]/[hostname]/[webappname].xml; kontekstikirjeldus määrab näiteks nimed ressurssidele, sessioonihalduse parameetrid jmt. (olgu märgitud, et Tomcati varasemates versioonides sisaldusid kontekstikirjeldused põhikonfiguratsioonifailis server.xml)
* '''Dokumendipõhi''' (docBase) - kontekstile vastav kataloog Tomcati "webapps" kataloogis, mis tekib veebiaplikatsiooni serverisse rakendamisel
* '''Veebiarhiiv''' (Web application ARchive, war-file) - Java veebiaplikatsiooni jagatakse hea tava kohaselt selle üheainsa veebiarhiivi failina, mille laienditüübiks on "war". Tegemist on zip-protokolliga kokkupakitud kataloogiga, millel on Java veebirakenduste spetsifikatsioonile vastav ülesehitus. Siiski võib veebiaplikatsioon olla juurutamisel ka lahtipakendatud olekus (inglisekeelne termin on "war is exploded").

==Ülesehitus==

{| class="wikitable"
|+Kataloogid
|-
|style="color: green;" | $CATALINA_HOME
|baaskataloog, kuhu on Tomcat paigutatud
|-
|style="color: green;" | $CATALINA_BASE
|parasjagu töösoleva Tomcati eksemplari baaskataloog, mille alusel lahendatakse teed ülejäänud kataloogide ja failideni; ainult ühe kasutusel oleva Tomcati eksemplari puhul on see sama, mis $CATALINA_HOME

|-
|style="color: green;" | $CATALINA_BASE/bin
|serveri käivitus- ja abiskriptid
|-
|style="color: green;" | $CATALINA_BASE/conf
|konfiguratsioonifailid
|-
|style="color: green;" | $CATALINA_BASE/lib
|Tomcatile vaikimisi kättesaadavad Java klassiteegid (class libraries) ehk .jar-failid kuhu on Java kompileeritud kood kokku pakendatud
|-
|style="color: green;" | $CATALINA_BASE/logs
|logifailid paigutatakse vaikimisi siia
|-
|style="color: green;" | $CATALINA_BASE/webapps
|kataloog, kuhu paigutatakse serverisse juurutatavad veebiaplikatsioonid

|}

{| class="wikitable"
|+Mõned olulisemad failid
|-
|style="color: green;" | $CATALINA_BASE/bin/startup.sh
|serveri käivitusskript
|-
|style="color: green;" | $CATALINA_BASE/bin/shutdown.sh
|serveri peatusskript

|-
|style="color: green;" | $CATALINA_BASE/conf/server.xml
| konteineri peamine konfiguratsioonifail
|-
|style="color: green;" | $CATALINA_BASE/conf/[enginename]/[hostname]/[webappname].xml
|serveri administraatori jaoks konteinerisse endasse ümber kopeeritud rakendusepõhine kontekstikirjelduse konfiguratsioon failist $CATALINA_BASE/webapps/[ApplicationName]/META-INF/context.xml
|-
|style="color: green;" | $CATALINA_BASE/conf/[enginename]/[hostname]/context.xml
| fail, mis aitab administraatoril konteksti kohta käivat infot kirjeldada peremeesmasina-põhiselt ja halduseks mõeldud automaat-tööriistadel (näiteks Tomcat Manager ja TCD) oma tööd teha
|-
|style="color: green;" | $CATALINA_BASE/$CATALINA_BASE/conf/[enginename]/[hostname]/manager.xml
|fail, mis võimaldab lisada rakendustele ligipääsufiltreid
|-
|style="color: green;" | $CATALINA_BASE/webapps/[webappname]/META-INF/context.xml
|kontekstikirjeldusfail, mille veebirakenduse programmeerija on pakendanud oma aplikatsiooniga kaasa ning millega ta saab võimaluse kontekstikirjeldust omalt poolt mõjutada; kirjutatakse rakenduse uuestijuurutamisel üle, mistõttu administraator peaks muutma selle asemel konteinerisse ümber kopeeritud püsieksemplari $CATALINA_BASE/conf/[enginename]/[hostname]/context.xml
|-
|style="color: green;" | $CATALINA_BASE/webapps/[webappname]/WEB-INF/web.xml
|ka üks oluline Java veebiaplikatsiooni konfiguratsioonifail, mille pakendatakse koos veebiarhiiviga; enamasti muudab seda ainult programeerija; määrab muu hulgas millised aplikatsiooni osad vajavad autentimist või kui kiiresti veebisessioon aegub
|}

==Installeerimine==

===Installeerimine paketihalduriga===

<pre>
apt-cache search tomcat
apt-get install tomcat[version]-webapps
apt-get install tomcat[version]-admin
apt-get install tomcat[version]
</pre>

===Installeerimine käsitsi===

Paketihalduriga installeerides ei pruugi viimane Tomcati versioon olla kättesaadav ja see pakub ka vähem võimalusi kataloogide määramiseks jms. Käsitsi installeerimiseks tuleb laadida Tomcat kodulehelt alla. Lahtipakkimisel tekib kataloog, milles sisalduv fail "RUNNING.txt" on kõige kindlam allikas installeerimisel tekkivate probleemide vältimiseks ning lahendamiseks.

Vajaliku versiooni installeerimisfaili asukoha saab vaadata Tomcati kodulehelt sektsioonist "Download". Järgnevas näites installeerime Tomcati kõige uuema ebastabiilse kandidaatversiooni, mida näitab nimes sisalduv RC ehk "release candidate". Produktsioonikeskkonda tuleks siiski valida stabiilse versiooni. Käsitsi installeerimine on sarnane järgmisega:
<pre>
wget http://mirror.nexcess.net/apache/tomcat/tomcat-8/v8.0.0-RC5/bin/apache-tomcat-8.0.0-RC5.tar.gz
tar -zxvf apache-tomcat-8.0.0-RC5.tar.gz
mv /Users/kristjanveskimae/downloads/apache-tomcat-8.0.0-RC5 /usr/local/apache-tomcat-8.0.0-RC5
rm -f /Library/Tomcat
ln -s /usr/local/apache-tomcat-8.0.0-RC5/ /Library/Tomcat
chown -R kristjanveskimae /Library/Tomcat
chmod +x /Library/Tomcat/bin/*.sh
</pre>

==Käivitamine ja aplikatsiooni juurutamine==

===Konteineri käivitamine===

Tomcati käivitamise eelduseks on Java paigaldamine masinasse ning keskkonnamuutujate "JAVA_HOME" ja "JRE_HOME" defineerimine. Peale installeerimist võib kasutada skripte kataloogist $CATALINA_BASE/bin . Järgneb üks võimalik käivitamise ja peatamise näide, mis on kasutatav eelnevalt kirjeldatud käsitsi installeerimise juhul:
<pre>
/Library/Tomcat/bin/startup.sh
</pre>
ja peatamiseks
<pre>
/Library/Tomcat/bin/shutdown.sh
</pre>

===Näiteaplikatsiooni juurutamine===

Java veebiaplikatsiooni jagatakse hea tava kohaselt üheainsa veebiarhiivi failina. Siiski võib Tomcati juurutada ka lahtipakendatud olekus ("exploded") Java veebiaplikatsiooni.

====Käsitsi juurutamine ja mahavõtmine====

Näiteaplikatsiooni juurutamiseks lae selle veebiarhiivifail alla ning kopeeri oma konteineri juurutamiskataloogi 'webapps':
<pre>wget http://tomcat.apache.org/tomcat-8.0-doc/appdev/sample/sample.war
cp /Users/kristjanveskimae/downloads/sample.war /Library/Tomcat/webapps/sample.war</pre>

Kui konfiguratsioonifailis $CATALINA_BASE/conf/server.xml on märgendi "Host" atribuudi "autoDeploy" väärtus "true", installeerib ja uuendab Tomcat aplikatsioone dünaamiliselt töötamise ajal. Kui väärtuseks on "false", käib installeerimine staatiliselt ning serverisse juurutamiseks tuleb teha konteineri taaskäivitus. [http://tomcat.apache.org/tomcat-8.0-doc/manager-howto.html#Deploy_A_New_Application_from_a_Local_Path 1] Mõlemal juhul pakib konteiner arhiveeritud faili ise lahti samasse kausta $CATALINA_BASE/webapps ning ka juurutab selle. Tekkiv aplikatsioon on lokaalsest masinast seejärel kättesaadav aadressil http://localhost:8080/sample/ .

[[File:sample_app.png|400px]]

Veebirakenduse käsitsi mahavõtmiseks tuleb kustutada talle vastav dokumendipõhja kataloog "webapps" kataloogist. Samuti tuleks kustutada .war-fail olemaks kindel, et Tomcat ei rakenda uuel käivitamisel veebiaplikatsiooni veebiarhiivifailist. Veelgi lihtsam on mahavõtmine brauseriga haldusrakenduse kaudu.

Rakenduste baaskataloogi "webapps" asukohta saab muuta failis $CATALINA_BASE/conf/server.xml peremehepõhiselt määratava atribuudiga "appBase", sealjuures Tomcati vaikimisi peremees ehk "Host" on "localhost".

====Tomcati vahendid juurutamiseks====

Veebiaplikatsioonide juurutamine ja mahajuurutamine on võimalik ka kaughalduse teel tänu Tomcati internetipõhisele haldusrakendusele. Näiteks saab veebibrauserit kasutades teha serveri põhitoiminguid Tomcati enda HTML-põhise rakendusega "Tomcat Manager". Veebipõhine haldusrakendus töötab ka käsupõhise veebiteenusena, millele on valmis ehitatud Anti ja Maveni integratsioonid. Samuti eksisteerib käsurea kliendirakendus TCD (Tomcat Client Deployer). TCD ei kuulu Tomcati baaskoosseisu, kuid pakub peale serveri administreerimise tavatoimingute ka lisafunktsionaalsust nagu veebirakenduse kokkukompileerimine ja pakendamine. [http://tomcat.apache.org/tomcat-8.0-doc/manager-howto.html#Configuring_Manager_Application_Access 1]

====Haldurakendus "Tomcat Manager"====

Tomcati haldusrakendus "Tomcat Manager" (antud alamjaotuses lihtsalt haldusrakendus) on Tomcati enda veebiaplikatioon Tomcati brauseripõhiseks kaughalduseks, võimaldades muu hulgas järgnevat [http://tomcat.apache.org/tomcat-8.0-doc/manager-howto.html#Introduction 1]:
* Rakendada uue veebiaplikatsiooni war-faili üleslaadimisega;
* Näha kõiki rakendatud veebiaplikatsioone koos aktiivsete sessioonidega;
* Taasrakendada veebirakendust, näiteks veebiarhiivi pakitud klassifailide /WEB-INF/classes või teekide /WEB-INF/lib uuendamisel, kinnijooksmisel jms.;
* Peatada veebirakendust ilma serverist eemaldamata, samuti koos serverist eemaldamisega;
* Vaadata operatsioonisüsteemi ja Java parameetrite väärtusi;
* Näha kõiki saadaolevaid JNDI ressursse, k.a. andmebaasiühendusi, mis aitavad rakenduste programmeerijail defineerida <ResourceLink> elemendid web.xml konfiguratsioonifailis.

Tomcati installatsioon sisaldab haldusrakendust juba vaikimisi. Haldusrakenduse töölepanemiseks tuleb peremeesmasina konfiguratsioonikataloogi $CATALINA_BASE/conf/[enginename]/[hostname] lisada ka fail manager.xml. Vaikimisi valmiskonfigureeritud testrakendusel on see fail juba olemas asukohas $CATALINA_BASE/conf/Catalina/localhost/manager.xml . Rakendus asub vaikimisi aadressil http://[host]/manager/ , vaikimisi konfiguratsioone kasutades lahendub see asukohaks http://localhost:8080/manager/ . [http://tomcat.apache.org/tomcat-8.0-doc/manager-howto.html#Configuring_Manager_Application_Access 1]

====="Tomcat Manager" ligipääsu konfigureerimine=====

Vaikimisi on turvalisuspõhjustel ligipääs haldusrakendusele maha keeratud. Mismoodi täpselt kasutajatel ligipääsu võimaldada sõltub kasutatavast valdusest (realm). Vaikimisi defineerib $CATALINA_BASE/conf/server.xml valduseks "MemoryRealm". Vaikimisi loeb valdus "MemoryRealm" kasutajad failist $CATALINA_BASE/conf/tomcat-users.xml. Antud failis tuleb iga kasutaja defineerida omaette märgendiga <user>, mis näeb välja umbes järgmine [http://tomcat.apache.org/tomcat-8.0-doc/manager-howto.html#Configuring_Manager_Application_Access 1]:
<pre>
<user name="craig" password="secret" roles="manager-gui,manager-script" />
</pre>

Antud kasutajale on defineeritud korraga kaks rolli. Ligipääsu võimaldamiseks tulebki lihtsamal juhul kasutajatefailis $CATALINA_BASE/conf/tomcat-users.xml defineerida enda kasutaja. Kasutaja rolliks võib määrata näiteks "manager-gui", mis võimaldab ligipääsu kogu HTML liidese funktsionaalsusele.

Teised valdused on "JDBCRealm", mille puhul hoitakse kasutajatega seonduvat infot andmebaasis ja JNDIRealm, mille puhul kasutatakse lihtsustatud kataloogisirvimise protokolli (LDAP).
Lisaks saab haldusrakendusele keelata ligipääsu mujalt kui kindlaksmääratud IP-aadressidelt, lisades filtri "RemoteAddrValve" või "RemoteHostValve" konfigureerimisfaili manager.xml näiteks järgmiselt [http://tomcat.apache.org/tomcat-8.0-doc/manager-howto.html#Introduction 1]:
<pre>
<Context privileged="true">
<Valve className="org.apache.catalina.valves.RemoteAddrValve"
allow="127\.0\.0\.1"/>
</Context>
</pre>

=====Juurutamine ja mahavõtmine haldusrakendusega "Tomcat Manager"=====

Juurutamiseks lae kõigepealt veebiarhiivifail üles, kasutades esilehel asuvat sektsiooni "WAR file to deploy".
[[File:tomcat_manager_war_upload.png]]

Rakendus kuvatakse seejärel hallatavate rakenduste nimekirjas. Kui konteiner pole seadistatud üleslaetud aplikatsiooni kohe ka ise rakendama, tuleb vajutada "Start". Rakenduse peatamiseks kasuta "Stop", uuesti rakendamiseks "Redeploy" ja serverist eemaldamiseks "Undeploy".


[[File:tomcat_manager_apps_list.png|800px|Rakenduste nimekiri]]

==Näpunäiteid Tomcati reaalseks kasutamiseks==

===Juurutamise järjekord===

Tomcati käivitumisel juurutatakse aplikatsioonid sellises järjekorras [http://www.mulesoft.com/tomcat-deploy-procedures 2]:
# Konteinerisse kopeeritud kontekstikirjelduste järgi $CATALINA_BASE/conf/[EngineName]/[HostName]/[ApplicationName].xml ;
# Lahtipakitud rakendused "webapps" kataloogis;
# Pakitud rakenduste veebiarhiivid "webapps" kataloogis.

Seetõttu peaks käsitsi taasjuurutamisel kindluse mõttes eelnevalt kustutama rakenduse lahtipakitud dokumendipõhja kataloogi "webapps" kataloogist. Kontekstikirjelduse muutumisel tuleb jälgida, kas kirjeldus on juba kopeeritud serverisse ning vajadusel eelmise versiooni ümber muuta või kustutada.

===Reaalsele domeenile konfigureerimine===

Järgnevalt eeldame, et domeen ''www.minukodukas.ee'' on juba serverimasinaga seostatud. Et Tomcat hakkaks ka reaalselt Internetist tulevatele päringutele vastama, tuleb muuta failis $CATALINA_BASE/conf/server.xml konteinerile ''Catalina'' vastava teenusemärgendi sisu sarnaselt järgnevaga:

<pre>
<Service name="Catalina">
<Connector port="80" protocol="HTTP/1.1" connectionTimeout="20000" URIEncoding="UTF-8" redirectPort="8443" />
<Engine name="Catalina" defaultHost="www.minukodukas.ee">
<Host name="www.minukodukas.ee" appBase="webapps" unpackWARs="true" autoDeploy="false" deployOnStartup="false" xmlValidation="false" xmlNamespaceAware="false">
<Context path="" docBase="kodukas" debug="0" reloadable="true" />
</Host>
</Engine>
</Service>
</pre>

Ülal defineerime põhiliselt selle, et Tomcat kuulaks domeeni ''www.minukodukas.ee'' ja kasutaks HTTP päringute jaoks porti 80. Ühtlasti otsib Tomcat juurutatavat rakendust failist $CATALINA_BASE/webapps/kodukas.war. Kuna rajalisandiks on määratud tühi sõne (path=""), siis juurutataksegi aplikatsioon aadressile ''www.minukodukas.ee'' ilma rajalisandita (a'la ''www.minukodukas.ee/wiki''). Seetõttu pakitakse ka veebiarhiiv tegelikult lahti kataloogi $CATALINA_BASE/webapps/ROOT mitte kataloogi $CATALINA_BASE/webapps/kodukas nagu võiks eeldada.

===Käigultvahetus===

Võimaldamaks käigultvahetust (hot deployment) peab konteineri konfiguratsioonifailis $CATALINA_BASE/conf/server.xml olema peremehepõhise märgendi "Host" atribuudi "autoDeploy" väärtus "true". Sel juhul installeerib ja uuendab Tomcat aplikatsioone dünaamiliselt töötamise ajal. Kui väärtuseks on "false", käib installeerimine staatiliselt ning serverisse juurutamiseks tuleb teha konteineri taaskäivitus. Käigultvahetust saab määrata ka peremehe defineerimisel "Host Manager" rakendusega, mis on kättesaadav aadressil http://localhost:8080/host-manager/html . Kasutamiseks tuleb lisada oma kasutajale rolli "admin-gui" (vt. alajaotus ""Tomcat Manager" ligipääsu konfigureerimine").

[[File:host_manager_app.png]]

Käigultvahetust päästikuks on vaikimisi uuendatud veebiarhiivifaili või lahtipakitud veebirakenduse paigutamine "webapps" kataloogi. Käigultvahetuse päästikutele võib failis $CATALINA_BASE/conf/server.xml ka ise lisada kuulatavaid ressursse nagu web.xml muutmine või mõne teegifaili vahetamine (märgendis "Host").

===Klassiteekide väljatõstmine veebiarhiivifailist===

Kõik konteksti poolt kasutatavad Java klassiteegid võib pakendada veebiarhiivi sisse kataloogi "lib", kuid nii võib osutuda veebiarhiivi üleslaadimine ajakulukaks, eriti arenduskeskkonnas. Kui ei teki ohtu, et erinevad rakendused kasutavad sama teegi erinevaid versioone, siis on vahel parem lisada osa teeke konteineri kataloogi $CATALINA_BASE/libs, kust need tehakse siis konteineri poolt kättesaadavaks kõigile konteineris jooksutatavatele kontekstidele. Nii võib vähendada veebiarhiivi faili suurust märgatavalt, mis tõstab kokkuvõttes juurutamiskiirust ja ühes sellega programmeerijate tööviljakust.

===Mälukasutus===

Konteineri poolt kasutatavat mälu saab vaadata haldusrakendusest vajutades lingile "Server Status". Mälukasutus on toodud jaotuses "JVM", kus näidatakse nii maksimaalselt kättesaadavat mälu kui ka parasjagu reserveeritud mälu.

<pre>Free memory: 41.16 MB Total memory: 123.37 MB Max memory: 1027.56 MB</pre>

Mälu suurendamiseks võib näiteks defineerida skriptis $CATALINA_BASE/bin/catalina.sh muutuja "JAVA_OPTS" ning määrata Java mälukasutuse miinimum- ja maksimumväärtused sarnaselt järgnevatega [http://www.mkyong.com/tomcat/tomcat-javalangoutofmemoryerror-permgen-space/ 3]:
<pre>
JAVA_OPTS="-Xms1536m -Xmx1536m -XX:NewSize=256m -XX:MaxNewSize=256m -XX:PermSize=256m -XX:MaxPermSize=256m"
</pre>

===Logifailid===

Vaikimisi defineerib Tomcat failiga $CATALINA_BASE/conf/logging.properties viis logerit, mis tekitavad viis eraldi logifaili.

{| style="background:#cccc99;color:black;width:80%;" border="1" cellpadding="5" cellspacing="0" align="center"
|+ Tomcati tekitatavad logifailid "logs" kataloogis
!Fail !! Kasutus
|- style="background:white; color:black"
| style="width:300px" |catalina.out
| Tomcati käivitus- ja peatamisskriptide väljund, samuti juurutatud rakenduste prindilaused System.out ja veaväljundid System.err
|- style="background:white; color:black"
| style="width:300px" |catalina.[yyyy]-[mm]-[dd].log
| Pööratud (rotated) logifail catalina.out
|- style="background:white; color:black"
| style="width:300px" |host-manager.[yyyy]-[mm]-[dd].log
| Logi peremehehalduse rakendusele (rakendus on kättesaadav kohalikust masinast aadressil http://localhost:8080/host-manager/html )
|- style="background:white; color:black"
| style="width:300px" |localhost.[yyyy]-[mm]-[dd].log
| Peremehe "localhost" logi; mitme virtuaalse peremehe korral tekitatakse igale peremehele oma logi
|- style="background:white; color:black"
| style="width:300px" |localhost_access_log.[yyyy]-[mm]-[dd].txt
| Konteinerisse Internetist saabunud päringute logi
|- style="background:white; color:black"
| style="width:300px" |manager.[yyyy]-[mm]-[dd].log
| Haldusrakenduse tegevuste logi
|}

===Viiteid===

Palju vajalikku võib leida [http://tomcat.apache.org/tomcat-8.0-doc/index.html Tomcat 8 dokumentatsioonist]

Lisaks üks viide põhjalikule Tomcati versioon seitsme ülevaatele: http://www.ntu.edu.sg/home/ehchua/programming/howto/Tomcat_More.html

= Kasutatud materjalid =

#http://tomcat.apache.org/tomcat-8.0-doc/index.html
#http://www.mulesoft.com/tomcat-deploy-procedures
#http://www.mkyong.com/tomcat/tomcat-javalangoutofmemoryerror-permgen-space/

[[Category: Operatsioonisüsteemide administreerimine ja sidumine]]

Tomcat

2014-01-02T21:51:41Z

Kveskima: /* Haldurakendus "Tomcat Manager" */

==Autor==

Kristjan Veskimäe D32

2013

==Sissejuhatus==

Tomcat on vabalt kättesaadav server Java veebirakendustele. Põhimõtteliselt on tegemist Servlet/JSP spetsifikatsiooni toetava konteineriga. Kiire käivitumise ning rakenduste käigultvahetuse tõttu on Tomcat hea valik väiksemate ning keskmise suurusega Java veebirakenduste käitamiseks.

Antud töö kirjeldab Tomcati 8. versiooni. Põhiosa on üldiselt samasugune võrreldes paari eelmise versiooniga. Suuremad erinevused on versioonispetsiifilistes probleemides ja nende lahendamises, mida käesolev töö ei vaatle.

Töö vaatleb Tomcati paigaldamist ja seadistamist Unix-laadsesse keskkonda ning eeldab lugejalt algteadmisi sarnastes süsteemides. Tomcati on võimalik paigaldada ka Windows-keskkonda, kuid antud veebiserver eeldab kasutaja poolt käsureal töötamist ning Tomcati failihierarhias orienteerumist. Põhimõtteliselt on Java veebirakenduste arendamiseks IDE-abil võimalik siiski ka kasutada IDE-sse integreeritud Tomcati serverit - näiteks pakuvad sellist võimalust Eclipse EE ja NetBeans - kuid seda käesolev töö ei vaatle.

==Mõisted==

* '''Kontekst''' (context) - Tomcati mõistes üks konkreetne veebiaplikatsioon
* '''Konteiner''' (container) - veebiserver Tomcat ise
* '''Kontekstikirjeldus''' (context descriptor) - Tomcati-spetsiifiline konteksti konfiguratsioonimääratlus; peremehepõhine osa loetakse failist $CATALINA_HOME/conf/[enginename]/[hostname]/context.xml ja sellele lisatakse kontekstispetsiifilised täpsustused failist $CATALINA_BASE/conf/[enginename]/[hostname]/[webappname].xml; kontekstikirjeldus määrab näiteks nimed ressurssidele, sessioonihalduse parameetrid jmt. (olgu märgitud, et Tomcati varasemates versioonides sisaldusid kontekstikirjeldused põhikonfiguratsioonifailis server.xml)
* '''Dokumendipõhi''' (docBase) - kontekstile vastav kataloog Tomcati "webapps" kataloogis, mis tekib veebiaplikatsiooni serverisse rakendamisel
* '''Veebiarhiiv''' (Web application ARchive, war-file) - Java veebiaplikatsiooni jagatakse hea tava kohaselt selle üheainsa veebiarhiivi failina, mille laienditüübiks on "war". Tegemist on zip-protokolliga kokkupakitud kataloogiga, millel on Java veebirakenduste spetsifikatsioonile vastav ülesehitus. Siiski võib veebiaplikatsioon olla juurutamisel ka lahtipakendatud olekus (inglisekeelne termin on "war is exploded").

==Ülesehitus==

{| class="wikitable"
|+Kataloogid
|-
|style="color: green;" | $CATALINA_HOME
|baaskataloog, kuhu on Tomcat paigutatud
|-
|style="color: green;" | $CATALINA_BASE
|parasjagu töösoleva Tomcati eksemplari baaskataloog, mille alusel lahendatakse teed ülejäänud kataloogide ja failideni; ainult ühe kasutusel oleva Tomcati eksemplari puhul on see sama, mis $CATALINA_HOME

|-
|style="color: green;" | $CATALINA_BASE/bin
|serveri käivitus- ja abiskriptid
|-
|style="color: green;" | $CATALINA_BASE/conf
|konfiguratsioonifailid
|-
|style="color: green;" | $CATALINA_BASE/lib
|Tomcatile vaikimisi kättesaadavad Java klassiteegid (class libraries) ehk .jar-failid kuhu on Java kompileeritud kood kokku pakendatud
|-
|style="color: green;" | $CATALINA_BASE/logs
|logifailid paigutatakse vaikimisi siia
|-
|style="color: green;" | $CATALINA_BASE/webapps
|kataloog, kuhu paigutatakse serverisse juurutatavad veebiaplikatsioonid

|}

{| class="wikitable"
|+Mõned olulisemad failid
|-
|style="color: green;" | $CATALINA_BASE/bin/startup.sh
|serveri käivitusskript
|-
|style="color: green;" | $CATALINA_BASE/bin/shutdown.sh
|serveri peatusskript

|-
|style="color: green;" | $CATALINA_BASE/conf/server.xml
| konteineri peamine konfiguratsioonifail
|-
|style="color: green;" | $CATALINA_BASE/conf/[enginename]/[hostname]/[webappname].xml
|serveri administraatori jaoks konteinerisse endasse ümber kopeeritud rakendusepõhine kontekstikirjelduse konfiguratsioon failist $CATALINA_BASE/webapps/[ApplicationName]/META-INF/context.xml
|-
|style="color: green;" | $CATALINA_BASE/conf/[enginename]/[hostname]/context.xml
| fail, mis aitab administraatoril konteksti kohta käivat infot kirjeldada peremeesmasina-põhiselt ja halduseks mõeldud automaat-tööriistadel (näiteks Tomcat Manager ja TCD) oma tööd teha
|-
|style="color: green;" | $CATALINA_BASE/$CATALINA_BASE/conf/[enginename]/[hostname]/manager.xml
|fail, mis võimaldab lisada rakendustele ligipääsufiltreid
|-
|style="color: green;" | $CATALINA_BASE/webapps/[webappname]/META-INF/context.xml
|kontekstikirjeldusfail, mille veebirakenduse programmeerija on pakendanud oma aplikatsiooniga kaasa ning millega ta saab võimaluse kontekstikirjeldust omalt poolt mõjutada; kirjutatakse rakenduse uuestijuurutamisel üle, mistõttu administraator peaks muutma selle asemel konteinerisse ümber kopeeritud püsieksemplari $CATALINA_BASE/conf/[enginename]/[hostname]/context.xml
|-
|style="color: green;" | $CATALINA_BASE/webapps/[webappname]/WEB-INF/web.xml
|ka üks oluline Java veebiaplikatsiooni konfiguratsioonifail, mille pakendatakse koos veebiarhiiviga; enamasti muudab seda ainult programeerija; määrab muu hulgas millised aplikatsiooni osad vajavad autentimist või kui kiiresti veebisessioon aegub
|}

==Installeerimine==

===Installeerimine paketihalduriga===

<pre>
apt-cache search tomcat
apt-get install tomcat[version]-webapps
apt-get install tomcat[version]-admin
apt-get install tomcat[version]
</pre>

===Installeerimine käsitsi===

Paketihalduriga installeerides ei pruugi viimane Tomcati versioon olla kättesaadav ja see pakub ka vähem võimalusi kataloogide määramiseks jms. Käsitsi installeerimiseks tuleb laadida Tomcat kodulehelt alla. Lahtipakkimisel tekib kataloog, milles sisalduv fail "RUNNING.txt" on kõige kindlam allikas installeerimisel tekkivate probleemide vältimiseks ning lahendamiseks.

Vajaliku versiooni installeerimisfaili asukoha saab vaadata Tomcati kodulehelt sektsioonist "Download". Järgnevas näites installeerime Tomcati kõige uuema ebastabiilse kandidaatversiooni, mida näitab nimes sisalduv RC ehk "release candidate". Produktsioonikeskkonda tuleks siiski valida stabiilse versiooni. Käsitsi installeerimine on sarnane järgmisega:
<pre>
wget http://mirror.nexcess.net/apache/tomcat/tomcat-8/v8.0.0-RC5/bin/apache-tomcat-8.0.0-RC5.tar.gz
tar -zxvf apache-tomcat-8.0.0-RC5.tar.gz
mv /Users/kristjanveskimae/downloads/apache-tomcat-8.0.0-RC5 /usr/local/apache-tomcat-8.0.0-RC5
rm -f /Library/Tomcat
ln -s /usr/local/apache-tomcat-8.0.0-RC5/ /Library/Tomcat
chown -R kristjanveskimae /Library/Tomcat
chmod +x /Library/Tomcat/bin/*.sh
</pre>

==Käivitamine ja aplikatsiooni juurutamine==

===Konteineri käivitamine===

Tomcati käivitamise eelduseks on Java paigaldamine masinasse ning keskkonnamuutujate "JAVA_HOME" ja "JRE_HOME" defineerimine. Peale installeerimist võib kasutada skripte kataloogist $CATALINA_BASE/bin . Järgneb üks võimalik käivitamise ja peatamise näide, mis on kasutatav eelnevalt kirjeldatud käsitsi installeerimise juhul:
<pre>
/Library/Tomcat/bin/startup.sh
</pre>
ja peatamiseks
<pre>
/Library/Tomcat/bin/shutdown.sh
</pre>

===Näiteaplikatsiooni juurutamine===

Java veebiaplikatsiooni jagatakse hea tava kohaselt üheainsa veebiarhiivi failina. Siiski võib Tomcati juurutada ka lahtipakendatud olekus ("exploded") Java veebiaplikatsiooni.

====Käsitsi juurutamine ja mahavõtmine====

Näiteaplikatsiooni juurutamiseks lae selle veebiarhiivifail alla ning kopeeri oma konteineri juurutamiskataloogi 'webapps':
<pre>wget http://tomcat.apache.org/tomcat-8.0-doc/appdev/sample/sample.war
cp /Users/kristjanveskimae/downloads/sample.war /Library/Tomcat/webapps/sample.war</pre>

Kui konfiguratsioonifailis $CATALINA_BASE/conf/server.xml on märgendi "Host" atribuudi "autoDeploy" väärtus "true", installeerib ja uuendab Tomcat aplikatsioone dünaamiliselt töötamise ajal. Kui väärtuseks on "false", käib installeerimine staatiliselt ning serverisse juurutamiseks tuleb teha konteineri taaskäivitus. [http://tomcat.apache.org/tomcat-8.0-doc/manager-howto.html#Deploy_A_New_Application_from_a_Local_Path 2] Mõlemal juhul pakib konteiner arhiveeritud faili ise lahti samasse kausta $CATALINA_BASE/webapps ning ka juurutab selle. Tekkiv aplikatsioon on lokaalsest masinast seejärel kättesaadav aadressil http://localhost:8080/sample/ .

[[File:sample_app.png|400px]]

Veebirakenduse käsitsi mahavõtmiseks tuleb kustutada talle vastav dokumendipõhja kataloog "webapps" kataloogist. Samuti tuleks kustutada .war-fail olemaks kindel, et Tomcat ei rakenda uuel käivitamisel veebiaplikatsiooni veebiarhiivifailist. Veelgi lihtsam on mahavõtmine brauseriga haldusrakenduse kaudu.

Rakenduste baaskataloogi "webapps" asukohta saab muuta failis $CATALINA_BASE/conf/server.xml peremehepõhiselt määratava atribuudiga "appBase", sealjuures Tomcati vaikimisi peremees ehk "Host" on "localhost".

====Tomcati vahendid juurutamiseks====

Veebiaplikatsioonide juurutamine ja mahajuurutamine on võimalik ka kaughalduse teel tänu Tomcati internetipõhisele haldusrakendusele. Näiteks saab veebibrauserit kasutades teha serveri põhitoiminguid Tomcati enda HTML-põhise rakendusega "Tomcat Manager". Veebipõhine haldusrakendus töötab ka käsupõhise veebiteenusena, millele on valmis ehitatud Anti ja Maveni integratsioonid. Samuti eksisteerib käsurea kliendirakendus TCD (Tomcat Client Deployer). TCD ei kuulu Tomcati baaskoosseisu, kuid pakub peale serveri administreerimise tavatoimingute ka lisafunktsionaalsust nagu veebirakenduse kokkukompileerimine ja pakendamine. [http://tomcat.apache.org/tomcat-8.0-doc/manager-howto.html#Configuring_Manager_Application_Access 1]

====Haldurakendus "Tomcat Manager"====

Tomcati haldusrakendus "Tomcat Manager" (antud alamjaotuses lihtsalt haldusrakendus) on Tomcati enda veebiaplikatioon Tomcati brauseripõhiseks kaughalduseks, võimaldades muu hulgas järgnevat [http://tomcat.apache.org/tomcat-8.0-doc/manager-howto.html#Introduction 1]:
* Rakendada uue veebiaplikatsiooni war-faili üleslaadimisega;
* Näha kõiki rakendatud veebiaplikatsioone koos aktiivsete sessioonidega;
* Taasrakendada veebirakendust, näiteks veebiarhiivi pakitud klassifailide /WEB-INF/classes või teekide /WEB-INF/lib uuendamisel, kinnijooksmisel jms.;
* Peatada veebirakendust ilma serverist eemaldamata, samuti koos serverist eemaldamisega;
* Vaadata operatsioonisüsteemi ja Java parameetrite väärtusi;
* Näha kõiki saadaolevaid JNDI ressursse, k.a. andmebaasiühendusi, mis aitavad rakenduste programmeerijail defineerida <ResourceLink> elemendid web.xml konfiguratsioonifailis.

Tomcati installatsioon sisaldab haldusrakendust juba vaikimisi. Haldusrakenduse töölepanemiseks tuleb peremeesmasina konfiguratsioonikataloogi $CATALINA_BASE/conf/[enginename]/[hostname] lisada ka fail manager.xml. Vaikimisi valmiskonfigureeritud testrakendusel on see fail juba olemas asukohas $CATALINA_BASE/conf/Catalina/localhost/manager.xml . Rakendus asub vaikimisi aadressil http://[host]/manager/ , vaikimisi konfiguratsioone kasutades lahendub see asukohaks http://localhost:8080/manager/ . [http://tomcat.apache.org/tomcat-8.0-doc/manager-howto.html#Configuring_Manager_Application_Access 1]

====="Tomcat Manager" ligipääsu konfigureerimine=====

Vaikimisi on turvalisuspõhjustel ligipääs haldusrakendusele maha keeratud. Mismoodi täpselt kasutajatel ligipääsu võimaldada sõltub kasutatavast valdusest (realm). Vaikimisi defineerib $CATALINA_BASE/conf/server.xml valduseks "MemoryRealm". Vaikimisi loeb valdus "MemoryRealm" kasutajad failist $CATALINA_BASE/conf/tomcat-users.xml. Antud failis tuleb iga kasutaja defineerida omaette märgendiga <user>, mis näeb välja umbes järgmine [http://tomcat.apache.org/tomcat-8.0-doc/manager-howto.html#Configuring_Manager_Application_Access 1]:
<pre>
<user name="craig" password="secret" roles="manager-gui,manager-script" />
</pre>

Antud kasutajale on defineeritud korraga kaks rolli. Ligipääsu võimaldamiseks tulebki lihtsamal juhul kasutajatefailis $CATALINA_BASE/conf/tomcat-users.xml defineerida enda kasutaja. Kasutaja rolliks võib määrata näiteks "manager-gui", mis võimaldab ligipääsu kogu HTML liidese funktsionaalsusele.

Teised valdused on "JDBCRealm", mille puhul hoitakse kasutajatega seonduvat infot andmebaasis ja JNDIRealm, mille puhul kasutatakse lihtsustatud kataloogisirvimise protokolli (LDAP).
Lisaks saab haldusrakendusele keelata ligipääsu mujalt kui kindlaksmääratud IP-aadressidelt, lisades filtri "RemoteAddrValve" või "RemoteHostValve" konfigureerimisfaili manager.xml näiteks järgmiselt [http://tomcat.apache.org/tomcat-8.0-doc/manager-howto.html#Introduction 1]:
<pre>
<Context privileged="true">
<Valve className="org.apache.catalina.valves.RemoteAddrValve"
allow="127\.0\.0\.1"/>
</Context>
</pre>

=====Juurutamine ja mahavõtmine haldusrakendusega "Tomcat Manager"=====

Juurutamiseks lae kõigepealt veebiarhiivifail üles, kasutades esilehel asuvat sektsiooni "WAR file to deploy".
[[File:tomcat_manager_war_upload.png]]

Rakendus kuvatakse seejärel hallatavate rakenduste nimekirjas. Kui konteiner pole seadistatud üleslaetud aplikatsiooni kohe ka ise rakendama, tuleb vajutada "Start". Rakenduse peatamiseks kasuta "Stop", uuesti rakendamiseks "Redeploy" ja serverist eemaldamiseks "Undeploy".


[[File:tomcat_manager_apps_list.png|800px|Rakenduste nimekiri]]

==Näpunäiteid Tomcati reaalseks kasutamiseks==

===Juurutamise järjekord===

Tomcati käivitumisel juurutatakse aplikatsioonid sellises järjekorras [http://www.mulesoft.com/tomcat-deploy-procedures 2]:
# Konteinerisse kopeeritud kontekstikirjelduste järgi $CATALINA_BASE/conf/[EngineName]/[HostName]/[ApplicationName].xml ;
# Lahtipakitud rakendused "webapps" kataloogis;
# Pakitud rakenduste veebiarhiivid "webapps" kataloogis.

Seetõttu peaks käsitsi taasjuurutamisel kindluse mõttes eelnevalt kustutama rakenduse lahtipakitud dokumendipõhja kataloogi "webapps" kataloogist. Kontekstikirjelduse muutumisel tuleb jälgida, kas kirjeldus on juba kopeeritud serverisse ning vajadusel eelmise versiooni ümber muuta või kustutada.

===Reaalsele domeenile konfigureerimine===

Järgnevalt eeldame, et domeen ''www.minukodukas.ee'' on juba serverimasinaga seostatud. Et Tomcat hakkaks ka reaalselt Internetist tulevatele päringutele vastama, tuleb muuta failis $CATALINA_BASE/conf/server.xml konteinerile ''Catalina'' vastava teenusemärgendi sisu sarnaselt järgnevaga:

<pre>
<Service name="Catalina">
<Connector port="80" protocol="HTTP/1.1" connectionTimeout="20000" URIEncoding="UTF-8" redirectPort="8443" />
<Engine name="Catalina" defaultHost="www.minukodukas.ee">
<Host name="www.minukodukas.ee" appBase="webapps" unpackWARs="true" autoDeploy="false" deployOnStartup="false" xmlValidation="false" xmlNamespaceAware="false">
<Context path="" docBase="kodukas" debug="0" reloadable="true" />
</Host>
</Engine>
</Service>
</pre>

Ülal defineerime põhiliselt selle, et Tomcat kuulaks domeeni ''www.minukodukas.ee'' ja kasutaks HTTP päringute jaoks porti 80. Ühtlasti otsib Tomcat juurutatavat rakendust failist $CATALINA_BASE/webapps/kodukas.war. Kuna rajalisandiks on määratud tühi sõne (path=""), siis juurutataksegi aplikatsioon aadressile ''www.minukodukas.ee'' ilma rajalisandita (a'la ''www.minukodukas.ee/wiki''). Seetõttu pakitakse ka veebiarhiiv tegelikult lahti kataloogi $CATALINA_BASE/webapps/ROOT mitte kataloogi $CATALINA_BASE/webapps/kodukas nagu võiks eeldada.

===Käigultvahetus===

Võimaldamaks käigultvahetust (hot deployment) peab konteineri konfiguratsioonifailis $CATALINA_BASE/conf/server.xml olema peremehepõhise märgendi "Host" atribuudi "autoDeploy" väärtus "true". Sel juhul installeerib ja uuendab Tomcat aplikatsioone dünaamiliselt töötamise ajal. Kui väärtuseks on "false", käib installeerimine staatiliselt ning serverisse juurutamiseks tuleb teha konteineri taaskäivitus. Käigultvahetust saab määrata ka peremehe defineerimisel "Host Manager" rakendusega, mis on kättesaadav aadressil http://localhost:8080/host-manager/html . Kasutamiseks tuleb lisada oma kasutajale rolli "admin-gui" (vt. alajaotus ""Tomcat Manager" ligipääsu konfigureerimine").

[[File:host_manager_app.png]]

Käigultvahetust päästikuks on vaikimisi uuendatud veebiarhiivifaili või lahtipakitud veebirakenduse paigutamine "webapps" kataloogi. Käigultvahetuse päästikutele võib failis $CATALINA_BASE/conf/server.xml ka ise lisada kuulatavaid ressursse nagu web.xml muutmine või mõne teegifaili vahetamine (märgendis "Host").

===Klassiteekide väljatõstmine veebiarhiivifailist===

Kõik konteksti poolt kasutatavad Java klassiteegid võib pakendada veebiarhiivi sisse kataloogi "lib", kuid nii võib osutuda veebiarhiivi üleslaadimine ajakulukaks, eriti arenduskeskkonnas. Kui ei teki ohtu, et erinevad rakendused kasutavad sama teegi erinevaid versioone, siis on vahel parem lisada osa teeke konteineri kataloogi $CATALINA_BASE/libs, kust need tehakse siis konteineri poolt kättesaadavaks kõigile konteineris jooksutatavatele kontekstidele. Nii võib vähendada veebiarhiivi faili suurust märgatavalt, mis tõstab kokkuvõttes juurutamiskiirust ja ühes sellega programmeerijate tööviljakust.

===Mälukasutus===

Konteineri poolt kasutatavat mälu saab vaadata haldusrakendusest vajutades lingile "Server Status". Mälukasutus on toodud jaotuses "JVM", kus näidatakse nii maksimaalselt kättesaadavat mälu kui ka parasjagu reserveeritud mälu.

<pre>Free memory: 41.16 MB Total memory: 123.37 MB Max memory: 1027.56 MB</pre>

Mälu suurendamiseks võib näiteks defineerida skriptis $CATALINA_BASE/bin/catalina.sh muutuja "JAVA_OPTS" ning määrata Java mälukasutuse miinimum- ja maksimumväärtused sarnaselt järgnevatega [http://www.mkyong.com/tomcat/tomcat-javalangoutofmemoryerror-permgen-space/ 3]:
<pre>
JAVA_OPTS="-Xms1536m -Xmx1536m -XX:NewSize=256m -XX:MaxNewSize=256m -XX:PermSize=256m -XX:MaxPermSize=256m"
</pre>

===Logifailid===

Vaikimisi defineerib Tomcat failiga $CATALINA_BASE/conf/logging.properties viis logerit, mis tekitavad viis eraldi logifaili.

{| style="background:#cccc99;color:black;width:80%;" border="1" cellpadding="5" cellspacing="0" align="center"
|+ Tomcati tekitatavad logifailid "logs" kataloogis
!Fail !! Kasutus
|- style="background:white; color:black"
| style="width:300px" |catalina.out
| Tomcati käivitus- ja peatamisskriptide väljund, samuti juurutatud rakenduste prindilaused System.out ja veaväljundid System.err
|- style="background:white; color:black"
| style="width:300px" |catalina.[yyyy]-[mm]-[dd].log
| Pööratud (rotated) logifail catalina.out
|- style="background:white; color:black"
| style="width:300px" |host-manager.[yyyy]-[mm]-[dd].log
| Logi peremehehalduse rakendusele (rakendus on kättesaadav kohalikust masinast aadressil http://localhost:8080/host-manager/html )
|- style="background:white; color:black"
| style="width:300px" |localhost.[yyyy]-[mm]-[dd].log
| Peremehe "localhost" logi; mitme virtuaalse peremehe korral tekitatakse igale peremehele oma logi
|- style="background:white; color:black"
| style="width:300px" |localhost_access_log.[yyyy]-[mm]-[dd].txt
| Konteinerisse Internetist saabunud päringute logi
|- style="background:white; color:black"
| style="width:300px" |manager.[yyyy]-[mm]-[dd].log
| Haldusrakenduse tegevuste logi
|}

===Viiteid===

Palju vajalikku võib leida [http://tomcat.apache.org/tomcat-8.0-doc/index.html Tomcat 8 dokumentatsioonist]

Lisaks üks viide põhjalikule Tomcati versioon seitsme ülevaatele: http://www.ntu.edu.sg/home/ehchua/programming/howto/Tomcat_More.html

= Kasutatud materjalid =

#http://tomcat.apache.org/tomcat-8.0-doc/index.html
#http://www.mulesoft.com/tomcat-deploy-procedures
#http://www.mkyong.com/tomcat/tomcat-javalangoutofmemoryerror-permgen-space/

[[Category: Operatsioonisüsteemide administreerimine ja sidumine]]

Tomcat

2014-01-02T21:51:12Z

Kveskima: /* "Tomcat Manager" ligipääsu konfigureerimine */

==Autor==

Kristjan Veskimäe D32

2013

==Sissejuhatus==

Tomcat on vabalt kättesaadav server Java veebirakendustele. Põhimõtteliselt on tegemist Servlet/JSP spetsifikatsiooni toetava konteineriga. Kiire käivitumise ning rakenduste käigultvahetuse tõttu on Tomcat hea valik väiksemate ning keskmise suurusega Java veebirakenduste käitamiseks.

Antud töö kirjeldab Tomcati 8. versiooni. Põhiosa on üldiselt samasugune võrreldes paari eelmise versiooniga. Suuremad erinevused on versioonispetsiifilistes probleemides ja nende lahendamises, mida käesolev töö ei vaatle.

Töö vaatleb Tomcati paigaldamist ja seadistamist Unix-laadsesse keskkonda ning eeldab lugejalt algteadmisi sarnastes süsteemides. Tomcati on võimalik paigaldada ka Windows-keskkonda, kuid antud veebiserver eeldab kasutaja poolt käsureal töötamist ning Tomcati failihierarhias orienteerumist. Põhimõtteliselt on Java veebirakenduste arendamiseks IDE-abil võimalik siiski ka kasutada IDE-sse integreeritud Tomcati serverit - näiteks pakuvad sellist võimalust Eclipse EE ja NetBeans - kuid seda käesolev töö ei vaatle.

==Mõisted==

* '''Kontekst''' (context) - Tomcati mõistes üks konkreetne veebiaplikatsioon
* '''Konteiner''' (container) - veebiserver Tomcat ise
* '''Kontekstikirjeldus''' (context descriptor) - Tomcati-spetsiifiline konteksti konfiguratsioonimääratlus; peremehepõhine osa loetakse failist $CATALINA_HOME/conf/[enginename]/[hostname]/context.xml ja sellele lisatakse kontekstispetsiifilised täpsustused failist $CATALINA_BASE/conf/[enginename]/[hostname]/[webappname].xml; kontekstikirjeldus määrab näiteks nimed ressurssidele, sessioonihalduse parameetrid jmt. (olgu märgitud, et Tomcati varasemates versioonides sisaldusid kontekstikirjeldused põhikonfiguratsioonifailis server.xml)
* '''Dokumendipõhi''' (docBase) - kontekstile vastav kataloog Tomcati "webapps" kataloogis, mis tekib veebiaplikatsiooni serverisse rakendamisel
* '''Veebiarhiiv''' (Web application ARchive, war-file) - Java veebiaplikatsiooni jagatakse hea tava kohaselt selle üheainsa veebiarhiivi failina, mille laienditüübiks on "war". Tegemist on zip-protokolliga kokkupakitud kataloogiga, millel on Java veebirakenduste spetsifikatsioonile vastav ülesehitus. Siiski võib veebiaplikatsioon olla juurutamisel ka lahtipakendatud olekus (inglisekeelne termin on "war is exploded").

==Ülesehitus==

{| class="wikitable"
|+Kataloogid
|-
|style="color: green;" | $CATALINA_HOME
|baaskataloog, kuhu on Tomcat paigutatud
|-
|style="color: green;" | $CATALINA_BASE
|parasjagu töösoleva Tomcati eksemplari baaskataloog, mille alusel lahendatakse teed ülejäänud kataloogide ja failideni; ainult ühe kasutusel oleva Tomcati eksemplari puhul on see sama, mis $CATALINA_HOME

|-
|style="color: green;" | $CATALINA_BASE/bin
|serveri käivitus- ja abiskriptid
|-
|style="color: green;" | $CATALINA_BASE/conf
|konfiguratsioonifailid
|-
|style="color: green;" | $CATALINA_BASE/lib
|Tomcatile vaikimisi kättesaadavad Java klassiteegid (class libraries) ehk .jar-failid kuhu on Java kompileeritud kood kokku pakendatud
|-
|style="color: green;" | $CATALINA_BASE/logs
|logifailid paigutatakse vaikimisi siia
|-
|style="color: green;" | $CATALINA_BASE/webapps
|kataloog, kuhu paigutatakse serverisse juurutatavad veebiaplikatsioonid

|}

{| class="wikitable"
|+Mõned olulisemad failid
|-
|style="color: green;" | $CATALINA_BASE/bin/startup.sh
|serveri käivitusskript
|-
|style="color: green;" | $CATALINA_BASE/bin/shutdown.sh
|serveri peatusskript

|-
|style="color: green;" | $CATALINA_BASE/conf/server.xml
| konteineri peamine konfiguratsioonifail
|-
|style="color: green;" | $CATALINA_BASE/conf/[enginename]/[hostname]/[webappname].xml
|serveri administraatori jaoks konteinerisse endasse ümber kopeeritud rakendusepõhine kontekstikirjelduse konfiguratsioon failist $CATALINA_BASE/webapps/[ApplicationName]/META-INF/context.xml
|-
|style="color: green;" | $CATALINA_BASE/conf/[enginename]/[hostname]/context.xml
| fail, mis aitab administraatoril konteksti kohta käivat infot kirjeldada peremeesmasina-põhiselt ja halduseks mõeldud automaat-tööriistadel (näiteks Tomcat Manager ja TCD) oma tööd teha
|-
|style="color: green;" | $CATALINA_BASE/$CATALINA_BASE/conf/[enginename]/[hostname]/manager.xml
|fail, mis võimaldab lisada rakendustele ligipääsufiltreid
|-
|style="color: green;" | $CATALINA_BASE/webapps/[webappname]/META-INF/context.xml
|kontekstikirjeldusfail, mille veebirakenduse programmeerija on pakendanud oma aplikatsiooniga kaasa ning millega ta saab võimaluse kontekstikirjeldust omalt poolt mõjutada; kirjutatakse rakenduse uuestijuurutamisel üle, mistõttu administraator peaks muutma selle asemel konteinerisse ümber kopeeritud püsieksemplari $CATALINA_BASE/conf/[enginename]/[hostname]/context.xml
|-
|style="color: green;" | $CATALINA_BASE/webapps/[webappname]/WEB-INF/web.xml
|ka üks oluline Java veebiaplikatsiooni konfiguratsioonifail, mille pakendatakse koos veebiarhiiviga; enamasti muudab seda ainult programeerija; määrab muu hulgas millised aplikatsiooni osad vajavad autentimist või kui kiiresti veebisessioon aegub
|}

==Installeerimine==

===Installeerimine paketihalduriga===

<pre>
apt-cache search tomcat
apt-get install tomcat[version]-webapps
apt-get install tomcat[version]-admin
apt-get install tomcat[version]
</pre>

===Installeerimine käsitsi===

Paketihalduriga installeerides ei pruugi viimane Tomcati versioon olla kättesaadav ja see pakub ka vähem võimalusi kataloogide määramiseks jms. Käsitsi installeerimiseks tuleb laadida Tomcat kodulehelt alla. Lahtipakkimisel tekib kataloog, milles sisalduv fail "RUNNING.txt" on kõige kindlam allikas installeerimisel tekkivate probleemide vältimiseks ning lahendamiseks.

Vajaliku versiooni installeerimisfaili asukoha saab vaadata Tomcati kodulehelt sektsioonist "Download". Järgnevas näites installeerime Tomcati kõige uuema ebastabiilse kandidaatversiooni, mida näitab nimes sisalduv RC ehk "release candidate". Produktsioonikeskkonda tuleks siiski valida stabiilse versiooni. Käsitsi installeerimine on sarnane järgmisega:
<pre>
wget http://mirror.nexcess.net/apache/tomcat/tomcat-8/v8.0.0-RC5/bin/apache-tomcat-8.0.0-RC5.tar.gz
tar -zxvf apache-tomcat-8.0.0-RC5.tar.gz
mv /Users/kristjanveskimae/downloads/apache-tomcat-8.0.0-RC5 /usr/local/apache-tomcat-8.0.0-RC5
rm -f /Library/Tomcat
ln -s /usr/local/apache-tomcat-8.0.0-RC5/ /Library/Tomcat
chown -R kristjanveskimae /Library/Tomcat
chmod +x /Library/Tomcat/bin/*.sh
</pre>

==Käivitamine ja aplikatsiooni juurutamine==

===Konteineri käivitamine===

Tomcati käivitamise eelduseks on Java paigaldamine masinasse ning keskkonnamuutujate "JAVA_HOME" ja "JRE_HOME" defineerimine. Peale installeerimist võib kasutada skripte kataloogist $CATALINA_BASE/bin . Järgneb üks võimalik käivitamise ja peatamise näide, mis on kasutatav eelnevalt kirjeldatud käsitsi installeerimise juhul:
<pre>
/Library/Tomcat/bin/startup.sh
</pre>
ja peatamiseks
<pre>
/Library/Tomcat/bin/shutdown.sh
</pre>

===Näiteaplikatsiooni juurutamine===

Java veebiaplikatsiooni jagatakse hea tava kohaselt üheainsa veebiarhiivi failina. Siiski võib Tomcati juurutada ka lahtipakendatud olekus ("exploded") Java veebiaplikatsiooni.

====Käsitsi juurutamine ja mahavõtmine====

Näiteaplikatsiooni juurutamiseks lae selle veebiarhiivifail alla ning kopeeri oma konteineri juurutamiskataloogi 'webapps':
<pre>wget http://tomcat.apache.org/tomcat-8.0-doc/appdev/sample/sample.war
cp /Users/kristjanveskimae/downloads/sample.war /Library/Tomcat/webapps/sample.war</pre>

Kui konfiguratsioonifailis $CATALINA_BASE/conf/server.xml on märgendi "Host" atribuudi "autoDeploy" väärtus "true", installeerib ja uuendab Tomcat aplikatsioone dünaamiliselt töötamise ajal. Kui väärtuseks on "false", käib installeerimine staatiliselt ning serverisse juurutamiseks tuleb teha konteineri taaskäivitus. [http://tomcat.apache.org/tomcat-8.0-doc/manager-howto.html#Deploy_A_New_Application_from_a_Local_Path 2] Mõlemal juhul pakib konteiner arhiveeritud faili ise lahti samasse kausta $CATALINA_BASE/webapps ning ka juurutab selle. Tekkiv aplikatsioon on lokaalsest masinast seejärel kättesaadav aadressil http://localhost:8080/sample/ .

[[File:sample_app.png|400px]]

Veebirakenduse käsitsi mahavõtmiseks tuleb kustutada talle vastav dokumendipõhja kataloog "webapps" kataloogist. Samuti tuleks kustutada .war-fail olemaks kindel, et Tomcat ei rakenda uuel käivitamisel veebiaplikatsiooni veebiarhiivifailist. Veelgi lihtsam on mahavõtmine brauseriga haldusrakenduse kaudu.

Rakenduste baaskataloogi "webapps" asukohta saab muuta failis $CATALINA_BASE/conf/server.xml peremehepõhiselt määratava atribuudiga "appBase", sealjuures Tomcati vaikimisi peremees ehk "Host" on "localhost".

====Tomcati vahendid juurutamiseks====

Veebiaplikatsioonide juurutamine ja mahajuurutamine on võimalik ka kaughalduse teel tänu Tomcati internetipõhisele haldusrakendusele. Näiteks saab veebibrauserit kasutades teha serveri põhitoiminguid Tomcati enda HTML-põhise rakendusega "Tomcat Manager". Veebipõhine haldusrakendus töötab ka käsupõhise veebiteenusena, millele on valmis ehitatud Anti ja Maveni integratsioonid. Samuti eksisteerib käsurea kliendirakendus TCD (Tomcat Client Deployer). TCD ei kuulu Tomcati baaskoosseisu, kuid pakub peale serveri administreerimise tavatoimingute ka lisafunktsionaalsust nagu veebirakenduse kokkukompileerimine ja pakendamine. [http://tomcat.apache.org/tomcat-8.0-doc/manager-howto.html#Configuring_Manager_Application_Access 1]

====Haldurakendus "Tomcat Manager"====

Tomcati haldusrakendus "Tomcat Manager" (antud alamjaotuses lihtsalt haldusrakendus) on Tomcati enda veebiaplikatioon Tomcati brauseripõhiseks kaughalduseks, võimaldades muu hulgas järgnevat [http://tomcat.apache.org/tomcat-8.0-doc/manager-howto.html#Introduction 3]:
* Rakendada uue veebiaplikatsiooni war-faili üleslaadimisega;
* Näha kõiki rakendatud veebiaplikatsioone koos aktiivsete sessioonidega;
* Taasrakendada veebirakendust, näiteks veebiarhiivi pakitud klassifailide /WEB-INF/classes või teekide /WEB-INF/lib uuendamisel, kinnijooksmisel jms.;
* Peatada veebirakendust ilma serverist eemaldamata, samuti koos serverist eemaldamisega;
* Vaadata operatsioonisüsteemi ja Java parameetrite väärtusi;
* Näha kõiki saadaolevaid JNDI ressursse, k.a. andmebaasiühendusi, mis aitavad rakenduste programmeerijail defineerida <ResourceLink> elemendid web.xml konfiguratsioonifailis.

Tomcati installatsioon sisaldab haldusrakendust juba vaikimisi. Haldusrakenduse töölepanemiseks tuleb peremeesmasina konfiguratsioonikataloogi $CATALINA_BASE/conf/[enginename]/[hostname] lisada ka fail manager.xml. Vaikimisi valmiskonfigureeritud testrakendusel on see fail juba olemas asukohas $CATALINA_BASE/conf/Catalina/localhost/manager.xml . Rakendus asub vaikimisi aadressil http://[host]/manager/ , vaikimisi konfiguratsioone kasutades lahendub see asukohaks http://localhost:8080/manager/ . [http://tomcat.apache.org/tomcat-8.0-doc/manager-howto.html#Configuring_Manager_Application_Access 4]

====="Tomcat Manager" ligipääsu konfigureerimine=====

Vaikimisi on turvalisuspõhjustel ligipääs haldusrakendusele maha keeratud. Mismoodi täpselt kasutajatel ligipääsu võimaldada sõltub kasutatavast valdusest (realm). Vaikimisi defineerib $CATALINA_BASE/conf/server.xml valduseks "MemoryRealm". Vaikimisi loeb valdus "MemoryRealm" kasutajad failist $CATALINA_BASE/conf/tomcat-users.xml. Antud failis tuleb iga kasutaja defineerida omaette märgendiga <user>, mis näeb välja umbes järgmine [http://tomcat.apache.org/tomcat-8.0-doc/manager-howto.html#Configuring_Manager_Application_Access 1]:
<pre>
<user name="craig" password="secret" roles="manager-gui,manager-script" />
</pre>

Antud kasutajale on defineeritud korraga kaks rolli. Ligipääsu võimaldamiseks tulebki lihtsamal juhul kasutajatefailis $CATALINA_BASE/conf/tomcat-users.xml defineerida enda kasutaja. Kasutaja rolliks võib määrata näiteks "manager-gui", mis võimaldab ligipääsu kogu HTML liidese funktsionaalsusele.

Teised valdused on "JDBCRealm", mille puhul hoitakse kasutajatega seonduvat infot andmebaasis ja JNDIRealm, mille puhul kasutatakse lihtsustatud kataloogisirvimise protokolli (LDAP).
Lisaks saab haldusrakendusele keelata ligipääsu mujalt kui kindlaksmääratud IP-aadressidelt, lisades filtri "RemoteAddrValve" või "RemoteHostValve" konfigureerimisfaili manager.xml näiteks järgmiselt [http://tomcat.apache.org/tomcat-8.0-doc/manager-howto.html#Introduction 1]:
<pre>
<Context privileged="true">
<Valve className="org.apache.catalina.valves.RemoteAddrValve"
allow="127\.0\.0\.1"/>
</Context>
</pre>

=====Juurutamine ja mahavõtmine haldusrakendusega "Tomcat Manager"=====

Juurutamiseks lae kõigepealt veebiarhiivifail üles, kasutades esilehel asuvat sektsiooni "WAR file to deploy".
[[File:tomcat_manager_war_upload.png]]

Rakendus kuvatakse seejärel hallatavate rakenduste nimekirjas. Kui konteiner pole seadistatud üleslaetud aplikatsiooni kohe ka ise rakendama, tuleb vajutada "Start". Rakenduse peatamiseks kasuta "Stop", uuesti rakendamiseks "Redeploy" ja serverist eemaldamiseks "Undeploy".


[[File:tomcat_manager_apps_list.png|800px|Rakenduste nimekiri]]

==Näpunäiteid Tomcati reaalseks kasutamiseks==

===Juurutamise järjekord===

Tomcati käivitumisel juurutatakse aplikatsioonid sellises järjekorras [http://www.mulesoft.com/tomcat-deploy-procedures 2]:
# Konteinerisse kopeeritud kontekstikirjelduste järgi $CATALINA_BASE/conf/[EngineName]/[HostName]/[ApplicationName].xml ;
# Lahtipakitud rakendused "webapps" kataloogis;
# Pakitud rakenduste veebiarhiivid "webapps" kataloogis.

Seetõttu peaks käsitsi taasjuurutamisel kindluse mõttes eelnevalt kustutama rakenduse lahtipakitud dokumendipõhja kataloogi "webapps" kataloogist. Kontekstikirjelduse muutumisel tuleb jälgida, kas kirjeldus on juba kopeeritud serverisse ning vajadusel eelmise versiooni ümber muuta või kustutada.

===Reaalsele domeenile konfigureerimine===

Järgnevalt eeldame, et domeen ''www.minukodukas.ee'' on juba serverimasinaga seostatud. Et Tomcat hakkaks ka reaalselt Internetist tulevatele päringutele vastama, tuleb muuta failis $CATALINA_BASE/conf/server.xml konteinerile ''Catalina'' vastava teenusemärgendi sisu sarnaselt järgnevaga:

<pre>
<Service name="Catalina">
<Connector port="80" protocol="HTTP/1.1" connectionTimeout="20000" URIEncoding="UTF-8" redirectPort="8443" />
<Engine name="Catalina" defaultHost="www.minukodukas.ee">
<Host name="www.minukodukas.ee" appBase="webapps" unpackWARs="true" autoDeploy="false" deployOnStartup="false" xmlValidation="false" xmlNamespaceAware="false">
<Context path="" docBase="kodukas" debug="0" reloadable="true" />
</Host>
</Engine>
</Service>
</pre>

Ülal defineerime põhiliselt selle, et Tomcat kuulaks domeeni ''www.minukodukas.ee'' ja kasutaks HTTP päringute jaoks porti 80. Ühtlasti otsib Tomcat juurutatavat rakendust failist $CATALINA_BASE/webapps/kodukas.war. Kuna rajalisandiks on määratud tühi sõne (path=""), siis juurutataksegi aplikatsioon aadressile ''www.minukodukas.ee'' ilma rajalisandita (a'la ''www.minukodukas.ee/wiki''). Seetõttu pakitakse ka veebiarhiiv tegelikult lahti kataloogi $CATALINA_BASE/webapps/ROOT mitte kataloogi $CATALINA_BASE/webapps/kodukas nagu võiks eeldada.

===Käigultvahetus===

Võimaldamaks käigultvahetust (hot deployment) peab konteineri konfiguratsioonifailis $CATALINA_BASE/conf/server.xml olema peremehepõhise märgendi "Host" atribuudi "autoDeploy" väärtus "true". Sel juhul installeerib ja uuendab Tomcat aplikatsioone dünaamiliselt töötamise ajal. Kui väärtuseks on "false", käib installeerimine staatiliselt ning serverisse juurutamiseks tuleb teha konteineri taaskäivitus. Käigultvahetust saab määrata ka peremehe defineerimisel "Host Manager" rakendusega, mis on kättesaadav aadressil http://localhost:8080/host-manager/html . Kasutamiseks tuleb lisada oma kasutajale rolli "admin-gui" (vt. alajaotus ""Tomcat Manager" ligipääsu konfigureerimine").

[[File:host_manager_app.png]]

Käigultvahetust päästikuks on vaikimisi uuendatud veebiarhiivifaili või lahtipakitud veebirakenduse paigutamine "webapps" kataloogi. Käigultvahetuse päästikutele võib failis $CATALINA_BASE/conf/server.xml ka ise lisada kuulatavaid ressursse nagu web.xml muutmine või mõne teegifaili vahetamine (märgendis "Host").

===Klassiteekide väljatõstmine veebiarhiivifailist===

Kõik konteksti poolt kasutatavad Java klassiteegid võib pakendada veebiarhiivi sisse kataloogi "lib", kuid nii võib osutuda veebiarhiivi üleslaadimine ajakulukaks, eriti arenduskeskkonnas. Kui ei teki ohtu, et erinevad rakendused kasutavad sama teegi erinevaid versioone, siis on vahel parem lisada osa teeke konteineri kataloogi $CATALINA_BASE/libs, kust need tehakse siis konteineri poolt kättesaadavaks kõigile konteineris jooksutatavatele kontekstidele. Nii võib vähendada veebiarhiivi faili suurust märgatavalt, mis tõstab kokkuvõttes juurutamiskiirust ja ühes sellega programmeerijate tööviljakust.

===Mälukasutus===

Konteineri poolt kasutatavat mälu saab vaadata haldusrakendusest vajutades lingile "Server Status". Mälukasutus on toodud jaotuses "JVM", kus näidatakse nii maksimaalselt kättesaadavat mälu kui ka parasjagu reserveeritud mälu.

<pre>Free memory: 41.16 MB Total memory: 123.37 MB Max memory: 1027.56 MB</pre>

Mälu suurendamiseks võib näiteks defineerida skriptis $CATALINA_BASE/bin/catalina.sh muutuja "JAVA_OPTS" ning määrata Java mälukasutuse miinimum- ja maksimumväärtused sarnaselt järgnevatega [http://www.mkyong.com/tomcat/tomcat-javalangoutofmemoryerror-permgen-space/ 3]:
<pre>
JAVA_OPTS="-Xms1536m -Xmx1536m -XX:NewSize=256m -XX:MaxNewSize=256m -XX:PermSize=256m -XX:MaxPermSize=256m"
</pre>

===Logifailid===

Vaikimisi defineerib Tomcat failiga $CATALINA_BASE/conf/logging.properties viis logerit, mis tekitavad viis eraldi logifaili.

{| style="background:#cccc99;color:black;width:80%;" border="1" cellpadding="5" cellspacing="0" align="center"
|+ Tomcati tekitatavad logifailid "logs" kataloogis
!Fail !! Kasutus
|- style="background:white; color:black"
| style="width:300px" |catalina.out
| Tomcati käivitus- ja peatamisskriptide väljund, samuti juurutatud rakenduste prindilaused System.out ja veaväljundid System.err
|- style="background:white; color:black"
| style="width:300px" |catalina.[yyyy]-[mm]-[dd].log
| Pööratud (rotated) logifail catalina.out
|- style="background:white; color:black"
| style="width:300px" |host-manager.[yyyy]-[mm]-[dd].log
| Logi peremehehalduse rakendusele (rakendus on kättesaadav kohalikust masinast aadressil http://localhost:8080/host-manager/html )
|- style="background:white; color:black"
| style="width:300px" |localhost.[yyyy]-[mm]-[dd].log
| Peremehe "localhost" logi; mitme virtuaalse peremehe korral tekitatakse igale peremehele oma logi
|- style="background:white; color:black"
| style="width:300px" |localhost_access_log.[yyyy]-[mm]-[dd].txt
| Konteinerisse Internetist saabunud päringute logi
|- style="background:white; color:black"
| style="width:300px" |manager.[yyyy]-[mm]-[dd].log
| Haldusrakenduse tegevuste logi
|}

===Viiteid===

Palju vajalikku võib leida [http://tomcat.apache.org/tomcat-8.0-doc/index.html Tomcat 8 dokumentatsioonist]

Lisaks üks viide põhjalikule Tomcati versioon seitsme ülevaatele: http://www.ntu.edu.sg/home/ehchua/programming/howto/Tomcat_More.html

= Kasutatud materjalid =

#http://tomcat.apache.org/tomcat-8.0-doc/index.html
#http://www.mulesoft.com/tomcat-deploy-procedures
#http://www.mkyong.com/tomcat/tomcat-javalangoutofmemoryerror-permgen-space/

[[Category: Operatsioonisüsteemide administreerimine ja sidumine]]

Tomcat

2014-01-02T21:50:52Z

Kveskima: /* Juurutamise järjekord */

==Autor==

Kristjan Veskimäe D32

2013

==Sissejuhatus==

Tomcat on vabalt kättesaadav server Java veebirakendustele. Põhimõtteliselt on tegemist Servlet/JSP spetsifikatsiooni toetava konteineriga. Kiire käivitumise ning rakenduste käigultvahetuse tõttu on Tomcat hea valik väiksemate ning keskmise suurusega Java veebirakenduste käitamiseks.

Antud töö kirjeldab Tomcati 8. versiooni. Põhiosa on üldiselt samasugune võrreldes paari eelmise versiooniga. Suuremad erinevused on versioonispetsiifilistes probleemides ja nende lahendamises, mida käesolev töö ei vaatle.

Töö vaatleb Tomcati paigaldamist ja seadistamist Unix-laadsesse keskkonda ning eeldab lugejalt algteadmisi sarnastes süsteemides. Tomcati on võimalik paigaldada ka Windows-keskkonda, kuid antud veebiserver eeldab kasutaja poolt käsureal töötamist ning Tomcati failihierarhias orienteerumist. Põhimõtteliselt on Java veebirakenduste arendamiseks IDE-abil võimalik siiski ka kasutada IDE-sse integreeritud Tomcati serverit - näiteks pakuvad sellist võimalust Eclipse EE ja NetBeans - kuid seda käesolev töö ei vaatle.

==Mõisted==

* '''Kontekst''' (context) - Tomcati mõistes üks konkreetne veebiaplikatsioon
* '''Konteiner''' (container) - veebiserver Tomcat ise
* '''Kontekstikirjeldus''' (context descriptor) - Tomcati-spetsiifiline konteksti konfiguratsioonimääratlus; peremehepõhine osa loetakse failist $CATALINA_HOME/conf/[enginename]/[hostname]/context.xml ja sellele lisatakse kontekstispetsiifilised täpsustused failist $CATALINA_BASE/conf/[enginename]/[hostname]/[webappname].xml; kontekstikirjeldus määrab näiteks nimed ressurssidele, sessioonihalduse parameetrid jmt. (olgu märgitud, et Tomcati varasemates versioonides sisaldusid kontekstikirjeldused põhikonfiguratsioonifailis server.xml)
* '''Dokumendipõhi''' (docBase) - kontekstile vastav kataloog Tomcati "webapps" kataloogis, mis tekib veebiaplikatsiooni serverisse rakendamisel
* '''Veebiarhiiv''' (Web application ARchive, war-file) - Java veebiaplikatsiooni jagatakse hea tava kohaselt selle üheainsa veebiarhiivi failina, mille laienditüübiks on "war". Tegemist on zip-protokolliga kokkupakitud kataloogiga, millel on Java veebirakenduste spetsifikatsioonile vastav ülesehitus. Siiski võib veebiaplikatsioon olla juurutamisel ka lahtipakendatud olekus (inglisekeelne termin on "war is exploded").

==Ülesehitus==

{| class="wikitable"
|+Kataloogid
|-
|style="color: green;" | $CATALINA_HOME
|baaskataloog, kuhu on Tomcat paigutatud
|-
|style="color: green;" | $CATALINA_BASE
|parasjagu töösoleva Tomcati eksemplari baaskataloog, mille alusel lahendatakse teed ülejäänud kataloogide ja failideni; ainult ühe kasutusel oleva Tomcati eksemplari puhul on see sama, mis $CATALINA_HOME

|-
|style="color: green;" | $CATALINA_BASE/bin
|serveri käivitus- ja abiskriptid
|-
|style="color: green;" | $CATALINA_BASE/conf
|konfiguratsioonifailid
|-
|style="color: green;" | $CATALINA_BASE/lib
|Tomcatile vaikimisi kättesaadavad Java klassiteegid (class libraries) ehk .jar-failid kuhu on Java kompileeritud kood kokku pakendatud
|-
|style="color: green;" | $CATALINA_BASE/logs
|logifailid paigutatakse vaikimisi siia
|-
|style="color: green;" | $CATALINA_BASE/webapps
|kataloog, kuhu paigutatakse serverisse juurutatavad veebiaplikatsioonid

|}

{| class="wikitable"
|+Mõned olulisemad failid
|-
|style="color: green;" | $CATALINA_BASE/bin/startup.sh
|serveri käivitusskript
|-
|style="color: green;" | $CATALINA_BASE/bin/shutdown.sh
|serveri peatusskript

|-
|style="color: green;" | $CATALINA_BASE/conf/server.xml
| konteineri peamine konfiguratsioonifail
|-
|style="color: green;" | $CATALINA_BASE/conf/[enginename]/[hostname]/[webappname].xml
|serveri administraatori jaoks konteinerisse endasse ümber kopeeritud rakendusepõhine kontekstikirjelduse konfiguratsioon failist $CATALINA_BASE/webapps/[ApplicationName]/META-INF/context.xml
|-
|style="color: green;" | $CATALINA_BASE/conf/[enginename]/[hostname]/context.xml
| fail, mis aitab administraatoril konteksti kohta käivat infot kirjeldada peremeesmasina-põhiselt ja halduseks mõeldud automaat-tööriistadel (näiteks Tomcat Manager ja TCD) oma tööd teha
|-
|style="color: green;" | $CATALINA_BASE/$CATALINA_BASE/conf/[enginename]/[hostname]/manager.xml
|fail, mis võimaldab lisada rakendustele ligipääsufiltreid
|-
|style="color: green;" | $CATALINA_BASE/webapps/[webappname]/META-INF/context.xml
|kontekstikirjeldusfail, mille veebirakenduse programmeerija on pakendanud oma aplikatsiooniga kaasa ning millega ta saab võimaluse kontekstikirjeldust omalt poolt mõjutada; kirjutatakse rakenduse uuestijuurutamisel üle, mistõttu administraator peaks muutma selle asemel konteinerisse ümber kopeeritud püsieksemplari $CATALINA_BASE/conf/[enginename]/[hostname]/context.xml
|-
|style="color: green;" | $CATALINA_BASE/webapps/[webappname]/WEB-INF/web.xml
|ka üks oluline Java veebiaplikatsiooni konfiguratsioonifail, mille pakendatakse koos veebiarhiiviga; enamasti muudab seda ainult programeerija; määrab muu hulgas millised aplikatsiooni osad vajavad autentimist või kui kiiresti veebisessioon aegub
|}

==Installeerimine==

===Installeerimine paketihalduriga===

<pre>
apt-cache search tomcat
apt-get install tomcat[version]-webapps
apt-get install tomcat[version]-admin
apt-get install tomcat[version]
</pre>

===Installeerimine käsitsi===

Paketihalduriga installeerides ei pruugi viimane Tomcati versioon olla kättesaadav ja see pakub ka vähem võimalusi kataloogide määramiseks jms. Käsitsi installeerimiseks tuleb laadida Tomcat kodulehelt alla. Lahtipakkimisel tekib kataloog, milles sisalduv fail "RUNNING.txt" on kõige kindlam allikas installeerimisel tekkivate probleemide vältimiseks ning lahendamiseks.

Vajaliku versiooni installeerimisfaili asukoha saab vaadata Tomcati kodulehelt sektsioonist "Download". Järgnevas näites installeerime Tomcati kõige uuema ebastabiilse kandidaatversiooni, mida näitab nimes sisalduv RC ehk "release candidate". Produktsioonikeskkonda tuleks siiski valida stabiilse versiooni. Käsitsi installeerimine on sarnane järgmisega:
<pre>
wget http://mirror.nexcess.net/apache/tomcat/tomcat-8/v8.0.0-RC5/bin/apache-tomcat-8.0.0-RC5.tar.gz
tar -zxvf apache-tomcat-8.0.0-RC5.tar.gz
mv /Users/kristjanveskimae/downloads/apache-tomcat-8.0.0-RC5 /usr/local/apache-tomcat-8.0.0-RC5
rm -f /Library/Tomcat
ln -s /usr/local/apache-tomcat-8.0.0-RC5/ /Library/Tomcat
chown -R kristjanveskimae /Library/Tomcat
chmod +x /Library/Tomcat/bin/*.sh
</pre>

==Käivitamine ja aplikatsiooni juurutamine==

===Konteineri käivitamine===

Tomcati käivitamise eelduseks on Java paigaldamine masinasse ning keskkonnamuutujate "JAVA_HOME" ja "JRE_HOME" defineerimine. Peale installeerimist võib kasutada skripte kataloogist $CATALINA_BASE/bin . Järgneb üks võimalik käivitamise ja peatamise näide, mis on kasutatav eelnevalt kirjeldatud käsitsi installeerimise juhul:
<pre>
/Library/Tomcat/bin/startup.sh
</pre>
ja peatamiseks
<pre>
/Library/Tomcat/bin/shutdown.sh
</pre>

===Näiteaplikatsiooni juurutamine===

Java veebiaplikatsiooni jagatakse hea tava kohaselt üheainsa veebiarhiivi failina. Siiski võib Tomcati juurutada ka lahtipakendatud olekus ("exploded") Java veebiaplikatsiooni.

====Käsitsi juurutamine ja mahavõtmine====

Näiteaplikatsiooni juurutamiseks lae selle veebiarhiivifail alla ning kopeeri oma konteineri juurutamiskataloogi 'webapps':
<pre>wget http://tomcat.apache.org/tomcat-8.0-doc/appdev/sample/sample.war
cp /Users/kristjanveskimae/downloads/sample.war /Library/Tomcat/webapps/sample.war</pre>

Kui konfiguratsioonifailis $CATALINA_BASE/conf/server.xml on märgendi "Host" atribuudi "autoDeploy" väärtus "true", installeerib ja uuendab Tomcat aplikatsioone dünaamiliselt töötamise ajal. Kui väärtuseks on "false", käib installeerimine staatiliselt ning serverisse juurutamiseks tuleb teha konteineri taaskäivitus. [http://tomcat.apache.org/tomcat-8.0-doc/manager-howto.html#Deploy_A_New_Application_from_a_Local_Path 2] Mõlemal juhul pakib konteiner arhiveeritud faili ise lahti samasse kausta $CATALINA_BASE/webapps ning ka juurutab selle. Tekkiv aplikatsioon on lokaalsest masinast seejärel kättesaadav aadressil http://localhost:8080/sample/ .

[[File:sample_app.png|400px]]

Veebirakenduse käsitsi mahavõtmiseks tuleb kustutada talle vastav dokumendipõhja kataloog "webapps" kataloogist. Samuti tuleks kustutada .war-fail olemaks kindel, et Tomcat ei rakenda uuel käivitamisel veebiaplikatsiooni veebiarhiivifailist. Veelgi lihtsam on mahavõtmine brauseriga haldusrakenduse kaudu.

Rakenduste baaskataloogi "webapps" asukohta saab muuta failis $CATALINA_BASE/conf/server.xml peremehepõhiselt määratava atribuudiga "appBase", sealjuures Tomcati vaikimisi peremees ehk "Host" on "localhost".

====Tomcati vahendid juurutamiseks====

Veebiaplikatsioonide juurutamine ja mahajuurutamine on võimalik ka kaughalduse teel tänu Tomcati internetipõhisele haldusrakendusele. Näiteks saab veebibrauserit kasutades teha serveri põhitoiminguid Tomcati enda HTML-põhise rakendusega "Tomcat Manager". Veebipõhine haldusrakendus töötab ka käsupõhise veebiteenusena, millele on valmis ehitatud Anti ja Maveni integratsioonid. Samuti eksisteerib käsurea kliendirakendus TCD (Tomcat Client Deployer). TCD ei kuulu Tomcati baaskoosseisu, kuid pakub peale serveri administreerimise tavatoimingute ka lisafunktsionaalsust nagu veebirakenduse kokkukompileerimine ja pakendamine. [http://tomcat.apache.org/tomcat-8.0-doc/manager-howto.html#Configuring_Manager_Application_Access 1]

====Haldurakendus "Tomcat Manager"====

Tomcati haldusrakendus "Tomcat Manager" (antud alamjaotuses lihtsalt haldusrakendus) on Tomcati enda veebiaplikatioon Tomcati brauseripõhiseks kaughalduseks, võimaldades muu hulgas järgnevat [http://tomcat.apache.org/tomcat-8.0-doc/manager-howto.html#Introduction 3]:
* Rakendada uue veebiaplikatsiooni war-faili üleslaadimisega;
* Näha kõiki rakendatud veebiaplikatsioone koos aktiivsete sessioonidega;
* Taasrakendada veebirakendust, näiteks veebiarhiivi pakitud klassifailide /WEB-INF/classes või teekide /WEB-INF/lib uuendamisel, kinnijooksmisel jms.;
* Peatada veebirakendust ilma serverist eemaldamata, samuti koos serverist eemaldamisega;
* Vaadata operatsioonisüsteemi ja Java parameetrite väärtusi;
* Näha kõiki saadaolevaid JNDI ressursse, k.a. andmebaasiühendusi, mis aitavad rakenduste programmeerijail defineerida <ResourceLink> elemendid web.xml konfiguratsioonifailis.

Tomcati installatsioon sisaldab haldusrakendust juba vaikimisi. Haldusrakenduse töölepanemiseks tuleb peremeesmasina konfiguratsioonikataloogi $CATALINA_BASE/conf/[enginename]/[hostname] lisada ka fail manager.xml. Vaikimisi valmiskonfigureeritud testrakendusel on see fail juba olemas asukohas $CATALINA_BASE/conf/Catalina/localhost/manager.xml . Rakendus asub vaikimisi aadressil http://[host]/manager/ , vaikimisi konfiguratsioone kasutades lahendub see asukohaks http://localhost:8080/manager/ . [http://tomcat.apache.org/tomcat-8.0-doc/manager-howto.html#Configuring_Manager_Application_Access 4]

====="Tomcat Manager" ligipääsu konfigureerimine=====

Vaikimisi on turvalisuspõhjustel ligipääs haldusrakendusele maha keeratud. Mismoodi täpselt kasutajatel ligipääsu võimaldada sõltub kasutatavast valdusest (realm). Vaikimisi defineerib $CATALINA_BASE/conf/server.xml valduseks "MemoryRealm". Vaikimisi loeb valdus "MemoryRealm" kasutajad failist $CATALINA_BASE/conf/tomcat-users.xml. Antud failis tuleb iga kasutaja defineerida omaette märgendiga <user>, mis näeb välja umbes järgmine [http://tomcat.apache.org/tomcat-8.0-doc/manager-howto.html#Configuring_Manager_Application_Access 8]:
<pre>
<user name="craig" password="secret" roles="manager-gui,manager-script" />
</pre>

Antud kasutajale on defineeritud korraga kaks rolli. Ligipääsu võimaldamiseks tulebki lihtsamal juhul kasutajatefailis $CATALINA_BASE/conf/tomcat-users.xml defineerida enda kasutaja. Kasutaja rolliks võib määrata näiteks "manager-gui", mis võimaldab ligipääsu kogu HTML liidese funktsionaalsusele.

Teised valdused on "JDBCRealm", mille puhul hoitakse kasutajatega seonduvat infot andmebaasis ja JNDIRealm, mille puhul kasutatakse lihtsustatud kataloogisirvimise protokolli (LDAP).
Lisaks saab haldusrakendusele keelata ligipääsu mujalt kui kindlaksmääratud IP-aadressidelt, lisades filtri "RemoteAddrValve" või "RemoteHostValve" konfigureerimisfaili manager.xml näiteks järgmiselt [http://tomcat.apache.org/tomcat-8.0-doc/manager-howto.html#Introduction 6]:
<pre>
<Context privileged="true">
<Valve className="org.apache.catalina.valves.RemoteAddrValve"
allow="127\.0\.0\.1"/>
</Context>
</pre>

=====Juurutamine ja mahavõtmine haldusrakendusega "Tomcat Manager"=====

Juurutamiseks lae kõigepealt veebiarhiivifail üles, kasutades esilehel asuvat sektsiooni "WAR file to deploy".
[[File:tomcat_manager_war_upload.png]]

Rakendus kuvatakse seejärel hallatavate rakenduste nimekirjas. Kui konteiner pole seadistatud üleslaetud aplikatsiooni kohe ka ise rakendama, tuleb vajutada "Start". Rakenduse peatamiseks kasuta "Stop", uuesti rakendamiseks "Redeploy" ja serverist eemaldamiseks "Undeploy".


[[File:tomcat_manager_apps_list.png|800px|Rakenduste nimekiri]]

==Näpunäiteid Tomcati reaalseks kasutamiseks==

===Juurutamise järjekord===

Tomcati käivitumisel juurutatakse aplikatsioonid sellises järjekorras [http://www.mulesoft.com/tomcat-deploy-procedures 2]:
# Konteinerisse kopeeritud kontekstikirjelduste järgi $CATALINA_BASE/conf/[EngineName]/[HostName]/[ApplicationName].xml ;
# Lahtipakitud rakendused "webapps" kataloogis;
# Pakitud rakenduste veebiarhiivid "webapps" kataloogis.

Seetõttu peaks käsitsi taasjuurutamisel kindluse mõttes eelnevalt kustutama rakenduse lahtipakitud dokumendipõhja kataloogi "webapps" kataloogist. Kontekstikirjelduse muutumisel tuleb jälgida, kas kirjeldus on juba kopeeritud serverisse ning vajadusel eelmise versiooni ümber muuta või kustutada.

===Reaalsele domeenile konfigureerimine===

Järgnevalt eeldame, et domeen ''www.minukodukas.ee'' on juba serverimasinaga seostatud. Et Tomcat hakkaks ka reaalselt Internetist tulevatele päringutele vastama, tuleb muuta failis $CATALINA_BASE/conf/server.xml konteinerile ''Catalina'' vastava teenusemärgendi sisu sarnaselt järgnevaga:

<pre>
<Service name="Catalina">
<Connector port="80" protocol="HTTP/1.1" connectionTimeout="20000" URIEncoding="UTF-8" redirectPort="8443" />
<Engine name="Catalina" defaultHost="www.minukodukas.ee">
<Host name="www.minukodukas.ee" appBase="webapps" unpackWARs="true" autoDeploy="false" deployOnStartup="false" xmlValidation="false" xmlNamespaceAware="false">
<Context path="" docBase="kodukas" debug="0" reloadable="true" />
</Host>
</Engine>
</Service>
</pre>

Ülal defineerime põhiliselt selle, et Tomcat kuulaks domeeni ''www.minukodukas.ee'' ja kasutaks HTTP päringute jaoks porti 80. Ühtlasti otsib Tomcat juurutatavat rakendust failist $CATALINA_BASE/webapps/kodukas.war. Kuna rajalisandiks on määratud tühi sõne (path=""), siis juurutataksegi aplikatsioon aadressile ''www.minukodukas.ee'' ilma rajalisandita (a'la ''www.minukodukas.ee/wiki''). Seetõttu pakitakse ka veebiarhiiv tegelikult lahti kataloogi $CATALINA_BASE/webapps/ROOT mitte kataloogi $CATALINA_BASE/webapps/kodukas nagu võiks eeldada.

===Käigultvahetus===

Võimaldamaks käigultvahetust (hot deployment) peab konteineri konfiguratsioonifailis $CATALINA_BASE/conf/server.xml olema peremehepõhise märgendi "Host" atribuudi "autoDeploy" väärtus "true". Sel juhul installeerib ja uuendab Tomcat aplikatsioone dünaamiliselt töötamise ajal. Kui väärtuseks on "false", käib installeerimine staatiliselt ning serverisse juurutamiseks tuleb teha konteineri taaskäivitus. Käigultvahetust saab määrata ka peremehe defineerimisel "Host Manager" rakendusega, mis on kättesaadav aadressil http://localhost:8080/host-manager/html . Kasutamiseks tuleb lisada oma kasutajale rolli "admin-gui" (vt. alajaotus ""Tomcat Manager" ligipääsu konfigureerimine").

[[File:host_manager_app.png]]

Käigultvahetust päästikuks on vaikimisi uuendatud veebiarhiivifaili või lahtipakitud veebirakenduse paigutamine "webapps" kataloogi. Käigultvahetuse päästikutele võib failis $CATALINA_BASE/conf/server.xml ka ise lisada kuulatavaid ressursse nagu web.xml muutmine või mõne teegifaili vahetamine (märgendis "Host").

===Klassiteekide väljatõstmine veebiarhiivifailist===

Kõik konteksti poolt kasutatavad Java klassiteegid võib pakendada veebiarhiivi sisse kataloogi "lib", kuid nii võib osutuda veebiarhiivi üleslaadimine ajakulukaks, eriti arenduskeskkonnas. Kui ei teki ohtu, et erinevad rakendused kasutavad sama teegi erinevaid versioone, siis on vahel parem lisada osa teeke konteineri kataloogi $CATALINA_BASE/libs, kust need tehakse siis konteineri poolt kättesaadavaks kõigile konteineris jooksutatavatele kontekstidele. Nii võib vähendada veebiarhiivi faili suurust märgatavalt, mis tõstab kokkuvõttes juurutamiskiirust ja ühes sellega programmeerijate tööviljakust.

===Mälukasutus===

Konteineri poolt kasutatavat mälu saab vaadata haldusrakendusest vajutades lingile "Server Status". Mälukasutus on toodud jaotuses "JVM", kus näidatakse nii maksimaalselt kättesaadavat mälu kui ka parasjagu reserveeritud mälu.

<pre>Free memory: 41.16 MB Total memory: 123.37 MB Max memory: 1027.56 MB</pre>

Mälu suurendamiseks võib näiteks defineerida skriptis $CATALINA_BASE/bin/catalina.sh muutuja "JAVA_OPTS" ning määrata Java mälukasutuse miinimum- ja maksimumväärtused sarnaselt järgnevatega [http://www.mkyong.com/tomcat/tomcat-javalangoutofmemoryerror-permgen-space/ 3]:
<pre>
JAVA_OPTS="-Xms1536m -Xmx1536m -XX:NewSize=256m -XX:MaxNewSize=256m -XX:PermSize=256m -XX:MaxPermSize=256m"
</pre>

===Logifailid===

Vaikimisi defineerib Tomcat failiga $CATALINA_BASE/conf/logging.properties viis logerit, mis tekitavad viis eraldi logifaili.

{| style="background:#cccc99;color:black;width:80%;" border="1" cellpadding="5" cellspacing="0" align="center"
|+ Tomcati tekitatavad logifailid "logs" kataloogis
!Fail !! Kasutus
|- style="background:white; color:black"
| style="width:300px" |catalina.out
| Tomcati käivitus- ja peatamisskriptide väljund, samuti juurutatud rakenduste prindilaused System.out ja veaväljundid System.err
|- style="background:white; color:black"
| style="width:300px" |catalina.[yyyy]-[mm]-[dd].log
| Pööratud (rotated) logifail catalina.out
|- style="background:white; color:black"
| style="width:300px" |host-manager.[yyyy]-[mm]-[dd].log
| Logi peremehehalduse rakendusele (rakendus on kättesaadav kohalikust masinast aadressil http://localhost:8080/host-manager/html )
|- style="background:white; color:black"
| style="width:300px" |localhost.[yyyy]-[mm]-[dd].log
| Peremehe "localhost" logi; mitme virtuaalse peremehe korral tekitatakse igale peremehele oma logi
|- style="background:white; color:black"
| style="width:300px" |localhost_access_log.[yyyy]-[mm]-[dd].txt
| Konteinerisse Internetist saabunud päringute logi
|- style="background:white; color:black"
| style="width:300px" |manager.[yyyy]-[mm]-[dd].log
| Haldusrakenduse tegevuste logi
|}

===Viiteid===

Palju vajalikku võib leida [http://tomcat.apache.org/tomcat-8.0-doc/index.html Tomcat 8 dokumentatsioonist]

Lisaks üks viide põhjalikule Tomcati versioon seitsme ülevaatele: http://www.ntu.edu.sg/home/ehchua/programming/howto/Tomcat_More.html

= Kasutatud materjalid =

#http://tomcat.apache.org/tomcat-8.0-doc/index.html
#http://www.mulesoft.com/tomcat-deploy-procedures
#http://www.mkyong.com/tomcat/tomcat-javalangoutofmemoryerror-permgen-space/

[[Category: Operatsioonisüsteemide administreerimine ja sidumine]]

Tomcat

2014-01-02T21:50:36Z

Kveskima: /* Mälukasutus */

==Autor==

Kristjan Veskimäe D32

2013

==Sissejuhatus==

Tomcat on vabalt kättesaadav server Java veebirakendustele. Põhimõtteliselt on tegemist Servlet/JSP spetsifikatsiooni toetava konteineriga. Kiire käivitumise ning rakenduste käigultvahetuse tõttu on Tomcat hea valik väiksemate ning keskmise suurusega Java veebirakenduste käitamiseks.

Antud töö kirjeldab Tomcati 8. versiooni. Põhiosa on üldiselt samasugune võrreldes paari eelmise versiooniga. Suuremad erinevused on versioonispetsiifilistes probleemides ja nende lahendamises, mida käesolev töö ei vaatle.

Töö vaatleb Tomcati paigaldamist ja seadistamist Unix-laadsesse keskkonda ning eeldab lugejalt algteadmisi sarnastes süsteemides. Tomcati on võimalik paigaldada ka Windows-keskkonda, kuid antud veebiserver eeldab kasutaja poolt käsureal töötamist ning Tomcati failihierarhias orienteerumist. Põhimõtteliselt on Java veebirakenduste arendamiseks IDE-abil võimalik siiski ka kasutada IDE-sse integreeritud Tomcati serverit - näiteks pakuvad sellist võimalust Eclipse EE ja NetBeans - kuid seda käesolev töö ei vaatle.

==Mõisted==

* '''Kontekst''' (context) - Tomcati mõistes üks konkreetne veebiaplikatsioon
* '''Konteiner''' (container) - veebiserver Tomcat ise
* '''Kontekstikirjeldus''' (context descriptor) - Tomcati-spetsiifiline konteksti konfiguratsioonimääratlus; peremehepõhine osa loetakse failist $CATALINA_HOME/conf/[enginename]/[hostname]/context.xml ja sellele lisatakse kontekstispetsiifilised täpsustused failist $CATALINA_BASE/conf/[enginename]/[hostname]/[webappname].xml; kontekstikirjeldus määrab näiteks nimed ressurssidele, sessioonihalduse parameetrid jmt. (olgu märgitud, et Tomcati varasemates versioonides sisaldusid kontekstikirjeldused põhikonfiguratsioonifailis server.xml)
* '''Dokumendipõhi''' (docBase) - kontekstile vastav kataloog Tomcati "webapps" kataloogis, mis tekib veebiaplikatsiooni serverisse rakendamisel
* '''Veebiarhiiv''' (Web application ARchive, war-file) - Java veebiaplikatsiooni jagatakse hea tava kohaselt selle üheainsa veebiarhiivi failina, mille laienditüübiks on "war". Tegemist on zip-protokolliga kokkupakitud kataloogiga, millel on Java veebirakenduste spetsifikatsioonile vastav ülesehitus. Siiski võib veebiaplikatsioon olla juurutamisel ka lahtipakendatud olekus (inglisekeelne termin on "war is exploded").

==Ülesehitus==

{| class="wikitable"
|+Kataloogid
|-
|style="color: green;" | $CATALINA_HOME
|baaskataloog, kuhu on Tomcat paigutatud
|-
|style="color: green;" | $CATALINA_BASE
|parasjagu töösoleva Tomcati eksemplari baaskataloog, mille alusel lahendatakse teed ülejäänud kataloogide ja failideni; ainult ühe kasutusel oleva Tomcati eksemplari puhul on see sama, mis $CATALINA_HOME

|-
|style="color: green;" | $CATALINA_BASE/bin
|serveri käivitus- ja abiskriptid
|-
|style="color: green;" | $CATALINA_BASE/conf
|konfiguratsioonifailid
|-
|style="color: green;" | $CATALINA_BASE/lib
|Tomcatile vaikimisi kättesaadavad Java klassiteegid (class libraries) ehk .jar-failid kuhu on Java kompileeritud kood kokku pakendatud
|-
|style="color: green;" | $CATALINA_BASE/logs
|logifailid paigutatakse vaikimisi siia
|-
|style="color: green;" | $CATALINA_BASE/webapps
|kataloog, kuhu paigutatakse serverisse juurutatavad veebiaplikatsioonid

|}

{| class="wikitable"
|+Mõned olulisemad failid
|-
|style="color: green;" | $CATALINA_BASE/bin/startup.sh
|serveri käivitusskript
|-
|style="color: green;" | $CATALINA_BASE/bin/shutdown.sh
|serveri peatusskript

|-
|style="color: green;" | $CATALINA_BASE/conf/server.xml
| konteineri peamine konfiguratsioonifail
|-
|style="color: green;" | $CATALINA_BASE/conf/[enginename]/[hostname]/[webappname].xml
|serveri administraatori jaoks konteinerisse endasse ümber kopeeritud rakendusepõhine kontekstikirjelduse konfiguratsioon failist $CATALINA_BASE/webapps/[ApplicationName]/META-INF/context.xml
|-
|style="color: green;" | $CATALINA_BASE/conf/[enginename]/[hostname]/context.xml
| fail, mis aitab administraatoril konteksti kohta käivat infot kirjeldada peremeesmasina-põhiselt ja halduseks mõeldud automaat-tööriistadel (näiteks Tomcat Manager ja TCD) oma tööd teha
|-
|style="color: green;" | $CATALINA_BASE/$CATALINA_BASE/conf/[enginename]/[hostname]/manager.xml
|fail, mis võimaldab lisada rakendustele ligipääsufiltreid
|-
|style="color: green;" | $CATALINA_BASE/webapps/[webappname]/META-INF/context.xml
|kontekstikirjeldusfail, mille veebirakenduse programmeerija on pakendanud oma aplikatsiooniga kaasa ning millega ta saab võimaluse kontekstikirjeldust omalt poolt mõjutada; kirjutatakse rakenduse uuestijuurutamisel üle, mistõttu administraator peaks muutma selle asemel konteinerisse ümber kopeeritud püsieksemplari $CATALINA_BASE/conf/[enginename]/[hostname]/context.xml
|-
|style="color: green;" | $CATALINA_BASE/webapps/[webappname]/WEB-INF/web.xml
|ka üks oluline Java veebiaplikatsiooni konfiguratsioonifail, mille pakendatakse koos veebiarhiiviga; enamasti muudab seda ainult programeerija; määrab muu hulgas millised aplikatsiooni osad vajavad autentimist või kui kiiresti veebisessioon aegub
|}

==Installeerimine==

===Installeerimine paketihalduriga===

<pre>
apt-cache search tomcat
apt-get install tomcat[version]-webapps
apt-get install tomcat[version]-admin
apt-get install tomcat[version]
</pre>

===Installeerimine käsitsi===

Paketihalduriga installeerides ei pruugi viimane Tomcati versioon olla kättesaadav ja see pakub ka vähem võimalusi kataloogide määramiseks jms. Käsitsi installeerimiseks tuleb laadida Tomcat kodulehelt alla. Lahtipakkimisel tekib kataloog, milles sisalduv fail "RUNNING.txt" on kõige kindlam allikas installeerimisel tekkivate probleemide vältimiseks ning lahendamiseks.

Vajaliku versiooni installeerimisfaili asukoha saab vaadata Tomcati kodulehelt sektsioonist "Download". Järgnevas näites installeerime Tomcati kõige uuema ebastabiilse kandidaatversiooni, mida näitab nimes sisalduv RC ehk "release candidate". Produktsioonikeskkonda tuleks siiski valida stabiilse versiooni. Käsitsi installeerimine on sarnane järgmisega:
<pre>
wget http://mirror.nexcess.net/apache/tomcat/tomcat-8/v8.0.0-RC5/bin/apache-tomcat-8.0.0-RC5.tar.gz
tar -zxvf apache-tomcat-8.0.0-RC5.tar.gz
mv /Users/kristjanveskimae/downloads/apache-tomcat-8.0.0-RC5 /usr/local/apache-tomcat-8.0.0-RC5
rm -f /Library/Tomcat
ln -s /usr/local/apache-tomcat-8.0.0-RC5/ /Library/Tomcat
chown -R kristjanveskimae /Library/Tomcat
chmod +x /Library/Tomcat/bin/*.sh
</pre>

==Käivitamine ja aplikatsiooni juurutamine==

===Konteineri käivitamine===

Tomcati käivitamise eelduseks on Java paigaldamine masinasse ning keskkonnamuutujate "JAVA_HOME" ja "JRE_HOME" defineerimine. Peale installeerimist võib kasutada skripte kataloogist $CATALINA_BASE/bin . Järgneb üks võimalik käivitamise ja peatamise näide, mis on kasutatav eelnevalt kirjeldatud käsitsi installeerimise juhul:
<pre>
/Library/Tomcat/bin/startup.sh
</pre>
ja peatamiseks
<pre>
/Library/Tomcat/bin/shutdown.sh
</pre>

===Näiteaplikatsiooni juurutamine===

Java veebiaplikatsiooni jagatakse hea tava kohaselt üheainsa veebiarhiivi failina. Siiski võib Tomcati juurutada ka lahtipakendatud olekus ("exploded") Java veebiaplikatsiooni.

====Käsitsi juurutamine ja mahavõtmine====

Näiteaplikatsiooni juurutamiseks lae selle veebiarhiivifail alla ning kopeeri oma konteineri juurutamiskataloogi 'webapps':
<pre>wget http://tomcat.apache.org/tomcat-8.0-doc/appdev/sample/sample.war
cp /Users/kristjanveskimae/downloads/sample.war /Library/Tomcat/webapps/sample.war</pre>

Kui konfiguratsioonifailis $CATALINA_BASE/conf/server.xml on märgendi "Host" atribuudi "autoDeploy" väärtus "true", installeerib ja uuendab Tomcat aplikatsioone dünaamiliselt töötamise ajal. Kui väärtuseks on "false", käib installeerimine staatiliselt ning serverisse juurutamiseks tuleb teha konteineri taaskäivitus. [http://tomcat.apache.org/tomcat-8.0-doc/manager-howto.html#Deploy_A_New_Application_from_a_Local_Path 2] Mõlemal juhul pakib konteiner arhiveeritud faili ise lahti samasse kausta $CATALINA_BASE/webapps ning ka juurutab selle. Tekkiv aplikatsioon on lokaalsest masinast seejärel kättesaadav aadressil http://localhost:8080/sample/ .

[[File:sample_app.png|400px]]

Veebirakenduse käsitsi mahavõtmiseks tuleb kustutada talle vastav dokumendipõhja kataloog "webapps" kataloogist. Samuti tuleks kustutada .war-fail olemaks kindel, et Tomcat ei rakenda uuel käivitamisel veebiaplikatsiooni veebiarhiivifailist. Veelgi lihtsam on mahavõtmine brauseriga haldusrakenduse kaudu.

Rakenduste baaskataloogi "webapps" asukohta saab muuta failis $CATALINA_BASE/conf/server.xml peremehepõhiselt määratava atribuudiga "appBase", sealjuures Tomcati vaikimisi peremees ehk "Host" on "localhost".

====Tomcati vahendid juurutamiseks====

Veebiaplikatsioonide juurutamine ja mahajuurutamine on võimalik ka kaughalduse teel tänu Tomcati internetipõhisele haldusrakendusele. Näiteks saab veebibrauserit kasutades teha serveri põhitoiminguid Tomcati enda HTML-põhise rakendusega "Tomcat Manager". Veebipõhine haldusrakendus töötab ka käsupõhise veebiteenusena, millele on valmis ehitatud Anti ja Maveni integratsioonid. Samuti eksisteerib käsurea kliendirakendus TCD (Tomcat Client Deployer). TCD ei kuulu Tomcati baaskoosseisu, kuid pakub peale serveri administreerimise tavatoimingute ka lisafunktsionaalsust nagu veebirakenduse kokkukompileerimine ja pakendamine. [http://tomcat.apache.org/tomcat-8.0-doc/manager-howto.html#Configuring_Manager_Application_Access 1]

====Haldurakendus "Tomcat Manager"====

Tomcati haldusrakendus "Tomcat Manager" (antud alamjaotuses lihtsalt haldusrakendus) on Tomcati enda veebiaplikatioon Tomcati brauseripõhiseks kaughalduseks, võimaldades muu hulgas järgnevat [http://tomcat.apache.org/tomcat-8.0-doc/manager-howto.html#Introduction 3]:
* Rakendada uue veebiaplikatsiooni war-faili üleslaadimisega;
* Näha kõiki rakendatud veebiaplikatsioone koos aktiivsete sessioonidega;
* Taasrakendada veebirakendust, näiteks veebiarhiivi pakitud klassifailide /WEB-INF/classes või teekide /WEB-INF/lib uuendamisel, kinnijooksmisel jms.;
* Peatada veebirakendust ilma serverist eemaldamata, samuti koos serverist eemaldamisega;
* Vaadata operatsioonisüsteemi ja Java parameetrite väärtusi;
* Näha kõiki saadaolevaid JNDI ressursse, k.a. andmebaasiühendusi, mis aitavad rakenduste programmeerijail defineerida <ResourceLink> elemendid web.xml konfiguratsioonifailis.

Tomcati installatsioon sisaldab haldusrakendust juba vaikimisi. Haldusrakenduse töölepanemiseks tuleb peremeesmasina konfiguratsioonikataloogi $CATALINA_BASE/conf/[enginename]/[hostname] lisada ka fail manager.xml. Vaikimisi valmiskonfigureeritud testrakendusel on see fail juba olemas asukohas $CATALINA_BASE/conf/Catalina/localhost/manager.xml . Rakendus asub vaikimisi aadressil http://[host]/manager/ , vaikimisi konfiguratsioone kasutades lahendub see asukohaks http://localhost:8080/manager/ . [http://tomcat.apache.org/tomcat-8.0-doc/manager-howto.html#Configuring_Manager_Application_Access 4]

====="Tomcat Manager" ligipääsu konfigureerimine=====

Vaikimisi on turvalisuspõhjustel ligipääs haldusrakendusele maha keeratud. Mismoodi täpselt kasutajatel ligipääsu võimaldada sõltub kasutatavast valdusest (realm). Vaikimisi defineerib $CATALINA_BASE/conf/server.xml valduseks "MemoryRealm". Vaikimisi loeb valdus "MemoryRealm" kasutajad failist $CATALINA_BASE/conf/tomcat-users.xml. Antud failis tuleb iga kasutaja defineerida omaette märgendiga <user>, mis näeb välja umbes järgmine [http://tomcat.apache.org/tomcat-8.0-doc/manager-howto.html#Configuring_Manager_Application_Access 8]:
<pre>
<user name="craig" password="secret" roles="manager-gui,manager-script" />
</pre>

Antud kasutajale on defineeritud korraga kaks rolli. Ligipääsu võimaldamiseks tulebki lihtsamal juhul kasutajatefailis $CATALINA_BASE/conf/tomcat-users.xml defineerida enda kasutaja. Kasutaja rolliks võib määrata näiteks "manager-gui", mis võimaldab ligipääsu kogu HTML liidese funktsionaalsusele.

Teised valdused on "JDBCRealm", mille puhul hoitakse kasutajatega seonduvat infot andmebaasis ja JNDIRealm, mille puhul kasutatakse lihtsustatud kataloogisirvimise protokolli (LDAP).
Lisaks saab haldusrakendusele keelata ligipääsu mujalt kui kindlaksmääratud IP-aadressidelt, lisades filtri "RemoteAddrValve" või "RemoteHostValve" konfigureerimisfaili manager.xml näiteks järgmiselt [http://tomcat.apache.org/tomcat-8.0-doc/manager-howto.html#Introduction 6]:
<pre>
<Context privileged="true">
<Valve className="org.apache.catalina.valves.RemoteAddrValve"
allow="127\.0\.0\.1"/>
</Context>
</pre>

=====Juurutamine ja mahavõtmine haldusrakendusega "Tomcat Manager"=====

Juurutamiseks lae kõigepealt veebiarhiivifail üles, kasutades esilehel asuvat sektsiooni "WAR file to deploy".
[[File:tomcat_manager_war_upload.png]]

Rakendus kuvatakse seejärel hallatavate rakenduste nimekirjas. Kui konteiner pole seadistatud üleslaetud aplikatsiooni kohe ka ise rakendama, tuleb vajutada "Start". Rakenduse peatamiseks kasuta "Stop", uuesti rakendamiseks "Redeploy" ja serverist eemaldamiseks "Undeploy".


[[File:tomcat_manager_apps_list.png|800px|Rakenduste nimekiri]]

==Näpunäiteid Tomcati reaalseks kasutamiseks==

===Juurutamise järjekord===

Tomcati käivitumisel juurutatakse aplikatsioonid sellises järjekorras [http://www.mulesoft.com/tomcat-deploy-procedures 9]:
# Konteinerisse kopeeritud kontekstikirjelduste järgi $CATALINA_BASE/conf/[EngineName]/[HostName]/[ApplicationName].xml ;
# Lahtipakitud rakendused "webapps" kataloogis;
# Pakitud rakenduste veebiarhiivid "webapps" kataloogis.

Seetõttu peaks käsitsi taasjuurutamisel kindluse mõttes eelnevalt kustutama rakenduse lahtipakitud dokumendipõhja kataloogi "webapps" kataloogist. Kontekstikirjelduse muutumisel tuleb jälgida, kas kirjeldus on juba kopeeritud serverisse ning vajadusel eelmise versiooni ümber muuta või kustutada.

===Reaalsele domeenile konfigureerimine===

Järgnevalt eeldame, et domeen ''www.minukodukas.ee'' on juba serverimasinaga seostatud. Et Tomcat hakkaks ka reaalselt Internetist tulevatele päringutele vastama, tuleb muuta failis $CATALINA_BASE/conf/server.xml konteinerile ''Catalina'' vastava teenusemärgendi sisu sarnaselt järgnevaga:

<pre>
<Service name="Catalina">
<Connector port="80" protocol="HTTP/1.1" connectionTimeout="20000" URIEncoding="UTF-8" redirectPort="8443" />
<Engine name="Catalina" defaultHost="www.minukodukas.ee">
<Host name="www.minukodukas.ee" appBase="webapps" unpackWARs="true" autoDeploy="false" deployOnStartup="false" xmlValidation="false" xmlNamespaceAware="false">
<Context path="" docBase="kodukas" debug="0" reloadable="true" />
</Host>
</Engine>
</Service>
</pre>

Ülal defineerime põhiliselt selle, et Tomcat kuulaks domeeni ''www.minukodukas.ee'' ja kasutaks HTTP päringute jaoks porti 80. Ühtlasti otsib Tomcat juurutatavat rakendust failist $CATALINA_BASE/webapps/kodukas.war. Kuna rajalisandiks on määratud tühi sõne (path=""), siis juurutataksegi aplikatsioon aadressile ''www.minukodukas.ee'' ilma rajalisandita (a'la ''www.minukodukas.ee/wiki''). Seetõttu pakitakse ka veebiarhiiv tegelikult lahti kataloogi $CATALINA_BASE/webapps/ROOT mitte kataloogi $CATALINA_BASE/webapps/kodukas nagu võiks eeldada.

===Käigultvahetus===

Võimaldamaks käigultvahetust (hot deployment) peab konteineri konfiguratsioonifailis $CATALINA_BASE/conf/server.xml olema peremehepõhise märgendi "Host" atribuudi "autoDeploy" väärtus "true". Sel juhul installeerib ja uuendab Tomcat aplikatsioone dünaamiliselt töötamise ajal. Kui väärtuseks on "false", käib installeerimine staatiliselt ning serverisse juurutamiseks tuleb teha konteineri taaskäivitus. Käigultvahetust saab määrata ka peremehe defineerimisel "Host Manager" rakendusega, mis on kättesaadav aadressil http://localhost:8080/host-manager/html . Kasutamiseks tuleb lisada oma kasutajale rolli "admin-gui" (vt. alajaotus ""Tomcat Manager" ligipääsu konfigureerimine").

[[File:host_manager_app.png]]

Käigultvahetust päästikuks on vaikimisi uuendatud veebiarhiivifaili või lahtipakitud veebirakenduse paigutamine "webapps" kataloogi. Käigultvahetuse päästikutele võib failis $CATALINA_BASE/conf/server.xml ka ise lisada kuulatavaid ressursse nagu web.xml muutmine või mõne teegifaili vahetamine (märgendis "Host").

===Klassiteekide väljatõstmine veebiarhiivifailist===

Kõik konteksti poolt kasutatavad Java klassiteegid võib pakendada veebiarhiivi sisse kataloogi "lib", kuid nii võib osutuda veebiarhiivi üleslaadimine ajakulukaks, eriti arenduskeskkonnas. Kui ei teki ohtu, et erinevad rakendused kasutavad sama teegi erinevaid versioone, siis on vahel parem lisada osa teeke konteineri kataloogi $CATALINA_BASE/libs, kust need tehakse siis konteineri poolt kättesaadavaks kõigile konteineris jooksutatavatele kontekstidele. Nii võib vähendada veebiarhiivi faili suurust märgatavalt, mis tõstab kokkuvõttes juurutamiskiirust ja ühes sellega programmeerijate tööviljakust.

===Mälukasutus===

Konteineri poolt kasutatavat mälu saab vaadata haldusrakendusest vajutades lingile "Server Status". Mälukasutus on toodud jaotuses "JVM", kus näidatakse nii maksimaalselt kättesaadavat mälu kui ka parasjagu reserveeritud mälu.

<pre>Free memory: 41.16 MB Total memory: 123.37 MB Max memory: 1027.56 MB</pre>

Mälu suurendamiseks võib näiteks defineerida skriptis $CATALINA_BASE/bin/catalina.sh muutuja "JAVA_OPTS" ning määrata Java mälukasutuse miinimum- ja maksimumväärtused sarnaselt järgnevatega [http://www.mkyong.com/tomcat/tomcat-javalangoutofmemoryerror-permgen-space/ 3]:
<pre>
JAVA_OPTS="-Xms1536m -Xmx1536m -XX:NewSize=256m -XX:MaxNewSize=256m -XX:PermSize=256m -XX:MaxPermSize=256m"
</pre>

===Logifailid===

Vaikimisi defineerib Tomcat failiga $CATALINA_BASE/conf/logging.properties viis logerit, mis tekitavad viis eraldi logifaili.

{| style="background:#cccc99;color:black;width:80%;" border="1" cellpadding="5" cellspacing="0" align="center"
|+ Tomcati tekitatavad logifailid "logs" kataloogis
!Fail !! Kasutus
|- style="background:white; color:black"
| style="width:300px" |catalina.out
| Tomcati käivitus- ja peatamisskriptide väljund, samuti juurutatud rakenduste prindilaused System.out ja veaväljundid System.err
|- style="background:white; color:black"
| style="width:300px" |catalina.[yyyy]-[mm]-[dd].log
| Pööratud (rotated) logifail catalina.out
|- style="background:white; color:black"
| style="width:300px" |host-manager.[yyyy]-[mm]-[dd].log
| Logi peremehehalduse rakendusele (rakendus on kättesaadav kohalikust masinast aadressil http://localhost:8080/host-manager/html )
|- style="background:white; color:black"
| style="width:300px" |localhost.[yyyy]-[mm]-[dd].log
| Peremehe "localhost" logi; mitme virtuaalse peremehe korral tekitatakse igale peremehele oma logi
|- style="background:white; color:black"
| style="width:300px" |localhost_access_log.[yyyy]-[mm]-[dd].txt
| Konteinerisse Internetist saabunud päringute logi
|- style="background:white; color:black"
| style="width:300px" |manager.[yyyy]-[mm]-[dd].log
| Haldusrakenduse tegevuste logi
|}

===Viiteid===

Palju vajalikku võib leida [http://tomcat.apache.org/tomcat-8.0-doc/index.html Tomcat 8 dokumentatsioonist]

Lisaks üks viide põhjalikule Tomcati versioon seitsme ülevaatele: http://www.ntu.edu.sg/home/ehchua/programming/howto/Tomcat_More.html

= Kasutatud materjalid =

#http://tomcat.apache.org/tomcat-8.0-doc/index.html
#http://www.mulesoft.com/tomcat-deploy-procedures
#http://www.mkyong.com/tomcat/tomcat-javalangoutofmemoryerror-permgen-space/

[[Category: Operatsioonisüsteemide administreerimine ja sidumine]]

Tomcat

2014-01-02T21:50:11Z

Kveskima: /* Kasutatud materjalid */

==Autor==

Kristjan Veskimäe D32

2013

==Sissejuhatus==

Tomcat on vabalt kättesaadav server Java veebirakendustele. Põhimõtteliselt on tegemist Servlet/JSP spetsifikatsiooni toetava konteineriga. Kiire käivitumise ning rakenduste käigultvahetuse tõttu on Tomcat hea valik väiksemate ning keskmise suurusega Java veebirakenduste käitamiseks.

Antud töö kirjeldab Tomcati 8. versiooni. Põhiosa on üldiselt samasugune võrreldes paari eelmise versiooniga. Suuremad erinevused on versioonispetsiifilistes probleemides ja nende lahendamises, mida käesolev töö ei vaatle.

Töö vaatleb Tomcati paigaldamist ja seadistamist Unix-laadsesse keskkonda ning eeldab lugejalt algteadmisi sarnastes süsteemides. Tomcati on võimalik paigaldada ka Windows-keskkonda, kuid antud veebiserver eeldab kasutaja poolt käsureal töötamist ning Tomcati failihierarhias orienteerumist. Põhimõtteliselt on Java veebirakenduste arendamiseks IDE-abil võimalik siiski ka kasutada IDE-sse integreeritud Tomcati serverit - näiteks pakuvad sellist võimalust Eclipse EE ja NetBeans - kuid seda käesolev töö ei vaatle.

==Mõisted==

* '''Kontekst''' (context) - Tomcati mõistes üks konkreetne veebiaplikatsioon
* '''Konteiner''' (container) - veebiserver Tomcat ise
* '''Kontekstikirjeldus''' (context descriptor) - Tomcati-spetsiifiline konteksti konfiguratsioonimääratlus; peremehepõhine osa loetakse failist $CATALINA_HOME/conf/[enginename]/[hostname]/context.xml ja sellele lisatakse kontekstispetsiifilised täpsustused failist $CATALINA_BASE/conf/[enginename]/[hostname]/[webappname].xml; kontekstikirjeldus määrab näiteks nimed ressurssidele, sessioonihalduse parameetrid jmt. (olgu märgitud, et Tomcati varasemates versioonides sisaldusid kontekstikirjeldused põhikonfiguratsioonifailis server.xml)
* '''Dokumendipõhi''' (docBase) - kontekstile vastav kataloog Tomcati "webapps" kataloogis, mis tekib veebiaplikatsiooni serverisse rakendamisel
* '''Veebiarhiiv''' (Web application ARchive, war-file) - Java veebiaplikatsiooni jagatakse hea tava kohaselt selle üheainsa veebiarhiivi failina, mille laienditüübiks on "war". Tegemist on zip-protokolliga kokkupakitud kataloogiga, millel on Java veebirakenduste spetsifikatsioonile vastav ülesehitus. Siiski võib veebiaplikatsioon olla juurutamisel ka lahtipakendatud olekus (inglisekeelne termin on "war is exploded").

==Ülesehitus==

{| class="wikitable"
|+Kataloogid
|-
|style="color: green;" | $CATALINA_HOME
|baaskataloog, kuhu on Tomcat paigutatud
|-
|style="color: green;" | $CATALINA_BASE
|parasjagu töösoleva Tomcati eksemplari baaskataloog, mille alusel lahendatakse teed ülejäänud kataloogide ja failideni; ainult ühe kasutusel oleva Tomcati eksemplari puhul on see sama, mis $CATALINA_HOME

|-
|style="color: green;" | $CATALINA_BASE/bin
|serveri käivitus- ja abiskriptid
|-
|style="color: green;" | $CATALINA_BASE/conf
|konfiguratsioonifailid
|-
|style="color: green;" | $CATALINA_BASE/lib
|Tomcatile vaikimisi kättesaadavad Java klassiteegid (class libraries) ehk .jar-failid kuhu on Java kompileeritud kood kokku pakendatud
|-
|style="color: green;" | $CATALINA_BASE/logs
|logifailid paigutatakse vaikimisi siia
|-
|style="color: green;" | $CATALINA_BASE/webapps
|kataloog, kuhu paigutatakse serverisse juurutatavad veebiaplikatsioonid

|}

{| class="wikitable"
|+Mõned olulisemad failid
|-
|style="color: green;" | $CATALINA_BASE/bin/startup.sh
|serveri käivitusskript
|-
|style="color: green;" | $CATALINA_BASE/bin/shutdown.sh
|serveri peatusskript

|-
|style="color: green;" | $CATALINA_BASE/conf/server.xml
| konteineri peamine konfiguratsioonifail
|-
|style="color: green;" | $CATALINA_BASE/conf/[enginename]/[hostname]/[webappname].xml
|serveri administraatori jaoks konteinerisse endasse ümber kopeeritud rakendusepõhine kontekstikirjelduse konfiguratsioon failist $CATALINA_BASE/webapps/[ApplicationName]/META-INF/context.xml
|-
|style="color: green;" | $CATALINA_BASE/conf/[enginename]/[hostname]/context.xml
| fail, mis aitab administraatoril konteksti kohta käivat infot kirjeldada peremeesmasina-põhiselt ja halduseks mõeldud automaat-tööriistadel (näiteks Tomcat Manager ja TCD) oma tööd teha
|-
|style="color: green;" | $CATALINA_BASE/$CATALINA_BASE/conf/[enginename]/[hostname]/manager.xml
|fail, mis võimaldab lisada rakendustele ligipääsufiltreid
|-
|style="color: green;" | $CATALINA_BASE/webapps/[webappname]/META-INF/context.xml
|kontekstikirjeldusfail, mille veebirakenduse programmeerija on pakendanud oma aplikatsiooniga kaasa ning millega ta saab võimaluse kontekstikirjeldust omalt poolt mõjutada; kirjutatakse rakenduse uuestijuurutamisel üle, mistõttu administraator peaks muutma selle asemel konteinerisse ümber kopeeritud püsieksemplari $CATALINA_BASE/conf/[enginename]/[hostname]/context.xml
|-
|style="color: green;" | $CATALINA_BASE/webapps/[webappname]/WEB-INF/web.xml
|ka üks oluline Java veebiaplikatsiooni konfiguratsioonifail, mille pakendatakse koos veebiarhiiviga; enamasti muudab seda ainult programeerija; määrab muu hulgas millised aplikatsiooni osad vajavad autentimist või kui kiiresti veebisessioon aegub
|}

==Installeerimine==

===Installeerimine paketihalduriga===

<pre>
apt-cache search tomcat
apt-get install tomcat[version]-webapps
apt-get install tomcat[version]-admin
apt-get install tomcat[version]
</pre>

===Installeerimine käsitsi===

Paketihalduriga installeerides ei pruugi viimane Tomcati versioon olla kättesaadav ja see pakub ka vähem võimalusi kataloogide määramiseks jms. Käsitsi installeerimiseks tuleb laadida Tomcat kodulehelt alla. Lahtipakkimisel tekib kataloog, milles sisalduv fail "RUNNING.txt" on kõige kindlam allikas installeerimisel tekkivate probleemide vältimiseks ning lahendamiseks.

Vajaliku versiooni installeerimisfaili asukoha saab vaadata Tomcati kodulehelt sektsioonist "Download". Järgnevas näites installeerime Tomcati kõige uuema ebastabiilse kandidaatversiooni, mida näitab nimes sisalduv RC ehk "release candidate". Produktsioonikeskkonda tuleks siiski valida stabiilse versiooni. Käsitsi installeerimine on sarnane järgmisega:
<pre>
wget http://mirror.nexcess.net/apache/tomcat/tomcat-8/v8.0.0-RC5/bin/apache-tomcat-8.0.0-RC5.tar.gz
tar -zxvf apache-tomcat-8.0.0-RC5.tar.gz
mv /Users/kristjanveskimae/downloads/apache-tomcat-8.0.0-RC5 /usr/local/apache-tomcat-8.0.0-RC5
rm -f /Library/Tomcat
ln -s /usr/local/apache-tomcat-8.0.0-RC5/ /Library/Tomcat
chown -R kristjanveskimae /Library/Tomcat
chmod +x /Library/Tomcat/bin/*.sh
</pre>

==Käivitamine ja aplikatsiooni juurutamine==

===Konteineri käivitamine===

Tomcati käivitamise eelduseks on Java paigaldamine masinasse ning keskkonnamuutujate "JAVA_HOME" ja "JRE_HOME" defineerimine. Peale installeerimist võib kasutada skripte kataloogist $CATALINA_BASE/bin . Järgneb üks võimalik käivitamise ja peatamise näide, mis on kasutatav eelnevalt kirjeldatud käsitsi installeerimise juhul:
<pre>
/Library/Tomcat/bin/startup.sh
</pre>
ja peatamiseks
<pre>
/Library/Tomcat/bin/shutdown.sh
</pre>

===Näiteaplikatsiooni juurutamine===

Java veebiaplikatsiooni jagatakse hea tava kohaselt üheainsa veebiarhiivi failina. Siiski võib Tomcati juurutada ka lahtipakendatud olekus ("exploded") Java veebiaplikatsiooni.

====Käsitsi juurutamine ja mahavõtmine====

Näiteaplikatsiooni juurutamiseks lae selle veebiarhiivifail alla ning kopeeri oma konteineri juurutamiskataloogi 'webapps':
<pre>wget http://tomcat.apache.org/tomcat-8.0-doc/appdev/sample/sample.war
cp /Users/kristjanveskimae/downloads/sample.war /Library/Tomcat/webapps/sample.war</pre>

Kui konfiguratsioonifailis $CATALINA_BASE/conf/server.xml on märgendi "Host" atribuudi "autoDeploy" väärtus "true", installeerib ja uuendab Tomcat aplikatsioone dünaamiliselt töötamise ajal. Kui väärtuseks on "false", käib installeerimine staatiliselt ning serverisse juurutamiseks tuleb teha konteineri taaskäivitus. [http://tomcat.apache.org/tomcat-8.0-doc/manager-howto.html#Deploy_A_New_Application_from_a_Local_Path 2] Mõlemal juhul pakib konteiner arhiveeritud faili ise lahti samasse kausta $CATALINA_BASE/webapps ning ka juurutab selle. Tekkiv aplikatsioon on lokaalsest masinast seejärel kättesaadav aadressil http://localhost:8080/sample/ .

[[File:sample_app.png|400px]]

Veebirakenduse käsitsi mahavõtmiseks tuleb kustutada talle vastav dokumendipõhja kataloog "webapps" kataloogist. Samuti tuleks kustutada .war-fail olemaks kindel, et Tomcat ei rakenda uuel käivitamisel veebiaplikatsiooni veebiarhiivifailist. Veelgi lihtsam on mahavõtmine brauseriga haldusrakenduse kaudu.

Rakenduste baaskataloogi "webapps" asukohta saab muuta failis $CATALINA_BASE/conf/server.xml peremehepõhiselt määratava atribuudiga "appBase", sealjuures Tomcati vaikimisi peremees ehk "Host" on "localhost".

====Tomcati vahendid juurutamiseks====

Veebiaplikatsioonide juurutamine ja mahajuurutamine on võimalik ka kaughalduse teel tänu Tomcati internetipõhisele haldusrakendusele. Näiteks saab veebibrauserit kasutades teha serveri põhitoiminguid Tomcati enda HTML-põhise rakendusega "Tomcat Manager". Veebipõhine haldusrakendus töötab ka käsupõhise veebiteenusena, millele on valmis ehitatud Anti ja Maveni integratsioonid. Samuti eksisteerib käsurea kliendirakendus TCD (Tomcat Client Deployer). TCD ei kuulu Tomcati baaskoosseisu, kuid pakub peale serveri administreerimise tavatoimingute ka lisafunktsionaalsust nagu veebirakenduse kokkukompileerimine ja pakendamine. [http://tomcat.apache.org/tomcat-8.0-doc/manager-howto.html#Configuring_Manager_Application_Access 1]

====Haldurakendus "Tomcat Manager"====

Tomcati haldusrakendus "Tomcat Manager" (antud alamjaotuses lihtsalt haldusrakendus) on Tomcati enda veebiaplikatioon Tomcati brauseripõhiseks kaughalduseks, võimaldades muu hulgas järgnevat [http://tomcat.apache.org/tomcat-8.0-doc/manager-howto.html#Introduction 3]:
* Rakendada uue veebiaplikatsiooni war-faili üleslaadimisega;
* Näha kõiki rakendatud veebiaplikatsioone koos aktiivsete sessioonidega;
* Taasrakendada veebirakendust, näiteks veebiarhiivi pakitud klassifailide /WEB-INF/classes või teekide /WEB-INF/lib uuendamisel, kinnijooksmisel jms.;
* Peatada veebirakendust ilma serverist eemaldamata, samuti koos serverist eemaldamisega;
* Vaadata operatsioonisüsteemi ja Java parameetrite väärtusi;
* Näha kõiki saadaolevaid JNDI ressursse, k.a. andmebaasiühendusi, mis aitavad rakenduste programmeerijail defineerida <ResourceLink> elemendid web.xml konfiguratsioonifailis.

Tomcati installatsioon sisaldab haldusrakendust juba vaikimisi. Haldusrakenduse töölepanemiseks tuleb peremeesmasina konfiguratsioonikataloogi $CATALINA_BASE/conf/[enginename]/[hostname] lisada ka fail manager.xml. Vaikimisi valmiskonfigureeritud testrakendusel on see fail juba olemas asukohas $CATALINA_BASE/conf/Catalina/localhost/manager.xml . Rakendus asub vaikimisi aadressil http://[host]/manager/ , vaikimisi konfiguratsioone kasutades lahendub see asukohaks http://localhost:8080/manager/ . [http://tomcat.apache.org/tomcat-8.0-doc/manager-howto.html#Configuring_Manager_Application_Access 4]

====="Tomcat Manager" ligipääsu konfigureerimine=====

Vaikimisi on turvalisuspõhjustel ligipääs haldusrakendusele maha keeratud. Mismoodi täpselt kasutajatel ligipääsu võimaldada sõltub kasutatavast valdusest (realm). Vaikimisi defineerib $CATALINA_BASE/conf/server.xml valduseks "MemoryRealm". Vaikimisi loeb valdus "MemoryRealm" kasutajad failist $CATALINA_BASE/conf/tomcat-users.xml. Antud failis tuleb iga kasutaja defineerida omaette märgendiga <user>, mis näeb välja umbes järgmine [http://tomcat.apache.org/tomcat-8.0-doc/manager-howto.html#Configuring_Manager_Application_Access 8]:
<pre>
<user name="craig" password="secret" roles="manager-gui,manager-script" />
</pre>

Antud kasutajale on defineeritud korraga kaks rolli. Ligipääsu võimaldamiseks tulebki lihtsamal juhul kasutajatefailis $CATALINA_BASE/conf/tomcat-users.xml defineerida enda kasutaja. Kasutaja rolliks võib määrata näiteks "manager-gui", mis võimaldab ligipääsu kogu HTML liidese funktsionaalsusele.

Teised valdused on "JDBCRealm", mille puhul hoitakse kasutajatega seonduvat infot andmebaasis ja JNDIRealm, mille puhul kasutatakse lihtsustatud kataloogisirvimise protokolli (LDAP).
Lisaks saab haldusrakendusele keelata ligipääsu mujalt kui kindlaksmääratud IP-aadressidelt, lisades filtri "RemoteAddrValve" või "RemoteHostValve" konfigureerimisfaili manager.xml näiteks järgmiselt [http://tomcat.apache.org/tomcat-8.0-doc/manager-howto.html#Introduction 6]:
<pre>
<Context privileged="true">
<Valve className="org.apache.catalina.valves.RemoteAddrValve"
allow="127\.0\.0\.1"/>
</Context>
</pre>

=====Juurutamine ja mahavõtmine haldusrakendusega "Tomcat Manager"=====

Juurutamiseks lae kõigepealt veebiarhiivifail üles, kasutades esilehel asuvat sektsiooni "WAR file to deploy".
[[File:tomcat_manager_war_upload.png]]

Rakendus kuvatakse seejärel hallatavate rakenduste nimekirjas. Kui konteiner pole seadistatud üleslaetud aplikatsiooni kohe ka ise rakendama, tuleb vajutada "Start". Rakenduse peatamiseks kasuta "Stop", uuesti rakendamiseks "Redeploy" ja serverist eemaldamiseks "Undeploy".


[[File:tomcat_manager_apps_list.png|800px|Rakenduste nimekiri]]

==Näpunäiteid Tomcati reaalseks kasutamiseks==

===Juurutamise järjekord===

Tomcati käivitumisel juurutatakse aplikatsioonid sellises järjekorras [http://www.mulesoft.com/tomcat-deploy-procedures 9]:
# Konteinerisse kopeeritud kontekstikirjelduste järgi $CATALINA_BASE/conf/[EngineName]/[HostName]/[ApplicationName].xml ;
# Lahtipakitud rakendused "webapps" kataloogis;
# Pakitud rakenduste veebiarhiivid "webapps" kataloogis.

Seetõttu peaks käsitsi taasjuurutamisel kindluse mõttes eelnevalt kustutama rakenduse lahtipakitud dokumendipõhja kataloogi "webapps" kataloogist. Kontekstikirjelduse muutumisel tuleb jälgida, kas kirjeldus on juba kopeeritud serverisse ning vajadusel eelmise versiooni ümber muuta või kustutada.

===Reaalsele domeenile konfigureerimine===

Järgnevalt eeldame, et domeen ''www.minukodukas.ee'' on juba serverimasinaga seostatud. Et Tomcat hakkaks ka reaalselt Internetist tulevatele päringutele vastama, tuleb muuta failis $CATALINA_BASE/conf/server.xml konteinerile ''Catalina'' vastava teenusemärgendi sisu sarnaselt järgnevaga:

<pre>
<Service name="Catalina">
<Connector port="80" protocol="HTTP/1.1" connectionTimeout="20000" URIEncoding="UTF-8" redirectPort="8443" />
<Engine name="Catalina" defaultHost="www.minukodukas.ee">
<Host name="www.minukodukas.ee" appBase="webapps" unpackWARs="true" autoDeploy="false" deployOnStartup="false" xmlValidation="false" xmlNamespaceAware="false">
<Context path="" docBase="kodukas" debug="0" reloadable="true" />
</Host>
</Engine>
</Service>
</pre>

Ülal defineerime põhiliselt selle, et Tomcat kuulaks domeeni ''www.minukodukas.ee'' ja kasutaks HTTP päringute jaoks porti 80. Ühtlasti otsib Tomcat juurutatavat rakendust failist $CATALINA_BASE/webapps/kodukas.war. Kuna rajalisandiks on määratud tühi sõne (path=""), siis juurutataksegi aplikatsioon aadressile ''www.minukodukas.ee'' ilma rajalisandita (a'la ''www.minukodukas.ee/wiki''). Seetõttu pakitakse ka veebiarhiiv tegelikult lahti kataloogi $CATALINA_BASE/webapps/ROOT mitte kataloogi $CATALINA_BASE/webapps/kodukas nagu võiks eeldada.

===Käigultvahetus===

Võimaldamaks käigultvahetust (hot deployment) peab konteineri konfiguratsioonifailis $CATALINA_BASE/conf/server.xml olema peremehepõhise märgendi "Host" atribuudi "autoDeploy" väärtus "true". Sel juhul installeerib ja uuendab Tomcat aplikatsioone dünaamiliselt töötamise ajal. Kui väärtuseks on "false", käib installeerimine staatiliselt ning serverisse juurutamiseks tuleb teha konteineri taaskäivitus. Käigultvahetust saab määrata ka peremehe defineerimisel "Host Manager" rakendusega, mis on kättesaadav aadressil http://localhost:8080/host-manager/html . Kasutamiseks tuleb lisada oma kasutajale rolli "admin-gui" (vt. alajaotus ""Tomcat Manager" ligipääsu konfigureerimine").

[[File:host_manager_app.png]]

Käigultvahetust päästikuks on vaikimisi uuendatud veebiarhiivifaili või lahtipakitud veebirakenduse paigutamine "webapps" kataloogi. Käigultvahetuse päästikutele võib failis $CATALINA_BASE/conf/server.xml ka ise lisada kuulatavaid ressursse nagu web.xml muutmine või mõne teegifaili vahetamine (märgendis "Host").

===Klassiteekide väljatõstmine veebiarhiivifailist===

Kõik konteksti poolt kasutatavad Java klassiteegid võib pakendada veebiarhiivi sisse kataloogi "lib", kuid nii võib osutuda veebiarhiivi üleslaadimine ajakulukaks, eriti arenduskeskkonnas. Kui ei teki ohtu, et erinevad rakendused kasutavad sama teegi erinevaid versioone, siis on vahel parem lisada osa teeke konteineri kataloogi $CATALINA_BASE/libs, kust need tehakse siis konteineri poolt kättesaadavaks kõigile konteineris jooksutatavatele kontekstidele. Nii võib vähendada veebiarhiivi faili suurust märgatavalt, mis tõstab kokkuvõttes juurutamiskiirust ja ühes sellega programmeerijate tööviljakust.

===Mälukasutus===

Konteineri poolt kasutatavat mälu saab vaadata haldusrakendusest vajutades lingile "Server Status". Mälukasutus on toodud jaotuses "JVM", kus näidatakse nii maksimaalselt kättesaadavat mälu kui ka parasjagu reserveeritud mälu.

<pre>Free memory: 41.16 MB Total memory: 123.37 MB Max memory: 1027.56 MB</pre>

Mälu suurendamiseks võib näiteks defineerida skriptis $CATALINA_BASE/bin/catalina.sh muutuja "JAVA_OPTS" ning määrata Java mälukasutuse miinimum- ja maksimumväärtused sarnaselt järgnevatega [http://www.mkyong.com/tomcat/tomcat-javalangoutofmemoryerror-permgen-space/ 5]:
<pre>
JAVA_OPTS="-Xms1536m -Xmx1536m -XX:NewSize=256m -XX:MaxNewSize=256m -XX:PermSize=256m -XX:MaxPermSize=256m"
</pre>

===Logifailid===

Vaikimisi defineerib Tomcat failiga $CATALINA_BASE/conf/logging.properties viis logerit, mis tekitavad viis eraldi logifaili.

{| style="background:#cccc99;color:black;width:80%;" border="1" cellpadding="5" cellspacing="0" align="center"
|+ Tomcati tekitatavad logifailid "logs" kataloogis
!Fail !! Kasutus
|- style="background:white; color:black"
| style="width:300px" |catalina.out
| Tomcati käivitus- ja peatamisskriptide väljund, samuti juurutatud rakenduste prindilaused System.out ja veaväljundid System.err
|- style="background:white; color:black"
| style="width:300px" |catalina.[yyyy]-[mm]-[dd].log
| Pööratud (rotated) logifail catalina.out
|- style="background:white; color:black"
| style="width:300px" |host-manager.[yyyy]-[mm]-[dd].log
| Logi peremehehalduse rakendusele (rakendus on kättesaadav kohalikust masinast aadressil http://localhost:8080/host-manager/html )
|- style="background:white; color:black"
| style="width:300px" |localhost.[yyyy]-[mm]-[dd].log
| Peremehe "localhost" logi; mitme virtuaalse peremehe korral tekitatakse igale peremehele oma logi
|- style="background:white; color:black"
| style="width:300px" |localhost_access_log.[yyyy]-[mm]-[dd].txt
| Konteinerisse Internetist saabunud päringute logi
|- style="background:white; color:black"
| style="width:300px" |manager.[yyyy]-[mm]-[dd].log
| Haldusrakenduse tegevuste logi
|}

===Viiteid===

Palju vajalikku võib leida [http://tomcat.apache.org/tomcat-8.0-doc/index.html Tomcat 8 dokumentatsioonist]

Lisaks üks viide põhjalikule Tomcati versioon seitsme ülevaatele: http://www.ntu.edu.sg/home/ehchua/programming/howto/Tomcat_More.html

= Kasutatud materjalid =

#http://tomcat.apache.org/tomcat-8.0-doc/index.html
#http://www.mulesoft.com/tomcat-deploy-procedures
#http://www.mkyong.com/tomcat/tomcat-javalangoutofmemoryerror-permgen-space/

[[Category: Operatsioonisüsteemide administreerimine ja sidumine]]

Tomcat

2014-01-02T21:47:07Z

Kveskima: /* Juurutamise järjekord */

==Autor==

Kristjan Veskimäe D32

2013

==Sissejuhatus==

Tomcat on vabalt kättesaadav server Java veebirakendustele. Põhimõtteliselt on tegemist Servlet/JSP spetsifikatsiooni toetava konteineriga. Kiire käivitumise ning rakenduste käigultvahetuse tõttu on Tomcat hea valik väiksemate ning keskmise suurusega Java veebirakenduste käitamiseks.

Antud töö kirjeldab Tomcati 8. versiooni. Põhiosa on üldiselt samasugune võrreldes paari eelmise versiooniga. Suuremad erinevused on versioonispetsiifilistes probleemides ja nende lahendamises, mida käesolev töö ei vaatle.

Töö vaatleb Tomcati paigaldamist ja seadistamist Unix-laadsesse keskkonda ning eeldab lugejalt algteadmisi sarnastes süsteemides. Tomcati on võimalik paigaldada ka Windows-keskkonda, kuid antud veebiserver eeldab kasutaja poolt käsureal töötamist ning Tomcati failihierarhias orienteerumist. Põhimõtteliselt on Java veebirakenduste arendamiseks IDE-abil võimalik siiski ka kasutada IDE-sse integreeritud Tomcati serverit - näiteks pakuvad sellist võimalust Eclipse EE ja NetBeans - kuid seda käesolev töö ei vaatle.

==Mõisted==

* '''Kontekst''' (context) - Tomcati mõistes üks konkreetne veebiaplikatsioon
* '''Konteiner''' (container) - veebiserver Tomcat ise
* '''Kontekstikirjeldus''' (context descriptor) - Tomcati-spetsiifiline konteksti konfiguratsioonimääratlus; peremehepõhine osa loetakse failist $CATALINA_HOME/conf/[enginename]/[hostname]/context.xml ja sellele lisatakse kontekstispetsiifilised täpsustused failist $CATALINA_BASE/conf/[enginename]/[hostname]/[webappname].xml; kontekstikirjeldus määrab näiteks nimed ressurssidele, sessioonihalduse parameetrid jmt. (olgu märgitud, et Tomcati varasemates versioonides sisaldusid kontekstikirjeldused põhikonfiguratsioonifailis server.xml)
* '''Dokumendipõhi''' (docBase) - kontekstile vastav kataloog Tomcati "webapps" kataloogis, mis tekib veebiaplikatsiooni serverisse rakendamisel
* '''Veebiarhiiv''' (Web application ARchive, war-file) - Java veebiaplikatsiooni jagatakse hea tava kohaselt selle üheainsa veebiarhiivi failina, mille laienditüübiks on "war". Tegemist on zip-protokolliga kokkupakitud kataloogiga, millel on Java veebirakenduste spetsifikatsioonile vastav ülesehitus. Siiski võib veebiaplikatsioon olla juurutamisel ka lahtipakendatud olekus (inglisekeelne termin on "war is exploded").

==Ülesehitus==

{| class="wikitable"
|+Kataloogid
|-
|style="color: green;" | $CATALINA_HOME
|baaskataloog, kuhu on Tomcat paigutatud
|-
|style="color: green;" | $CATALINA_BASE
|parasjagu töösoleva Tomcati eksemplari baaskataloog, mille alusel lahendatakse teed ülejäänud kataloogide ja failideni; ainult ühe kasutusel oleva Tomcati eksemplari puhul on see sama, mis $CATALINA_HOME

|-
|style="color: green;" | $CATALINA_BASE/bin
|serveri käivitus- ja abiskriptid
|-
|style="color: green;" | $CATALINA_BASE/conf
|konfiguratsioonifailid
|-
|style="color: green;" | $CATALINA_BASE/lib
|Tomcatile vaikimisi kättesaadavad Java klassiteegid (class libraries) ehk .jar-failid kuhu on Java kompileeritud kood kokku pakendatud
|-
|style="color: green;" | $CATALINA_BASE/logs
|logifailid paigutatakse vaikimisi siia
|-
|style="color: green;" | $CATALINA_BASE/webapps
|kataloog, kuhu paigutatakse serverisse juurutatavad veebiaplikatsioonid

|}

{| class="wikitable"
|+Mõned olulisemad failid
|-
|style="color: green;" | $CATALINA_BASE/bin/startup.sh
|serveri käivitusskript
|-
|style="color: green;" | $CATALINA_BASE/bin/shutdown.sh
|serveri peatusskript

|-
|style="color: green;" | $CATALINA_BASE/conf/server.xml
| konteineri peamine konfiguratsioonifail
|-
|style="color: green;" | $CATALINA_BASE/conf/[enginename]/[hostname]/[webappname].xml
|serveri administraatori jaoks konteinerisse endasse ümber kopeeritud rakendusepõhine kontekstikirjelduse konfiguratsioon failist $CATALINA_BASE/webapps/[ApplicationName]/META-INF/context.xml
|-
|style="color: green;" | $CATALINA_BASE/conf/[enginename]/[hostname]/context.xml
| fail, mis aitab administraatoril konteksti kohta käivat infot kirjeldada peremeesmasina-põhiselt ja halduseks mõeldud automaat-tööriistadel (näiteks Tomcat Manager ja TCD) oma tööd teha
|-
|style="color: green;" | $CATALINA_BASE/$CATALINA_BASE/conf/[enginename]/[hostname]/manager.xml
|fail, mis võimaldab lisada rakendustele ligipääsufiltreid
|-
|style="color: green;" | $CATALINA_BASE/webapps/[webappname]/META-INF/context.xml
|kontekstikirjeldusfail, mille veebirakenduse programmeerija on pakendanud oma aplikatsiooniga kaasa ning millega ta saab võimaluse kontekstikirjeldust omalt poolt mõjutada; kirjutatakse rakenduse uuestijuurutamisel üle, mistõttu administraator peaks muutma selle asemel konteinerisse ümber kopeeritud püsieksemplari $CATALINA_BASE/conf/[enginename]/[hostname]/context.xml
|-
|style="color: green;" | $CATALINA_BASE/webapps/[webappname]/WEB-INF/web.xml
|ka üks oluline Java veebiaplikatsiooni konfiguratsioonifail, mille pakendatakse koos veebiarhiiviga; enamasti muudab seda ainult programeerija; määrab muu hulgas millised aplikatsiooni osad vajavad autentimist või kui kiiresti veebisessioon aegub
|}

==Installeerimine==

===Installeerimine paketihalduriga===

<pre>
apt-cache search tomcat
apt-get install tomcat[version]-webapps
apt-get install tomcat[version]-admin
apt-get install tomcat[version]
</pre>

===Installeerimine käsitsi===

Paketihalduriga installeerides ei pruugi viimane Tomcati versioon olla kättesaadav ja see pakub ka vähem võimalusi kataloogide määramiseks jms. Käsitsi installeerimiseks tuleb laadida Tomcat kodulehelt alla. Lahtipakkimisel tekib kataloog, milles sisalduv fail "RUNNING.txt" on kõige kindlam allikas installeerimisel tekkivate probleemide vältimiseks ning lahendamiseks.

Vajaliku versiooni installeerimisfaili asukoha saab vaadata Tomcati kodulehelt sektsioonist "Download". Järgnevas näites installeerime Tomcati kõige uuema ebastabiilse kandidaatversiooni, mida näitab nimes sisalduv RC ehk "release candidate". Produktsioonikeskkonda tuleks siiski valida stabiilse versiooni. Käsitsi installeerimine on sarnane järgmisega:
<pre>
wget http://mirror.nexcess.net/apache/tomcat/tomcat-8/v8.0.0-RC5/bin/apache-tomcat-8.0.0-RC5.tar.gz
tar -zxvf apache-tomcat-8.0.0-RC5.tar.gz
mv /Users/kristjanveskimae/downloads/apache-tomcat-8.0.0-RC5 /usr/local/apache-tomcat-8.0.0-RC5
rm -f /Library/Tomcat
ln -s /usr/local/apache-tomcat-8.0.0-RC5/ /Library/Tomcat
chown -R kristjanveskimae /Library/Tomcat
chmod +x /Library/Tomcat/bin/*.sh
</pre>

==Käivitamine ja aplikatsiooni juurutamine==

===Konteineri käivitamine===

Tomcati käivitamise eelduseks on Java paigaldamine masinasse ning keskkonnamuutujate "JAVA_HOME" ja "JRE_HOME" defineerimine. Peale installeerimist võib kasutada skripte kataloogist $CATALINA_BASE/bin . Järgneb üks võimalik käivitamise ja peatamise näide, mis on kasutatav eelnevalt kirjeldatud käsitsi installeerimise juhul:
<pre>
/Library/Tomcat/bin/startup.sh
</pre>
ja peatamiseks
<pre>
/Library/Tomcat/bin/shutdown.sh
</pre>

===Näiteaplikatsiooni juurutamine===

Java veebiaplikatsiooni jagatakse hea tava kohaselt üheainsa veebiarhiivi failina. Siiski võib Tomcati juurutada ka lahtipakendatud olekus ("exploded") Java veebiaplikatsiooni.

====Käsitsi juurutamine ja mahavõtmine====

Näiteaplikatsiooni juurutamiseks lae selle veebiarhiivifail alla ning kopeeri oma konteineri juurutamiskataloogi 'webapps':
<pre>wget http://tomcat.apache.org/tomcat-8.0-doc/appdev/sample/sample.war
cp /Users/kristjanveskimae/downloads/sample.war /Library/Tomcat/webapps/sample.war</pre>

Kui konfiguratsioonifailis $CATALINA_BASE/conf/server.xml on märgendi "Host" atribuudi "autoDeploy" väärtus "true", installeerib ja uuendab Tomcat aplikatsioone dünaamiliselt töötamise ajal. Kui väärtuseks on "false", käib installeerimine staatiliselt ning serverisse juurutamiseks tuleb teha konteineri taaskäivitus. [http://tomcat.apache.org/tomcat-8.0-doc/manager-howto.html#Deploy_A_New_Application_from_a_Local_Path 2] Mõlemal juhul pakib konteiner arhiveeritud faili ise lahti samasse kausta $CATALINA_BASE/webapps ning ka juurutab selle. Tekkiv aplikatsioon on lokaalsest masinast seejärel kättesaadav aadressil http://localhost:8080/sample/ .

[[File:sample_app.png|400px]]

Veebirakenduse käsitsi mahavõtmiseks tuleb kustutada talle vastav dokumendipõhja kataloog "webapps" kataloogist. Samuti tuleks kustutada .war-fail olemaks kindel, et Tomcat ei rakenda uuel käivitamisel veebiaplikatsiooni veebiarhiivifailist. Veelgi lihtsam on mahavõtmine brauseriga haldusrakenduse kaudu.

Rakenduste baaskataloogi "webapps" asukohta saab muuta failis $CATALINA_BASE/conf/server.xml peremehepõhiselt määratava atribuudiga "appBase", sealjuures Tomcati vaikimisi peremees ehk "Host" on "localhost".

====Tomcati vahendid juurutamiseks====

Veebiaplikatsioonide juurutamine ja mahajuurutamine on võimalik ka kaughalduse teel tänu Tomcati internetipõhisele haldusrakendusele. Näiteks saab veebibrauserit kasutades teha serveri põhitoiminguid Tomcati enda HTML-põhise rakendusega "Tomcat Manager". Veebipõhine haldusrakendus töötab ka käsupõhise veebiteenusena, millele on valmis ehitatud Anti ja Maveni integratsioonid. Samuti eksisteerib käsurea kliendirakendus TCD (Tomcat Client Deployer). TCD ei kuulu Tomcati baaskoosseisu, kuid pakub peale serveri administreerimise tavatoimingute ka lisafunktsionaalsust nagu veebirakenduse kokkukompileerimine ja pakendamine. [http://tomcat.apache.org/tomcat-8.0-doc/manager-howto.html#Configuring_Manager_Application_Access 1]

====Haldurakendus "Tomcat Manager"====

Tomcati haldusrakendus "Tomcat Manager" (antud alamjaotuses lihtsalt haldusrakendus) on Tomcati enda veebiaplikatioon Tomcati brauseripõhiseks kaughalduseks, võimaldades muu hulgas järgnevat [http://tomcat.apache.org/tomcat-8.0-doc/manager-howto.html#Introduction 3]:
* Rakendada uue veebiaplikatsiooni war-faili üleslaadimisega;
* Näha kõiki rakendatud veebiaplikatsioone koos aktiivsete sessioonidega;
* Taasrakendada veebirakendust, näiteks veebiarhiivi pakitud klassifailide /WEB-INF/classes või teekide /WEB-INF/lib uuendamisel, kinnijooksmisel jms.;
* Peatada veebirakendust ilma serverist eemaldamata, samuti koos serverist eemaldamisega;
* Vaadata operatsioonisüsteemi ja Java parameetrite väärtusi;
* Näha kõiki saadaolevaid JNDI ressursse, k.a. andmebaasiühendusi, mis aitavad rakenduste programmeerijail defineerida <ResourceLink> elemendid web.xml konfiguratsioonifailis.

Tomcati installatsioon sisaldab haldusrakendust juba vaikimisi. Haldusrakenduse töölepanemiseks tuleb peremeesmasina konfiguratsioonikataloogi $CATALINA_BASE/conf/[enginename]/[hostname] lisada ka fail manager.xml. Vaikimisi valmiskonfigureeritud testrakendusel on see fail juba olemas asukohas $CATALINA_BASE/conf/Catalina/localhost/manager.xml . Rakendus asub vaikimisi aadressil http://[host]/manager/ , vaikimisi konfiguratsioone kasutades lahendub see asukohaks http://localhost:8080/manager/ . [http://tomcat.apache.org/tomcat-8.0-doc/manager-howto.html#Configuring_Manager_Application_Access 4]

====="Tomcat Manager" ligipääsu konfigureerimine=====

Vaikimisi on turvalisuspõhjustel ligipääs haldusrakendusele maha keeratud. Mismoodi täpselt kasutajatel ligipääsu võimaldada sõltub kasutatavast valdusest (realm). Vaikimisi defineerib $CATALINA_BASE/conf/server.xml valduseks "MemoryRealm". Vaikimisi loeb valdus "MemoryRealm" kasutajad failist $CATALINA_BASE/conf/tomcat-users.xml. Antud failis tuleb iga kasutaja defineerida omaette märgendiga <user>, mis näeb välja umbes järgmine [http://tomcat.apache.org/tomcat-8.0-doc/manager-howto.html#Configuring_Manager_Application_Access 8]:
<pre>
<user name="craig" password="secret" roles="manager-gui,manager-script" />
</pre>

Antud kasutajale on defineeritud korraga kaks rolli. Ligipääsu võimaldamiseks tulebki lihtsamal juhul kasutajatefailis $CATALINA_BASE/conf/tomcat-users.xml defineerida enda kasutaja. Kasutaja rolliks võib määrata näiteks "manager-gui", mis võimaldab ligipääsu kogu HTML liidese funktsionaalsusele.

Teised valdused on "JDBCRealm", mille puhul hoitakse kasutajatega seonduvat infot andmebaasis ja JNDIRealm, mille puhul kasutatakse lihtsustatud kataloogisirvimise protokolli (LDAP).
Lisaks saab haldusrakendusele keelata ligipääsu mujalt kui kindlaksmääratud IP-aadressidelt, lisades filtri "RemoteAddrValve" või "RemoteHostValve" konfigureerimisfaili manager.xml näiteks järgmiselt [http://tomcat.apache.org/tomcat-8.0-doc/manager-howto.html#Introduction 6]:
<pre>
<Context privileged="true">
<Valve className="org.apache.catalina.valves.RemoteAddrValve"
allow="127\.0\.0\.1"/>
</Context>
</pre>

=====Juurutamine ja mahavõtmine haldusrakendusega "Tomcat Manager"=====

Juurutamiseks lae kõigepealt veebiarhiivifail üles, kasutades esilehel asuvat sektsiooni "WAR file to deploy".
[[File:tomcat_manager_war_upload.png]]

Rakendus kuvatakse seejärel hallatavate rakenduste nimekirjas. Kui konteiner pole seadistatud üleslaetud aplikatsiooni kohe ka ise rakendama, tuleb vajutada "Start". Rakenduse peatamiseks kasuta "Stop", uuesti rakendamiseks "Redeploy" ja serverist eemaldamiseks "Undeploy".


[[File:tomcat_manager_apps_list.png|800px|Rakenduste nimekiri]]

==Näpunäiteid Tomcati reaalseks kasutamiseks==

===Juurutamise järjekord===

Tomcati käivitumisel juurutatakse aplikatsioonid sellises järjekorras [http://www.mulesoft.com/tomcat-deploy-procedures 9]:
# Konteinerisse kopeeritud kontekstikirjelduste järgi $CATALINA_BASE/conf/[EngineName]/[HostName]/[ApplicationName].xml ;
# Lahtipakitud rakendused "webapps" kataloogis;
# Pakitud rakenduste veebiarhiivid "webapps" kataloogis.

Seetõttu peaks käsitsi taasjuurutamisel kindluse mõttes eelnevalt kustutama rakenduse lahtipakitud dokumendipõhja kataloogi "webapps" kataloogist. Kontekstikirjelduse muutumisel tuleb jälgida, kas kirjeldus on juba kopeeritud serverisse ning vajadusel eelmise versiooni ümber muuta või kustutada.

===Reaalsele domeenile konfigureerimine===

Järgnevalt eeldame, et domeen ''www.minukodukas.ee'' on juba serverimasinaga seostatud. Et Tomcat hakkaks ka reaalselt Internetist tulevatele päringutele vastama, tuleb muuta failis $CATALINA_BASE/conf/server.xml konteinerile ''Catalina'' vastava teenusemärgendi sisu sarnaselt järgnevaga:

<pre>
<Service name="Catalina">
<Connector port="80" protocol="HTTP/1.1" connectionTimeout="20000" URIEncoding="UTF-8" redirectPort="8443" />
<Engine name="Catalina" defaultHost="www.minukodukas.ee">
<Host name="www.minukodukas.ee" appBase="webapps" unpackWARs="true" autoDeploy="false" deployOnStartup="false" xmlValidation="false" xmlNamespaceAware="false">
<Context path="" docBase="kodukas" debug="0" reloadable="true" />
</Host>
</Engine>
</Service>
</pre>

Ülal defineerime põhiliselt selle, et Tomcat kuulaks domeeni ''www.minukodukas.ee'' ja kasutaks HTTP päringute jaoks porti 80. Ühtlasti otsib Tomcat juurutatavat rakendust failist $CATALINA_BASE/webapps/kodukas.war. Kuna rajalisandiks on määratud tühi sõne (path=""), siis juurutataksegi aplikatsioon aadressile ''www.minukodukas.ee'' ilma rajalisandita (a'la ''www.minukodukas.ee/wiki''). Seetõttu pakitakse ka veebiarhiiv tegelikult lahti kataloogi $CATALINA_BASE/webapps/ROOT mitte kataloogi $CATALINA_BASE/webapps/kodukas nagu võiks eeldada.

===Käigultvahetus===

Võimaldamaks käigultvahetust (hot deployment) peab konteineri konfiguratsioonifailis $CATALINA_BASE/conf/server.xml olema peremehepõhise märgendi "Host" atribuudi "autoDeploy" väärtus "true". Sel juhul installeerib ja uuendab Tomcat aplikatsioone dünaamiliselt töötamise ajal. Kui väärtuseks on "false", käib installeerimine staatiliselt ning serverisse juurutamiseks tuleb teha konteineri taaskäivitus. Käigultvahetust saab määrata ka peremehe defineerimisel "Host Manager" rakendusega, mis on kättesaadav aadressil http://localhost:8080/host-manager/html . Kasutamiseks tuleb lisada oma kasutajale rolli "admin-gui" (vt. alajaotus ""Tomcat Manager" ligipääsu konfigureerimine").

[[File:host_manager_app.png]]

Käigultvahetust päästikuks on vaikimisi uuendatud veebiarhiivifaili või lahtipakitud veebirakenduse paigutamine "webapps" kataloogi. Käigultvahetuse päästikutele võib failis $CATALINA_BASE/conf/server.xml ka ise lisada kuulatavaid ressursse nagu web.xml muutmine või mõne teegifaili vahetamine (märgendis "Host").

===Klassiteekide väljatõstmine veebiarhiivifailist===

Kõik konteksti poolt kasutatavad Java klassiteegid võib pakendada veebiarhiivi sisse kataloogi "lib", kuid nii võib osutuda veebiarhiivi üleslaadimine ajakulukaks, eriti arenduskeskkonnas. Kui ei teki ohtu, et erinevad rakendused kasutavad sama teegi erinevaid versioone, siis on vahel parem lisada osa teeke konteineri kataloogi $CATALINA_BASE/libs, kust need tehakse siis konteineri poolt kättesaadavaks kõigile konteineris jooksutatavatele kontekstidele. Nii võib vähendada veebiarhiivi faili suurust märgatavalt, mis tõstab kokkuvõttes juurutamiskiirust ja ühes sellega programmeerijate tööviljakust.

===Mälukasutus===

Konteineri poolt kasutatavat mälu saab vaadata haldusrakendusest vajutades lingile "Server Status". Mälukasutus on toodud jaotuses "JVM", kus näidatakse nii maksimaalselt kättesaadavat mälu kui ka parasjagu reserveeritud mälu.

<pre>Free memory: 41.16 MB Total memory: 123.37 MB Max memory: 1027.56 MB</pre>

Mälu suurendamiseks võib näiteks defineerida skriptis $CATALINA_BASE/bin/catalina.sh muutuja "JAVA_OPTS" ning määrata Java mälukasutuse miinimum- ja maksimumväärtused sarnaselt järgnevatega [http://www.mkyong.com/tomcat/tomcat-javalangoutofmemoryerror-permgen-space/ 5]:
<pre>
JAVA_OPTS="-Xms1536m -Xmx1536m -XX:NewSize=256m -XX:MaxNewSize=256m -XX:PermSize=256m -XX:MaxPermSize=256m"
</pre>

===Logifailid===

Vaikimisi defineerib Tomcat failiga $CATALINA_BASE/conf/logging.properties viis logerit, mis tekitavad viis eraldi logifaili.

{| style="background:#cccc99;color:black;width:80%;" border="1" cellpadding="5" cellspacing="0" align="center"
|+ Tomcati tekitatavad logifailid "logs" kataloogis
!Fail !! Kasutus
|- style="background:white; color:black"
| style="width:300px" |catalina.out
| Tomcati käivitus- ja peatamisskriptide väljund, samuti juurutatud rakenduste prindilaused System.out ja veaväljundid System.err
|- style="background:white; color:black"
| style="width:300px" |catalina.[yyyy]-[mm]-[dd].log
| Pööratud (rotated) logifail catalina.out
|- style="background:white; color:black"
| style="width:300px" |host-manager.[yyyy]-[mm]-[dd].log
| Logi peremehehalduse rakendusele (rakendus on kättesaadav kohalikust masinast aadressil http://localhost:8080/host-manager/html )
|- style="background:white; color:black"
| style="width:300px" |localhost.[yyyy]-[mm]-[dd].log
| Peremehe "localhost" logi; mitme virtuaalse peremehe korral tekitatakse igale peremehele oma logi
|- style="background:white; color:black"
| style="width:300px" |localhost_access_log.[yyyy]-[mm]-[dd].txt
| Konteinerisse Internetist saabunud päringute logi
|- style="background:white; color:black"
| style="width:300px" |manager.[yyyy]-[mm]-[dd].log
| Haldusrakenduse tegevuste logi
|}

===Viiteid===

Palju vajalikku võib leida [http://tomcat.apache.org/tomcat-8.0-doc/index.html Tomcat 8 dokumentatsioonist]

Lisaks üks viide põhjalikule Tomcati versioon seitsme ülevaatele: http://www.ntu.edu.sg/home/ehchua/programming/howto/Tomcat_More.html

= Kasutatud materjalid =

*http://tomcat.apache.org/tomcat-8.0-doc/index.html
*http://www.mulesoft.com/tomcat-deploy-procedures
*http://www.mkyong.com/tomcat/tomcat-javalangoutofmemoryerror-permgen-space/

[[Category: Operatsioonisüsteemide administreerimine ja sidumine]]

Tomcat

2014-01-02T21:45:47Z

Kveskima: /* "Tomcat Manager" ligipääsu konfigureerimine */

==Autor==

Kristjan Veskimäe D32

2013

==Sissejuhatus==

Tomcat on vabalt kättesaadav server Java veebirakendustele. Põhimõtteliselt on tegemist Servlet/JSP spetsifikatsiooni toetava konteineriga. Kiire käivitumise ning rakenduste käigultvahetuse tõttu on Tomcat hea valik väiksemate ning keskmise suurusega Java veebirakenduste käitamiseks.

Antud töö kirjeldab Tomcati 8. versiooni. Põhiosa on üldiselt samasugune võrreldes paari eelmise versiooniga. Suuremad erinevused on versioonispetsiifilistes probleemides ja nende lahendamises, mida käesolev töö ei vaatle.

Töö vaatleb Tomcati paigaldamist ja seadistamist Unix-laadsesse keskkonda ning eeldab lugejalt algteadmisi sarnastes süsteemides. Tomcati on võimalik paigaldada ka Windows-keskkonda, kuid antud veebiserver eeldab kasutaja poolt käsureal töötamist ning Tomcati failihierarhias orienteerumist. Põhimõtteliselt on Java veebirakenduste arendamiseks IDE-abil võimalik siiski ka kasutada IDE-sse integreeritud Tomcati serverit - näiteks pakuvad sellist võimalust Eclipse EE ja NetBeans - kuid seda käesolev töö ei vaatle.

==Mõisted==

* '''Kontekst''' (context) - Tomcati mõistes üks konkreetne veebiaplikatsioon
* '''Konteiner''' (container) - veebiserver Tomcat ise
* '''Kontekstikirjeldus''' (context descriptor) - Tomcati-spetsiifiline konteksti konfiguratsioonimääratlus; peremehepõhine osa loetakse failist $CATALINA_HOME/conf/[enginename]/[hostname]/context.xml ja sellele lisatakse kontekstispetsiifilised täpsustused failist $CATALINA_BASE/conf/[enginename]/[hostname]/[webappname].xml; kontekstikirjeldus määrab näiteks nimed ressurssidele, sessioonihalduse parameetrid jmt. (olgu märgitud, et Tomcati varasemates versioonides sisaldusid kontekstikirjeldused põhikonfiguratsioonifailis server.xml)
* '''Dokumendipõhi''' (docBase) - kontekstile vastav kataloog Tomcati "webapps" kataloogis, mis tekib veebiaplikatsiooni serverisse rakendamisel
* '''Veebiarhiiv''' (Web application ARchive, war-file) - Java veebiaplikatsiooni jagatakse hea tava kohaselt selle üheainsa veebiarhiivi failina, mille laienditüübiks on "war". Tegemist on zip-protokolliga kokkupakitud kataloogiga, millel on Java veebirakenduste spetsifikatsioonile vastav ülesehitus. Siiski võib veebiaplikatsioon olla juurutamisel ka lahtipakendatud olekus (inglisekeelne termin on "war is exploded").

==Ülesehitus==

{| class="wikitable"
|+Kataloogid
|-
|style="color: green;" | $CATALINA_HOME
|baaskataloog, kuhu on Tomcat paigutatud
|-
|style="color: green;" | $CATALINA_BASE
|parasjagu töösoleva Tomcati eksemplari baaskataloog, mille alusel lahendatakse teed ülejäänud kataloogide ja failideni; ainult ühe kasutusel oleva Tomcati eksemplari puhul on see sama, mis $CATALINA_HOME

|-
|style="color: green;" | $CATALINA_BASE/bin
|serveri käivitus- ja abiskriptid
|-
|style="color: green;" | $CATALINA_BASE/conf
|konfiguratsioonifailid
|-
|style="color: green;" | $CATALINA_BASE/lib
|Tomcatile vaikimisi kättesaadavad Java klassiteegid (class libraries) ehk .jar-failid kuhu on Java kompileeritud kood kokku pakendatud
|-
|style="color: green;" | $CATALINA_BASE/logs
|logifailid paigutatakse vaikimisi siia
|-
|style="color: green;" | $CATALINA_BASE/webapps
|kataloog, kuhu paigutatakse serverisse juurutatavad veebiaplikatsioonid

|}

{| class="wikitable"
|+Mõned olulisemad failid
|-
|style="color: green;" | $CATALINA_BASE/bin/startup.sh
|serveri käivitusskript
|-
|style="color: green;" | $CATALINA_BASE/bin/shutdown.sh
|serveri peatusskript

|-
|style="color: green;" | $CATALINA_BASE/conf/server.xml
| konteineri peamine konfiguratsioonifail
|-
|style="color: green;" | $CATALINA_BASE/conf/[enginename]/[hostname]/[webappname].xml
|serveri administraatori jaoks konteinerisse endasse ümber kopeeritud rakendusepõhine kontekstikirjelduse konfiguratsioon failist $CATALINA_BASE/webapps/[ApplicationName]/META-INF/context.xml
|-
|style="color: green;" | $CATALINA_BASE/conf/[enginename]/[hostname]/context.xml
| fail, mis aitab administraatoril konteksti kohta käivat infot kirjeldada peremeesmasina-põhiselt ja halduseks mõeldud automaat-tööriistadel (näiteks Tomcat Manager ja TCD) oma tööd teha
|-
|style="color: green;" | $CATALINA_BASE/$CATALINA_BASE/conf/[enginename]/[hostname]/manager.xml
|fail, mis võimaldab lisada rakendustele ligipääsufiltreid
|-
|style="color: green;" | $CATALINA_BASE/webapps/[webappname]/META-INF/context.xml
|kontekstikirjeldusfail, mille veebirakenduse programmeerija on pakendanud oma aplikatsiooniga kaasa ning millega ta saab võimaluse kontekstikirjeldust omalt poolt mõjutada; kirjutatakse rakenduse uuestijuurutamisel üle, mistõttu administraator peaks muutma selle asemel konteinerisse ümber kopeeritud püsieksemplari $CATALINA_BASE/conf/[enginename]/[hostname]/context.xml
|-
|style="color: green;" | $CATALINA_BASE/webapps/[webappname]/WEB-INF/web.xml
|ka üks oluline Java veebiaplikatsiooni konfiguratsioonifail, mille pakendatakse koos veebiarhiiviga; enamasti muudab seda ainult programeerija; määrab muu hulgas millised aplikatsiooni osad vajavad autentimist või kui kiiresti veebisessioon aegub
|}

==Installeerimine==

===Installeerimine paketihalduriga===

<pre>
apt-cache search tomcat
apt-get install tomcat[version]-webapps
apt-get install tomcat[version]-admin
apt-get install tomcat[version]
</pre>

===Installeerimine käsitsi===

Paketihalduriga installeerides ei pruugi viimane Tomcati versioon olla kättesaadav ja see pakub ka vähem võimalusi kataloogide määramiseks jms. Käsitsi installeerimiseks tuleb laadida Tomcat kodulehelt alla. Lahtipakkimisel tekib kataloog, milles sisalduv fail "RUNNING.txt" on kõige kindlam allikas installeerimisel tekkivate probleemide vältimiseks ning lahendamiseks.

Vajaliku versiooni installeerimisfaili asukoha saab vaadata Tomcati kodulehelt sektsioonist "Download". Järgnevas näites installeerime Tomcati kõige uuema ebastabiilse kandidaatversiooni, mida näitab nimes sisalduv RC ehk "release candidate". Produktsioonikeskkonda tuleks siiski valida stabiilse versiooni. Käsitsi installeerimine on sarnane järgmisega:
<pre>
wget http://mirror.nexcess.net/apache/tomcat/tomcat-8/v8.0.0-RC5/bin/apache-tomcat-8.0.0-RC5.tar.gz
tar -zxvf apache-tomcat-8.0.0-RC5.tar.gz
mv /Users/kristjanveskimae/downloads/apache-tomcat-8.0.0-RC5 /usr/local/apache-tomcat-8.0.0-RC5
rm -f /Library/Tomcat
ln -s /usr/local/apache-tomcat-8.0.0-RC5/ /Library/Tomcat
chown -R kristjanveskimae /Library/Tomcat
chmod +x /Library/Tomcat/bin/*.sh
</pre>

==Käivitamine ja aplikatsiooni juurutamine==

===Konteineri käivitamine===

Tomcati käivitamise eelduseks on Java paigaldamine masinasse ning keskkonnamuutujate "JAVA_HOME" ja "JRE_HOME" defineerimine. Peale installeerimist võib kasutada skripte kataloogist $CATALINA_BASE/bin . Järgneb üks võimalik käivitamise ja peatamise näide, mis on kasutatav eelnevalt kirjeldatud käsitsi installeerimise juhul:
<pre>
/Library/Tomcat/bin/startup.sh
</pre>
ja peatamiseks
<pre>
/Library/Tomcat/bin/shutdown.sh
</pre>

===Näiteaplikatsiooni juurutamine===

Java veebiaplikatsiooni jagatakse hea tava kohaselt üheainsa veebiarhiivi failina. Siiski võib Tomcati juurutada ka lahtipakendatud olekus ("exploded") Java veebiaplikatsiooni.

====Käsitsi juurutamine ja mahavõtmine====

Näiteaplikatsiooni juurutamiseks lae selle veebiarhiivifail alla ning kopeeri oma konteineri juurutamiskataloogi 'webapps':
<pre>wget http://tomcat.apache.org/tomcat-8.0-doc/appdev/sample/sample.war
cp /Users/kristjanveskimae/downloads/sample.war /Library/Tomcat/webapps/sample.war</pre>

Kui konfiguratsioonifailis $CATALINA_BASE/conf/server.xml on märgendi "Host" atribuudi "autoDeploy" väärtus "true", installeerib ja uuendab Tomcat aplikatsioone dünaamiliselt töötamise ajal. Kui väärtuseks on "false", käib installeerimine staatiliselt ning serverisse juurutamiseks tuleb teha konteineri taaskäivitus. [http://tomcat.apache.org/tomcat-8.0-doc/manager-howto.html#Deploy_A_New_Application_from_a_Local_Path 2] Mõlemal juhul pakib konteiner arhiveeritud faili ise lahti samasse kausta $CATALINA_BASE/webapps ning ka juurutab selle. Tekkiv aplikatsioon on lokaalsest masinast seejärel kättesaadav aadressil http://localhost:8080/sample/ .

[[File:sample_app.png|400px]]

Veebirakenduse käsitsi mahavõtmiseks tuleb kustutada talle vastav dokumendipõhja kataloog "webapps" kataloogist. Samuti tuleks kustutada .war-fail olemaks kindel, et Tomcat ei rakenda uuel käivitamisel veebiaplikatsiooni veebiarhiivifailist. Veelgi lihtsam on mahavõtmine brauseriga haldusrakenduse kaudu.

Rakenduste baaskataloogi "webapps" asukohta saab muuta failis $CATALINA_BASE/conf/server.xml peremehepõhiselt määratava atribuudiga "appBase", sealjuures Tomcati vaikimisi peremees ehk "Host" on "localhost".

====Tomcati vahendid juurutamiseks====

Veebiaplikatsioonide juurutamine ja mahajuurutamine on võimalik ka kaughalduse teel tänu Tomcati internetipõhisele haldusrakendusele. Näiteks saab veebibrauserit kasutades teha serveri põhitoiminguid Tomcati enda HTML-põhise rakendusega "Tomcat Manager". Veebipõhine haldusrakendus töötab ka käsupõhise veebiteenusena, millele on valmis ehitatud Anti ja Maveni integratsioonid. Samuti eksisteerib käsurea kliendirakendus TCD (Tomcat Client Deployer). TCD ei kuulu Tomcati baaskoosseisu, kuid pakub peale serveri administreerimise tavatoimingute ka lisafunktsionaalsust nagu veebirakenduse kokkukompileerimine ja pakendamine. [http://tomcat.apache.org/tomcat-8.0-doc/manager-howto.html#Configuring_Manager_Application_Access 1]

====Haldurakendus "Tomcat Manager"====

Tomcati haldusrakendus "Tomcat Manager" (antud alamjaotuses lihtsalt haldusrakendus) on Tomcati enda veebiaplikatioon Tomcati brauseripõhiseks kaughalduseks, võimaldades muu hulgas järgnevat [http://tomcat.apache.org/tomcat-8.0-doc/manager-howto.html#Introduction 3]:
* Rakendada uue veebiaplikatsiooni war-faili üleslaadimisega;
* Näha kõiki rakendatud veebiaplikatsioone koos aktiivsete sessioonidega;
* Taasrakendada veebirakendust, näiteks veebiarhiivi pakitud klassifailide /WEB-INF/classes või teekide /WEB-INF/lib uuendamisel, kinnijooksmisel jms.;
* Peatada veebirakendust ilma serverist eemaldamata, samuti koos serverist eemaldamisega;
* Vaadata operatsioonisüsteemi ja Java parameetrite väärtusi;
* Näha kõiki saadaolevaid JNDI ressursse, k.a. andmebaasiühendusi, mis aitavad rakenduste programmeerijail defineerida <ResourceLink> elemendid web.xml konfiguratsioonifailis.

Tomcati installatsioon sisaldab haldusrakendust juba vaikimisi. Haldusrakenduse töölepanemiseks tuleb peremeesmasina konfiguratsioonikataloogi $CATALINA_BASE/conf/[enginename]/[hostname] lisada ka fail manager.xml. Vaikimisi valmiskonfigureeritud testrakendusel on see fail juba olemas asukohas $CATALINA_BASE/conf/Catalina/localhost/manager.xml . Rakendus asub vaikimisi aadressil http://[host]/manager/ , vaikimisi konfiguratsioone kasutades lahendub see asukohaks http://localhost:8080/manager/ . [http://tomcat.apache.org/tomcat-8.0-doc/manager-howto.html#Configuring_Manager_Application_Access 4]

====="Tomcat Manager" ligipääsu konfigureerimine=====

Vaikimisi on turvalisuspõhjustel ligipääs haldusrakendusele maha keeratud. Mismoodi täpselt kasutajatel ligipääsu võimaldada sõltub kasutatavast valdusest (realm). Vaikimisi defineerib $CATALINA_BASE/conf/server.xml valduseks "MemoryRealm". Vaikimisi loeb valdus "MemoryRealm" kasutajad failist $CATALINA_BASE/conf/tomcat-users.xml. Antud failis tuleb iga kasutaja defineerida omaette märgendiga <user>, mis näeb välja umbes järgmine [http://tomcat.apache.org/tomcat-8.0-doc/manager-howto.html#Configuring_Manager_Application_Access 8]:
<pre>
<user name="craig" password="secret" roles="manager-gui,manager-script" />
</pre>

Antud kasutajale on defineeritud korraga kaks rolli. Ligipääsu võimaldamiseks tulebki lihtsamal juhul kasutajatefailis $CATALINA_BASE/conf/tomcat-users.xml defineerida enda kasutaja. Kasutaja rolliks võib määrata näiteks "manager-gui", mis võimaldab ligipääsu kogu HTML liidese funktsionaalsusele.

Teised valdused on "JDBCRealm", mille puhul hoitakse kasutajatega seonduvat infot andmebaasis ja JNDIRealm, mille puhul kasutatakse lihtsustatud kataloogisirvimise protokolli (LDAP).
Lisaks saab haldusrakendusele keelata ligipääsu mujalt kui kindlaksmääratud IP-aadressidelt, lisades filtri "RemoteAddrValve" või "RemoteHostValve" konfigureerimisfaili manager.xml näiteks järgmiselt [http://tomcat.apache.org/tomcat-8.0-doc/manager-howto.html#Introduction 6]:
<pre>
<Context privileged="true">
<Valve className="org.apache.catalina.valves.RemoteAddrValve"
allow="127\.0\.0\.1"/>
</Context>
</pre>

=====Juurutamine ja mahavõtmine haldusrakendusega "Tomcat Manager"=====

Juurutamiseks lae kõigepealt veebiarhiivifail üles, kasutades esilehel asuvat sektsiooni "WAR file to deploy".
[[File:tomcat_manager_war_upload.png]]

Rakendus kuvatakse seejärel hallatavate rakenduste nimekirjas. Kui konteiner pole seadistatud üleslaetud aplikatsiooni kohe ka ise rakendama, tuleb vajutada "Start". Rakenduse peatamiseks kasuta "Stop", uuesti rakendamiseks "Redeploy" ja serverist eemaldamiseks "Undeploy".


[[File:tomcat_manager_apps_list.png|800px|Rakenduste nimekiri]]

==Näpunäiteid Tomcati reaalseks kasutamiseks==

===Juurutamise järjekord===

Tomcati käivitumisel juurutatakse aplikatsioonid sellises järjekorras:
# Konteinerisse kopeeritud kontekstikirjelduste järgi $CATALINA_BASE/conf/[EngineName]/[HostName]/[ApplicationName].xml ;
# Lahtipakitud rakendused "webapps" kataloogis;
# Pakitud rakenduste veebiarhiivid "webapps" kataloogis.

Seetõttu peaks käsitsi taasjuurutamisel kindluse mõttes eelnevalt kustutama rakenduse lahtipakitud dokumendipõhja kataloogi "webapps" kataloogist. Kontekstikirjelduse muutumisel tuleb jälgida, kas kirjeldus on juba kopeeritud serverisse ning vajadusel eelmise versiooni ümber muuta või kustutada.

===Reaalsele domeenile konfigureerimine===

Järgnevalt eeldame, et domeen ''www.minukodukas.ee'' on juba serverimasinaga seostatud. Et Tomcat hakkaks ka reaalselt Internetist tulevatele päringutele vastama, tuleb muuta failis $CATALINA_BASE/conf/server.xml konteinerile ''Catalina'' vastava teenusemärgendi sisu sarnaselt järgnevaga:

<pre>
<Service name="Catalina">
<Connector port="80" protocol="HTTP/1.1" connectionTimeout="20000" URIEncoding="UTF-8" redirectPort="8443" />
<Engine name="Catalina" defaultHost="www.minukodukas.ee">
<Host name="www.minukodukas.ee" appBase="webapps" unpackWARs="true" autoDeploy="false" deployOnStartup="false" xmlValidation="false" xmlNamespaceAware="false">
<Context path="" docBase="kodukas" debug="0" reloadable="true" />
</Host>
</Engine>
</Service>
</pre>

Ülal defineerime põhiliselt selle, et Tomcat kuulaks domeeni ''www.minukodukas.ee'' ja kasutaks HTTP päringute jaoks porti 80. Ühtlasti otsib Tomcat juurutatavat rakendust failist $CATALINA_BASE/webapps/kodukas.war. Kuna rajalisandiks on määratud tühi sõne (path=""), siis juurutataksegi aplikatsioon aadressile ''www.minukodukas.ee'' ilma rajalisandita (a'la ''www.minukodukas.ee/wiki''). Seetõttu pakitakse ka veebiarhiiv tegelikult lahti kataloogi $CATALINA_BASE/webapps/ROOT mitte kataloogi $CATALINA_BASE/webapps/kodukas nagu võiks eeldada.

===Käigultvahetus===

Võimaldamaks käigultvahetust (hot deployment) peab konteineri konfiguratsioonifailis $CATALINA_BASE/conf/server.xml olema peremehepõhise märgendi "Host" atribuudi "autoDeploy" väärtus "true". Sel juhul installeerib ja uuendab Tomcat aplikatsioone dünaamiliselt töötamise ajal. Kui väärtuseks on "false", käib installeerimine staatiliselt ning serverisse juurutamiseks tuleb teha konteineri taaskäivitus. Käigultvahetust saab määrata ka peremehe defineerimisel "Host Manager" rakendusega, mis on kättesaadav aadressil http://localhost:8080/host-manager/html . Kasutamiseks tuleb lisada oma kasutajale rolli "admin-gui" (vt. alajaotus ""Tomcat Manager" ligipääsu konfigureerimine").

[[File:host_manager_app.png]]

Käigultvahetust päästikuks on vaikimisi uuendatud veebiarhiivifaili või lahtipakitud veebirakenduse paigutamine "webapps" kataloogi. Käigultvahetuse päästikutele võib failis $CATALINA_BASE/conf/server.xml ka ise lisada kuulatavaid ressursse nagu web.xml muutmine või mõne teegifaili vahetamine (märgendis "Host").

===Klassiteekide väljatõstmine veebiarhiivifailist===

Kõik konteksti poolt kasutatavad Java klassiteegid võib pakendada veebiarhiivi sisse kataloogi "lib", kuid nii võib osutuda veebiarhiivi üleslaadimine ajakulukaks, eriti arenduskeskkonnas. Kui ei teki ohtu, et erinevad rakendused kasutavad sama teegi erinevaid versioone, siis on vahel parem lisada osa teeke konteineri kataloogi $CATALINA_BASE/libs, kust need tehakse siis konteineri poolt kättesaadavaks kõigile konteineris jooksutatavatele kontekstidele. Nii võib vähendada veebiarhiivi faili suurust märgatavalt, mis tõstab kokkuvõttes juurutamiskiirust ja ühes sellega programmeerijate tööviljakust.

===Mälukasutus===

Konteineri poolt kasutatavat mälu saab vaadata haldusrakendusest vajutades lingile "Server Status". Mälukasutus on toodud jaotuses "JVM", kus näidatakse nii maksimaalselt kättesaadavat mälu kui ka parasjagu reserveeritud mälu.

<pre>Free memory: 41.16 MB Total memory: 123.37 MB Max memory: 1027.56 MB</pre>

Mälu suurendamiseks võib näiteks defineerida skriptis $CATALINA_BASE/bin/catalina.sh muutuja "JAVA_OPTS" ning määrata Java mälukasutuse miinimum- ja maksimumväärtused sarnaselt järgnevatega [http://www.mkyong.com/tomcat/tomcat-javalangoutofmemoryerror-permgen-space/ 5]:
<pre>
JAVA_OPTS="-Xms1536m -Xmx1536m -XX:NewSize=256m -XX:MaxNewSize=256m -XX:PermSize=256m -XX:MaxPermSize=256m"
</pre>

===Logifailid===

Vaikimisi defineerib Tomcat failiga $CATALINA_BASE/conf/logging.properties viis logerit, mis tekitavad viis eraldi logifaili.

{| style="background:#cccc99;color:black;width:80%;" border="1" cellpadding="5" cellspacing="0" align="center"
|+ Tomcati tekitatavad logifailid "logs" kataloogis
!Fail !! Kasutus
|- style="background:white; color:black"
| style="width:300px" |catalina.out
| Tomcati käivitus- ja peatamisskriptide väljund, samuti juurutatud rakenduste prindilaused System.out ja veaväljundid System.err
|- style="background:white; color:black"
| style="width:300px" |catalina.[yyyy]-[mm]-[dd].log
| Pööratud (rotated) logifail catalina.out
|- style="background:white; color:black"
| style="width:300px" |host-manager.[yyyy]-[mm]-[dd].log
| Logi peremehehalduse rakendusele (rakendus on kättesaadav kohalikust masinast aadressil http://localhost:8080/host-manager/html )
|- style="background:white; color:black"
| style="width:300px" |localhost.[yyyy]-[mm]-[dd].log
| Peremehe "localhost" logi; mitme virtuaalse peremehe korral tekitatakse igale peremehele oma logi
|- style="background:white; color:black"
| style="width:300px" |localhost_access_log.[yyyy]-[mm]-[dd].txt
| Konteinerisse Internetist saabunud päringute logi
|- style="background:white; color:black"
| style="width:300px" |manager.[yyyy]-[mm]-[dd].log
| Haldusrakenduse tegevuste logi
|}

===Viiteid===

Palju vajalikku võib leida [http://tomcat.apache.org/tomcat-8.0-doc/index.html Tomcat 8 dokumentatsioonist]

Lisaks üks viide põhjalikule Tomcati versioon seitsme ülevaatele: http://www.ntu.edu.sg/home/ehchua/programming/howto/Tomcat_More.html

= Kasutatud materjalid =

*http://tomcat.apache.org/tomcat-8.0-doc/index.html
*http://www.mulesoft.com/tomcat-deploy-procedures
*http://www.mkyong.com/tomcat/tomcat-javalangoutofmemoryerror-permgen-space/

[[Category: Operatsioonisüsteemide administreerimine ja sidumine]]

Tomcat

2014-01-02T21:39:47Z

Kveskima: /* "Tomcat Manager" ligipääsu konfigureerimine */

==Autor==

Kristjan Veskimäe D32

2013

==Sissejuhatus==

Tomcat on vabalt kättesaadav server Java veebirakendustele. Põhimõtteliselt on tegemist Servlet/JSP spetsifikatsiooni toetava konteineriga. Kiire käivitumise ning rakenduste käigultvahetuse tõttu on Tomcat hea valik väiksemate ning keskmise suurusega Java veebirakenduste käitamiseks.

Antud töö kirjeldab Tomcati 8. versiooni. Põhiosa on üldiselt samasugune võrreldes paari eelmise versiooniga. Suuremad erinevused on versioonispetsiifilistes probleemides ja nende lahendamises, mida käesolev töö ei vaatle.

Töö vaatleb Tomcati paigaldamist ja seadistamist Unix-laadsesse keskkonda ning eeldab lugejalt algteadmisi sarnastes süsteemides. Tomcati on võimalik paigaldada ka Windows-keskkonda, kuid antud veebiserver eeldab kasutaja poolt käsureal töötamist ning Tomcati failihierarhias orienteerumist. Põhimõtteliselt on Java veebirakenduste arendamiseks IDE-abil võimalik siiski ka kasutada IDE-sse integreeritud Tomcati serverit - näiteks pakuvad sellist võimalust Eclipse EE ja NetBeans - kuid seda käesolev töö ei vaatle.

==Mõisted==

* '''Kontekst''' (context) - Tomcati mõistes üks konkreetne veebiaplikatsioon
* '''Konteiner''' (container) - veebiserver Tomcat ise
* '''Kontekstikirjeldus''' (context descriptor) - Tomcati-spetsiifiline konteksti konfiguratsioonimääratlus; peremehepõhine osa loetakse failist $CATALINA_HOME/conf/[enginename]/[hostname]/context.xml ja sellele lisatakse kontekstispetsiifilised täpsustused failist $CATALINA_BASE/conf/[enginename]/[hostname]/[webappname].xml; kontekstikirjeldus määrab näiteks nimed ressurssidele, sessioonihalduse parameetrid jmt. (olgu märgitud, et Tomcati varasemates versioonides sisaldusid kontekstikirjeldused põhikonfiguratsioonifailis server.xml)
* '''Dokumendipõhi''' (docBase) - kontekstile vastav kataloog Tomcati "webapps" kataloogis, mis tekib veebiaplikatsiooni serverisse rakendamisel
* '''Veebiarhiiv''' (Web application ARchive, war-file) - Java veebiaplikatsiooni jagatakse hea tava kohaselt selle üheainsa veebiarhiivi failina, mille laienditüübiks on "war". Tegemist on zip-protokolliga kokkupakitud kataloogiga, millel on Java veebirakenduste spetsifikatsioonile vastav ülesehitus. Siiski võib veebiaplikatsioon olla juurutamisel ka lahtipakendatud olekus (inglisekeelne termin on "war is exploded").

==Ülesehitus==

{| class="wikitable"
|+Kataloogid
|-
|style="color: green;" | $CATALINA_HOME
|baaskataloog, kuhu on Tomcat paigutatud
|-
|style="color: green;" | $CATALINA_BASE
|parasjagu töösoleva Tomcati eksemplari baaskataloog, mille alusel lahendatakse teed ülejäänud kataloogide ja failideni; ainult ühe kasutusel oleva Tomcati eksemplari puhul on see sama, mis $CATALINA_HOME

|-
|style="color: green;" | $CATALINA_BASE/bin
|serveri käivitus- ja abiskriptid
|-
|style="color: green;" | $CATALINA_BASE/conf
|konfiguratsioonifailid
|-
|style="color: green;" | $CATALINA_BASE/lib
|Tomcatile vaikimisi kättesaadavad Java klassiteegid (class libraries) ehk .jar-failid kuhu on Java kompileeritud kood kokku pakendatud
|-
|style="color: green;" | $CATALINA_BASE/logs
|logifailid paigutatakse vaikimisi siia
|-
|style="color: green;" | $CATALINA_BASE/webapps
|kataloog, kuhu paigutatakse serverisse juurutatavad veebiaplikatsioonid

|}

{| class="wikitable"
|+Mõned olulisemad failid
|-
|style="color: green;" | $CATALINA_BASE/bin/startup.sh
|serveri käivitusskript
|-
|style="color: green;" | $CATALINA_BASE/bin/shutdown.sh
|serveri peatusskript

|-
|style="color: green;" | $CATALINA_BASE/conf/server.xml
| konteineri peamine konfiguratsioonifail
|-
|style="color: green;" | $CATALINA_BASE/conf/[enginename]/[hostname]/[webappname].xml
|serveri administraatori jaoks konteinerisse endasse ümber kopeeritud rakendusepõhine kontekstikirjelduse konfiguratsioon failist $CATALINA_BASE/webapps/[ApplicationName]/META-INF/context.xml
|-
|style="color: green;" | $CATALINA_BASE/conf/[enginename]/[hostname]/context.xml
| fail, mis aitab administraatoril konteksti kohta käivat infot kirjeldada peremeesmasina-põhiselt ja halduseks mõeldud automaat-tööriistadel (näiteks Tomcat Manager ja TCD) oma tööd teha
|-
|style="color: green;" | $CATALINA_BASE/$CATALINA_BASE/conf/[enginename]/[hostname]/manager.xml
|fail, mis võimaldab lisada rakendustele ligipääsufiltreid
|-
|style="color: green;" | $CATALINA_BASE/webapps/[webappname]/META-INF/context.xml
|kontekstikirjeldusfail, mille veebirakenduse programmeerija on pakendanud oma aplikatsiooniga kaasa ning millega ta saab võimaluse kontekstikirjeldust omalt poolt mõjutada; kirjutatakse rakenduse uuestijuurutamisel üle, mistõttu administraator peaks muutma selle asemel konteinerisse ümber kopeeritud püsieksemplari $CATALINA_BASE/conf/[enginename]/[hostname]/context.xml
|-
|style="color: green;" | $CATALINA_BASE/webapps/[webappname]/WEB-INF/web.xml
|ka üks oluline Java veebiaplikatsiooni konfiguratsioonifail, mille pakendatakse koos veebiarhiiviga; enamasti muudab seda ainult programeerija; määrab muu hulgas millised aplikatsiooni osad vajavad autentimist või kui kiiresti veebisessioon aegub
|}

==Installeerimine==

===Installeerimine paketihalduriga===

<pre>
apt-cache search tomcat
apt-get install tomcat[version]-webapps
apt-get install tomcat[version]-admin
apt-get install tomcat[version]
</pre>

===Installeerimine käsitsi===

Paketihalduriga installeerides ei pruugi viimane Tomcati versioon olla kättesaadav ja see pakub ka vähem võimalusi kataloogide määramiseks jms. Käsitsi installeerimiseks tuleb laadida Tomcat kodulehelt alla. Lahtipakkimisel tekib kataloog, milles sisalduv fail "RUNNING.txt" on kõige kindlam allikas installeerimisel tekkivate probleemide vältimiseks ning lahendamiseks.

Vajaliku versiooni installeerimisfaili asukoha saab vaadata Tomcati kodulehelt sektsioonist "Download". Järgnevas näites installeerime Tomcati kõige uuema ebastabiilse kandidaatversiooni, mida näitab nimes sisalduv RC ehk "release candidate". Produktsioonikeskkonda tuleks siiski valida stabiilse versiooni. Käsitsi installeerimine on sarnane järgmisega:
<pre>
wget http://mirror.nexcess.net/apache/tomcat/tomcat-8/v8.0.0-RC5/bin/apache-tomcat-8.0.0-RC5.tar.gz
tar -zxvf apache-tomcat-8.0.0-RC5.tar.gz
mv /Users/kristjanveskimae/downloads/apache-tomcat-8.0.0-RC5 /usr/local/apache-tomcat-8.0.0-RC5
rm -f /Library/Tomcat
ln -s /usr/local/apache-tomcat-8.0.0-RC5/ /Library/Tomcat
chown -R kristjanveskimae /Library/Tomcat
chmod +x /Library/Tomcat/bin/*.sh
</pre>

==Käivitamine ja aplikatsiooni juurutamine==

===Konteineri käivitamine===

Tomcati käivitamise eelduseks on Java paigaldamine masinasse ning keskkonnamuutujate "JAVA_HOME" ja "JRE_HOME" defineerimine. Peale installeerimist võib kasutada skripte kataloogist $CATALINA_BASE/bin . Järgneb üks võimalik käivitamise ja peatamise näide, mis on kasutatav eelnevalt kirjeldatud käsitsi installeerimise juhul:
<pre>
/Library/Tomcat/bin/startup.sh
</pre>
ja peatamiseks
<pre>
/Library/Tomcat/bin/shutdown.sh
</pre>

===Näiteaplikatsiooni juurutamine===

Java veebiaplikatsiooni jagatakse hea tava kohaselt üheainsa veebiarhiivi failina. Siiski võib Tomcati juurutada ka lahtipakendatud olekus ("exploded") Java veebiaplikatsiooni.

====Käsitsi juurutamine ja mahavõtmine====

Näiteaplikatsiooni juurutamiseks lae selle veebiarhiivifail alla ning kopeeri oma konteineri juurutamiskataloogi 'webapps':
<pre>wget http://tomcat.apache.org/tomcat-8.0-doc/appdev/sample/sample.war
cp /Users/kristjanveskimae/downloads/sample.war /Library/Tomcat/webapps/sample.war</pre>

Kui konfiguratsioonifailis $CATALINA_BASE/conf/server.xml on märgendi "Host" atribuudi "autoDeploy" väärtus "true", installeerib ja uuendab Tomcat aplikatsioone dünaamiliselt töötamise ajal. Kui väärtuseks on "false", käib installeerimine staatiliselt ning serverisse juurutamiseks tuleb teha konteineri taaskäivitus. [http://tomcat.apache.org/tomcat-8.0-doc/manager-howto.html#Deploy_A_New_Application_from_a_Local_Path 2] Mõlemal juhul pakib konteiner arhiveeritud faili ise lahti samasse kausta $CATALINA_BASE/webapps ning ka juurutab selle. Tekkiv aplikatsioon on lokaalsest masinast seejärel kättesaadav aadressil http://localhost:8080/sample/ .

[[File:sample_app.png|400px]]

Veebirakenduse käsitsi mahavõtmiseks tuleb kustutada talle vastav dokumendipõhja kataloog "webapps" kataloogist. Samuti tuleks kustutada .war-fail olemaks kindel, et Tomcat ei rakenda uuel käivitamisel veebiaplikatsiooni veebiarhiivifailist. Veelgi lihtsam on mahavõtmine brauseriga haldusrakenduse kaudu.

Rakenduste baaskataloogi "webapps" asukohta saab muuta failis $CATALINA_BASE/conf/server.xml peremehepõhiselt määratava atribuudiga "appBase", sealjuures Tomcati vaikimisi peremees ehk "Host" on "localhost".

====Tomcati vahendid juurutamiseks====

Veebiaplikatsioonide juurutamine ja mahajuurutamine on võimalik ka kaughalduse teel tänu Tomcati internetipõhisele haldusrakendusele. Näiteks saab veebibrauserit kasutades teha serveri põhitoiminguid Tomcati enda HTML-põhise rakendusega "Tomcat Manager". Veebipõhine haldusrakendus töötab ka käsupõhise veebiteenusena, millele on valmis ehitatud Anti ja Maveni integratsioonid. Samuti eksisteerib käsurea kliendirakendus TCD (Tomcat Client Deployer). TCD ei kuulu Tomcati baaskoosseisu, kuid pakub peale serveri administreerimise tavatoimingute ka lisafunktsionaalsust nagu veebirakenduse kokkukompileerimine ja pakendamine. [http://tomcat.apache.org/tomcat-8.0-doc/manager-howto.html#Configuring_Manager_Application_Access 1]

====Haldurakendus "Tomcat Manager"====

Tomcati haldusrakendus "Tomcat Manager" (antud alamjaotuses lihtsalt haldusrakendus) on Tomcati enda veebiaplikatioon Tomcati brauseripõhiseks kaughalduseks, võimaldades muu hulgas järgnevat [http://tomcat.apache.org/tomcat-8.0-doc/manager-howto.html#Introduction 3]:
* Rakendada uue veebiaplikatsiooni war-faili üleslaadimisega;
* Näha kõiki rakendatud veebiaplikatsioone koos aktiivsete sessioonidega;
* Taasrakendada veebirakendust, näiteks veebiarhiivi pakitud klassifailide /WEB-INF/classes või teekide /WEB-INF/lib uuendamisel, kinnijooksmisel jms.;
* Peatada veebirakendust ilma serverist eemaldamata, samuti koos serverist eemaldamisega;
* Vaadata operatsioonisüsteemi ja Java parameetrite väärtusi;
* Näha kõiki saadaolevaid JNDI ressursse, k.a. andmebaasiühendusi, mis aitavad rakenduste programmeerijail defineerida <ResourceLink> elemendid web.xml konfiguratsioonifailis.

Tomcati installatsioon sisaldab haldusrakendust juba vaikimisi. Haldusrakenduse töölepanemiseks tuleb peremeesmasina konfiguratsioonikataloogi $CATALINA_BASE/conf/[enginename]/[hostname] lisada ka fail manager.xml. Vaikimisi valmiskonfigureeritud testrakendusel on see fail juba olemas asukohas $CATALINA_BASE/conf/Catalina/localhost/manager.xml . Rakendus asub vaikimisi aadressil http://[host]/manager/ , vaikimisi konfiguratsioone kasutades lahendub see asukohaks http://localhost:8080/manager/ . [http://tomcat.apache.org/tomcat-8.0-doc/manager-howto.html#Configuring_Manager_Application_Access 4]

====="Tomcat Manager" ligipääsu konfigureerimine=====

Vaikimisi on turvalisuspõhjustel ligipääs haldusrakendusele maha keeratud. Mismoodi täpselt kasutajatel ligipääsu võimaldada sõltub kasutatavast valdusest (realm). Vaikimisi defineerib $CATALINA_BASE/conf/server.xml valduseks "MemoryRealm". Vaikimisi loeb valdus "MemoryRealm" kasutajad failist $CATALINA_BASE/conf/tomcat-users.xml. Antud failis tuleb iga kasutaja defineerida omaette märgendiga <user>, mis näeb välja umbes järgmine:
<pre>
<user name="craig" password="secret" roles="manager-gui,manager-script" />
</pre>

Antud kasutajale on defineeritud korraga kaks rolli. Ligipääsu võimaldamiseks tulebki lihtsamal juhul kasutajatefailis $CATALINA_BASE/conf/tomcat-users.xml defineerida enda kasutaja. Kasutaja rolliks võib määrata näiteks "manager-gui", mis võimaldab ligipääsu kogu HTML liidese funktsionaalsusele.

Teised valdused on "JDBCRealm", mille puhul hoitakse kasutajatega seonduvat infot andmebaasis ja JNDIRealm, mille puhul kasutatakse lihtsustatud kataloogisirvimise protokolli (LDAP).
Lisaks saab haldusrakendusele keelata ligipääsu mujalt kui kindlaksmääratud IP-aadressidelt, lisades filtri "RemoteAddrValve" või "RemoteHostValve" konfigureerimisfaili manager.xml näiteks järgmiselt [http://tomcat.apache.org/tomcat-8.0-doc/manager-howto.html#Introduction 6]:
<pre>
<Context privileged="true">
<Valve className="org.apache.catalina.valves.RemoteAddrValve"
allow="127\.0\.0\.1"/>
</Context>
</pre>

=====Juurutamine ja mahavõtmine haldusrakendusega "Tomcat Manager"=====

Juurutamiseks lae kõigepealt veebiarhiivifail üles, kasutades esilehel asuvat sektsiooni "WAR file to deploy".
[[File:tomcat_manager_war_upload.png]]

Rakendus kuvatakse seejärel hallatavate rakenduste nimekirjas. Kui konteiner pole seadistatud üleslaetud aplikatsiooni kohe ka ise rakendama, tuleb vajutada "Start". Rakenduse peatamiseks kasuta "Stop", uuesti rakendamiseks "Redeploy" ja serverist eemaldamiseks "Undeploy".


[[File:tomcat_manager_apps_list.png|800px|Rakenduste nimekiri]]

==Näpunäiteid Tomcati reaalseks kasutamiseks==

===Juurutamise järjekord===

Tomcati käivitumisel juurutatakse aplikatsioonid sellises järjekorras:
# Konteinerisse kopeeritud kontekstikirjelduste järgi $CATALINA_BASE/conf/[EngineName]/[HostName]/[ApplicationName].xml ;
# Lahtipakitud rakendused "webapps" kataloogis;
# Pakitud rakenduste veebiarhiivid "webapps" kataloogis.

Seetõttu peaks käsitsi taasjuurutamisel kindluse mõttes eelnevalt kustutama rakenduse lahtipakitud dokumendipõhja kataloogi "webapps" kataloogist. Kontekstikirjelduse muutumisel tuleb jälgida, kas kirjeldus on juba kopeeritud serverisse ning vajadusel eelmise versiooni ümber muuta või kustutada.

===Reaalsele domeenile konfigureerimine===

Järgnevalt eeldame, et domeen ''www.minukodukas.ee'' on juba serverimasinaga seostatud. Et Tomcat hakkaks ka reaalselt Internetist tulevatele päringutele vastama, tuleb muuta failis $CATALINA_BASE/conf/server.xml konteinerile ''Catalina'' vastava teenusemärgendi sisu sarnaselt järgnevaga:

<pre>
<Service name="Catalina">
<Connector port="80" protocol="HTTP/1.1" connectionTimeout="20000" URIEncoding="UTF-8" redirectPort="8443" />
<Engine name="Catalina" defaultHost="www.minukodukas.ee">
<Host name="www.minukodukas.ee" appBase="webapps" unpackWARs="true" autoDeploy="false" deployOnStartup="false" xmlValidation="false" xmlNamespaceAware="false">
<Context path="" docBase="kodukas" debug="0" reloadable="true" />
</Host>
</Engine>
</Service>
</pre>

Ülal defineerime põhiliselt selle, et Tomcat kuulaks domeeni ''www.minukodukas.ee'' ja kasutaks HTTP päringute jaoks porti 80. Ühtlasti otsib Tomcat juurutatavat rakendust failist $CATALINA_BASE/webapps/kodukas.war. Kuna rajalisandiks on määratud tühi sõne (path=""), siis juurutataksegi aplikatsioon aadressile ''www.minukodukas.ee'' ilma rajalisandita (a'la ''www.minukodukas.ee/wiki''). Seetõttu pakitakse ka veebiarhiiv tegelikult lahti kataloogi $CATALINA_BASE/webapps/ROOT mitte kataloogi $CATALINA_BASE/webapps/kodukas nagu võiks eeldada.

===Käigultvahetus===

Võimaldamaks käigultvahetust (hot deployment) peab konteineri konfiguratsioonifailis $CATALINA_BASE/conf/server.xml olema peremehepõhise märgendi "Host" atribuudi "autoDeploy" väärtus "true". Sel juhul installeerib ja uuendab Tomcat aplikatsioone dünaamiliselt töötamise ajal. Kui väärtuseks on "false", käib installeerimine staatiliselt ning serverisse juurutamiseks tuleb teha konteineri taaskäivitus. Käigultvahetust saab määrata ka peremehe defineerimisel "Host Manager" rakendusega, mis on kättesaadav aadressil http://localhost:8080/host-manager/html . Kasutamiseks tuleb lisada oma kasutajale rolli "admin-gui" (vt. alajaotus ""Tomcat Manager" ligipääsu konfigureerimine").

[[File:host_manager_app.png]]

Käigultvahetust päästikuks on vaikimisi uuendatud veebiarhiivifaili või lahtipakitud veebirakenduse paigutamine "webapps" kataloogi. Käigultvahetuse päästikutele võib failis $CATALINA_BASE/conf/server.xml ka ise lisada kuulatavaid ressursse nagu web.xml muutmine või mõne teegifaili vahetamine (märgendis "Host").

===Klassiteekide väljatõstmine veebiarhiivifailist===

Kõik konteksti poolt kasutatavad Java klassiteegid võib pakendada veebiarhiivi sisse kataloogi "lib", kuid nii võib osutuda veebiarhiivi üleslaadimine ajakulukaks, eriti arenduskeskkonnas. Kui ei teki ohtu, et erinevad rakendused kasutavad sama teegi erinevaid versioone, siis on vahel parem lisada osa teeke konteineri kataloogi $CATALINA_BASE/libs, kust need tehakse siis konteineri poolt kättesaadavaks kõigile konteineris jooksutatavatele kontekstidele. Nii võib vähendada veebiarhiivi faili suurust märgatavalt, mis tõstab kokkuvõttes juurutamiskiirust ja ühes sellega programmeerijate tööviljakust.

===Mälukasutus===

Konteineri poolt kasutatavat mälu saab vaadata haldusrakendusest vajutades lingile "Server Status". Mälukasutus on toodud jaotuses "JVM", kus näidatakse nii maksimaalselt kättesaadavat mälu kui ka parasjagu reserveeritud mälu.

<pre>Free memory: 41.16 MB Total memory: 123.37 MB Max memory: 1027.56 MB</pre>

Mälu suurendamiseks võib näiteks defineerida skriptis $CATALINA_BASE/bin/catalina.sh muutuja "JAVA_OPTS" ning määrata Java mälukasutuse miinimum- ja maksimumväärtused sarnaselt järgnevatega [http://www.mkyong.com/tomcat/tomcat-javalangoutofmemoryerror-permgen-space/ 5]:
<pre>
JAVA_OPTS="-Xms1536m -Xmx1536m -XX:NewSize=256m -XX:MaxNewSize=256m -XX:PermSize=256m -XX:MaxPermSize=256m"
</pre>

===Logifailid===

Vaikimisi defineerib Tomcat failiga $CATALINA_BASE/conf/logging.properties viis logerit, mis tekitavad viis eraldi logifaili.

{| style="background:#cccc99;color:black;width:80%;" border="1" cellpadding="5" cellspacing="0" align="center"
|+ Tomcati tekitatavad logifailid "logs" kataloogis
!Fail !! Kasutus
|- style="background:white; color:black"
| style="width:300px" |catalina.out
| Tomcati käivitus- ja peatamisskriptide väljund, samuti juurutatud rakenduste prindilaused System.out ja veaväljundid System.err
|- style="background:white; color:black"
| style="width:300px" |catalina.[yyyy]-[mm]-[dd].log
| Pööratud (rotated) logifail catalina.out
|- style="background:white; color:black"
| style="width:300px" |host-manager.[yyyy]-[mm]-[dd].log
| Logi peremehehalduse rakendusele (rakendus on kättesaadav kohalikust masinast aadressil http://localhost:8080/host-manager/html )
|- style="background:white; color:black"
| style="width:300px" |localhost.[yyyy]-[mm]-[dd].log
| Peremehe "localhost" logi; mitme virtuaalse peremehe korral tekitatakse igale peremehele oma logi
|- style="background:white; color:black"
| style="width:300px" |localhost_access_log.[yyyy]-[mm]-[dd].txt
| Konteinerisse Internetist saabunud päringute logi
|- style="background:white; color:black"
| style="width:300px" |manager.[yyyy]-[mm]-[dd].log
| Haldusrakenduse tegevuste logi
|}

===Viiteid===

Palju vajalikku võib leida [http://tomcat.apache.org/tomcat-8.0-doc/index.html Tomcat 8 dokumentatsioonist]

Lisaks üks viide põhjalikule Tomcati versioon seitsme ülevaatele: http://www.ntu.edu.sg/home/ehchua/programming/howto/Tomcat_More.html

= Kasutatud materjalid =

*http://tomcat.apache.org/tomcat-8.0-doc/index.html
*http://www.mulesoft.com/tomcat-deploy-procedures
*http://www.mkyong.com/tomcat/tomcat-javalangoutofmemoryerror-permgen-space/

[[Category: Operatsioonisüsteemide administreerimine ja sidumine]]

Tomcat

2014-01-02T21:37:51Z

Kveskima: /* Mälukasutus */

==Autor==

Kristjan Veskimäe D32

2013

==Sissejuhatus==

Tomcat on vabalt kättesaadav server Java veebirakendustele. Põhimõtteliselt on tegemist Servlet/JSP spetsifikatsiooni toetava konteineriga. Kiire käivitumise ning rakenduste käigultvahetuse tõttu on Tomcat hea valik väiksemate ning keskmise suurusega Java veebirakenduste käitamiseks.

Antud töö kirjeldab Tomcati 8. versiooni. Põhiosa on üldiselt samasugune võrreldes paari eelmise versiooniga. Suuremad erinevused on versioonispetsiifilistes probleemides ja nende lahendamises, mida käesolev töö ei vaatle.

Töö vaatleb Tomcati paigaldamist ja seadistamist Unix-laadsesse keskkonda ning eeldab lugejalt algteadmisi sarnastes süsteemides. Tomcati on võimalik paigaldada ka Windows-keskkonda, kuid antud veebiserver eeldab kasutaja poolt käsureal töötamist ning Tomcati failihierarhias orienteerumist. Põhimõtteliselt on Java veebirakenduste arendamiseks IDE-abil võimalik siiski ka kasutada IDE-sse integreeritud Tomcati serverit - näiteks pakuvad sellist võimalust Eclipse EE ja NetBeans - kuid seda käesolev töö ei vaatle.

==Mõisted==

* '''Kontekst''' (context) - Tomcati mõistes üks konkreetne veebiaplikatsioon
* '''Konteiner''' (container) - veebiserver Tomcat ise
* '''Kontekstikirjeldus''' (context descriptor) - Tomcati-spetsiifiline konteksti konfiguratsioonimääratlus; peremehepõhine osa loetakse failist $CATALINA_HOME/conf/[enginename]/[hostname]/context.xml ja sellele lisatakse kontekstispetsiifilised täpsustused failist $CATALINA_BASE/conf/[enginename]/[hostname]/[webappname].xml; kontekstikirjeldus määrab näiteks nimed ressurssidele, sessioonihalduse parameetrid jmt. (olgu märgitud, et Tomcati varasemates versioonides sisaldusid kontekstikirjeldused põhikonfiguratsioonifailis server.xml)
* '''Dokumendipõhi''' (docBase) - kontekstile vastav kataloog Tomcati "webapps" kataloogis, mis tekib veebiaplikatsiooni serverisse rakendamisel
* '''Veebiarhiiv''' (Web application ARchive, war-file) - Java veebiaplikatsiooni jagatakse hea tava kohaselt selle üheainsa veebiarhiivi failina, mille laienditüübiks on "war". Tegemist on zip-protokolliga kokkupakitud kataloogiga, millel on Java veebirakenduste spetsifikatsioonile vastav ülesehitus. Siiski võib veebiaplikatsioon olla juurutamisel ka lahtipakendatud olekus (inglisekeelne termin on "war is exploded").

==Ülesehitus==

{| class="wikitable"
|+Kataloogid
|-
|style="color: green;" | $CATALINA_HOME
|baaskataloog, kuhu on Tomcat paigutatud
|-
|style="color: green;" | $CATALINA_BASE
|parasjagu töösoleva Tomcati eksemplari baaskataloog, mille alusel lahendatakse teed ülejäänud kataloogide ja failideni; ainult ühe kasutusel oleva Tomcati eksemplari puhul on see sama, mis $CATALINA_HOME

|-
|style="color: green;" | $CATALINA_BASE/bin
|serveri käivitus- ja abiskriptid
|-
|style="color: green;" | $CATALINA_BASE/conf
|konfiguratsioonifailid
|-
|style="color: green;" | $CATALINA_BASE/lib
|Tomcatile vaikimisi kättesaadavad Java klassiteegid (class libraries) ehk .jar-failid kuhu on Java kompileeritud kood kokku pakendatud
|-
|style="color: green;" | $CATALINA_BASE/logs
|logifailid paigutatakse vaikimisi siia
|-
|style="color: green;" | $CATALINA_BASE/webapps
|kataloog, kuhu paigutatakse serverisse juurutatavad veebiaplikatsioonid

|}

{| class="wikitable"
|+Mõned olulisemad failid
|-
|style="color: green;" | $CATALINA_BASE/bin/startup.sh
|serveri käivitusskript
|-
|style="color: green;" | $CATALINA_BASE/bin/shutdown.sh
|serveri peatusskript

|-
|style="color: green;" | $CATALINA_BASE/conf/server.xml
| konteineri peamine konfiguratsioonifail
|-
|style="color: green;" | $CATALINA_BASE/conf/[enginename]/[hostname]/[webappname].xml
|serveri administraatori jaoks konteinerisse endasse ümber kopeeritud rakendusepõhine kontekstikirjelduse konfiguratsioon failist $CATALINA_BASE/webapps/[ApplicationName]/META-INF/context.xml
|-
|style="color: green;" | $CATALINA_BASE/conf/[enginename]/[hostname]/context.xml
| fail, mis aitab administraatoril konteksti kohta käivat infot kirjeldada peremeesmasina-põhiselt ja halduseks mõeldud automaat-tööriistadel (näiteks Tomcat Manager ja TCD) oma tööd teha
|-
|style="color: green;" | $CATALINA_BASE/$CATALINA_BASE/conf/[enginename]/[hostname]/manager.xml
|fail, mis võimaldab lisada rakendustele ligipääsufiltreid
|-
|style="color: green;" | $CATALINA_BASE/webapps/[webappname]/META-INF/context.xml
|kontekstikirjeldusfail, mille veebirakenduse programmeerija on pakendanud oma aplikatsiooniga kaasa ning millega ta saab võimaluse kontekstikirjeldust omalt poolt mõjutada; kirjutatakse rakenduse uuestijuurutamisel üle, mistõttu administraator peaks muutma selle asemel konteinerisse ümber kopeeritud püsieksemplari $CATALINA_BASE/conf/[enginename]/[hostname]/context.xml
|-
|style="color: green;" | $CATALINA_BASE/webapps/[webappname]/WEB-INF/web.xml
|ka üks oluline Java veebiaplikatsiooni konfiguratsioonifail, mille pakendatakse koos veebiarhiiviga; enamasti muudab seda ainult programeerija; määrab muu hulgas millised aplikatsiooni osad vajavad autentimist või kui kiiresti veebisessioon aegub
|}

==Installeerimine==

===Installeerimine paketihalduriga===

<pre>
apt-cache search tomcat
apt-get install tomcat[version]-webapps
apt-get install tomcat[version]-admin
apt-get install tomcat[version]
</pre>

===Installeerimine käsitsi===

Paketihalduriga installeerides ei pruugi viimane Tomcati versioon olla kättesaadav ja see pakub ka vähem võimalusi kataloogide määramiseks jms. Käsitsi installeerimiseks tuleb laadida Tomcat kodulehelt alla. Lahtipakkimisel tekib kataloog, milles sisalduv fail "RUNNING.txt" on kõige kindlam allikas installeerimisel tekkivate probleemide vältimiseks ning lahendamiseks.

Vajaliku versiooni installeerimisfaili asukoha saab vaadata Tomcati kodulehelt sektsioonist "Download". Järgnevas näites installeerime Tomcati kõige uuema ebastabiilse kandidaatversiooni, mida näitab nimes sisalduv RC ehk "release candidate". Produktsioonikeskkonda tuleks siiski valida stabiilse versiooni. Käsitsi installeerimine on sarnane järgmisega:
<pre>
wget http://mirror.nexcess.net/apache/tomcat/tomcat-8/v8.0.0-RC5/bin/apache-tomcat-8.0.0-RC5.tar.gz
tar -zxvf apache-tomcat-8.0.0-RC5.tar.gz
mv /Users/kristjanveskimae/downloads/apache-tomcat-8.0.0-RC5 /usr/local/apache-tomcat-8.0.0-RC5
rm -f /Library/Tomcat
ln -s /usr/local/apache-tomcat-8.0.0-RC5/ /Library/Tomcat
chown -R kristjanveskimae /Library/Tomcat
chmod +x /Library/Tomcat/bin/*.sh
</pre>

==Käivitamine ja aplikatsiooni juurutamine==

===Konteineri käivitamine===

Tomcati käivitamise eelduseks on Java paigaldamine masinasse ning keskkonnamuutujate "JAVA_HOME" ja "JRE_HOME" defineerimine. Peale installeerimist võib kasutada skripte kataloogist $CATALINA_BASE/bin . Järgneb üks võimalik käivitamise ja peatamise näide, mis on kasutatav eelnevalt kirjeldatud käsitsi installeerimise juhul:
<pre>
/Library/Tomcat/bin/startup.sh
</pre>
ja peatamiseks
<pre>
/Library/Tomcat/bin/shutdown.sh
</pre>

===Näiteaplikatsiooni juurutamine===

Java veebiaplikatsiooni jagatakse hea tava kohaselt üheainsa veebiarhiivi failina. Siiski võib Tomcati juurutada ka lahtipakendatud olekus ("exploded") Java veebiaplikatsiooni.

====Käsitsi juurutamine ja mahavõtmine====

Näiteaplikatsiooni juurutamiseks lae selle veebiarhiivifail alla ning kopeeri oma konteineri juurutamiskataloogi 'webapps':
<pre>wget http://tomcat.apache.org/tomcat-8.0-doc/appdev/sample/sample.war
cp /Users/kristjanveskimae/downloads/sample.war /Library/Tomcat/webapps/sample.war</pre>

Kui konfiguratsioonifailis $CATALINA_BASE/conf/server.xml on märgendi "Host" atribuudi "autoDeploy" väärtus "true", installeerib ja uuendab Tomcat aplikatsioone dünaamiliselt töötamise ajal. Kui väärtuseks on "false", käib installeerimine staatiliselt ning serverisse juurutamiseks tuleb teha konteineri taaskäivitus. [http://tomcat.apache.org/tomcat-8.0-doc/manager-howto.html#Deploy_A_New_Application_from_a_Local_Path 2] Mõlemal juhul pakib konteiner arhiveeritud faili ise lahti samasse kausta $CATALINA_BASE/webapps ning ka juurutab selle. Tekkiv aplikatsioon on lokaalsest masinast seejärel kättesaadav aadressil http://localhost:8080/sample/ .

[[File:sample_app.png|400px]]

Veebirakenduse käsitsi mahavõtmiseks tuleb kustutada talle vastav dokumendipõhja kataloog "webapps" kataloogist. Samuti tuleks kustutada .war-fail olemaks kindel, et Tomcat ei rakenda uuel käivitamisel veebiaplikatsiooni veebiarhiivifailist. Veelgi lihtsam on mahavõtmine brauseriga haldusrakenduse kaudu.

Rakenduste baaskataloogi "webapps" asukohta saab muuta failis $CATALINA_BASE/conf/server.xml peremehepõhiselt määratava atribuudiga "appBase", sealjuures Tomcati vaikimisi peremees ehk "Host" on "localhost".

====Tomcati vahendid juurutamiseks====

Veebiaplikatsioonide juurutamine ja mahajuurutamine on võimalik ka kaughalduse teel tänu Tomcati internetipõhisele haldusrakendusele. Näiteks saab veebibrauserit kasutades teha serveri põhitoiminguid Tomcati enda HTML-põhise rakendusega "Tomcat Manager". Veebipõhine haldusrakendus töötab ka käsupõhise veebiteenusena, millele on valmis ehitatud Anti ja Maveni integratsioonid. Samuti eksisteerib käsurea kliendirakendus TCD (Tomcat Client Deployer). TCD ei kuulu Tomcati baaskoosseisu, kuid pakub peale serveri administreerimise tavatoimingute ka lisafunktsionaalsust nagu veebirakenduse kokkukompileerimine ja pakendamine. [http://tomcat.apache.org/tomcat-8.0-doc/manager-howto.html#Configuring_Manager_Application_Access 1]

====Haldurakendus "Tomcat Manager"====

Tomcati haldusrakendus "Tomcat Manager" (antud alamjaotuses lihtsalt haldusrakendus) on Tomcati enda veebiaplikatioon Tomcati brauseripõhiseks kaughalduseks, võimaldades muu hulgas järgnevat [http://tomcat.apache.org/tomcat-8.0-doc/manager-howto.html#Introduction 3]:
* Rakendada uue veebiaplikatsiooni war-faili üleslaadimisega;
* Näha kõiki rakendatud veebiaplikatsioone koos aktiivsete sessioonidega;
* Taasrakendada veebirakendust, näiteks veebiarhiivi pakitud klassifailide /WEB-INF/classes või teekide /WEB-INF/lib uuendamisel, kinnijooksmisel jms.;
* Peatada veebirakendust ilma serverist eemaldamata, samuti koos serverist eemaldamisega;
* Vaadata operatsioonisüsteemi ja Java parameetrite väärtusi;
* Näha kõiki saadaolevaid JNDI ressursse, k.a. andmebaasiühendusi, mis aitavad rakenduste programmeerijail defineerida <ResourceLink> elemendid web.xml konfiguratsioonifailis.

Tomcati installatsioon sisaldab haldusrakendust juba vaikimisi. Haldusrakenduse töölepanemiseks tuleb peremeesmasina konfiguratsioonikataloogi $CATALINA_BASE/conf/[enginename]/[hostname] lisada ka fail manager.xml. Vaikimisi valmiskonfigureeritud testrakendusel on see fail juba olemas asukohas $CATALINA_BASE/conf/Catalina/localhost/manager.xml . Rakendus asub vaikimisi aadressil http://[host]/manager/ , vaikimisi konfiguratsioone kasutades lahendub see asukohaks http://localhost:8080/manager/ . [http://tomcat.apache.org/tomcat-8.0-doc/manager-howto.html#Configuring_Manager_Application_Access 4]

====="Tomcat Manager" ligipääsu konfigureerimine=====

Vaikimisi on turvalisuspõhjustel ligipääs haldusrakendusele maha keeratud. Mismoodi täpselt kasutajatel ligipääsu võimaldada sõltub kasutatavast valdusest (realm). Vaikimisi defineerib $CATALINA_BASE/conf/server.xml valduseks "MemoryRealm". Vaikimisi loeb valdus "MemoryRealm" kasutajad failist $CATALINA_BASE/conf/tomcat-users.xml. Antud failis tuleb iga kasutaja defineerida omaette märgendiga <user>, mis näeb välja umbes järgmine:
<pre>
<user name="craig" password="secret" roles="manager-gui,manager-script" />
</pre>

Antud kasutajale on defineeritud korraga kaks rolli. Ligipääsu võimaldamiseks tulebki lihtsamal juhul kasutajatefailis $CATALINA_BASE/conf/tomcat-users.xml defineerida enda kasutaja. Kasutaja rolliks võib määrata näiteks "manager-gui", mis võimaldab ligipääsu kogu HTML liidese funktsionaalsusele.

Teised valdused on "JDBCRealm", mille puhul hoitakse kasutajatega seonduvat infot andmebaasis ja JNDIRealm, mille puhul kasutatakse lihtsustatud kataloogisirvimise protokolli (LDAP).
Lisaks saab haldusrakendusele keelata ligipääsu mujalt kui kindlaksmääratud IP-aadressidelt, lisades filtri "RemoteAddrValve" või "RemoteHostValve" konfigureerimisfaili manager.xml näiteks järgmiselt:
<pre>
<Context privileged="true">
<Valve className="org.apache.catalina.valves.RemoteAddrValve"
allow="127\.0\.0\.1"/>
</Context>
</pre>

=====Juurutamine ja mahavõtmine haldusrakendusega "Tomcat Manager"=====

Juurutamiseks lae kõigepealt veebiarhiivifail üles, kasutades esilehel asuvat sektsiooni "WAR file to deploy".
[[File:tomcat_manager_war_upload.png]]

Rakendus kuvatakse seejärel hallatavate rakenduste nimekirjas. Kui konteiner pole seadistatud üleslaetud aplikatsiooni kohe ka ise rakendama, tuleb vajutada "Start". Rakenduse peatamiseks kasuta "Stop", uuesti rakendamiseks "Redeploy" ja serverist eemaldamiseks "Undeploy".


[[File:tomcat_manager_apps_list.png|800px|Rakenduste nimekiri]]

==Näpunäiteid Tomcati reaalseks kasutamiseks==

===Juurutamise järjekord===

Tomcati käivitumisel juurutatakse aplikatsioonid sellises järjekorras:
# Konteinerisse kopeeritud kontekstikirjelduste järgi $CATALINA_BASE/conf/[EngineName]/[HostName]/[ApplicationName].xml ;
# Lahtipakitud rakendused "webapps" kataloogis;
# Pakitud rakenduste veebiarhiivid "webapps" kataloogis.

Seetõttu peaks käsitsi taasjuurutamisel kindluse mõttes eelnevalt kustutama rakenduse lahtipakitud dokumendipõhja kataloogi "webapps" kataloogist. Kontekstikirjelduse muutumisel tuleb jälgida, kas kirjeldus on juba kopeeritud serverisse ning vajadusel eelmise versiooni ümber muuta või kustutada.

===Reaalsele domeenile konfigureerimine===

Järgnevalt eeldame, et domeen ''www.minukodukas.ee'' on juba serverimasinaga seostatud. Et Tomcat hakkaks ka reaalselt Internetist tulevatele päringutele vastama, tuleb muuta failis $CATALINA_BASE/conf/server.xml konteinerile ''Catalina'' vastava teenusemärgendi sisu sarnaselt järgnevaga:

<pre>
<Service name="Catalina">
<Connector port="80" protocol="HTTP/1.1" connectionTimeout="20000" URIEncoding="UTF-8" redirectPort="8443" />
<Engine name="Catalina" defaultHost="www.minukodukas.ee">
<Host name="www.minukodukas.ee" appBase="webapps" unpackWARs="true" autoDeploy="false" deployOnStartup="false" xmlValidation="false" xmlNamespaceAware="false">
<Context path="" docBase="kodukas" debug="0" reloadable="true" />
</Host>
</Engine>
</Service>
</pre>

Ülal defineerime põhiliselt selle, et Tomcat kuulaks domeeni ''www.minukodukas.ee'' ja kasutaks HTTP päringute jaoks porti 80. Ühtlasti otsib Tomcat juurutatavat rakendust failist $CATALINA_BASE/webapps/kodukas.war. Kuna rajalisandiks on määratud tühi sõne (path=""), siis juurutataksegi aplikatsioon aadressile ''www.minukodukas.ee'' ilma rajalisandita (a'la ''www.minukodukas.ee/wiki''). Seetõttu pakitakse ka veebiarhiiv tegelikult lahti kataloogi $CATALINA_BASE/webapps/ROOT mitte kataloogi $CATALINA_BASE/webapps/kodukas nagu võiks eeldada.

===Käigultvahetus===

Võimaldamaks käigultvahetust (hot deployment) peab konteineri konfiguratsioonifailis $CATALINA_BASE/conf/server.xml olema peremehepõhise märgendi "Host" atribuudi "autoDeploy" väärtus "true". Sel juhul installeerib ja uuendab Tomcat aplikatsioone dünaamiliselt töötamise ajal. Kui väärtuseks on "false", käib installeerimine staatiliselt ning serverisse juurutamiseks tuleb teha konteineri taaskäivitus. Käigultvahetust saab määrata ka peremehe defineerimisel "Host Manager" rakendusega, mis on kättesaadav aadressil http://localhost:8080/host-manager/html . Kasutamiseks tuleb lisada oma kasutajale rolli "admin-gui" (vt. alajaotus ""Tomcat Manager" ligipääsu konfigureerimine").

[[File:host_manager_app.png]]

Käigultvahetust päästikuks on vaikimisi uuendatud veebiarhiivifaili või lahtipakitud veebirakenduse paigutamine "webapps" kataloogi. Käigultvahetuse päästikutele võib failis $CATALINA_BASE/conf/server.xml ka ise lisada kuulatavaid ressursse nagu web.xml muutmine või mõne teegifaili vahetamine (märgendis "Host").

===Klassiteekide väljatõstmine veebiarhiivifailist===

Kõik konteksti poolt kasutatavad Java klassiteegid võib pakendada veebiarhiivi sisse kataloogi "lib", kuid nii võib osutuda veebiarhiivi üleslaadimine ajakulukaks, eriti arenduskeskkonnas. Kui ei teki ohtu, et erinevad rakendused kasutavad sama teegi erinevaid versioone, siis on vahel parem lisada osa teeke konteineri kataloogi $CATALINA_BASE/libs, kust need tehakse siis konteineri poolt kättesaadavaks kõigile konteineris jooksutatavatele kontekstidele. Nii võib vähendada veebiarhiivi faili suurust märgatavalt, mis tõstab kokkuvõttes juurutamiskiirust ja ühes sellega programmeerijate tööviljakust.

===Mälukasutus===

Konteineri poolt kasutatavat mälu saab vaadata haldusrakendusest vajutades lingile "Server Status". Mälukasutus on toodud jaotuses "JVM", kus näidatakse nii maksimaalselt kättesaadavat mälu kui ka parasjagu reserveeritud mälu.

<pre>Free memory: 41.16 MB Total memory: 123.37 MB Max memory: 1027.56 MB</pre>

Mälu suurendamiseks võib näiteks defineerida skriptis $CATALINA_BASE/bin/catalina.sh muutuja "JAVA_OPTS" ning määrata Java mälukasutuse miinimum- ja maksimumväärtused sarnaselt järgnevatega [http://www.mkyong.com/tomcat/tomcat-javalangoutofmemoryerror-permgen-space/ 5]:
<pre>
JAVA_OPTS="-Xms1536m -Xmx1536m -XX:NewSize=256m -XX:MaxNewSize=256m -XX:PermSize=256m -XX:MaxPermSize=256m"
</pre>

===Logifailid===

Vaikimisi defineerib Tomcat failiga $CATALINA_BASE/conf/logging.properties viis logerit, mis tekitavad viis eraldi logifaili.

{| style="background:#cccc99;color:black;width:80%;" border="1" cellpadding="5" cellspacing="0" align="center"
|+ Tomcati tekitatavad logifailid "logs" kataloogis
!Fail !! Kasutus
|- style="background:white; color:black"
| style="width:300px" |catalina.out
| Tomcati käivitus- ja peatamisskriptide väljund, samuti juurutatud rakenduste prindilaused System.out ja veaväljundid System.err
|- style="background:white; color:black"
| style="width:300px" |catalina.[yyyy]-[mm]-[dd].log
| Pööratud (rotated) logifail catalina.out
|- style="background:white; color:black"
| style="width:300px" |host-manager.[yyyy]-[mm]-[dd].log
| Logi peremehehalduse rakendusele (rakendus on kättesaadav kohalikust masinast aadressil http://localhost:8080/host-manager/html )
|- style="background:white; color:black"
| style="width:300px" |localhost.[yyyy]-[mm]-[dd].log
| Peremehe "localhost" logi; mitme virtuaalse peremehe korral tekitatakse igale peremehele oma logi
|- style="background:white; color:black"
| style="width:300px" |localhost_access_log.[yyyy]-[mm]-[dd].txt
| Konteinerisse Internetist saabunud päringute logi
|- style="background:white; color:black"
| style="width:300px" |manager.[yyyy]-[mm]-[dd].log
| Haldusrakenduse tegevuste logi
|}

===Viiteid===

Palju vajalikku võib leida [http://tomcat.apache.org/tomcat-8.0-doc/index.html Tomcat 8 dokumentatsioonist]

Lisaks üks viide põhjalikule Tomcati versioon seitsme ülevaatele: http://www.ntu.edu.sg/home/ehchua/programming/howto/Tomcat_More.html

= Kasutatud materjalid =

*http://tomcat.apache.org/tomcat-8.0-doc/index.html
*http://www.mulesoft.com/tomcat-deploy-procedures
*http://www.mkyong.com/tomcat/tomcat-javalangoutofmemoryerror-permgen-space/

[[Category: Operatsioonisüsteemide administreerimine ja sidumine]]

Tomcat

2014-01-02T21:36:30Z

Kveskima: /* Haldurakendus "Tomcat Manager" */

==Autor==

Kristjan Veskimäe D32

2013

==Sissejuhatus==

Tomcat on vabalt kättesaadav server Java veebirakendustele. Põhimõtteliselt on tegemist Servlet/JSP spetsifikatsiooni toetava konteineriga. Kiire käivitumise ning rakenduste käigultvahetuse tõttu on Tomcat hea valik väiksemate ning keskmise suurusega Java veebirakenduste käitamiseks.

Antud töö kirjeldab Tomcati 8. versiooni. Põhiosa on üldiselt samasugune võrreldes paari eelmise versiooniga. Suuremad erinevused on versioonispetsiifilistes probleemides ja nende lahendamises, mida käesolev töö ei vaatle.

Töö vaatleb Tomcati paigaldamist ja seadistamist Unix-laadsesse keskkonda ning eeldab lugejalt algteadmisi sarnastes süsteemides. Tomcati on võimalik paigaldada ka Windows-keskkonda, kuid antud veebiserver eeldab kasutaja poolt käsureal töötamist ning Tomcati failihierarhias orienteerumist. Põhimõtteliselt on Java veebirakenduste arendamiseks IDE-abil võimalik siiski ka kasutada IDE-sse integreeritud Tomcati serverit - näiteks pakuvad sellist võimalust Eclipse EE ja NetBeans - kuid seda käesolev töö ei vaatle.

==Mõisted==

* '''Kontekst''' (context) - Tomcati mõistes üks konkreetne veebiaplikatsioon
* '''Konteiner''' (container) - veebiserver Tomcat ise
* '''Kontekstikirjeldus''' (context descriptor) - Tomcati-spetsiifiline konteksti konfiguratsioonimääratlus; peremehepõhine osa loetakse failist $CATALINA_HOME/conf/[enginename]/[hostname]/context.xml ja sellele lisatakse kontekstispetsiifilised täpsustused failist $CATALINA_BASE/conf/[enginename]/[hostname]/[webappname].xml; kontekstikirjeldus määrab näiteks nimed ressurssidele, sessioonihalduse parameetrid jmt. (olgu märgitud, et Tomcati varasemates versioonides sisaldusid kontekstikirjeldused põhikonfiguratsioonifailis server.xml)
* '''Dokumendipõhi''' (docBase) - kontekstile vastav kataloog Tomcati "webapps" kataloogis, mis tekib veebiaplikatsiooni serverisse rakendamisel
* '''Veebiarhiiv''' (Web application ARchive, war-file) - Java veebiaplikatsiooni jagatakse hea tava kohaselt selle üheainsa veebiarhiivi failina, mille laienditüübiks on "war". Tegemist on zip-protokolliga kokkupakitud kataloogiga, millel on Java veebirakenduste spetsifikatsioonile vastav ülesehitus. Siiski võib veebiaplikatsioon olla juurutamisel ka lahtipakendatud olekus (inglisekeelne termin on "war is exploded").

==Ülesehitus==

{| class="wikitable"
|+Kataloogid
|-
|style="color: green;" | $CATALINA_HOME
|baaskataloog, kuhu on Tomcat paigutatud
|-
|style="color: green;" | $CATALINA_BASE
|parasjagu töösoleva Tomcati eksemplari baaskataloog, mille alusel lahendatakse teed ülejäänud kataloogide ja failideni; ainult ühe kasutusel oleva Tomcati eksemplari puhul on see sama, mis $CATALINA_HOME

|-
|style="color: green;" | $CATALINA_BASE/bin
|serveri käivitus- ja abiskriptid
|-
|style="color: green;" | $CATALINA_BASE/conf
|konfiguratsioonifailid
|-
|style="color: green;" | $CATALINA_BASE/lib
|Tomcatile vaikimisi kättesaadavad Java klassiteegid (class libraries) ehk .jar-failid kuhu on Java kompileeritud kood kokku pakendatud
|-
|style="color: green;" | $CATALINA_BASE/logs
|logifailid paigutatakse vaikimisi siia
|-
|style="color: green;" | $CATALINA_BASE/webapps
|kataloog, kuhu paigutatakse serverisse juurutatavad veebiaplikatsioonid

|}

{| class="wikitable"
|+Mõned olulisemad failid
|-
|style="color: green;" | $CATALINA_BASE/bin/startup.sh
|serveri käivitusskript
|-
|style="color: green;" | $CATALINA_BASE/bin/shutdown.sh
|serveri peatusskript

|-
|style="color: green;" | $CATALINA_BASE/conf/server.xml
| konteineri peamine konfiguratsioonifail
|-
|style="color: green;" | $CATALINA_BASE/conf/[enginename]/[hostname]/[webappname].xml
|serveri administraatori jaoks konteinerisse endasse ümber kopeeritud rakendusepõhine kontekstikirjelduse konfiguratsioon failist $CATALINA_BASE/webapps/[ApplicationName]/META-INF/context.xml
|-
|style="color: green;" | $CATALINA_BASE/conf/[enginename]/[hostname]/context.xml
| fail, mis aitab administraatoril konteksti kohta käivat infot kirjeldada peremeesmasina-põhiselt ja halduseks mõeldud automaat-tööriistadel (näiteks Tomcat Manager ja TCD) oma tööd teha
|-
|style="color: green;" | $CATALINA_BASE/$CATALINA_BASE/conf/[enginename]/[hostname]/manager.xml
|fail, mis võimaldab lisada rakendustele ligipääsufiltreid
|-
|style="color: green;" | $CATALINA_BASE/webapps/[webappname]/META-INF/context.xml
|kontekstikirjeldusfail, mille veebirakenduse programmeerija on pakendanud oma aplikatsiooniga kaasa ning millega ta saab võimaluse kontekstikirjeldust omalt poolt mõjutada; kirjutatakse rakenduse uuestijuurutamisel üle, mistõttu administraator peaks muutma selle asemel konteinerisse ümber kopeeritud püsieksemplari $CATALINA_BASE/conf/[enginename]/[hostname]/context.xml
|-
|style="color: green;" | $CATALINA_BASE/webapps/[webappname]/WEB-INF/web.xml
|ka üks oluline Java veebiaplikatsiooni konfiguratsioonifail, mille pakendatakse koos veebiarhiiviga; enamasti muudab seda ainult programeerija; määrab muu hulgas millised aplikatsiooni osad vajavad autentimist või kui kiiresti veebisessioon aegub
|}

==Installeerimine==

===Installeerimine paketihalduriga===

<pre>
apt-cache search tomcat
apt-get install tomcat[version]-webapps
apt-get install tomcat[version]-admin
apt-get install tomcat[version]
</pre>

===Installeerimine käsitsi===

Paketihalduriga installeerides ei pruugi viimane Tomcati versioon olla kättesaadav ja see pakub ka vähem võimalusi kataloogide määramiseks jms. Käsitsi installeerimiseks tuleb laadida Tomcat kodulehelt alla. Lahtipakkimisel tekib kataloog, milles sisalduv fail "RUNNING.txt" on kõige kindlam allikas installeerimisel tekkivate probleemide vältimiseks ning lahendamiseks.

Vajaliku versiooni installeerimisfaili asukoha saab vaadata Tomcati kodulehelt sektsioonist "Download". Järgnevas näites installeerime Tomcati kõige uuema ebastabiilse kandidaatversiooni, mida näitab nimes sisalduv RC ehk "release candidate". Produktsioonikeskkonda tuleks siiski valida stabiilse versiooni. Käsitsi installeerimine on sarnane järgmisega:
<pre>
wget http://mirror.nexcess.net/apache/tomcat/tomcat-8/v8.0.0-RC5/bin/apache-tomcat-8.0.0-RC5.tar.gz
tar -zxvf apache-tomcat-8.0.0-RC5.tar.gz
mv /Users/kristjanveskimae/downloads/apache-tomcat-8.0.0-RC5 /usr/local/apache-tomcat-8.0.0-RC5
rm -f /Library/Tomcat
ln -s /usr/local/apache-tomcat-8.0.0-RC5/ /Library/Tomcat
chown -R kristjanveskimae /Library/Tomcat
chmod +x /Library/Tomcat/bin/*.sh
</pre>

==Käivitamine ja aplikatsiooni juurutamine==

===Konteineri käivitamine===

Tomcati käivitamise eelduseks on Java paigaldamine masinasse ning keskkonnamuutujate "JAVA_HOME" ja "JRE_HOME" defineerimine. Peale installeerimist võib kasutada skripte kataloogist $CATALINA_BASE/bin . Järgneb üks võimalik käivitamise ja peatamise näide, mis on kasutatav eelnevalt kirjeldatud käsitsi installeerimise juhul:
<pre>
/Library/Tomcat/bin/startup.sh
</pre>
ja peatamiseks
<pre>
/Library/Tomcat/bin/shutdown.sh
</pre>

===Näiteaplikatsiooni juurutamine===

Java veebiaplikatsiooni jagatakse hea tava kohaselt üheainsa veebiarhiivi failina. Siiski võib Tomcati juurutada ka lahtipakendatud olekus ("exploded") Java veebiaplikatsiooni.

====Käsitsi juurutamine ja mahavõtmine====

Näiteaplikatsiooni juurutamiseks lae selle veebiarhiivifail alla ning kopeeri oma konteineri juurutamiskataloogi 'webapps':
<pre>wget http://tomcat.apache.org/tomcat-8.0-doc/appdev/sample/sample.war
cp /Users/kristjanveskimae/downloads/sample.war /Library/Tomcat/webapps/sample.war</pre>

Kui konfiguratsioonifailis $CATALINA_BASE/conf/server.xml on märgendi "Host" atribuudi "autoDeploy" väärtus "true", installeerib ja uuendab Tomcat aplikatsioone dünaamiliselt töötamise ajal. Kui väärtuseks on "false", käib installeerimine staatiliselt ning serverisse juurutamiseks tuleb teha konteineri taaskäivitus. [http://tomcat.apache.org/tomcat-8.0-doc/manager-howto.html#Deploy_A_New_Application_from_a_Local_Path 2] Mõlemal juhul pakib konteiner arhiveeritud faili ise lahti samasse kausta $CATALINA_BASE/webapps ning ka juurutab selle. Tekkiv aplikatsioon on lokaalsest masinast seejärel kättesaadav aadressil http://localhost:8080/sample/ .

[[File:sample_app.png|400px]]

Veebirakenduse käsitsi mahavõtmiseks tuleb kustutada talle vastav dokumendipõhja kataloog "webapps" kataloogist. Samuti tuleks kustutada .war-fail olemaks kindel, et Tomcat ei rakenda uuel käivitamisel veebiaplikatsiooni veebiarhiivifailist. Veelgi lihtsam on mahavõtmine brauseriga haldusrakenduse kaudu.

Rakenduste baaskataloogi "webapps" asukohta saab muuta failis $CATALINA_BASE/conf/server.xml peremehepõhiselt määratava atribuudiga "appBase", sealjuures Tomcati vaikimisi peremees ehk "Host" on "localhost".

====Tomcati vahendid juurutamiseks====

Veebiaplikatsioonide juurutamine ja mahajuurutamine on võimalik ka kaughalduse teel tänu Tomcati internetipõhisele haldusrakendusele. Näiteks saab veebibrauserit kasutades teha serveri põhitoiminguid Tomcati enda HTML-põhise rakendusega "Tomcat Manager". Veebipõhine haldusrakendus töötab ka käsupõhise veebiteenusena, millele on valmis ehitatud Anti ja Maveni integratsioonid. Samuti eksisteerib käsurea kliendirakendus TCD (Tomcat Client Deployer). TCD ei kuulu Tomcati baaskoosseisu, kuid pakub peale serveri administreerimise tavatoimingute ka lisafunktsionaalsust nagu veebirakenduse kokkukompileerimine ja pakendamine. [http://tomcat.apache.org/tomcat-8.0-doc/manager-howto.html#Configuring_Manager_Application_Access 1]

====Haldurakendus "Tomcat Manager"====

Tomcati haldusrakendus "Tomcat Manager" (antud alamjaotuses lihtsalt haldusrakendus) on Tomcati enda veebiaplikatioon Tomcati brauseripõhiseks kaughalduseks, võimaldades muu hulgas järgnevat [http://tomcat.apache.org/tomcat-8.0-doc/manager-howto.html#Introduction 3]:
* Rakendada uue veebiaplikatsiooni war-faili üleslaadimisega;
* Näha kõiki rakendatud veebiaplikatsioone koos aktiivsete sessioonidega;
* Taasrakendada veebirakendust, näiteks veebiarhiivi pakitud klassifailide /WEB-INF/classes või teekide /WEB-INF/lib uuendamisel, kinnijooksmisel jms.;
* Peatada veebirakendust ilma serverist eemaldamata, samuti koos serverist eemaldamisega;
* Vaadata operatsioonisüsteemi ja Java parameetrite väärtusi;
* Näha kõiki saadaolevaid JNDI ressursse, k.a. andmebaasiühendusi, mis aitavad rakenduste programmeerijail defineerida <ResourceLink> elemendid web.xml konfiguratsioonifailis.

Tomcati installatsioon sisaldab haldusrakendust juba vaikimisi. Haldusrakenduse töölepanemiseks tuleb peremeesmasina konfiguratsioonikataloogi $CATALINA_BASE/conf/[enginename]/[hostname] lisada ka fail manager.xml. Vaikimisi valmiskonfigureeritud testrakendusel on see fail juba olemas asukohas $CATALINA_BASE/conf/Catalina/localhost/manager.xml . Rakendus asub vaikimisi aadressil http://[host]/manager/ , vaikimisi konfiguratsioone kasutades lahendub see asukohaks http://localhost:8080/manager/ . [http://tomcat.apache.org/tomcat-8.0-doc/manager-howto.html#Configuring_Manager_Application_Access 4]

====="Tomcat Manager" ligipääsu konfigureerimine=====

Vaikimisi on turvalisuspõhjustel ligipääs haldusrakendusele maha keeratud. Mismoodi täpselt kasutajatel ligipääsu võimaldada sõltub kasutatavast valdusest (realm). Vaikimisi defineerib $CATALINA_BASE/conf/server.xml valduseks "MemoryRealm". Vaikimisi loeb valdus "MemoryRealm" kasutajad failist $CATALINA_BASE/conf/tomcat-users.xml. Antud failis tuleb iga kasutaja defineerida omaette märgendiga <user>, mis näeb välja umbes järgmine:
<pre>
<user name="craig" password="secret" roles="manager-gui,manager-script" />
</pre>

Antud kasutajale on defineeritud korraga kaks rolli. Ligipääsu võimaldamiseks tulebki lihtsamal juhul kasutajatefailis $CATALINA_BASE/conf/tomcat-users.xml defineerida enda kasutaja. Kasutaja rolliks võib määrata näiteks "manager-gui", mis võimaldab ligipääsu kogu HTML liidese funktsionaalsusele.

Teised valdused on "JDBCRealm", mille puhul hoitakse kasutajatega seonduvat infot andmebaasis ja JNDIRealm, mille puhul kasutatakse lihtsustatud kataloogisirvimise protokolli (LDAP).
Lisaks saab haldusrakendusele keelata ligipääsu mujalt kui kindlaksmääratud IP-aadressidelt, lisades filtri "RemoteAddrValve" või "RemoteHostValve" konfigureerimisfaili manager.xml näiteks järgmiselt:
<pre>
<Context privileged="true">
<Valve className="org.apache.catalina.valves.RemoteAddrValve"
allow="127\.0\.0\.1"/>
</Context>
</pre>

=====Juurutamine ja mahavõtmine haldusrakendusega "Tomcat Manager"=====

Juurutamiseks lae kõigepealt veebiarhiivifail üles, kasutades esilehel asuvat sektsiooni "WAR file to deploy".
[[File:tomcat_manager_war_upload.png]]

Rakendus kuvatakse seejärel hallatavate rakenduste nimekirjas. Kui konteiner pole seadistatud üleslaetud aplikatsiooni kohe ka ise rakendama, tuleb vajutada "Start". Rakenduse peatamiseks kasuta "Stop", uuesti rakendamiseks "Redeploy" ja serverist eemaldamiseks "Undeploy".


[[File:tomcat_manager_apps_list.png|800px|Rakenduste nimekiri]]

==Näpunäiteid Tomcati reaalseks kasutamiseks==

===Juurutamise järjekord===

Tomcati käivitumisel juurutatakse aplikatsioonid sellises järjekorras:
# Konteinerisse kopeeritud kontekstikirjelduste järgi $CATALINA_BASE/conf/[EngineName]/[HostName]/[ApplicationName].xml ;
# Lahtipakitud rakendused "webapps" kataloogis;
# Pakitud rakenduste veebiarhiivid "webapps" kataloogis.

Seetõttu peaks käsitsi taasjuurutamisel kindluse mõttes eelnevalt kustutama rakenduse lahtipakitud dokumendipõhja kataloogi "webapps" kataloogist. Kontekstikirjelduse muutumisel tuleb jälgida, kas kirjeldus on juba kopeeritud serverisse ning vajadusel eelmise versiooni ümber muuta või kustutada.

===Reaalsele domeenile konfigureerimine===

Järgnevalt eeldame, et domeen ''www.minukodukas.ee'' on juba serverimasinaga seostatud. Et Tomcat hakkaks ka reaalselt Internetist tulevatele päringutele vastama, tuleb muuta failis $CATALINA_BASE/conf/server.xml konteinerile ''Catalina'' vastava teenusemärgendi sisu sarnaselt järgnevaga:

<pre>
<Service name="Catalina">
<Connector port="80" protocol="HTTP/1.1" connectionTimeout="20000" URIEncoding="UTF-8" redirectPort="8443" />
<Engine name="Catalina" defaultHost="www.minukodukas.ee">
<Host name="www.minukodukas.ee" appBase="webapps" unpackWARs="true" autoDeploy="false" deployOnStartup="false" xmlValidation="false" xmlNamespaceAware="false">
<Context path="" docBase="kodukas" debug="0" reloadable="true" />
</Host>
</Engine>
</Service>
</pre>

Ülal defineerime põhiliselt selle, et Tomcat kuulaks domeeni ''www.minukodukas.ee'' ja kasutaks HTTP päringute jaoks porti 80. Ühtlasti otsib Tomcat juurutatavat rakendust failist $CATALINA_BASE/webapps/kodukas.war. Kuna rajalisandiks on määratud tühi sõne (path=""), siis juurutataksegi aplikatsioon aadressile ''www.minukodukas.ee'' ilma rajalisandita (a'la ''www.minukodukas.ee/wiki''). Seetõttu pakitakse ka veebiarhiiv tegelikult lahti kataloogi $CATALINA_BASE/webapps/ROOT mitte kataloogi $CATALINA_BASE/webapps/kodukas nagu võiks eeldada.

===Käigultvahetus===

Võimaldamaks käigultvahetust (hot deployment) peab konteineri konfiguratsioonifailis $CATALINA_BASE/conf/server.xml olema peremehepõhise märgendi "Host" atribuudi "autoDeploy" väärtus "true". Sel juhul installeerib ja uuendab Tomcat aplikatsioone dünaamiliselt töötamise ajal. Kui väärtuseks on "false", käib installeerimine staatiliselt ning serverisse juurutamiseks tuleb teha konteineri taaskäivitus. Käigultvahetust saab määrata ka peremehe defineerimisel "Host Manager" rakendusega, mis on kättesaadav aadressil http://localhost:8080/host-manager/html . Kasutamiseks tuleb lisada oma kasutajale rolli "admin-gui" (vt. alajaotus ""Tomcat Manager" ligipääsu konfigureerimine").

[[File:host_manager_app.png]]

Käigultvahetust päästikuks on vaikimisi uuendatud veebiarhiivifaili või lahtipakitud veebirakenduse paigutamine "webapps" kataloogi. Käigultvahetuse päästikutele võib failis $CATALINA_BASE/conf/server.xml ka ise lisada kuulatavaid ressursse nagu web.xml muutmine või mõne teegifaili vahetamine (märgendis "Host").

===Klassiteekide väljatõstmine veebiarhiivifailist===

Kõik konteksti poolt kasutatavad Java klassiteegid võib pakendada veebiarhiivi sisse kataloogi "lib", kuid nii võib osutuda veebiarhiivi üleslaadimine ajakulukaks, eriti arenduskeskkonnas. Kui ei teki ohtu, et erinevad rakendused kasutavad sama teegi erinevaid versioone, siis on vahel parem lisada osa teeke konteineri kataloogi $CATALINA_BASE/libs, kust need tehakse siis konteineri poolt kättesaadavaks kõigile konteineris jooksutatavatele kontekstidele. Nii võib vähendada veebiarhiivi faili suurust märgatavalt, mis tõstab kokkuvõttes juurutamiskiirust ja ühes sellega programmeerijate tööviljakust.

===Mälukasutus===

Konteineri poolt kasutatavat mälu saab vaadata haldusrakendusest vajutades lingile "Server Status". Mälukasutus on toodud jaotuses "JVM", kus näidatakse nii maksimaalselt kättesaadavat mälu kui ka parasjagu reserveeritud mälu.

<pre>Free memory: 41.16 MB Total memory: 123.37 MB Max memory: 1027.56 MB</pre>

Mälu suurendamiseks võib näiteks defineerida skriptis $CATALINA_BASE/bin/catalina.sh muutuja "JAVA_OPTS" ning määrata Java mälukasutuse miinimum- ja maksimumväärtused sarnaselt järgnevatega:
<pre>
JAVA_OPTS="-Xms1536m -Xmx1536m -XX:NewSize=256m -XX:MaxNewSize=256m -XX:PermSize=256m -XX:MaxPermSize=256m"
</pre>

===Logifailid===

Vaikimisi defineerib Tomcat failiga $CATALINA_BASE/conf/logging.properties viis logerit, mis tekitavad viis eraldi logifaili.

{| style="background:#cccc99;color:black;width:80%;" border="1" cellpadding="5" cellspacing="0" align="center"
|+ Tomcati tekitatavad logifailid "logs" kataloogis
!Fail !! Kasutus
|- style="background:white; color:black"
| style="width:300px" |catalina.out
| Tomcati käivitus- ja peatamisskriptide väljund, samuti juurutatud rakenduste prindilaused System.out ja veaväljundid System.err
|- style="background:white; color:black"
| style="width:300px" |catalina.[yyyy]-[mm]-[dd].log
| Pööratud (rotated) logifail catalina.out
|- style="background:white; color:black"
| style="width:300px" |host-manager.[yyyy]-[mm]-[dd].log
| Logi peremehehalduse rakendusele (rakendus on kättesaadav kohalikust masinast aadressil http://localhost:8080/host-manager/html )
|- style="background:white; color:black"
| style="width:300px" |localhost.[yyyy]-[mm]-[dd].log
| Peremehe "localhost" logi; mitme virtuaalse peremehe korral tekitatakse igale peremehele oma logi
|- style="background:white; color:black"
| style="width:300px" |localhost_access_log.[yyyy]-[mm]-[dd].txt
| Konteinerisse Internetist saabunud päringute logi
|- style="background:white; color:black"
| style="width:300px" |manager.[yyyy]-[mm]-[dd].log
| Haldusrakenduse tegevuste logi
|}

===Viiteid===

Palju vajalikku võib leida [http://tomcat.apache.org/tomcat-8.0-doc/index.html Tomcat 8 dokumentatsioonist]

Lisaks üks viide põhjalikule Tomcati versioon seitsme ülevaatele: http://www.ntu.edu.sg/home/ehchua/programming/howto/Tomcat_More.html

= Kasutatud materjalid =

*http://tomcat.apache.org/tomcat-8.0-doc/index.html
*http://www.mulesoft.com/tomcat-deploy-procedures
*http://www.mkyong.com/tomcat/tomcat-javalangoutofmemoryerror-permgen-space/

[[Category: Operatsioonisüsteemide administreerimine ja sidumine]]

Tomcat

2014-01-02T21:34:54Z

Kveskima: /* Haldurakendus "Tomcat Manager" */

==Autor==

Kristjan Veskimäe D32

2013

==Sissejuhatus==

Tomcat on vabalt kättesaadav server Java veebirakendustele. Põhimõtteliselt on tegemist Servlet/JSP spetsifikatsiooni toetava konteineriga. Kiire käivitumise ning rakenduste käigultvahetuse tõttu on Tomcat hea valik väiksemate ning keskmise suurusega Java veebirakenduste käitamiseks.

Antud töö kirjeldab Tomcati 8. versiooni. Põhiosa on üldiselt samasugune võrreldes paari eelmise versiooniga. Suuremad erinevused on versioonispetsiifilistes probleemides ja nende lahendamises, mida käesolev töö ei vaatle.

Töö vaatleb Tomcati paigaldamist ja seadistamist Unix-laadsesse keskkonda ning eeldab lugejalt algteadmisi sarnastes süsteemides. Tomcati on võimalik paigaldada ka Windows-keskkonda, kuid antud veebiserver eeldab kasutaja poolt käsureal töötamist ning Tomcati failihierarhias orienteerumist. Põhimõtteliselt on Java veebirakenduste arendamiseks IDE-abil võimalik siiski ka kasutada IDE-sse integreeritud Tomcati serverit - näiteks pakuvad sellist võimalust Eclipse EE ja NetBeans - kuid seda käesolev töö ei vaatle.

==Mõisted==

* '''Kontekst''' (context) - Tomcati mõistes üks konkreetne veebiaplikatsioon
* '''Konteiner''' (container) - veebiserver Tomcat ise
* '''Kontekstikirjeldus''' (context descriptor) - Tomcati-spetsiifiline konteksti konfiguratsioonimääratlus; peremehepõhine osa loetakse failist $CATALINA_HOME/conf/[enginename]/[hostname]/context.xml ja sellele lisatakse kontekstispetsiifilised täpsustused failist $CATALINA_BASE/conf/[enginename]/[hostname]/[webappname].xml; kontekstikirjeldus määrab näiteks nimed ressurssidele, sessioonihalduse parameetrid jmt. (olgu märgitud, et Tomcati varasemates versioonides sisaldusid kontekstikirjeldused põhikonfiguratsioonifailis server.xml)
* '''Dokumendipõhi''' (docBase) - kontekstile vastav kataloog Tomcati "webapps" kataloogis, mis tekib veebiaplikatsiooni serverisse rakendamisel
* '''Veebiarhiiv''' (Web application ARchive, war-file) - Java veebiaplikatsiooni jagatakse hea tava kohaselt selle üheainsa veebiarhiivi failina, mille laienditüübiks on "war". Tegemist on zip-protokolliga kokkupakitud kataloogiga, millel on Java veebirakenduste spetsifikatsioonile vastav ülesehitus. Siiski võib veebiaplikatsioon olla juurutamisel ka lahtipakendatud olekus (inglisekeelne termin on "war is exploded").

==Ülesehitus==

{| class="wikitable"
|+Kataloogid
|-
|style="color: green;" | $CATALINA_HOME
|baaskataloog, kuhu on Tomcat paigutatud
|-
|style="color: green;" | $CATALINA_BASE
|parasjagu töösoleva Tomcati eksemplari baaskataloog, mille alusel lahendatakse teed ülejäänud kataloogide ja failideni; ainult ühe kasutusel oleva Tomcati eksemplari puhul on see sama, mis $CATALINA_HOME

|-
|style="color: green;" | $CATALINA_BASE/bin
|serveri käivitus- ja abiskriptid
|-
|style="color: green;" | $CATALINA_BASE/conf
|konfiguratsioonifailid
|-
|style="color: green;" | $CATALINA_BASE/lib
|Tomcatile vaikimisi kättesaadavad Java klassiteegid (class libraries) ehk .jar-failid kuhu on Java kompileeritud kood kokku pakendatud
|-
|style="color: green;" | $CATALINA_BASE/logs
|logifailid paigutatakse vaikimisi siia
|-
|style="color: green;" | $CATALINA_BASE/webapps
|kataloog, kuhu paigutatakse serverisse juurutatavad veebiaplikatsioonid

|}

{| class="wikitable"
|+Mõned olulisemad failid
|-
|style="color: green;" | $CATALINA_BASE/bin/startup.sh
|serveri käivitusskript
|-
|style="color: green;" | $CATALINA_BASE/bin/shutdown.sh
|serveri peatusskript

|-
|style="color: green;" | $CATALINA_BASE/conf/server.xml
| konteineri peamine konfiguratsioonifail
|-
|style="color: green;" | $CATALINA_BASE/conf/[enginename]/[hostname]/[webappname].xml
|serveri administraatori jaoks konteinerisse endasse ümber kopeeritud rakendusepõhine kontekstikirjelduse konfiguratsioon failist $CATALINA_BASE/webapps/[ApplicationName]/META-INF/context.xml
|-
|style="color: green;" | $CATALINA_BASE/conf/[enginename]/[hostname]/context.xml
| fail, mis aitab administraatoril konteksti kohta käivat infot kirjeldada peremeesmasina-põhiselt ja halduseks mõeldud automaat-tööriistadel (näiteks Tomcat Manager ja TCD) oma tööd teha
|-
|style="color: green;" | $CATALINA_BASE/$CATALINA_BASE/conf/[enginename]/[hostname]/manager.xml
|fail, mis võimaldab lisada rakendustele ligipääsufiltreid
|-
|style="color: green;" | $CATALINA_BASE/webapps/[webappname]/META-INF/context.xml
|kontekstikirjeldusfail, mille veebirakenduse programmeerija on pakendanud oma aplikatsiooniga kaasa ning millega ta saab võimaluse kontekstikirjeldust omalt poolt mõjutada; kirjutatakse rakenduse uuestijuurutamisel üle, mistõttu administraator peaks muutma selle asemel konteinerisse ümber kopeeritud püsieksemplari $CATALINA_BASE/conf/[enginename]/[hostname]/context.xml
|-
|style="color: green;" | $CATALINA_BASE/webapps/[webappname]/WEB-INF/web.xml
|ka üks oluline Java veebiaplikatsiooni konfiguratsioonifail, mille pakendatakse koos veebiarhiiviga; enamasti muudab seda ainult programeerija; määrab muu hulgas millised aplikatsiooni osad vajavad autentimist või kui kiiresti veebisessioon aegub
|}

==Installeerimine==

===Installeerimine paketihalduriga===

<pre>
apt-cache search tomcat
apt-get install tomcat[version]-webapps
apt-get install tomcat[version]-admin
apt-get install tomcat[version]
</pre>

===Installeerimine käsitsi===

Paketihalduriga installeerides ei pruugi viimane Tomcati versioon olla kättesaadav ja see pakub ka vähem võimalusi kataloogide määramiseks jms. Käsitsi installeerimiseks tuleb laadida Tomcat kodulehelt alla. Lahtipakkimisel tekib kataloog, milles sisalduv fail "RUNNING.txt" on kõige kindlam allikas installeerimisel tekkivate probleemide vältimiseks ning lahendamiseks.

Vajaliku versiooni installeerimisfaili asukoha saab vaadata Tomcati kodulehelt sektsioonist "Download". Järgnevas näites installeerime Tomcati kõige uuema ebastabiilse kandidaatversiooni, mida näitab nimes sisalduv RC ehk "release candidate". Produktsioonikeskkonda tuleks siiski valida stabiilse versiooni. Käsitsi installeerimine on sarnane järgmisega:
<pre>
wget http://mirror.nexcess.net/apache/tomcat/tomcat-8/v8.0.0-RC5/bin/apache-tomcat-8.0.0-RC5.tar.gz
tar -zxvf apache-tomcat-8.0.0-RC5.tar.gz
mv /Users/kristjanveskimae/downloads/apache-tomcat-8.0.0-RC5 /usr/local/apache-tomcat-8.0.0-RC5
rm -f /Library/Tomcat
ln -s /usr/local/apache-tomcat-8.0.0-RC5/ /Library/Tomcat
chown -R kristjanveskimae /Library/Tomcat
chmod +x /Library/Tomcat/bin/*.sh
</pre>

==Käivitamine ja aplikatsiooni juurutamine==

===Konteineri käivitamine===

Tomcati käivitamise eelduseks on Java paigaldamine masinasse ning keskkonnamuutujate "JAVA_HOME" ja "JRE_HOME" defineerimine. Peale installeerimist võib kasutada skripte kataloogist $CATALINA_BASE/bin . Järgneb üks võimalik käivitamise ja peatamise näide, mis on kasutatav eelnevalt kirjeldatud käsitsi installeerimise juhul:
<pre>
/Library/Tomcat/bin/startup.sh
</pre>
ja peatamiseks
<pre>
/Library/Tomcat/bin/shutdown.sh
</pre>

===Näiteaplikatsiooni juurutamine===

Java veebiaplikatsiooni jagatakse hea tava kohaselt üheainsa veebiarhiivi failina. Siiski võib Tomcati juurutada ka lahtipakendatud olekus ("exploded") Java veebiaplikatsiooni.

====Käsitsi juurutamine ja mahavõtmine====

Näiteaplikatsiooni juurutamiseks lae selle veebiarhiivifail alla ning kopeeri oma konteineri juurutamiskataloogi 'webapps':
<pre>wget http://tomcat.apache.org/tomcat-8.0-doc/appdev/sample/sample.war
cp /Users/kristjanveskimae/downloads/sample.war /Library/Tomcat/webapps/sample.war</pre>

Kui konfiguratsioonifailis $CATALINA_BASE/conf/server.xml on märgendi "Host" atribuudi "autoDeploy" väärtus "true", installeerib ja uuendab Tomcat aplikatsioone dünaamiliselt töötamise ajal. Kui väärtuseks on "false", käib installeerimine staatiliselt ning serverisse juurutamiseks tuleb teha konteineri taaskäivitus. [http://tomcat.apache.org/tomcat-8.0-doc/manager-howto.html#Deploy_A_New_Application_from_a_Local_Path 2] Mõlemal juhul pakib konteiner arhiveeritud faili ise lahti samasse kausta $CATALINA_BASE/webapps ning ka juurutab selle. Tekkiv aplikatsioon on lokaalsest masinast seejärel kättesaadav aadressil http://localhost:8080/sample/ .

[[File:sample_app.png|400px]]

Veebirakenduse käsitsi mahavõtmiseks tuleb kustutada talle vastav dokumendipõhja kataloog "webapps" kataloogist. Samuti tuleks kustutada .war-fail olemaks kindel, et Tomcat ei rakenda uuel käivitamisel veebiaplikatsiooni veebiarhiivifailist. Veelgi lihtsam on mahavõtmine brauseriga haldusrakenduse kaudu.

Rakenduste baaskataloogi "webapps" asukohta saab muuta failis $CATALINA_BASE/conf/server.xml peremehepõhiselt määratava atribuudiga "appBase", sealjuures Tomcati vaikimisi peremees ehk "Host" on "localhost".

====Tomcati vahendid juurutamiseks====

Veebiaplikatsioonide juurutamine ja mahajuurutamine on võimalik ka kaughalduse teel tänu Tomcati internetipõhisele haldusrakendusele. Näiteks saab veebibrauserit kasutades teha serveri põhitoiminguid Tomcati enda HTML-põhise rakendusega "Tomcat Manager". Veebipõhine haldusrakendus töötab ka käsupõhise veebiteenusena, millele on valmis ehitatud Anti ja Maveni integratsioonid. Samuti eksisteerib käsurea kliendirakendus TCD (Tomcat Client Deployer). TCD ei kuulu Tomcati baaskoosseisu, kuid pakub peale serveri administreerimise tavatoimingute ka lisafunktsionaalsust nagu veebirakenduse kokkukompileerimine ja pakendamine. [http://tomcat.apache.org/tomcat-8.0-doc/manager-howto.html#Configuring_Manager_Application_Access 1]

====Haldurakendus "Tomcat Manager"====

Tomcati haldusrakendus "Tomcat Manager" (antud alamjaotuses lihtsalt haldusrakendus) on Tomcati enda veebiaplikatioon Tomcati brauseripõhiseks kaughalduseks, võimaldades muu hulgas järgnevat [http://tomcat.apache.org/tomcat-8.0-doc/manager-howto.html#Introduction 3]:
* Rakendada uue veebiaplikatsiooni war-faili üleslaadimisega;
* Näha kõiki rakendatud veebiaplikatsioone koos aktiivsete sessioonidega;
* Taasrakendada veebirakendust, näiteks veebiarhiivi pakitud klassifailide /WEB-INF/classes või teekide /WEB-INF/lib uuendamisel, kinnijooksmisel jms.;
* Peatada veebirakendust ilma serverist eemaldamata, samuti koos serverist eemaldamisega;
* Vaadata operatsioonisüsteemi ja Java parameetrite väärtusi;
* Näha kõiki saadaolevaid JNDI ressursse, k.a. andmebaasiühendusi, mis aitavad rakenduste programmeerijail defineerida <ResourceLink> elemendid web.xml konfiguratsioonifailis.

Tomcati installatsioon sisaldab haldusrakendust juba vaikimisi. Haldusrakenduse töölepanemiseks tuleb peremeesmasina konfiguratsioonikataloogi $CATALINA_BASE/conf/[enginename]/[hostname] lisada ka fail manager.xml. Vaikimisi valmiskonfigureeritud testrakendusel on see fail juba olemas asukohas $CATALINA_BASE/conf/Catalina/localhost/manager.xml . Rakendus asub vaikimisi aadressil http://[host]/manager/ , vaikimisi konfiguratsioone kasutades lahendub see asukohaks http://localhost:8080/manager/ .

====="Tomcat Manager" ligipääsu konfigureerimine=====

Vaikimisi on turvalisuspõhjustel ligipääs haldusrakendusele maha keeratud. Mismoodi täpselt kasutajatel ligipääsu võimaldada sõltub kasutatavast valdusest (realm). Vaikimisi defineerib $CATALINA_BASE/conf/server.xml valduseks "MemoryRealm". Vaikimisi loeb valdus "MemoryRealm" kasutajad failist $CATALINA_BASE/conf/tomcat-users.xml. Antud failis tuleb iga kasutaja defineerida omaette märgendiga <user>, mis näeb välja umbes järgmine:
<pre>
<user name="craig" password="secret" roles="manager-gui,manager-script" />
</pre>

Antud kasutajale on defineeritud korraga kaks rolli. Ligipääsu võimaldamiseks tulebki lihtsamal juhul kasutajatefailis $CATALINA_BASE/conf/tomcat-users.xml defineerida enda kasutaja. Kasutaja rolliks võib määrata näiteks "manager-gui", mis võimaldab ligipääsu kogu HTML liidese funktsionaalsusele.

Teised valdused on "JDBCRealm", mille puhul hoitakse kasutajatega seonduvat infot andmebaasis ja JNDIRealm, mille puhul kasutatakse lihtsustatud kataloogisirvimise protokolli (LDAP).
Lisaks saab haldusrakendusele keelata ligipääsu mujalt kui kindlaksmääratud IP-aadressidelt, lisades filtri "RemoteAddrValve" või "RemoteHostValve" konfigureerimisfaili manager.xml näiteks järgmiselt:
<pre>
<Context privileged="true">
<Valve className="org.apache.catalina.valves.RemoteAddrValve"
allow="127\.0\.0\.1"/>
</Context>
</pre>

=====Juurutamine ja mahavõtmine haldusrakendusega "Tomcat Manager"=====

Juurutamiseks lae kõigepealt veebiarhiivifail üles, kasutades esilehel asuvat sektsiooni "WAR file to deploy".
[[File:tomcat_manager_war_upload.png]]

Rakendus kuvatakse seejärel hallatavate rakenduste nimekirjas. Kui konteiner pole seadistatud üleslaetud aplikatsiooni kohe ka ise rakendama, tuleb vajutada "Start". Rakenduse peatamiseks kasuta "Stop", uuesti rakendamiseks "Redeploy" ja serverist eemaldamiseks "Undeploy".


[[File:tomcat_manager_apps_list.png|800px|Rakenduste nimekiri]]

==Näpunäiteid Tomcati reaalseks kasutamiseks==

===Juurutamise järjekord===

Tomcati käivitumisel juurutatakse aplikatsioonid sellises järjekorras:
# Konteinerisse kopeeritud kontekstikirjelduste järgi $CATALINA_BASE/conf/[EngineName]/[HostName]/[ApplicationName].xml ;
# Lahtipakitud rakendused "webapps" kataloogis;
# Pakitud rakenduste veebiarhiivid "webapps" kataloogis.

Seetõttu peaks käsitsi taasjuurutamisel kindluse mõttes eelnevalt kustutama rakenduse lahtipakitud dokumendipõhja kataloogi "webapps" kataloogist. Kontekstikirjelduse muutumisel tuleb jälgida, kas kirjeldus on juba kopeeritud serverisse ning vajadusel eelmise versiooni ümber muuta või kustutada.

===Reaalsele domeenile konfigureerimine===

Järgnevalt eeldame, et domeen ''www.minukodukas.ee'' on juba serverimasinaga seostatud. Et Tomcat hakkaks ka reaalselt Internetist tulevatele päringutele vastama, tuleb muuta failis $CATALINA_BASE/conf/server.xml konteinerile ''Catalina'' vastava teenusemärgendi sisu sarnaselt järgnevaga:

<pre>
<Service name="Catalina">
<Connector port="80" protocol="HTTP/1.1" connectionTimeout="20000" URIEncoding="UTF-8" redirectPort="8443" />
<Engine name="Catalina" defaultHost="www.minukodukas.ee">
<Host name="www.minukodukas.ee" appBase="webapps" unpackWARs="true" autoDeploy="false" deployOnStartup="false" xmlValidation="false" xmlNamespaceAware="false">
<Context path="" docBase="kodukas" debug="0" reloadable="true" />
</Host>
</Engine>
</Service>
</pre>

Ülal defineerime põhiliselt selle, et Tomcat kuulaks domeeni ''www.minukodukas.ee'' ja kasutaks HTTP päringute jaoks porti 80. Ühtlasti otsib Tomcat juurutatavat rakendust failist $CATALINA_BASE/webapps/kodukas.war. Kuna rajalisandiks on määratud tühi sõne (path=""), siis juurutataksegi aplikatsioon aadressile ''www.minukodukas.ee'' ilma rajalisandita (a'la ''www.minukodukas.ee/wiki''). Seetõttu pakitakse ka veebiarhiiv tegelikult lahti kataloogi $CATALINA_BASE/webapps/ROOT mitte kataloogi $CATALINA_BASE/webapps/kodukas nagu võiks eeldada.

===Käigultvahetus===

Võimaldamaks käigultvahetust (hot deployment) peab konteineri konfiguratsioonifailis $CATALINA_BASE/conf/server.xml olema peremehepõhise märgendi "Host" atribuudi "autoDeploy" väärtus "true". Sel juhul installeerib ja uuendab Tomcat aplikatsioone dünaamiliselt töötamise ajal. Kui väärtuseks on "false", käib installeerimine staatiliselt ning serverisse juurutamiseks tuleb teha konteineri taaskäivitus. Käigultvahetust saab määrata ka peremehe defineerimisel "Host Manager" rakendusega, mis on kättesaadav aadressil http://localhost:8080/host-manager/html . Kasutamiseks tuleb lisada oma kasutajale rolli "admin-gui" (vt. alajaotus ""Tomcat Manager" ligipääsu konfigureerimine").

[[File:host_manager_app.png]]

Käigultvahetust päästikuks on vaikimisi uuendatud veebiarhiivifaili või lahtipakitud veebirakenduse paigutamine "webapps" kataloogi. Käigultvahetuse päästikutele võib failis $CATALINA_BASE/conf/server.xml ka ise lisada kuulatavaid ressursse nagu web.xml muutmine või mõne teegifaili vahetamine (märgendis "Host").

===Klassiteekide väljatõstmine veebiarhiivifailist===

Kõik konteksti poolt kasutatavad Java klassiteegid võib pakendada veebiarhiivi sisse kataloogi "lib", kuid nii võib osutuda veebiarhiivi üleslaadimine ajakulukaks, eriti arenduskeskkonnas. Kui ei teki ohtu, et erinevad rakendused kasutavad sama teegi erinevaid versioone, siis on vahel parem lisada osa teeke konteineri kataloogi $CATALINA_BASE/libs, kust need tehakse siis konteineri poolt kättesaadavaks kõigile konteineris jooksutatavatele kontekstidele. Nii võib vähendada veebiarhiivi faili suurust märgatavalt, mis tõstab kokkuvõttes juurutamiskiirust ja ühes sellega programmeerijate tööviljakust.

===Mälukasutus===

Konteineri poolt kasutatavat mälu saab vaadata haldusrakendusest vajutades lingile "Server Status". Mälukasutus on toodud jaotuses "JVM", kus näidatakse nii maksimaalselt kättesaadavat mälu kui ka parasjagu reserveeritud mälu.

<pre>Free memory: 41.16 MB Total memory: 123.37 MB Max memory: 1027.56 MB</pre>

Mälu suurendamiseks võib näiteks defineerida skriptis $CATALINA_BASE/bin/catalina.sh muutuja "JAVA_OPTS" ning määrata Java mälukasutuse miinimum- ja maksimumväärtused sarnaselt järgnevatega:
<pre>
JAVA_OPTS="-Xms1536m -Xmx1536m -XX:NewSize=256m -XX:MaxNewSize=256m -XX:PermSize=256m -XX:MaxPermSize=256m"
</pre>

===Logifailid===

Vaikimisi defineerib Tomcat failiga $CATALINA_BASE/conf/logging.properties viis logerit, mis tekitavad viis eraldi logifaili.

{| style="background:#cccc99;color:black;width:80%;" border="1" cellpadding="5" cellspacing="0" align="center"
|+ Tomcati tekitatavad logifailid "logs" kataloogis
!Fail !! Kasutus
|- style="background:white; color:black"
| style="width:300px" |catalina.out
| Tomcati käivitus- ja peatamisskriptide väljund, samuti juurutatud rakenduste prindilaused System.out ja veaväljundid System.err
|- style="background:white; color:black"
| style="width:300px" |catalina.[yyyy]-[mm]-[dd].log
| Pööratud (rotated) logifail catalina.out
|- style="background:white; color:black"
| style="width:300px" |host-manager.[yyyy]-[mm]-[dd].log
| Logi peremehehalduse rakendusele (rakendus on kättesaadav kohalikust masinast aadressil http://localhost:8080/host-manager/html )
|- style="background:white; color:black"
| style="width:300px" |localhost.[yyyy]-[mm]-[dd].log
| Peremehe "localhost" logi; mitme virtuaalse peremehe korral tekitatakse igale peremehele oma logi
|- style="background:white; color:black"
| style="width:300px" |localhost_access_log.[yyyy]-[mm]-[dd].txt
| Konteinerisse Internetist saabunud päringute logi
|- style="background:white; color:black"
| style="width:300px" |manager.[yyyy]-[mm]-[dd].log
| Haldusrakenduse tegevuste logi
|}

===Viiteid===

Palju vajalikku võib leida [http://tomcat.apache.org/tomcat-8.0-doc/index.html Tomcat 8 dokumentatsioonist]

Lisaks üks viide põhjalikule Tomcati versioon seitsme ülevaatele: http://www.ntu.edu.sg/home/ehchua/programming/howto/Tomcat_More.html

= Kasutatud materjalid =

*http://tomcat.apache.org/tomcat-8.0-doc/index.html
*http://www.mulesoft.com/tomcat-deploy-procedures
*http://www.mkyong.com/tomcat/tomcat-javalangoutofmemoryerror-permgen-space/

[[Category: Operatsioonisüsteemide administreerimine ja sidumine]]

Tomcat

2014-01-02T21:33:33Z

Kveskima: /* Käsitsi juurutamine ja mahavõtmine */

==Autor==

Kristjan Veskimäe D32

2013

==Sissejuhatus==

Tomcat on vabalt kättesaadav server Java veebirakendustele. Põhimõtteliselt on tegemist Servlet/JSP spetsifikatsiooni toetava konteineriga. Kiire käivitumise ning rakenduste käigultvahetuse tõttu on Tomcat hea valik väiksemate ning keskmise suurusega Java veebirakenduste käitamiseks.

Antud töö kirjeldab Tomcati 8. versiooni. Põhiosa on üldiselt samasugune võrreldes paari eelmise versiooniga. Suuremad erinevused on versioonispetsiifilistes probleemides ja nende lahendamises, mida käesolev töö ei vaatle.

Töö vaatleb Tomcati paigaldamist ja seadistamist Unix-laadsesse keskkonda ning eeldab lugejalt algteadmisi sarnastes süsteemides. Tomcati on võimalik paigaldada ka Windows-keskkonda, kuid antud veebiserver eeldab kasutaja poolt käsureal töötamist ning Tomcati failihierarhias orienteerumist. Põhimõtteliselt on Java veebirakenduste arendamiseks IDE-abil võimalik siiski ka kasutada IDE-sse integreeritud Tomcati serverit - näiteks pakuvad sellist võimalust Eclipse EE ja NetBeans - kuid seda käesolev töö ei vaatle.

==Mõisted==

* '''Kontekst''' (context) - Tomcati mõistes üks konkreetne veebiaplikatsioon
* '''Konteiner''' (container) - veebiserver Tomcat ise
* '''Kontekstikirjeldus''' (context descriptor) - Tomcati-spetsiifiline konteksti konfiguratsioonimääratlus; peremehepõhine osa loetakse failist $CATALINA_HOME/conf/[enginename]/[hostname]/context.xml ja sellele lisatakse kontekstispetsiifilised täpsustused failist $CATALINA_BASE/conf/[enginename]/[hostname]/[webappname].xml; kontekstikirjeldus määrab näiteks nimed ressurssidele, sessioonihalduse parameetrid jmt. (olgu märgitud, et Tomcati varasemates versioonides sisaldusid kontekstikirjeldused põhikonfiguratsioonifailis server.xml)
* '''Dokumendipõhi''' (docBase) - kontekstile vastav kataloog Tomcati "webapps" kataloogis, mis tekib veebiaplikatsiooni serverisse rakendamisel
* '''Veebiarhiiv''' (Web application ARchive, war-file) - Java veebiaplikatsiooni jagatakse hea tava kohaselt selle üheainsa veebiarhiivi failina, mille laienditüübiks on "war". Tegemist on zip-protokolliga kokkupakitud kataloogiga, millel on Java veebirakenduste spetsifikatsioonile vastav ülesehitus. Siiski võib veebiaplikatsioon olla juurutamisel ka lahtipakendatud olekus (inglisekeelne termin on "war is exploded").

==Ülesehitus==

{| class="wikitable"
|+Kataloogid
|-
|style="color: green;" | $CATALINA_HOME
|baaskataloog, kuhu on Tomcat paigutatud
|-
|style="color: green;" | $CATALINA_BASE
|parasjagu töösoleva Tomcati eksemplari baaskataloog, mille alusel lahendatakse teed ülejäänud kataloogide ja failideni; ainult ühe kasutusel oleva Tomcati eksemplari puhul on see sama, mis $CATALINA_HOME

|-
|style="color: green;" | $CATALINA_BASE/bin
|serveri käivitus- ja abiskriptid
|-
|style="color: green;" | $CATALINA_BASE/conf
|konfiguratsioonifailid
|-
|style="color: green;" | $CATALINA_BASE/lib
|Tomcatile vaikimisi kättesaadavad Java klassiteegid (class libraries) ehk .jar-failid kuhu on Java kompileeritud kood kokku pakendatud
|-
|style="color: green;" | $CATALINA_BASE/logs
|logifailid paigutatakse vaikimisi siia
|-
|style="color: green;" | $CATALINA_BASE/webapps
|kataloog, kuhu paigutatakse serverisse juurutatavad veebiaplikatsioonid

|}

{| class="wikitable"
|+Mõned olulisemad failid
|-
|style="color: green;" | $CATALINA_BASE/bin/startup.sh
|serveri käivitusskript
|-
|style="color: green;" | $CATALINA_BASE/bin/shutdown.sh
|serveri peatusskript

|-
|style="color: green;" | $CATALINA_BASE/conf/server.xml
| konteineri peamine konfiguratsioonifail
|-
|style="color: green;" | $CATALINA_BASE/conf/[enginename]/[hostname]/[webappname].xml
|serveri administraatori jaoks konteinerisse endasse ümber kopeeritud rakendusepõhine kontekstikirjelduse konfiguratsioon failist $CATALINA_BASE/webapps/[ApplicationName]/META-INF/context.xml
|-
|style="color: green;" | $CATALINA_BASE/conf/[enginename]/[hostname]/context.xml
| fail, mis aitab administraatoril konteksti kohta käivat infot kirjeldada peremeesmasina-põhiselt ja halduseks mõeldud automaat-tööriistadel (näiteks Tomcat Manager ja TCD) oma tööd teha
|-
|style="color: green;" | $CATALINA_BASE/$CATALINA_BASE/conf/[enginename]/[hostname]/manager.xml
|fail, mis võimaldab lisada rakendustele ligipääsufiltreid
|-
|style="color: green;" | $CATALINA_BASE/webapps/[webappname]/META-INF/context.xml
|kontekstikirjeldusfail, mille veebirakenduse programmeerija on pakendanud oma aplikatsiooniga kaasa ning millega ta saab võimaluse kontekstikirjeldust omalt poolt mõjutada; kirjutatakse rakenduse uuestijuurutamisel üle, mistõttu administraator peaks muutma selle asemel konteinerisse ümber kopeeritud püsieksemplari $CATALINA_BASE/conf/[enginename]/[hostname]/context.xml
|-
|style="color: green;" | $CATALINA_BASE/webapps/[webappname]/WEB-INF/web.xml
|ka üks oluline Java veebiaplikatsiooni konfiguratsioonifail, mille pakendatakse koos veebiarhiiviga; enamasti muudab seda ainult programeerija; määrab muu hulgas millised aplikatsiooni osad vajavad autentimist või kui kiiresti veebisessioon aegub
|}

==Installeerimine==

===Installeerimine paketihalduriga===

<pre>
apt-cache search tomcat
apt-get install tomcat[version]-webapps
apt-get install tomcat[version]-admin
apt-get install tomcat[version]
</pre>

===Installeerimine käsitsi===

Paketihalduriga installeerides ei pruugi viimane Tomcati versioon olla kättesaadav ja see pakub ka vähem võimalusi kataloogide määramiseks jms. Käsitsi installeerimiseks tuleb laadida Tomcat kodulehelt alla. Lahtipakkimisel tekib kataloog, milles sisalduv fail "RUNNING.txt" on kõige kindlam allikas installeerimisel tekkivate probleemide vältimiseks ning lahendamiseks.

Vajaliku versiooni installeerimisfaili asukoha saab vaadata Tomcati kodulehelt sektsioonist "Download". Järgnevas näites installeerime Tomcati kõige uuema ebastabiilse kandidaatversiooni, mida näitab nimes sisalduv RC ehk "release candidate". Produktsioonikeskkonda tuleks siiski valida stabiilse versiooni. Käsitsi installeerimine on sarnane järgmisega:
<pre>
wget http://mirror.nexcess.net/apache/tomcat/tomcat-8/v8.0.0-RC5/bin/apache-tomcat-8.0.0-RC5.tar.gz
tar -zxvf apache-tomcat-8.0.0-RC5.tar.gz
mv /Users/kristjanveskimae/downloads/apache-tomcat-8.0.0-RC5 /usr/local/apache-tomcat-8.0.0-RC5
rm -f /Library/Tomcat
ln -s /usr/local/apache-tomcat-8.0.0-RC5/ /Library/Tomcat
chown -R kristjanveskimae /Library/Tomcat
chmod +x /Library/Tomcat/bin/*.sh
</pre>

==Käivitamine ja aplikatsiooni juurutamine==

===Konteineri käivitamine===

Tomcati käivitamise eelduseks on Java paigaldamine masinasse ning keskkonnamuutujate "JAVA_HOME" ja "JRE_HOME" defineerimine. Peale installeerimist võib kasutada skripte kataloogist $CATALINA_BASE/bin . Järgneb üks võimalik käivitamise ja peatamise näide, mis on kasutatav eelnevalt kirjeldatud käsitsi installeerimise juhul:
<pre>
/Library/Tomcat/bin/startup.sh
</pre>
ja peatamiseks
<pre>
/Library/Tomcat/bin/shutdown.sh
</pre>

===Näiteaplikatsiooni juurutamine===

Java veebiaplikatsiooni jagatakse hea tava kohaselt üheainsa veebiarhiivi failina. Siiski võib Tomcati juurutada ka lahtipakendatud olekus ("exploded") Java veebiaplikatsiooni.

====Käsitsi juurutamine ja mahavõtmine====

Näiteaplikatsiooni juurutamiseks lae selle veebiarhiivifail alla ning kopeeri oma konteineri juurutamiskataloogi 'webapps':
<pre>wget http://tomcat.apache.org/tomcat-8.0-doc/appdev/sample/sample.war
cp /Users/kristjanveskimae/downloads/sample.war /Library/Tomcat/webapps/sample.war</pre>

Kui konfiguratsioonifailis $CATALINA_BASE/conf/server.xml on märgendi "Host" atribuudi "autoDeploy" väärtus "true", installeerib ja uuendab Tomcat aplikatsioone dünaamiliselt töötamise ajal. Kui väärtuseks on "false", käib installeerimine staatiliselt ning serverisse juurutamiseks tuleb teha konteineri taaskäivitus. [http://tomcat.apache.org/tomcat-8.0-doc/manager-howto.html#Deploy_A_New_Application_from_a_Local_Path 2] Mõlemal juhul pakib konteiner arhiveeritud faili ise lahti samasse kausta $CATALINA_BASE/webapps ning ka juurutab selle. Tekkiv aplikatsioon on lokaalsest masinast seejärel kättesaadav aadressil http://localhost:8080/sample/ .

[[File:sample_app.png|400px]]

Veebirakenduse käsitsi mahavõtmiseks tuleb kustutada talle vastav dokumendipõhja kataloog "webapps" kataloogist. Samuti tuleks kustutada .war-fail olemaks kindel, et Tomcat ei rakenda uuel käivitamisel veebiaplikatsiooni veebiarhiivifailist. Veelgi lihtsam on mahavõtmine brauseriga haldusrakenduse kaudu.

Rakenduste baaskataloogi "webapps" asukohta saab muuta failis $CATALINA_BASE/conf/server.xml peremehepõhiselt määratava atribuudiga "appBase", sealjuures Tomcati vaikimisi peremees ehk "Host" on "localhost".

====Tomcati vahendid juurutamiseks====

Veebiaplikatsioonide juurutamine ja mahajuurutamine on võimalik ka kaughalduse teel tänu Tomcati internetipõhisele haldusrakendusele. Näiteks saab veebibrauserit kasutades teha serveri põhitoiminguid Tomcati enda HTML-põhise rakendusega "Tomcat Manager". Veebipõhine haldusrakendus töötab ka käsupõhise veebiteenusena, millele on valmis ehitatud Anti ja Maveni integratsioonid. Samuti eksisteerib käsurea kliendirakendus TCD (Tomcat Client Deployer). TCD ei kuulu Tomcati baaskoosseisu, kuid pakub peale serveri administreerimise tavatoimingute ka lisafunktsionaalsust nagu veebirakenduse kokkukompileerimine ja pakendamine. [http://tomcat.apache.org/tomcat-8.0-doc/manager-howto.html#Configuring_Manager_Application_Access 1]

====Haldurakendus "Tomcat Manager"====

Tomcati haldusrakendus "Tomcat Manager" (antud alamjaotuses lihtsalt haldusrakendus) on Tomcati enda veebiaplikatioon Tomcati brauseripõhiseks kaughalduseks, võimaldades muu hulgas järgnevat:
* Rakendada uue veebiaplikatsiooni war-faili üleslaadimisega;
* Näha kõiki rakendatud veebiaplikatsioone koos aktiivsete sessioonidega;
* Taasrakendada veebirakendust, näiteks veebiarhiivi pakitud klassifailide /WEB-INF/classes või teekide /WEB-INF/lib uuendamisel, kinnijooksmisel jms.;
* Peatada veebirakendust ilma serverist eemaldamata, samuti koos serverist eemaldamisega;
* Vaadata operatsioonisüsteemi ja Java parameetrite väärtusi;
* Näha kõiki saadaolevaid JNDI ressursse, k.a. andmebaasiühendusi, mis aitavad rakenduste programmeerijail defineerida <ResourceLink> elemendid web.xml konfiguratsioonifailis.

Tomcati installatsioon sisaldab haldusrakendust juba vaikimisi. Haldusrakenduse töölepanemiseks tuleb peremeesmasina konfiguratsioonikataloogi $CATALINA_BASE/conf/[enginename]/[hostname] lisada ka fail manager.xml. Vaikimisi valmiskonfigureeritud testrakendusel on see fail juba olemas asukohas $CATALINA_BASE/conf/Catalina/localhost/manager.xml . Rakendus asub vaikimisi aadressil http://[host]/manager/ , vaikimisi konfiguratsioone kasutades lahendub see asukohaks http://localhost:8080/manager/ .

====="Tomcat Manager" ligipääsu konfigureerimine=====

Vaikimisi on turvalisuspõhjustel ligipääs haldusrakendusele maha keeratud. Mismoodi täpselt kasutajatel ligipääsu võimaldada sõltub kasutatavast valdusest (realm). Vaikimisi defineerib $CATALINA_BASE/conf/server.xml valduseks "MemoryRealm". Vaikimisi loeb valdus "MemoryRealm" kasutajad failist $CATALINA_BASE/conf/tomcat-users.xml. Antud failis tuleb iga kasutaja defineerida omaette märgendiga <user>, mis näeb välja umbes järgmine:
<pre>
<user name="craig" password="secret" roles="manager-gui,manager-script" />
</pre>

Antud kasutajale on defineeritud korraga kaks rolli. Ligipääsu võimaldamiseks tulebki lihtsamal juhul kasutajatefailis $CATALINA_BASE/conf/tomcat-users.xml defineerida enda kasutaja. Kasutaja rolliks võib määrata näiteks "manager-gui", mis võimaldab ligipääsu kogu HTML liidese funktsionaalsusele.

Teised valdused on "JDBCRealm", mille puhul hoitakse kasutajatega seonduvat infot andmebaasis ja JNDIRealm, mille puhul kasutatakse lihtsustatud kataloogisirvimise protokolli (LDAP).
Lisaks saab haldusrakendusele keelata ligipääsu mujalt kui kindlaksmääratud IP-aadressidelt, lisades filtri "RemoteAddrValve" või "RemoteHostValve" konfigureerimisfaili manager.xml näiteks järgmiselt:
<pre>
<Context privileged="true">
<Valve className="org.apache.catalina.valves.RemoteAddrValve"
allow="127\.0\.0\.1"/>
</Context>
</pre>

=====Juurutamine ja mahavõtmine haldusrakendusega "Tomcat Manager"=====

Juurutamiseks lae kõigepealt veebiarhiivifail üles, kasutades esilehel asuvat sektsiooni "WAR file to deploy".
[[File:tomcat_manager_war_upload.png]]

Rakendus kuvatakse seejärel hallatavate rakenduste nimekirjas. Kui konteiner pole seadistatud üleslaetud aplikatsiooni kohe ka ise rakendama, tuleb vajutada "Start". Rakenduse peatamiseks kasuta "Stop", uuesti rakendamiseks "Redeploy" ja serverist eemaldamiseks "Undeploy".


[[File:tomcat_manager_apps_list.png|800px|Rakenduste nimekiri]]

==Näpunäiteid Tomcati reaalseks kasutamiseks==

===Juurutamise järjekord===

Tomcati käivitumisel juurutatakse aplikatsioonid sellises järjekorras:
# Konteinerisse kopeeritud kontekstikirjelduste järgi $CATALINA_BASE/conf/[EngineName]/[HostName]/[ApplicationName].xml ;
# Lahtipakitud rakendused "webapps" kataloogis;
# Pakitud rakenduste veebiarhiivid "webapps" kataloogis.

Seetõttu peaks käsitsi taasjuurutamisel kindluse mõttes eelnevalt kustutama rakenduse lahtipakitud dokumendipõhja kataloogi "webapps" kataloogist. Kontekstikirjelduse muutumisel tuleb jälgida, kas kirjeldus on juba kopeeritud serverisse ning vajadusel eelmise versiooni ümber muuta või kustutada.

===Reaalsele domeenile konfigureerimine===

Järgnevalt eeldame, et domeen ''www.minukodukas.ee'' on juba serverimasinaga seostatud. Et Tomcat hakkaks ka reaalselt Internetist tulevatele päringutele vastama, tuleb muuta failis $CATALINA_BASE/conf/server.xml konteinerile ''Catalina'' vastava teenusemärgendi sisu sarnaselt järgnevaga:

<pre>
<Service name="Catalina">
<Connector port="80" protocol="HTTP/1.1" connectionTimeout="20000" URIEncoding="UTF-8" redirectPort="8443" />
<Engine name="Catalina" defaultHost="www.minukodukas.ee">
<Host name="www.minukodukas.ee" appBase="webapps" unpackWARs="true" autoDeploy="false" deployOnStartup="false" xmlValidation="false" xmlNamespaceAware="false">
<Context path="" docBase="kodukas" debug="0" reloadable="true" />
</Host>
</Engine>
</Service>
</pre>

Ülal defineerime põhiliselt selle, et Tomcat kuulaks domeeni ''www.minukodukas.ee'' ja kasutaks HTTP päringute jaoks porti 80. Ühtlasti otsib Tomcat juurutatavat rakendust failist $CATALINA_BASE/webapps/kodukas.war. Kuna rajalisandiks on määratud tühi sõne (path=""), siis juurutataksegi aplikatsioon aadressile ''www.minukodukas.ee'' ilma rajalisandita (a'la ''www.minukodukas.ee/wiki''). Seetõttu pakitakse ka veebiarhiiv tegelikult lahti kataloogi $CATALINA_BASE/webapps/ROOT mitte kataloogi $CATALINA_BASE/webapps/kodukas nagu võiks eeldada.

===Käigultvahetus===

Võimaldamaks käigultvahetust (hot deployment) peab konteineri konfiguratsioonifailis $CATALINA_BASE/conf/server.xml olema peremehepõhise märgendi "Host" atribuudi "autoDeploy" väärtus "true". Sel juhul installeerib ja uuendab Tomcat aplikatsioone dünaamiliselt töötamise ajal. Kui väärtuseks on "false", käib installeerimine staatiliselt ning serverisse juurutamiseks tuleb teha konteineri taaskäivitus. Käigultvahetust saab määrata ka peremehe defineerimisel "Host Manager" rakendusega, mis on kättesaadav aadressil http://localhost:8080/host-manager/html . Kasutamiseks tuleb lisada oma kasutajale rolli "admin-gui" (vt. alajaotus ""Tomcat Manager" ligipääsu konfigureerimine").

[[File:host_manager_app.png]]

Käigultvahetust päästikuks on vaikimisi uuendatud veebiarhiivifaili või lahtipakitud veebirakenduse paigutamine "webapps" kataloogi. Käigultvahetuse päästikutele võib failis $CATALINA_BASE/conf/server.xml ka ise lisada kuulatavaid ressursse nagu web.xml muutmine või mõne teegifaili vahetamine (märgendis "Host").

===Klassiteekide väljatõstmine veebiarhiivifailist===

Kõik konteksti poolt kasutatavad Java klassiteegid võib pakendada veebiarhiivi sisse kataloogi "lib", kuid nii võib osutuda veebiarhiivi üleslaadimine ajakulukaks, eriti arenduskeskkonnas. Kui ei teki ohtu, et erinevad rakendused kasutavad sama teegi erinevaid versioone, siis on vahel parem lisada osa teeke konteineri kataloogi $CATALINA_BASE/libs, kust need tehakse siis konteineri poolt kättesaadavaks kõigile konteineris jooksutatavatele kontekstidele. Nii võib vähendada veebiarhiivi faili suurust märgatavalt, mis tõstab kokkuvõttes juurutamiskiirust ja ühes sellega programmeerijate tööviljakust.

===Mälukasutus===

Konteineri poolt kasutatavat mälu saab vaadata haldusrakendusest vajutades lingile "Server Status". Mälukasutus on toodud jaotuses "JVM", kus näidatakse nii maksimaalselt kättesaadavat mälu kui ka parasjagu reserveeritud mälu.

<pre>Free memory: 41.16 MB Total memory: 123.37 MB Max memory: 1027.56 MB</pre>

Mälu suurendamiseks võib näiteks defineerida skriptis $CATALINA_BASE/bin/catalina.sh muutuja "JAVA_OPTS" ning määrata Java mälukasutuse miinimum- ja maksimumväärtused sarnaselt järgnevatega:
<pre>
JAVA_OPTS="-Xms1536m -Xmx1536m -XX:NewSize=256m -XX:MaxNewSize=256m -XX:PermSize=256m -XX:MaxPermSize=256m"
</pre>

===Logifailid===

Vaikimisi defineerib Tomcat failiga $CATALINA_BASE/conf/logging.properties viis logerit, mis tekitavad viis eraldi logifaili.

{| style="background:#cccc99;color:black;width:80%;" border="1" cellpadding="5" cellspacing="0" align="center"
|+ Tomcati tekitatavad logifailid "logs" kataloogis
!Fail !! Kasutus
|- style="background:white; color:black"
| style="width:300px" |catalina.out
| Tomcati käivitus- ja peatamisskriptide väljund, samuti juurutatud rakenduste prindilaused System.out ja veaväljundid System.err
|- style="background:white; color:black"
| style="width:300px" |catalina.[yyyy]-[mm]-[dd].log
| Pööratud (rotated) logifail catalina.out
|- style="background:white; color:black"
| style="width:300px" |host-manager.[yyyy]-[mm]-[dd].log
| Logi peremehehalduse rakendusele (rakendus on kättesaadav kohalikust masinast aadressil http://localhost:8080/host-manager/html )
|- style="background:white; color:black"
| style="width:300px" |localhost.[yyyy]-[mm]-[dd].log
| Peremehe "localhost" logi; mitme virtuaalse peremehe korral tekitatakse igale peremehele oma logi
|- style="background:white; color:black"
| style="width:300px" |localhost_access_log.[yyyy]-[mm]-[dd].txt
| Konteinerisse Internetist saabunud päringute logi
|- style="background:white; color:black"
| style="width:300px" |manager.[yyyy]-[mm]-[dd].log
| Haldusrakenduse tegevuste logi
|}

===Viiteid===

Palju vajalikku võib leida [http://tomcat.apache.org/tomcat-8.0-doc/index.html Tomcat 8 dokumentatsioonist]

Lisaks üks viide põhjalikule Tomcati versioon seitsme ülevaatele: http://www.ntu.edu.sg/home/ehchua/programming/howto/Tomcat_More.html

= Kasutatud materjalid =

*http://tomcat.apache.org/tomcat-8.0-doc/index.html
*http://www.mulesoft.com/tomcat-deploy-procedures
*http://www.mkyong.com/tomcat/tomcat-javalangoutofmemoryerror-permgen-space/

[[Category: Operatsioonisüsteemide administreerimine ja sidumine]]

Tomcat

2014-01-02T21:30:49Z

Kveskima: /* Tomcati vahendid juurutamiseks */

==Autor==

Kristjan Veskimäe D32

2013

==Sissejuhatus==

Tomcat on vabalt kättesaadav server Java veebirakendustele. Põhimõtteliselt on tegemist Servlet/JSP spetsifikatsiooni toetava konteineriga. Kiire käivitumise ning rakenduste käigultvahetuse tõttu on Tomcat hea valik väiksemate ning keskmise suurusega Java veebirakenduste käitamiseks.

Antud töö kirjeldab Tomcati 8. versiooni. Põhiosa on üldiselt samasugune võrreldes paari eelmise versiooniga. Suuremad erinevused on versioonispetsiifilistes probleemides ja nende lahendamises, mida käesolev töö ei vaatle.

Töö vaatleb Tomcati paigaldamist ja seadistamist Unix-laadsesse keskkonda ning eeldab lugejalt algteadmisi sarnastes süsteemides. Tomcati on võimalik paigaldada ka Windows-keskkonda, kuid antud veebiserver eeldab kasutaja poolt käsureal töötamist ning Tomcati failihierarhias orienteerumist. Põhimõtteliselt on Java veebirakenduste arendamiseks IDE-abil võimalik siiski ka kasutada IDE-sse integreeritud Tomcati serverit - näiteks pakuvad sellist võimalust Eclipse EE ja NetBeans - kuid seda käesolev töö ei vaatle.

==Mõisted==

* '''Kontekst''' (context) - Tomcati mõistes üks konkreetne veebiaplikatsioon
* '''Konteiner''' (container) - veebiserver Tomcat ise
* '''Kontekstikirjeldus''' (context descriptor) - Tomcati-spetsiifiline konteksti konfiguratsioonimääratlus; peremehepõhine osa loetakse failist $CATALINA_HOME/conf/[enginename]/[hostname]/context.xml ja sellele lisatakse kontekstispetsiifilised täpsustused failist $CATALINA_BASE/conf/[enginename]/[hostname]/[webappname].xml; kontekstikirjeldus määrab näiteks nimed ressurssidele, sessioonihalduse parameetrid jmt. (olgu märgitud, et Tomcati varasemates versioonides sisaldusid kontekstikirjeldused põhikonfiguratsioonifailis server.xml)
* '''Dokumendipõhi''' (docBase) - kontekstile vastav kataloog Tomcati "webapps" kataloogis, mis tekib veebiaplikatsiooni serverisse rakendamisel
* '''Veebiarhiiv''' (Web application ARchive, war-file) - Java veebiaplikatsiooni jagatakse hea tava kohaselt selle üheainsa veebiarhiivi failina, mille laienditüübiks on "war". Tegemist on zip-protokolliga kokkupakitud kataloogiga, millel on Java veebirakenduste spetsifikatsioonile vastav ülesehitus. Siiski võib veebiaplikatsioon olla juurutamisel ka lahtipakendatud olekus (inglisekeelne termin on "war is exploded").

==Ülesehitus==

{| class="wikitable"
|+Kataloogid
|-
|style="color: green;" | $CATALINA_HOME
|baaskataloog, kuhu on Tomcat paigutatud
|-
|style="color: green;" | $CATALINA_BASE
|parasjagu töösoleva Tomcati eksemplari baaskataloog, mille alusel lahendatakse teed ülejäänud kataloogide ja failideni; ainult ühe kasutusel oleva Tomcati eksemplari puhul on see sama, mis $CATALINA_HOME

|-
|style="color: green;" | $CATALINA_BASE/bin
|serveri käivitus- ja abiskriptid
|-
|style="color: green;" | $CATALINA_BASE/conf
|konfiguratsioonifailid
|-
|style="color: green;" | $CATALINA_BASE/lib
|Tomcatile vaikimisi kättesaadavad Java klassiteegid (class libraries) ehk .jar-failid kuhu on Java kompileeritud kood kokku pakendatud
|-
|style="color: green;" | $CATALINA_BASE/logs
|logifailid paigutatakse vaikimisi siia
|-
|style="color: green;" | $CATALINA_BASE/webapps
|kataloog, kuhu paigutatakse serverisse juurutatavad veebiaplikatsioonid

|}

{| class="wikitable"
|+Mõned olulisemad failid
|-
|style="color: green;" | $CATALINA_BASE/bin/startup.sh
|serveri käivitusskript
|-
|style="color: green;" | $CATALINA_BASE/bin/shutdown.sh
|serveri peatusskript

|-
|style="color: green;" | $CATALINA_BASE/conf/server.xml
| konteineri peamine konfiguratsioonifail
|-
|style="color: green;" | $CATALINA_BASE/conf/[enginename]/[hostname]/[webappname].xml
|serveri administraatori jaoks konteinerisse endasse ümber kopeeritud rakendusepõhine kontekstikirjelduse konfiguratsioon failist $CATALINA_BASE/webapps/[ApplicationName]/META-INF/context.xml
|-
|style="color: green;" | $CATALINA_BASE/conf/[enginename]/[hostname]/context.xml
| fail, mis aitab administraatoril konteksti kohta käivat infot kirjeldada peremeesmasina-põhiselt ja halduseks mõeldud automaat-tööriistadel (näiteks Tomcat Manager ja TCD) oma tööd teha
|-
|style="color: green;" | $CATALINA_BASE/$CATALINA_BASE/conf/[enginename]/[hostname]/manager.xml
|fail, mis võimaldab lisada rakendustele ligipääsufiltreid
|-
|style="color: green;" | $CATALINA_BASE/webapps/[webappname]/META-INF/context.xml
|kontekstikirjeldusfail, mille veebirakenduse programmeerija on pakendanud oma aplikatsiooniga kaasa ning millega ta saab võimaluse kontekstikirjeldust omalt poolt mõjutada; kirjutatakse rakenduse uuestijuurutamisel üle, mistõttu administraator peaks muutma selle asemel konteinerisse ümber kopeeritud püsieksemplari $CATALINA_BASE/conf/[enginename]/[hostname]/context.xml
|-
|style="color: green;" | $CATALINA_BASE/webapps/[webappname]/WEB-INF/web.xml
|ka üks oluline Java veebiaplikatsiooni konfiguratsioonifail, mille pakendatakse koos veebiarhiiviga; enamasti muudab seda ainult programeerija; määrab muu hulgas millised aplikatsiooni osad vajavad autentimist või kui kiiresti veebisessioon aegub
|}

==Installeerimine==

===Installeerimine paketihalduriga===

<pre>
apt-cache search tomcat
apt-get install tomcat[version]-webapps
apt-get install tomcat[version]-admin
apt-get install tomcat[version]
</pre>

===Installeerimine käsitsi===

Paketihalduriga installeerides ei pruugi viimane Tomcati versioon olla kättesaadav ja see pakub ka vähem võimalusi kataloogide määramiseks jms. Käsitsi installeerimiseks tuleb laadida Tomcat kodulehelt alla. Lahtipakkimisel tekib kataloog, milles sisalduv fail "RUNNING.txt" on kõige kindlam allikas installeerimisel tekkivate probleemide vältimiseks ning lahendamiseks.

Vajaliku versiooni installeerimisfaili asukoha saab vaadata Tomcati kodulehelt sektsioonist "Download". Järgnevas näites installeerime Tomcati kõige uuema ebastabiilse kandidaatversiooni, mida näitab nimes sisalduv RC ehk "release candidate". Produktsioonikeskkonda tuleks siiski valida stabiilse versiooni. Käsitsi installeerimine on sarnane järgmisega:
<pre>
wget http://mirror.nexcess.net/apache/tomcat/tomcat-8/v8.0.0-RC5/bin/apache-tomcat-8.0.0-RC5.tar.gz
tar -zxvf apache-tomcat-8.0.0-RC5.tar.gz
mv /Users/kristjanveskimae/downloads/apache-tomcat-8.0.0-RC5 /usr/local/apache-tomcat-8.0.0-RC5
rm -f /Library/Tomcat
ln -s /usr/local/apache-tomcat-8.0.0-RC5/ /Library/Tomcat
chown -R kristjanveskimae /Library/Tomcat
chmod +x /Library/Tomcat/bin/*.sh
</pre>

==Käivitamine ja aplikatsiooni juurutamine==

===Konteineri käivitamine===

Tomcati käivitamise eelduseks on Java paigaldamine masinasse ning keskkonnamuutujate "JAVA_HOME" ja "JRE_HOME" defineerimine. Peale installeerimist võib kasutada skripte kataloogist $CATALINA_BASE/bin . Järgneb üks võimalik käivitamise ja peatamise näide, mis on kasutatav eelnevalt kirjeldatud käsitsi installeerimise juhul:
<pre>
/Library/Tomcat/bin/startup.sh
</pre>
ja peatamiseks
<pre>
/Library/Tomcat/bin/shutdown.sh
</pre>

===Näiteaplikatsiooni juurutamine===

Java veebiaplikatsiooni jagatakse hea tava kohaselt üheainsa veebiarhiivi failina. Siiski võib Tomcati juurutada ka lahtipakendatud olekus ("exploded") Java veebiaplikatsiooni.

====Käsitsi juurutamine ja mahavõtmine====

Näiteaplikatsiooni juurutamiseks lae selle veebiarhiivifail alla ning kopeeri oma konteineri juurutamiskataloogi 'webapps':
<pre>wget http://tomcat.apache.org/tomcat-8.0-doc/appdev/sample/sample.war
cp /Users/kristjanveskimae/downloads/sample.war /Library/Tomcat/webapps/sample.war</pre>

Kui konfiguratsioonifailis $CATALINA_BASE/conf/server.xml on märgendi "Host" atribuudi "autoDeploy" väärtus "true", installeerib ja uuendab Tomcat aplikatsioone dünaamiliselt töötamise ajal. Kui väärtuseks on "false", käib installeerimine staatiliselt ning serverisse juurutamiseks tuleb teha konteineri taaskäivitus. Mõlemal juhul pakib konteiner arhiveeritud faili ise lahti samasse kausta $CATALINA_BASE/webapps ning ka juurutab selle. Tekkiv aplikatsioon on lokaalsest masinast seejärel kättesaadav aadressil http://localhost:8080/sample/ .

[[File:sample_app.png|400px]]

Veebirakenduse käsitsi mahavõtmiseks tuleb kustutada talle vastav dokumendipõhja kataloog "webapps" kataloogist. Samuti tuleks kustutada .war-fail olemaks kindel, et Tomcat ei rakenda uuel käivitamisel veebiaplikatsiooni veebiarhiivifailist. Veelgi lihtsam on mahavõtmine brauseriga haldusrakenduse kaudu.

Rakenduste baaskataloogi "webapps" asukohta saab muuta failis $CATALINA_BASE/conf/server.xml peremehepõhiselt määratava atribuudiga "appBase", sealjuures Tomcati vaikimisi peremees ehk "Host" on "localhost".

====Tomcati vahendid juurutamiseks====

Veebiaplikatsioonide juurutamine ja mahajuurutamine on võimalik ka kaughalduse teel tänu Tomcati internetipõhisele haldusrakendusele. Näiteks saab veebibrauserit kasutades teha serveri põhitoiminguid Tomcati enda HTML-põhise rakendusega "Tomcat Manager". Veebipõhine haldusrakendus töötab ka käsupõhise veebiteenusena, millele on valmis ehitatud Anti ja Maveni integratsioonid. Samuti eksisteerib käsurea kliendirakendus TCD (Tomcat Client Deployer). TCD ei kuulu Tomcati baaskoosseisu, kuid pakub peale serveri administreerimise tavatoimingute ka lisafunktsionaalsust nagu veebirakenduse kokkukompileerimine ja pakendamine. [http://tomcat.apache.org/tomcat-8.0-doc/manager-howto.html#Configuring_Manager_Application_Access 1]

====Haldurakendus "Tomcat Manager"====

Tomcati haldusrakendus "Tomcat Manager" (antud alamjaotuses lihtsalt haldusrakendus) on Tomcati enda veebiaplikatioon Tomcati brauseripõhiseks kaughalduseks, võimaldades muu hulgas järgnevat:
* Rakendada uue veebiaplikatsiooni war-faili üleslaadimisega;
* Näha kõiki rakendatud veebiaplikatsioone koos aktiivsete sessioonidega;
* Taasrakendada veebirakendust, näiteks veebiarhiivi pakitud klassifailide /WEB-INF/classes või teekide /WEB-INF/lib uuendamisel, kinnijooksmisel jms.;
* Peatada veebirakendust ilma serverist eemaldamata, samuti koos serverist eemaldamisega;
* Vaadata operatsioonisüsteemi ja Java parameetrite väärtusi;
* Näha kõiki saadaolevaid JNDI ressursse, k.a. andmebaasiühendusi, mis aitavad rakenduste programmeerijail defineerida <ResourceLink> elemendid web.xml konfiguratsioonifailis.

Tomcati installatsioon sisaldab haldusrakendust juba vaikimisi. Haldusrakenduse töölepanemiseks tuleb peremeesmasina konfiguratsioonikataloogi $CATALINA_BASE/conf/[enginename]/[hostname] lisada ka fail manager.xml. Vaikimisi valmiskonfigureeritud testrakendusel on see fail juba olemas asukohas $CATALINA_BASE/conf/Catalina/localhost/manager.xml . Rakendus asub vaikimisi aadressil http://[host]/manager/ , vaikimisi konfiguratsioone kasutades lahendub see asukohaks http://localhost:8080/manager/ .

====="Tomcat Manager" ligipääsu konfigureerimine=====

Vaikimisi on turvalisuspõhjustel ligipääs haldusrakendusele maha keeratud. Mismoodi täpselt kasutajatel ligipääsu võimaldada sõltub kasutatavast valdusest (realm). Vaikimisi defineerib $CATALINA_BASE/conf/server.xml valduseks "MemoryRealm". Vaikimisi loeb valdus "MemoryRealm" kasutajad failist $CATALINA_BASE/conf/tomcat-users.xml. Antud failis tuleb iga kasutaja defineerida omaette märgendiga <user>, mis näeb välja umbes järgmine:
<pre>
<user name="craig" password="secret" roles="manager-gui,manager-script" />
</pre>

Antud kasutajale on defineeritud korraga kaks rolli. Ligipääsu võimaldamiseks tulebki lihtsamal juhul kasutajatefailis $CATALINA_BASE/conf/tomcat-users.xml defineerida enda kasutaja. Kasutaja rolliks võib määrata näiteks "manager-gui", mis võimaldab ligipääsu kogu HTML liidese funktsionaalsusele.

Teised valdused on "JDBCRealm", mille puhul hoitakse kasutajatega seonduvat infot andmebaasis ja JNDIRealm, mille puhul kasutatakse lihtsustatud kataloogisirvimise protokolli (LDAP).
Lisaks saab haldusrakendusele keelata ligipääsu mujalt kui kindlaksmääratud IP-aadressidelt, lisades filtri "RemoteAddrValve" või "RemoteHostValve" konfigureerimisfaili manager.xml näiteks järgmiselt:
<pre>
<Context privileged="true">
<Valve className="org.apache.catalina.valves.RemoteAddrValve"
allow="127\.0\.0\.1"/>
</Context>
</pre>

=====Juurutamine ja mahavõtmine haldusrakendusega "Tomcat Manager"=====

Juurutamiseks lae kõigepealt veebiarhiivifail üles, kasutades esilehel asuvat sektsiooni "WAR file to deploy".
[[File:tomcat_manager_war_upload.png]]

Rakendus kuvatakse seejärel hallatavate rakenduste nimekirjas. Kui konteiner pole seadistatud üleslaetud aplikatsiooni kohe ka ise rakendama, tuleb vajutada "Start". Rakenduse peatamiseks kasuta "Stop", uuesti rakendamiseks "Redeploy" ja serverist eemaldamiseks "Undeploy".


[[File:tomcat_manager_apps_list.png|800px|Rakenduste nimekiri]]

==Näpunäiteid Tomcati reaalseks kasutamiseks==

===Juurutamise järjekord===

Tomcati käivitumisel juurutatakse aplikatsioonid sellises järjekorras:
# Konteinerisse kopeeritud kontekstikirjelduste järgi $CATALINA_BASE/conf/[EngineName]/[HostName]/[ApplicationName].xml ;
# Lahtipakitud rakendused "webapps" kataloogis;
# Pakitud rakenduste veebiarhiivid "webapps" kataloogis.

Seetõttu peaks käsitsi taasjuurutamisel kindluse mõttes eelnevalt kustutama rakenduse lahtipakitud dokumendipõhja kataloogi "webapps" kataloogist. Kontekstikirjelduse muutumisel tuleb jälgida, kas kirjeldus on juba kopeeritud serverisse ning vajadusel eelmise versiooni ümber muuta või kustutada.

===Reaalsele domeenile konfigureerimine===

Järgnevalt eeldame, et domeen ''www.minukodukas.ee'' on juba serverimasinaga seostatud. Et Tomcat hakkaks ka reaalselt Internetist tulevatele päringutele vastama, tuleb muuta failis $CATALINA_BASE/conf/server.xml konteinerile ''Catalina'' vastava teenusemärgendi sisu sarnaselt järgnevaga:

<pre>
<Service name="Catalina">
<Connector port="80" protocol="HTTP/1.1" connectionTimeout="20000" URIEncoding="UTF-8" redirectPort="8443" />
<Engine name="Catalina" defaultHost="www.minukodukas.ee">
<Host name="www.minukodukas.ee" appBase="webapps" unpackWARs="true" autoDeploy="false" deployOnStartup="false" xmlValidation="false" xmlNamespaceAware="false">
<Context path="" docBase="kodukas" debug="0" reloadable="true" />
</Host>
</Engine>
</Service>
</pre>

Ülal defineerime põhiliselt selle, et Tomcat kuulaks domeeni ''www.minukodukas.ee'' ja kasutaks HTTP päringute jaoks porti 80. Ühtlasti otsib Tomcat juurutatavat rakendust failist $CATALINA_BASE/webapps/kodukas.war. Kuna rajalisandiks on määratud tühi sõne (path=""), siis juurutataksegi aplikatsioon aadressile ''www.minukodukas.ee'' ilma rajalisandita (a'la ''www.minukodukas.ee/wiki''). Seetõttu pakitakse ka veebiarhiiv tegelikult lahti kataloogi $CATALINA_BASE/webapps/ROOT mitte kataloogi $CATALINA_BASE/webapps/kodukas nagu võiks eeldada.

===Käigultvahetus===

Võimaldamaks käigultvahetust (hot deployment) peab konteineri konfiguratsioonifailis $CATALINA_BASE/conf/server.xml olema peremehepõhise märgendi "Host" atribuudi "autoDeploy" väärtus "true". Sel juhul installeerib ja uuendab Tomcat aplikatsioone dünaamiliselt töötamise ajal. Kui väärtuseks on "false", käib installeerimine staatiliselt ning serverisse juurutamiseks tuleb teha konteineri taaskäivitus. Käigultvahetust saab määrata ka peremehe defineerimisel "Host Manager" rakendusega, mis on kättesaadav aadressil http://localhost:8080/host-manager/html . Kasutamiseks tuleb lisada oma kasutajale rolli "admin-gui" (vt. alajaotus ""Tomcat Manager" ligipääsu konfigureerimine").

[[File:host_manager_app.png]]

Käigultvahetust päästikuks on vaikimisi uuendatud veebiarhiivifaili või lahtipakitud veebirakenduse paigutamine "webapps" kataloogi. Käigultvahetuse päästikutele võib failis $CATALINA_BASE/conf/server.xml ka ise lisada kuulatavaid ressursse nagu web.xml muutmine või mõne teegifaili vahetamine (märgendis "Host").

===Klassiteekide väljatõstmine veebiarhiivifailist===

Kõik konteksti poolt kasutatavad Java klassiteegid võib pakendada veebiarhiivi sisse kataloogi "lib", kuid nii võib osutuda veebiarhiivi üleslaadimine ajakulukaks, eriti arenduskeskkonnas. Kui ei teki ohtu, et erinevad rakendused kasutavad sama teegi erinevaid versioone, siis on vahel parem lisada osa teeke konteineri kataloogi $CATALINA_BASE/libs, kust need tehakse siis konteineri poolt kättesaadavaks kõigile konteineris jooksutatavatele kontekstidele. Nii võib vähendada veebiarhiivi faili suurust märgatavalt, mis tõstab kokkuvõttes juurutamiskiirust ja ühes sellega programmeerijate tööviljakust.

===Mälukasutus===

Konteineri poolt kasutatavat mälu saab vaadata haldusrakendusest vajutades lingile "Server Status". Mälukasutus on toodud jaotuses "JVM", kus näidatakse nii maksimaalselt kättesaadavat mälu kui ka parasjagu reserveeritud mälu.

<pre>Free memory: 41.16 MB Total memory: 123.37 MB Max memory: 1027.56 MB</pre>

Mälu suurendamiseks võib näiteks defineerida skriptis $CATALINA_BASE/bin/catalina.sh muutuja "JAVA_OPTS" ning määrata Java mälukasutuse miinimum- ja maksimumväärtused sarnaselt järgnevatega:
<pre>
JAVA_OPTS="-Xms1536m -Xmx1536m -XX:NewSize=256m -XX:MaxNewSize=256m -XX:PermSize=256m -XX:MaxPermSize=256m"
</pre>

===Logifailid===

Vaikimisi defineerib Tomcat failiga $CATALINA_BASE/conf/logging.properties viis logerit, mis tekitavad viis eraldi logifaili.

{| style="background:#cccc99;color:black;width:80%;" border="1" cellpadding="5" cellspacing="0" align="center"
|+ Tomcati tekitatavad logifailid "logs" kataloogis
!Fail !! Kasutus
|- style="background:white; color:black"
| style="width:300px" |catalina.out
| Tomcati käivitus- ja peatamisskriptide väljund, samuti juurutatud rakenduste prindilaused System.out ja veaväljundid System.err
|- style="background:white; color:black"
| style="width:300px" |catalina.[yyyy]-[mm]-[dd].log
| Pööratud (rotated) logifail catalina.out
|- style="background:white; color:black"
| style="width:300px" |host-manager.[yyyy]-[mm]-[dd].log
| Logi peremehehalduse rakendusele (rakendus on kättesaadav kohalikust masinast aadressil http://localhost:8080/host-manager/html )
|- style="background:white; color:black"
| style="width:300px" |localhost.[yyyy]-[mm]-[dd].log
| Peremehe "localhost" logi; mitme virtuaalse peremehe korral tekitatakse igale peremehele oma logi
|- style="background:white; color:black"
| style="width:300px" |localhost_access_log.[yyyy]-[mm]-[dd].txt
| Konteinerisse Internetist saabunud päringute logi
|- style="background:white; color:black"
| style="width:300px" |manager.[yyyy]-[mm]-[dd].log
| Haldusrakenduse tegevuste logi
|}

===Viiteid===

Palju vajalikku võib leida [http://tomcat.apache.org/tomcat-8.0-doc/index.html Tomcat 8 dokumentatsioonist]

Lisaks üks viide põhjalikule Tomcati versioon seitsme ülevaatele: http://www.ntu.edu.sg/home/ehchua/programming/howto/Tomcat_More.html

= Kasutatud materjalid =

*http://tomcat.apache.org/tomcat-8.0-doc/index.html
*http://www.mulesoft.com/tomcat-deploy-procedures
*http://www.mkyong.com/tomcat/tomcat-javalangoutofmemoryerror-permgen-space/

[[Category: Operatsioonisüsteemide administreerimine ja sidumine]]