3.4. Mac OS X
*************

Note:

  The Bugzilla team has very little Mac expertise and we've not been
  able to do a successful install of the latest version. We got close,
  though. If you've managed it, tell us how and we can update these
  docs!


3.4.1. Install Packages
=======================

OS X 10.7 provides Perl 5.12 and Apache 2.2. Install the following
additional packages:

* git: Download an installer from the git website.

* MySQL: Download an installer from the MySQL website.


3.4.2. Bugzilla
===============

The best way to get Bugzilla is to check it out from git:

**git clone --branch release-X.X-stable
https://github.com/bugzilla/bugzilla**

Run the above command in your home directory, replacing "X.X" with the
2-digit version number of the stable release of Bugzilla that you want
- e.g. "4.4". This will place Bugzilla in the directory
"$HOME/bugzilla".

If that's not possible, you can download a tarball of Bugzilla.


3.4.3. Additional System Libraries
==================================

Apple does not include the GD library with Mac OS X. Bugzilla needs
this if you want to display bug graphs, and you need to install it
before you try installing the GD Perl module.

You can use MacPorts, Homebrew or Fink, all of which can install
common Unix programs on Mac OS X.

If you don't have one of the above installed already, pick one and
follow the instructions for setting it up. Then, use it to install the
"gd2" package (MacPorts/Fink) or the "gd" package (Brew).

The package manager may prompt you to install a number of
dependencies; you will need to agree to this.

Note:

  To prevent creating conflicts with the software that Apple installs
  by default, Fink creates its own directory tree at "/sw" where it
  installs most of the software that it installs. This means your
  libraries and headers will be at "/sw/lib" and "/sw/include" instead
  of "/usr/lib" and "/usr/include". When the Perl module config script
  for the GD module asks where your "libgd" is, be sure to tell it
  "/sw/lib".


3.4.4. Perl Modules
===================

Bugzilla requires a number of Perl modules. On Mac OS X, the easiest
thing to do is to install local copies (rather than system-wide
copies) of any ones that you don't already have. However, if you do
want to install them system-wide, run the below commands as root with
the **--global** option.

To check whether you have all the required modules and what is still
missing, run:

**perl checksetup.pl --check-modules**

You can run this command as many times as necessary.

Install all missing modules locally like this:

**perl install-module.pl --all**


3.4.5. Web Server
=================

Any web server that is capable of running CGI scripts can be made to
work. We have specific configuration instructions for the following:

* Apache

You'll need to create a symbolic link so the webserver can see
Bugzilla:

**cd /Library/WebServer/Documents**

**sudo ln -s $HOME/bugzilla bugzilla**

In System Preferences --> Sharing, enable the Web Sharing checkbox to
start Apache.


3.4.6. Database Engine
======================

Bugzilla supports MySQL, PostgreSQL, Oracle and SQLite as database
servers. You only require one of these systems to make use of
Bugzilla. MySQL is most commonly used on Mac OS X. (In fact, we have
no reports of anyone using anything else.) Configure your server
according to the instructions below:

* MySQL

* PostgreSQL

* Oracle

* SQLite


3.4.7. localconfig
==================

You should now change into the Bugzilla directory and run
"checksetup.pl", without any parameters:

**perl checksetup.pl**

"checksetup.pl" will write out a file called "localconfig". This file
contains the default settings for a number of Bugzilla parameters, the
most important of which are the group your web server runs as, and
information on how to connect to your database.

Load this file in your editor. You will need to check/change
"$db_driver" and "$db_pass", which are respectively the type of the
database you are using and the password for the "bugs" database user
you have created. "$db_driver" can be either "mysql", "Pg"
(PostgreSQL), "Oracle" or "Sqlite". All values are case sensitive.

Set the value of "$webservergroup" to the group your web server runs
as.

* Fedora/Red Hat: "apache"

* Debian/Ubuntu: "www-data"

* Mac OS X: "_www"

* Windows: ignore this setting; it does nothing

The other options in the "localconfig" file are documented by their
accompanying comments. If you have a non-standard database setup, you
may need to change one or more of the other "$db_*" parameters.

Note:

  If you are using Oracle, "$db_name" should be set to the SID name of
  your database (e.g. "XE" if you are using Oracle XE).


3.4.8. checksetup.pl
====================

Next, run "checksetup.pl" an additional time:

**perl checksetup.pl**

It reconfirms that all the modules are present, and notices the
altered localconfig file, which it assumes you have edited to your
satisfaction. It compiles the UI templates, connects to the database
using the "bugs" user you created and the password you defined, and
creates the "bugs" database and the tables therein.

After that, it asks for details of an administrator account. Bugzilla
can have multiple administrators - you can create more later - but it
needs one to start off with. Enter the email address of an
administrator, his or her full name, and a suitable Bugzilla password.

"checksetup.pl" will then finish. You may rerun "checksetup.pl" at any
time if you wish.


3.4.9. Success
==============

Your Bugzilla should now be working. Check by running:

**perl testserver.pl http://<your-bugzilla-server>/**

If that passes, access "http://<your-bugzilla-server>/" in your
browser - you should see the Bugzilla front page. Of course, if you
installed Bugzilla in a subdirectory, make sure that's in the URL.

Next, do the Essential Post-Installation Configuration.

======================================================================

This documentation undoubtedly has bugs; if you find some, please file
them here.
