-
-
Notifications
You must be signed in to change notification settings - Fork 26
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
copy existing bugzilla installation docs as is
- Loading branch information
Showing
35 changed files
with
2,758 additions
and
0 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,136 @@ | ||
.. _apache-windows: | ||
|
||
Apache on Windows | ||
################# | ||
|
||
Bugzilla supports all versions of Apache 2.2.x and 2.4.x. | ||
|
||
Installing | ||
========== | ||
|
||
Download the Apache HTTP Server as a :file:`.zip` archive either from the | ||
`Apache Lounge website <http://www.apachelounge.com/download>`_ or from the | ||
`Apache Haus website <http://www.apachehaus.com/cgi-bin/download.plx>`_. | ||
|
||
Unzip the archive into :file:`C:\\Apache24`. If you move it elsewhere, then | ||
you must edit several variables in :file:`httpd.conf`, including ``ServerRoot`` | ||
and ``DocumentRoot``. | ||
|
||
You must now edit the Apache configuration file :file:`C:\\Apache24\\conf\\httpd.conf` | ||
and do the following steps: | ||
|
||
#. Uncomment ``LoadModule cgi_module modules/mod_cgi.so`` at the beginning of the | ||
file to enable CGI support. | ||
#. Uncomment ``AddHandler cgi-script .cgi`` to register :file:`.cgi` files | ||
as CGI scripts. For this handler to work, you must create a key in the | ||
Windows registry named ``HKEY_CLASSES_ROOT\.cgi\Shell\ExecCGI\Command`` with | ||
the default value pointing to the full path of :file:`perl.exe` with a ``-T`` | ||
parameter. For example :file:`C:\\Perl\\bin\\perl.exe -T` if you use ActivePerl, | ||
or :file:`C:\\Strawberry\\perl\\bin\\perl.exe -T` if you use Strawberry Perl. | ||
#. Add an Alias and a Directory for Bugzilla: | ||
|
||
.. code-block:: apache | ||
Alias "/bugzilla/" "C:/bugzilla/" | ||
<Directory "C:/bugzilla"> | ||
ScriptInterpreterSource Registry-Strict | ||
Options +ExecCGI +FollowSymLinks | ||
DirectoryIndex index.cgi index.html | ||
AllowOverride All | ||
Require all granted | ||
</Directory> | ||
.. warning:: The above block takes a simple approach to access control and is | ||
correct for Apache 2.4. For Apache 2.2, replace ``Require all granted`` | ||
with ``Allow from all``. If you have other access control | ||
requirements, you may need to make further modifications. | ||
|
||
You now save your changes and start Apache as a service. From the Windows | ||
command line (:file:`cmd.exe`): | ||
|
||
:command:`C:\\Apache24\\bin>httpd.exe -k install` | ||
|
||
That's it! Bugzilla is now accessible from http://localhost/bugzilla. | ||
|
||
Apache Account Permissions | ||
========================== | ||
|
||
By default Apache installs itself to run as the SYSTEM account. For security | ||
reasons it's better the reconfigure the service to run as an Apache user. | ||
Create a new Windows user that is a member of **no** groups, and reconfigure | ||
the Apache2 service to run as that account. | ||
|
||
Whichever account you are running Apache as, SYSTEM or otherwise, needs write | ||
and modify access to the following directories and all their subdirectories. | ||
Depending on your version of Windows, this access may already be granted. | ||
|
||
* :file:`C:\\Bugzilla\\data` | ||
* :file:`C:\\Apache24\\logs` | ||
* :file:`C:\\Windows\\Temp` | ||
|
||
Note that :file:`C:\\Bugzilla\\data` is created the first time you run | ||
:file:`checksetup.pl`. | ||
|
||
Logging | ||
======= | ||
|
||
Unless you want to keep statistics on how many hits your Bugzilla install is | ||
getting, it's a good idea to disable logging by commenting out the | ||
``CustomLog`` directive in the Apache config file. | ||
|
||
If you don't disable logging, you should at least disable logging of "query | ||
strings". When external systems interact with Bugzilla via webservices | ||
(REST/XMLRPC/JSONRPC) they include the user's credentials as part of the URL | ||
(in the query string). Therefore, to avoid storing passwords in clear text | ||
on the server we recommend configuring Apache to not include the query string | ||
in its log files. | ||
|
||
#. Find the following line in the Apache config file, which defines the | ||
logging format for ``vhost_combined``: | ||
|
||
.. code-block:: apache | ||
LogFormat "%v:%p %h %l %u %t \"%r\" %>s %O \"%{Referer}i\" \"%{User-Agent}i\"" vhost_combined | ||
#. Replace ``%r`` with ``%m %U``. | ||
|
||
(If you have configured Apache differently, a different log line might apply. | ||
Adjust these instructions accordingly.) | ||
|
||
Using Apache with SSL | ||
===================== | ||
|
||
If you want to enable SSL with Apache, i.e. access Bugzilla from | ||
https://localhost/bugzilla, you need to do some extra steps: | ||
|
||
#. Edit :file:`C:\\Apache24\\conf\\httpd.conf` and uncomment these lines: | ||
|
||
* ``LoadModule ssl_module modules/mod_ssl.so`` | ||
* ``LoadModule socache_shmcb_module modules/mod_socache_shmcb.so`` | ||
* ``Include conf/extra/httpd-ssl.conf`` | ||
|
||
#. Create your :file:`.key` and :file:`.crt` files using :file:`openssl.exe` | ||
provided with Apache: | ||
|
||
:command:`C:\\Apache24\\bin>openssl.exe req -x509 -nodes -days 730 -newkey rsa:2048 -keyout server.key -out server.crt` | ||
|
||
:file:`openssl.exe` will ask you a few questions about your location and | ||
your company name to populate fields of the certificate. | ||
|
||
#. Once the key and the certificate for your server are generated, move them | ||
into :file:`C:\\Apache24\\conf` so that their location matches the | ||
``SSLCertificateFile`` and ``SSLCertificateKeyFile`` variables defined in | ||
:file:`C:\\Apache24\\conf\\extra\\httpd-ssl.conf` (which you don't need to | ||
edit). | ||
|
||
.. note:: This process leads to a self-signed certificate which will generate | ||
browser warnings on first visit. If your Bugzilla has a public DNS | ||
name, you can get a cert from a CA which will not have this problem. | ||
|
||
Restart Apache | ||
============== | ||
|
||
Finally, restart Apache to pick up the changes, either from the Services | ||
console or from the command line: | ||
|
||
:command:`C:\\Apache24\\bin>httpd.exe -k restart` |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,145 @@ | ||
.. This document is shared among all non-Windows OSes. | ||
.. _apache: | ||
|
||
Apache | ||
###### | ||
|
||
You have two options for running Bugzilla under Apache - mod_cgi (the | ||
default) and mod_perl. mod_perl is faster but takes more resources. You | ||
should probably only consider mod_perl if your Bugzilla is going to be heavily | ||
used. | ||
|
||
These instructions require editing the Apache configuration file, which is: | ||
|
||
* Fedora/Red Hat: :file:`/etc/httpd/conf/httpd.conf` | ||
* Debian/Ubuntu: :file:`/etc/apache2/apache2.conf` | ||
* Mac OS X: :file:`/etc/apache2/httpd.conf` | ||
|
||
Alternatively, on Debian or Ubuntu, you can instead put the below code into a | ||
separate file in the directory :file:`/etc/apache2/sites-enabled/`. | ||
|
||
In these instructions, when asked to restart Apache, the command is: | ||
|
||
:command:`sudo apachectl start` | ||
|
||
(or run it as root if your OS installation does not use sudo). | ||
|
||
Securing Apache | ||
=============== | ||
|
||
When external systems interact with Bugzilla via webservices | ||
(REST/XMLRPC/JSONRPC) they include the user's credentials as part of the URL | ||
(in the "query string"). Therefore, to avoid storing passwords in clear text | ||
on the server we recommend configuring Apache to not include the query string | ||
in its log files. | ||
|
||
#. Edit the Apache configuration file (see above). | ||
|
||
#. Find the following line in the above mentioned file, which defines the | ||
logging format for ``vhost_combined``: | ||
|
||
.. code-block:: apache | ||
LogFormat "%v:%p %h %l %u %t \"%r\" %>s %O \"%{Referer}i\" \"%{User-Agent}i\"" vhost_combined | ||
#. Replace ``%r`` with ``%m %U``. | ||
|
||
#. Restart Apache. | ||
|
||
.. _apache-mod_cgi: | ||
|
||
Apache with mod_cgi | ||
=================== | ||
|
||
To configure your Apache web server to work with Bugzilla while using | ||
mod_cgi, do the following: | ||
|
||
#. Edit the Apache configuration file (see above). | ||
|
||
#. Create a ``<Directory>`` directive that applies to the location | ||
of your Bugzilla installation. In this example, Bugzilla has | ||
been installed at :file:`/var/www/html/bugzilla`. On Mac OS X, use | ||
:file:`/Library/WebServer/Documents/bugzilla`. | ||
|
||
.. code-block:: apache | ||
<Directory /var/www/html/bugzilla> | ||
AddHandler cgi-script .cgi | ||
Options +ExecCGI +FollowSymLinks | ||
DirectoryIndex index.cgi index.html | ||
AllowOverride All | ||
</Directory> | ||
These instructions allow Apache to run .cgi files found within the Bugzilla | ||
directory; instructs the server to look for a file called :file:`index.cgi` | ||
or, if not found, :file:`index.html` if someone only types the directory name | ||
into the browser; and allows Bugzilla's :file:`.htaccess` files to override | ||
some global permissions. | ||
|
||
On some Linux distributions you will need to enable the Apache CGI | ||
module. On Debian/Ubuntu, this is done with: | ||
|
||
:command:`sudo a2enmod cgi` | ||
|
||
If you find that the webserver is returning the Perl code as text rather | ||
than executing it, then this is the problem. | ||
|
||
.. _apache-mod_perl: | ||
|
||
Apache with mod_perl | ||
==================== | ||
|
||
Some configuration is required to make Bugzilla work with Apache | ||
and mod_perl. | ||
|
||
.. note:: It is not known whether anyone has even tried mod_perl on Mac OS X. | ||
|
||
#. Edit the Apache configuration file (see above). | ||
|
||
#. Add the following information, substituting where appropriate with your | ||
own local paths. | ||
|
||
.. code-block:: apache | ||
PerlSwitches -w -T | ||
PerlConfigRequire /var/www/html/bugzilla/mod_perl.pl | ||
.. note:: This should be used instead of the <Directory> block | ||
shown above. This should also be above any other ``mod_perl`` | ||
directives within the :file:`httpd.conf` and the directives must be | ||
specified in the order above. | ||
|
||
.. warning:: You should also ensure that you have disabled ``KeepAlive`` | ||
support in your Apache install when utilizing Bugzilla under mod_perl | ||
or you may suffer a | ||
`performance penalty <http://modperlbook.org/html/11-4-KeepAlive.html>`_. | ||
|
||
On restarting Apache, Bugzilla should now be running within the | ||
mod_perl environment. | ||
|
||
Please bear the following points in mind when considering using Bugzilla | ||
under mod_perl: | ||
|
||
* mod_perl support in Bugzilla can take up a HUGE amount of RAM - easily | ||
30MB per httpd child. The more RAM you can get, the better. mod_perl is | ||
basically trading RAM for speed. At least 2GB total system RAM is | ||
recommended for running Bugzilla under mod_perl. | ||
|
||
* Under mod_perl, you have to restart Apache if you make any manual change to | ||
any Bugzilla file. You can't just reload--you have to actually | ||
*restart* the server (as in make sure it stops and starts | ||
again). You *can* change :file:`localconfig` and the :file:`params` file | ||
manually, if you want, because those are re-read every time you load a page. | ||
|
||
* You must run in Apache's Prefork MPM (this is the default). The Worker MPM | ||
may not work -- we haven't tested Bugzilla's mod_perl support under threads. | ||
(And, in fact, we're fairly sure it *won't* work.) | ||
|
||
* Bugzilla generally expects to be the only mod_perl application running on | ||
your entire server. It may or may not work if there are other applications also | ||
running under mod_perl. It does try its best to play nice with other mod_perl | ||
applications, but it still may have conflicts. | ||
|
||
* It is recommended that you have one Bugzilla instance running under mod_perl | ||
on your server. Bugzilla has not been tested with more than one instance running. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,38 @@ | ||
.. _backups: | ||
|
||
Backups | ||
####### | ||
|
||
Database | ||
======== | ||
|
||
Here are some sample commands you could use to backup | ||
your database, depending on what database system you're | ||
using. You may have to modify these commands for your | ||
particular setup. Replace the $VARIABLEs with appropriate values for your | ||
setup. | ||
|
||
MySQL | ||
----- | ||
|
||
:command:`mysqldump --max-allowed-packet=32M -u $USERNAME -p $DATABASENAME > backup.sql` | ||
|
||
The value for :command:`max-allowed-packet` should be the value you've set in | ||
your :ref:`MySQL configuration file <mysql>`, and should be larger than the | ||
largest attachment in your database. See the | ||
`mysqldump documentation <http://dev.mysql.com/doc/mysql/en/mysqldump.html>`_ | ||
for more information on :file:`mysqldump`. | ||
|
||
PostgreSQL | ||
---------- | ||
|
||
:command:`pg_dump --no-privileges --no-owner -h localhost -U $USERNAME > bugs.sql` | ||
|
||
Bugzilla | ||
======== | ||
|
||
The Bugzilla directory contains some data files and configuration files which | ||
you would want to retain. A simple recursive copy will do the job here. | ||
|
||
:command:`cp -rp $BUGZILLA_HOME /var/backups/bugzilla` | ||
|
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,18 @@ | ||
.. _db_server: | ||
|
||
Database Server | ||
############### | ||
|
||
Bugzilla requires a database to store its data. We recommend either MySQL or | ||
PostgreSQL for production installations. Oracle 10 should work fine, but very | ||
little or no testing has been done with Oracle 11 and 12. SQLite is easy to | ||
configure but, due to its limitations, it should only be used for testing | ||
purposes and very small installations. | ||
|
||
.. toctree:: | ||
:maxdepth: 1 | ||
|
||
mysql | ||
postgresql | ||
oracle | ||
sqlite |
Oops, something went wrong.