# Bugzilla: an MPL-2.0 Perl bug tracker you can still run with one compose command

> Bugzilla is the Mozilla community's web based bug tracking system, written in Perl as a set of CGI endpoints, licensed under MPL-2.0 and packaged for a quick Docker Compose start that prints your admin credentials on the console. The repository's file listing explains the architecture better than the README does.

**bugzilla/bugzilla** — Official repository for the Bugzilla bug tracking system. Report bugs to https://bugzilla.mozilla.org/enter_bug.cgi?product=Bugzilla&format=__default__ . Main website:

- Repository: https://github.com/bugzilla/bugzilla
- Website: http://www.bugzilla.org
- Stars: 864 · Forks: 320
- Language: Perl
- License: MPL-2.0
- Published: 2026-10-20 · Updated: 2026-10-20 · Language: en
- Canonical page: https://hysenlabs.com/projects/bugzilla-bugzilla

## A volunteer maintained tracker with a two decade footprint

Bugzilla is described as free and open source web based bug tracking software, developed by an active group of volunteers in the Mozilla community and used by thousands of projects and companies around the world. The README states that it can be installed on Linux and other Unix flavours, on Windows, or on Mac OS X.

The licence is the Mozilla Public License 2.0, and the README includes the standard notice that the source is also marked as Incompatible With Secondary Licenses as defined in that licence. It then makes the practical point clearly: this only matters if you want to modify the code and redistribute it, and as with all open source software there are no restrictions on running it or on modifying it for your own purposes.

That is the licence story in two sentences, and it is the part to read carefully in a procurement review. Running Bugzilla internally, unmodified, is unencumbered. Distributing a modified version puts the modified files under the MPL terms, and the secondary licence incompatibility means those files cannot be combined with code under a licence the MPL treats as incompatible.

The development picture is small and real. The default branch is 5.2, the last push was on 2026-09-06, and the repository has no GitHub releases, so the version you track is the branch rather than a tag. The project points at bugzilla.org as the main site, with the full documentation including installation instructions at bugzilla.org/docs. Bugs in Bugzilla itself are reported on bugzilla.mozilla.org, and the README asks people not to file test bugs in that installation.

## The file listing is the architecture

The repository root is unusually honest about how the system is built, because every entry is a URL handler.

There is enter_bug.cgi for filing a bug, buglist.cgi for the list view, attachment.cgi for uploads, chart.cgi for the graphs, config.cgi for configuration, admin.cgi for administration, createaccount.cgi for registration, index.cgi for the front page, duplicates.cgi for the duplicate workflow, and a long run of edit endpoints: editcomponents.cgi, editfields.cgi, editgroups.cgi, editkeywords.cgi, editmilestones.cgi, editparams.cgi, editproducts.cgi, editsettings.cgi, editusers.cgi, editvalues.cgi, editversions.cgi, editwhines.cgi and editworkflow.cgi.

Two more stand out. jsonrpc.cgi is the programmatic interface, which is how automation and integrations talk to the tracker, and descriptecomponents.cgi and describekeywords.cgi expose the product and keyword metadata in a machine readable form.

Underneath the endpoints sit the libraries in lib/, the templates and JavaScript in js/ and images/, the extension mechanism in extensions/, community contributions in contrib/, and the Perl module tree Bugzilla/ with its top level Bugzilla.pm. The build is a Build.PL, so the distribution is built with the standard Perl toolchain, and the .perltidyrc file at the root means the code is formatted with perltidy, a convention that keeps a large Perl codebase readable.

The operational scripts are just as revealing. checksetup.pl checks and repairs an installation, migrate.pl handles schema and data upgrades, importxml.pl imports bug data in XML, email_in.pl processes incoming mail, jobqueue.pl runs background jobs, and collectstats.pl gathers usage statistics. There is also a SECURITY.md for responsible disclosure, which is the file to look at before reporting a vulnerability in a product this widely deployed.

## The Compose quick start hands you the admin password on the console

The quickest way to see Bugzilla running is stated in one sentence. If you have Docker installed, change into the directory containing the README and type docker compose up, and the URL together with the username and password for the default admin account is printed on the console once the setup finishes.

The Compose file itself is the best documentation of a deployment, and it is short. The web service builds from the Dockerfile in the repository, runs a startup script, publishes port 80 of the container on host port 8080, mounts a named volume for the data directory, mounts the working tree at /mnt/sync, and uses tmpfs for /tmp and /run/lock.

```yaml
    volumes:
      - bugzilla5-data-dir:/var/www/html/data
      - .:/mnt/sync
    tmpfs:
      - /tmp
      - /run/lock
    ports:
      - 8080:80
    depends_on:
      - bugzilla5.db
    environment: &bugzilla_env
      - BZ_ADMIN_EMAIL=admin@bugzilla.test
      - BZ_ADMIN_PASSWORD=password01!
      - BZ_ADMIN_REALNAME=Test Admin
      - BZ_URLBASE=http://127.0.0.1:8080/
```

The database service is a second container built from a separate Dockerfile.mariadb, with a named volume for the MySQL data, and it inherits the same environment block through the YAML anchor. Two of those values need changing before any real deployment: the admin email and the admin password are in the file in plain sight, and the database credentials are equally simple.

The MariaDB container is configured with MARIADB_ROOT_HOST set to a wildcard and a root password of bugzilla, which is fine for a local look and wrong for a shared host.

There is one wrinkle the README explains. If checksetup.pl stops inside Docker because the UTF-8 conversion needs an interactive confirmation, the conversion can be allowed explicitly, and the file exposes the switch as an environment variable with a default of 0.

## The UTF-8 escape hatch comes with a warning, and it deserves one

The single most useful sentence in the README for a Docker user is the instruction that follows the environment variable.

```bash
BZ_ALLOW_UNSAFE_UTF8_CONVERSION=1 docker compose up
```

The variable name says what it means. The UTF-8 conversion in checksetup.pl normally asks for confirmation, which a non-interactive container cannot answer, and the flag turns that guard off. The README then adds the caveat directly: only do this if you understand the warning and have a backup of your data.

The reason the caution is there is not paranoia about a scary name. The conversion rewrites stored data, it is the kind of operation that is not obviously reversible, and the tool asking for a human to confirm is the tool telling you it is doing something to your existing installation. A fresh Compose stack has no data to convert, so the prompt stopping the container is a sign that the setup script is behaving as designed rather than a bug to work around.

The practical advice for a first run is therefore: let the conversion happen when it is asked for, and only set the variable when you have a copy of the data. For a team that has a production instance and is moving it into containers, that ordering is the difference between a migration and an incident.

The tmpfs mounts in the compose file point the same way. /tmp and the lock directory are deliberately not persisted, because a Perl web application that leaves stale lock files in a volume after a restart is a well known way to spend an afternoon.

## The Docker image is a wall of Perl modules

The Dockerfile is where the operational requirements of a Perl web application become visible, because it is a long apt install list and the base image is Ubuntu 24.04.

The web stack is Apache with mod_perl, and alongside it sit graphviz for the chart endpoint, perlmagick for image handling, mariadb-client, netcat-traditional, patchutils, tzdata and even vim-common. The module list is the interesting part: the C library, the DBI and DBD drivers, the date and time modules, the MIME and email handling modules, the HTML formatting and scrubbing modules, the locale codes, the XML and XML::Twig modules, the LDAP and SOAP clients, the JSON-RPC module, the template toolkit bindings, and the taint mode testing helper.

That list is a map of the features. The LDAP client is there for directory authentication, the SOAP and JSON-RPC modules for the interfaces, the HTML scrubber for user submitted content, the locale codes for the localisation of the interface, and the taint mode test helper because a Perl application that processes attacker-controlled input benefits from the interpreter's own taint checking during testing.

Then there is the part that shows the maintainers have dealt with a moving distribution:

```bash
RUN apt-get -y install build-essential && \
    cpan install Template::Toolkit DBD::MariaDB PatchReader && \
    rm -rf /root/.cpan && \
    apt-get purge -y --autoremove build-essential
```

The comment above it explains why: Ubuntu 24 does not ship new enough versions of a few modules, or does not ship them at all, so they come from CPAN. The build tools are installed, used and then removed again, so the final image does not carry a compiler.

For an operator, that is a fair summary of what running Bugzilla costs: a modern Linux image, a database container, a Perl module tree with a handful of pieces that must be compiled, and a web server in front.

## Where Bugzilla sits against a hosted tracker

The honest comparison is between running this yourself and paying someone else to run a bug tracker for you, and the difference is not in the features but in the obligations.

A hosted service gives you a working system with no Perl, no Apache and no database to maintain, and it moves the burden of upgrades, of the security response and of backups to somebody else. A self-hosted Bugzilla gives you the data in your own infrastructure, the ability to extend the tracker through the extensions/ directory, and control over the upgrade schedule, at the price of running Apache, mod_perl and MariaDB yourself and reading the release notes for each upgrade before applying it.

The upgrade path is documented in the repository rather than hidden. migrate.pl is the migration script, checksetup.pl both checks and repairs the installation, and the version scheme is carried by the branch names, with 5.2 as the default branch. A project that has run this for years will find the upgrade rhythm familiar; a project starting fresh will find the documentation at bugzilla.org/docs the place to start.

The communication channels reflect the same picture. Development and support have separate mailing lists on the Mozilla forums, developers are reachable on IRC at irc.mozilla.org, and the documentation is a website rather than a wiki. That is a community structure from the era when Bugzilla was the default, and it is one of the reasons the project is still maintained by volunteers rather than by a company with a support contract.

So the deciding question is not whether the tracker has the features you need. It is whether your organisation wants to own a Perl web application for the next decade, and if it does, this is a well documented one to own.

## Conclusion

Adopt Bugzilla if you want to self-host a bug tracker with a licence that lets you modify the code for your own purposes without publishing those changes, and you are prepared to run a Perl and Apache stack. Do not adopt it if you want a hosted service with no operations, or if your legal review prefers a permissive licence, because MPL-2.0 is a file level copyleft and the README also marks the code as incompatible with secondary licences. Before you deploy the Compose stack, change the default admin email and password, which the file ships in plain sight, decide where the data volume lives, and read the note about UTF-8 conversion, since forcing it past its interactive confirmation is something the README asks you to do only with a backup in hand.

## FAQ

### How do I run Bugzilla quickly to look at it?

The README says that if you have Docker installed, you change into the directory containing the README and run docker compose up. The URL to access and the username and password for the default admin account are shown on the console once the setup finishes, and the service is published on host port 8080.

### What licence is Bugzilla released under?

The Mozilla Public License 2.0, with the code also marked as Incompatible With Secondary Licenses as defined in that licence. The README notes that this only matters if you modify the code and redistribute it, and that there are no restrictions on running it or modifying it for your own purposes.

### What does the Bugzilla Docker Compose stack include?

Two services: a web service built from the repository Dockerfile that runs Apache with mod_perl, and a database service built from a separate MariaDB Dockerfile, with a named volume for the MySQL data and a second one for the Bugzilla data directory, plus tmpfs mounts for /tmp and the lock directory.

### What is the BZ_ALLOW_UNSAFE_UTF8_CONVERSION variable for?

It lets checksetup.pl perform the UTF-8 conversion without the interactive confirmation it normally requires, which otherwise stops the setup inside Docker. The README says to set it only if you understand the warning and have a backup of your data.

### Which Perl modules does the Bugzilla Docker image need beyond apt?

The Dockerfile installs most dependencies from Ubuntu 24.04 packages and then pulls Template::Toolkit, DBD::MariaDB and PatchReader from CPAN, with a comment explaining that Ubuntu 24 does not ship new enough versions of a few modules or does not ship them at all. The build tools are removed again after that step.

## Sources

- [bugzilla/bugzilla on GitHub](https://github.com/bugzilla/bugzilla)
- [Issues](https://github.com/bugzilla/bugzilla/issues)
- [License: MPL-2.0](https://github.com/bugzilla/bugzilla/blob/5.2/LICENSE)
- [Project website](http://www.bugzilla.org)
- [README](https://github.com/bugzilla/bugzilla/blob/5.2/README.md)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/bugzilla-bugzilla