install-guide.html 8.76 KB
Newer Older
Matt Tucker's avatar
Matt Tucker committed
1 2 3
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
4
  <title>Jive Software Wildfire Readme</title>
Matt Tucker's avatar
Matt Tucker committed
5 6 7
  <link href="style.css" rel="stylesheet" type="text/css">
</head>
<body>
8
<h1>Wildfire Installation Guide</h1>
Matt Tucker's avatar
Matt Tucker committed
9

10
<p>Wildfire is a powerful instant messaging (IM) and chat
Matt Tucker's avatar
Matt Tucker committed
11
server that implements the XMPP protocol. This document will guide 
12
you through installing Wildfire as a standalone
Matt Tucker's avatar
Matt Tucker committed
13
application. For a full list of features and more information, please
14 15
visit the Wildfire website: <a href="http://www.jivesoftware.org/wildfire"
 target="_top">http://www.jivesoftware.org/wildfire</a></p>
Matt Tucker's avatar
Matt Tucker committed
16

Matt Tucker's avatar
Matt Tucker committed
17
<h2>Installation</h2>
Matt Tucker's avatar
Matt Tucker committed
18
<ul>
Matt Tucker's avatar
Matt Tucker committed
19
<h3>Windows</h3>
20
Run the Wildfire installer. The application will be installed to <tt>c:\Program Files\Wildfire</tt> by default.
Matt Tucker's avatar
Matt Tucker committed
21 22 23
 
 <h3>Linux/Unix</h3>
 
24
 Choose either the RPM or tar.gz build. If using the RPM, run it using your package manager to install Wildfire to <tt>/opt/wildfire</tt>:
Matt Tucker's avatar
Matt Tucker committed
25

26
 <p><tt>rpm -ivh wildfire_2_4_0.rpm</tt></p>
Matt Tucker's avatar
Matt Tucker committed
27 28
 
 If using the .tar.gz, extract the archive to <tt>/opt</tt> or <tt>/usr/bin</tt>:
Matt Tucker's avatar
Matt Tucker committed
29

30
 <p><tt>tar -xzvf wildfire_2_4_0.tar.gz<br>
31
 mv wildfire /opt</tt></p>
Matt Tucker's avatar
Matt Tucker committed
32

Matt Tucker's avatar
Matt Tucker committed
33
 <p><b>Note:</b> the .tar.gz build does not contain a bundled Java runtime (JRE). Therefore, you must have JDK or JRE 1.5.0 (Java 5) or later installed on your system. You can check your java version by typing "java -version" at the command line and (if necessary) upgrade your Java installation by visiting http://java.sun.com.</p>
Matt Tucker's avatar
Matt Tucker committed
34

Matt Tucker's avatar
Matt Tucker committed
35
  </ul>
Matt Tucker's avatar
Matt Tucker committed
36
<h2>Setup Overview</h2>
37
<p>To complete the installation of Wildfire, you'll need to
Matt Tucker's avatar
Matt Tucker committed
38 39
perform each of the following steps: </p>
<ol>
Matt Tucker's avatar
Matt Tucker committed
40
  <li><a href="#database">Database</a> - if you choose to use an external database, you must
41
 prepare your database for Wildfire. </li>
Matt Tucker's avatar
Matt Tucker committed
42
  <li><a href="#config">Setup</a> - Use the built-in web-based setup
Matt Tucker's avatar
Matt Tucker committed
43
tool to setup and verify the server configuration.</li>
Matt Tucker's avatar
Matt Tucker committed
44
  <li><a href="#tools">Admin Console</a> - use the web-based admin tool to
Matt Tucker's avatar
Matt Tucker committed
45 46
manage the server.</li>
</ol>
Matt Tucker's avatar
Matt Tucker committed
47 48 49 50 51 52

<p>This document also includes information on:</p>

<ul>
    <li><a href="#windows">Running under Windows</a>
    <li><a href="#unix">Running under Unix/Linux</a>
Matt Tucker's avatar
Matt Tucker committed
53
    <li><a href="#plugins">Installing and using plugins</a>
Matt Tucker's avatar
Matt Tucker committed
54 55
</ul>

Matt Tucker's avatar
Matt Tucker committed
56 57 58
<h2><a name="distribution">Files in the Distribution</a></h2>
<p> The files in your distribution should be as follows (some
sub-directories omitted for brevity): </p>
59
<pre>wildfire/
Matt Tucker's avatar
Matt Tucker committed
60 61 62 63
 |- readme.html
 |- license.html
 |- conf/
 |- bin/
Matt Tucker's avatar
Matt Tucker committed
64
 |- jre/
Matt Tucker's avatar
Matt Tucker committed
65 66 67 68 69 70 71 72 73
 |- lib/
 |- plugins/
     |- admin/
 |- resources/
     |-database/
     |-security/
 |- documentation/</pre>

<ul> 
74
	 <li>The <tt>conf</tt> directory is where Wildfire stores
Matt Tucker's avatar
Matt Tucker committed
75
configuration files.</li>
Matt Tucker's avatar
Matt Tucker committed
76 77
  <li>The <tt>bin</tt> directory contains the server executables. Depending
on which distribution you installed, different executables will be available.</li>
78
  <li>The <tt>jre</tt> directory contains a Java 5 runtime that is bundled with the Windows and RPM versions of Wildfire.</li>
Matt Tucker's avatar
Matt Tucker committed
79
  <li>The <tt>lib</tt> directory contains libraries necessary for
80
running Wildfire.</li>
Matt Tucker's avatar
Matt Tucker committed
81
  <li>The <tt>plugins</tt> directory contains server plugins. By
82
default, Wildfire ships with a web-based admin console plugin.</li>
Matt Tucker's avatar
Matt Tucker committed
83
  <li>The <tt>resources/database</tt> directory contains SQL schema files to
84
create new Wildfire databases, as well as upgrade scripts for
Matt Tucker's avatar
Matt Tucker committed
85
existing installations. </li>
86
  <li>The <tt>resources/security</tt> directory is where Wildfire
Matt Tucker's avatar
Matt Tucker committed
87 88 89 90 91
maintains keystores to support SSL connection security.</li>
  <li>The <tt>documentation</tt> directory contains server
documentation.</li>
</ul><p>

Matt Tucker's avatar
Matt Tucker committed
92
<h2><a name="database">Setup the Database</a></h2>
93
<p> <a>Wildfire can store its data in an embedded database or you can choose to use
Matt Tucker's avatar
Matt Tucker committed
94
an external database such as MySQL or Oracle. If you would like to use an external database,
Matt Tucker's avatar
Matt Tucker committed
95 96 97 98
you must prepare it before proceeding with installation by running the appropriate database
schema. View the </a><a href="database.html">database
setup</a> documentation for more information.</p>

Matt Tucker's avatar
Matt Tucker committed
99 100
</p>
<h2><a name="config"></a>Setup the Server</h2>
Matt Tucker's avatar
Matt Tucker committed
101
<p>A web-based, "wizard" driven setup and configuration tool is built
102
into Wildfire. Simply launch Wildfire (platform-specific instructions below) and use a web browser to
Matt Tucker's avatar
Matt Tucker committed
103
connect to the admin console. The default port for the
104
web-based admin console is 9090. If you are on the same machine as Wildfire, the
Matt Tucker's avatar
Matt Tucker committed
105 106 107
following URL will usually work: 
<a href="http://127.0.0.1:9090">http://127.0.0.1:9090</a>.</p>

Matt Tucker's avatar
Matt Tucker committed
108
<h2><a name="tools">Admin Console</a></h2>
109
<p>After completing the above steps, Wildfire will be configured
Matt Tucker's avatar
Matt Tucker committed
110 111 112 113 114 115 116
and you can use the web-based admin console to administer
the server. The URL should be the same as you used to setup the server
unless you changed the port during the setup.<br>
</p>

<hr>

117
<h2><a name="windows">Running Wildfire in Windows</a></h2>
Matt Tucker's avatar
Matt Tucker committed
118

119 120 121
<p>If you used the Wildfire installer, a shortcut for starting the
a graphical launcher is provided in your Start Menu. Otherwise, run wildfire.exe in the <tt>bin/</tt> directory of your
Wildfire installation. A button on the on the launcher allows
Matt Tucker's avatar
Matt Tucker committed
122 123
you to automatically open your web browser to the correct URL to finish 
setting up the server: 
Matt Tucker's avatar
Matt Tucker committed
124 125

<p>
Matt Tucker's avatar
Matt Tucker committed
126
<div align="center">
127
<img src="images/launcher.png" alt="Wildfire Launcher" width="400" height="300" align="center">
Matt Tucker's avatar
Matt Tucker committed
128 129
</div>
</p>
Matt Tucker's avatar
Matt Tucker committed
130 131

<h3>Windows Service</h3>
132 133 134
<p>If you're running Wildfire on Windows, you will likely want to
run Wildfire as a standard Windows service after initial setup.
If you used the Windows installer, a <tt>wildfire-service.exe</tt> file
Matt Tucker's avatar
Matt Tucker committed
135
will be in the <tt>bin</tt> directory of the installation. You can use
136
this executable to install and control the Wildfire service.
Matt Tucker's avatar
Matt Tucker committed
137 138 139 140
</p>

From a console window, you can run the following commands:
<ul>
141 142 143 144
		<li><tt>wildfire-service /install</tt> -- installs the service.
		<li><tt>wildfire-service /uninstall</tt> -- uninstalls the service.
		<li><tt>wildfire-service /start</tt> -- starts the service
		<li><tt>wildfire-service /stop</tt> -- stops the service.
Matt Tucker's avatar
Matt Tucker committed
145 146 147 148 149 150
</ul>

<p>
<div align="center">
<img src="images/windows_service.png" alt="Windows Service" width="557" height="223" align="center">
</div>
Matt Tucker's avatar
Matt Tucker committed
151 152
</p>

Matt Tucker's avatar
Matt Tucker committed
153 154 155 156 157
<p>You can also use the Services tool in the Windows Control Panel to start and
stop the service.</p>

<p>Note: the graphical launcher is not compatible with the Windows service
at this time. If you install the service, you should use service controls
158 159 160 161
as described above to control the server rather than the graphical launcher.</p>

<h3>Custom Parameters</h3>

162
<p>Advanced users may wish to pass in parameters to the Java virtual machine (VM) to customize the runtime environment of Wildfire. You can do this by creating vmoptions files in the bin/ directory of your Wildfire installation. For the Windows service, you'd create a new text file called wildfire-service.exe.vmoptions. Each parameter to the VM should be on a new line of the file. For example, to set the minimum and max VM heap size to 256 MB, you'd use:
163 164 165 166

<pre>-Xms256m
-Xmx256m</pre>

167
To create parameters for the normal launcher, create a file called wildfired.exe.vmoptions (since the wildfire.exe launcher invokes the wildfired.exe executable to actually start the server).</p>
Matt Tucker's avatar
Matt Tucker committed
168

169
<h2><a name="unix">Running Wildfire in Linux/Unix</a></h2>
Matt Tucker's avatar
Matt Tucker committed
170

171
You can start and stop Wildfire using the <tt>bin/wildfire</tt> script in your Wildfire installation:
Matt Tucker's avatar
Matt Tucker committed
172 173 174

<p>
<tt>
175 176 177 178
# ./wildfire<br>
Usage: ./wildfire {start|stop}<br>
# ./wildfire start<br>
Starting wildfire
Matt Tucker's avatar
Matt Tucker committed
179 180
</tt></p>

181
If you would like to install Wildfire as a service, two scripts are provided in the <tt>bin/extra</tt>
Matt Tucker's avatar
Matt Tucker committed
182 183
directory:
<ul>
184 185
    <li>redhat-postinstall.sh -- automatically installs Wildfire as a service on Red Hat. It does so by creating a "jive" user and then copying the wildfired script to your init.d directory. This script must be run as root. Please see the comments in the script for additional information.</li>
    <li>wildfired -- script to run Wildfire as a service. You must manually configure this script. See the comments in
Matt Tucker's avatar
Matt Tucker committed
186
the script for additional details.</li>
Matt Tucker's avatar
Matt Tucker committed
187
</ul>
Matt Tucker's avatar
Matt Tucker committed
188 189 190

<h2><a name="plugins">Plugins</a></h2>

191 192
Plugins add additional features and protocol support to Wildfire. After setting up your
Wildfire installation, you may want to download and install plugins to enhance your
Matt Tucker's avatar
Matt Tucker committed
193
server. Plugins can be downloaded from the
194
<a href="http://www.jivesoftware.org/wildfire/plugins.jsp">plugins page</a> on jivesoftware.org.
Matt Tucker's avatar
Matt Tucker committed
195 196 197 198

<h3>Installing Plugins</h3>

Each plugin comes packaged as a .jar (JAR) file. After download the plugin, you can deploy it
199 200
by copying the plugin file to the <tt>plugins/</tt> directory of your Wildfire installation. A
plugin monitor will automatically extract the plugin into a directory and install the plugin in Wildfire.
Matt Tucker's avatar
Matt Tucker committed
201 202 203 204


<h3>Managing Plugins</h3>

205 206
Plugins can be managed inside the Wildfire admin console. You can also manually delete a plugin at any time by
deleting its JAR file (Wildfire will automatically remove the plugin from memory and delete it's directory when you
Matt Tucker's avatar
Matt Tucker committed
207
do so).
Matt Tucker's avatar
Matt Tucker committed
208 209 210

</body>
</html>