Kitsune: Mozilla Support Platform Setup and Architecture

What Kitsune Solves for Mozilla Support

Kitsune is not a generic Django starter project or a customer-support library intended for installation inside an unrelated application. The README identifies it as the platform that powers SuMo at support.mozilla.org. Its purpose is therefore tied to operating a full support website, with the repository showing the application code, templates, localization tooling, frontend assets, API support, asynchronous processing and browser tests in one codebase.

The intended users are maintainers working on Mozilla Support, contributors following the project's development documentation, and engineers who understand both server-side Django applications and frontend build pipelines. The repository structure also points to operations staff who must coordinate several services rather than only run a Python process. This makes Kitsune most relevant to teams that want the existing platform or need to study how Mozilla structures its support service.

The project does not present itself as a narrow API for ticket submission, knowledge-base search or chatbot functionality. Those capabilities may exist within the larger codebase, but the project description does not identify any of them as standalone interfaces. A team looking for one of those components should not assume it can install Kitsune and use only that part without reviewing the relevant documentation and application boundaries.

How the Kitsune Service Stack Fits Together

The application core is Django. The repository includes manage.py, the kitsune package, settings and configuration directories, WSGI configuration, templates and frontend sources. Dependencies add database access, caching, background jobs, search, identity integration, storage, localization and service communication. This indicates a conventional Django service with supporting infrastructure rather than a single-process library.

Data storage and supporting services are separate concerns. Docker Compose defines PostgreSQL, Redis, Elasticsearch and Kibana, plus Celery workers. PostgreSQL is the relational service visible in the Compose file, Redis supports caching and asynchronous work, and Elasticsearch is included as a distinct search dependency. Celery runs queues named celery, email, retrieval and retrieval_bulk, so some work is deliberately moved outside a web request. The Flower service provides a Celery monitoring interface on port 5555 when its profile is enabled.

The frontend is also part of the build rather than an optional afterthought. package.json contains Webpack configurations, Svelte sources, Babel and PostCSS configuration, style linting and browser synchronization. The Docker Compose `web` service listens on port 8000, while the `node` service exposes ports 3000 and 3001 for the development frontend. This split means a Kitsune development setup is expected to coordinate Python, Node and infrastructure processes.

Internationalization is also built into the delivery pipeline. The Dockerfile creates a localization stage, fetches Mozilla localization content, compiles it and copies generated catalogs into the static tree. Another stage runs `compilejsi18n`. The project therefore treats translated support content as part of application packaging, not as an afterthought.

Kitsune Development Setup and First Browser Use

The README does not provide a self-contained installation command. It directs contributors to the online documentation and specifically links to the development-environment guide at `https://mozilla.github.io/kitsune/hacking_howto/`. The repository supplies Docker Compose files, a Dockerfile, environment templates and a Python project definition, so the documented setup path should be followed rather than treating the README as a standalone installation manual.

The Python environment requires Python 3.14 and uses the `uv` workflow shown in the Dockerfile. The following command installs the locked development environment from the project metadata. It does not start every service, and the Dockerfile uses it while building the image.

uv sync --frozen --extra dev

The frontend has its own documented package scripts. For development installation, use the script defined in package.json:

npm run install-dev

After the development environment is configured, the frontend start script builds the assets and launches the related watcher and browser synchronization processes:

npm start

The Compose configuration exposes the web application on port 8000 and the node development service on ports 3000 and 3001. The README also identifies a staging site at `https://support.allizom.org/`. That staging site can provide a first view of the supported interface, but it is not documented as a local installation step. The local Docker services still require the environment values expected by the application, and the repository does not show the contents of the truncated environment configuration in full.

Search, Queues and Frontend Delivery Constraints

Kitsune's dependency on Elasticsearch changes the operational boundary compared with a small Django site. A deployment must keep the relational database and search index coherent, while the README does not document migration or reindexing instructions. That omission matters for operators. Adding or changing searchable support content may require deployment work that is not visible from the short project description.

Celery introduces another coordination layer. The worker command consumes `celery,email,retrieval,retrieval_bulk`, and Redis is listed as a dependency. If a worker is absent or a queue is misconfigured, the web application can remain available while email, retrieval or bulk processing fails separately. The architecture is appropriate for background work at platform scale, but it creates more failure modes than synchronous Django-only processing.

The frontend adds a separate compatibility constraint. package.json declares Node `^22.22.2 || ^24.15.0 || >=26.0.0` and npm `>=10.0.0`. These are exact project constraints. A contributor with an older Node release may be able to install Python dependencies yet still fail when running the frontend scripts. The repository also includes separate development, production and pre-render Webpack configurations, indicating that local development and production asset delivery are related but distinct workflows.

Deployment Boundaries and Operational Failure Modes

Kitsune is a complete platform, so deployment is more involved than installing a Python package. Docker Compose defines a `web` service, a `node` service, PostgreSQL, Redis, Elasticsearch, Kibana, Celery, Mailcatcher, optional Celery Beat and Flower. Some services run under profiles, while others are declared as dependencies. A deployment that starts only the `web` container will not reproduce the full documented environment.

The Dockerfile uses Python 3.14, installs system libraries for XML, images, PostgreSQL and other build needs, then runs `uv sync --frozen --extra dev --no-install-project`. It also includes build stages for localization and JavaScript internationalization before preparing frontend assets. This is useful for reproducibility, but it means the build image has substantial responsibilities. A failed localization fetch, asset compilation or frontend build can prevent a complete image from being produced.

The repository includes Sentry, caching, email-related queues and external-service clients. These dependencies can improve platform capabilities, but they also increase configuration and troubleshooting work. The README does not document rollback procedures, backup routines, database migration policy or required production secrets. Those omissions should be treated as documentation gaps rather than as evidence that Kitsune does not need them.

Kitsune Compared with a Reusable Django Application

The clearest alternative is a focused Django application or package built around the exact support feature a team needs. Such a project would normally define a smaller dependency set, expose a narrower data model and require fewer services. That approach avoids the full SuMo platform's search, queue, localization and frontend coordination, but it does not provide the existing Mozilla Support codebase or its established support-site structure.

Kitsune is therefore a platform adoption decision, not a package-level decision. Teams that need to operate a multilingual support site can gain an existing Django codebase, browser tests, localization stages and integration with services such as Elasticsearch and Celery. Teams that only need a small support widget, a static knowledge base or a standalone search endpoint should compare the cost of the full stack with the narrower alternatives available to them.

The repository also includes Playwright tests and a development browser synchronization setup, but the README does not explain whether the test suite is suitable as a general acceptance suite for downstream deployments. That is another boundary for adopters. They should inspect the test configuration and deployment documentation before treating the project as a pluggable support foundation.

Kitsune Release Cadence, Versioning and License

The repository is not archived, and its last push was on 2026-10-16. Recent releases include 1.8.0 on 2026-10-06, 1.7.26 on 2026-09-09 and 1.7.25 on 2026-09-03. That release history shows recent project activity, although it does not by itself establish compatibility with a particular deployment or guarantee a maintenance commitment.

The README says releases follow semantic versioning. It documents a MAJOR increment for incompatible API changes, a MINOR increment for backward-compatible functionality and a PATCH increment for backward-compatible bug fixes. The release process calls for a signed tag, a GitHub release draft documenting highlights and an external deployment trigger for the specified tag. The staging site is also identified as a place to inspect changes.

Kitsune is distributed under the BSD-3-Clause license, as stated in both the project metadata and repository metadata. Contributors are also asked to follow Mozilla's Community Participation Guidelines. The license permits use under its terms, but downstream operators still need to review the actual license file and any separate service, trademark or deployment requirements before distributing a modified deployment.

Editorial conclusion

Mozilla Support operators and contributors should adopt Kitsune when they need the existing SuMo platform, its localization workflow and its integrated support services. General Django projects and teams expecting a small reusable library should look elsewhere. Before adoption, verify Python 3.14, Node compatibility, required backing services, environment configuration and the cost of operating PostgreSQL, Redis and Elasticsearch together.

Frequently asked questions

Official sources

1. License: BSD-3-Clause
2. mozilla/kitsune on GitHub
3. Project website
4. README
5. Releases