# FOSSology turns a license scan into a reviewable compliance workflow

> FOSSology is a license, copyright and export control scanner that runs either as a command line toolkit or as a system with a PostgreSQL database, a scheduler and a web interface. Its differentiator for large projects is deduplication, and its operational trap is the database volume, where a wrong mount path quietly loses scan history.

**fossology/fossology** — FOSSology is an open source license compliance software system and toolkit.  As a toolkit you can run license, copyright and export control scans from the command line.  As a system, a database and web ui are provided to give you a compliance workflow. License, copyright and export scanners are tools used in the workflow.

- Repository: https://github.com/fossology/fossology
- Website: https://fossology.github.io/
- Stars: 1,040 · Forks: 664
- Language: HTML
- License: GPL-2.0
- Published: 2026-10-19 · Updated: 2026-10-19 · Language: en
- Canonical page: https://hysenlabs.com/projects/fossology-fossology

## Toolkit and system are two ways to use one codebase

FOSSology is described in two ways, and the distinction is the first thing to understand. As a toolkit it runs license, copyright and export control scans from the command line, which is the mode you want in a build script or a continuous integration job. As a system it adds a database and a web interface, which turns a scan into a workflow where a person can look at each hit, decide which license applies, and record that decision so the next scan starts from it. The scanners themselves are the tools, and the workflow is what holds the results together. The output side is what makes the workflow worthwhile, because one click can generate an SPDX file or a ReadMe with all the copyright notices from your software, and those documents are what an auditor asks for. The project also lists its users and states that FOSSology does not give legal advice, which is the right boundary for a tool that produces evidence rather than conclusions.

## Deduplication is the feature large projects care about

The feature the README puts first after the workflow is deduplication, and it is the one that changes whether a full scan is affordable. The described behaviour is that you can scan an entire distribution, rescan a new version, and have only the changed files rescanned. Without that, every release means re-running the analysis over every file you have ever shipped, which is exactly the kind of job that turns into an overnight batch nobody runs. With it, the marginal cost of a rescan is proportional to what changed, so a monthly compliance run stays cheap. This is also why the architecture is split the way it is, with a scheduler service that handles the analysis tasks, a web service for the interface, and a database that stores the data: the matching between a file and its previously recorded findings is the state that makes the second scan cheap. The matching is also where a mistake bites, because a scan that cannot find its own history will either rescan everything or lose the decisions a reviewer already made.

## The compose file splits scheduler, web and database

The Docker Compose recipe defines three services, and the division matters more than the individual containers. The scheduler service runs the FOSSology scheduler daemon, which is the component that handles analysis tasks. The web service runs the web server that provides the interface, and it publishes port 8081 to port 80 on the host. The db service runs a PostgreSQL server that stores the data, and it uses the postgres:16 image. Both application services point at the same database through the same environment variables:

```yaml
- FOSSOLOGY_DB_HOST=db
- FOSSOLOGY_DB_NAME=fossology
- FOSSOLOGY_DB_USER=fossy
- FOSSOLOGY_DB_PASSWORD=fossy
```

The web service also declares FOSSOLOGY_SCHEDULER_HOST=scheduler, which is how the interface finds the daemon that does the work, and the two application services share a named volume for the repository at /srv/fossology/repository/. The health checks are worth noticing because they are asymmetric: the web container checks its API health endpoint with curl, while the scheduler check is effectively a placeholder, so a compose stack can report itself healthy while the scheduler is not actually processing anything. Starting all three at once is a single command:

```sh
docker-compose up
```

## One command gives you a working instance

For a first look, the standalone image is the fastest route and the README treats it as the default. A pre-built image is published on Docker Hub, and the run command is short:

```sh
docker run -p 8081:80 fossology/fossology
```

The instance is then reachable on port 8081 of the host, and the README names the default credentials, user fossy and password fossy. The same credentials appear in the Compose file as the database user and password, which is convenient for a demo and is exactly what you must change before this goes anywhere real. The README is also direct about production: it strongly recommends an external database, because the standalone image does not take care of data persistence. That warning is the single most important operational fact on this page, and it is easy to miss because the one-line command appears first. If you take the standalone path and do not mount the database, restarting the container loses the scan history, and with it the deduplication advantage and every reviewer decision.

## Where you mount Postgres decides whether data survives

The README spends a specific section on PostgreSQL volume mounts, and the reason is that a plausible looking mount path silently breaks persistence. The guidance is to follow the mount path recommended by the official Postgres container documentation, and to avoid version specific internal paths such as the path used by the postgres:16 image, because those directories may not be persisted as expected when containers are recreated. The failure mode is nasty in practice: the container starts, the database looks fine, the UI works, and the history quietly disappears on the next recreate. The rule is simple to apply and worth memorising. Mount the data directory at the location the Postgres image defines, let Compose manage the named volume, and treat the compose file as the source of truth for where the data lives. The health check on the web service probes the API health endpoint, which tells you the process is alive, not that the volume is right, so persistence is something you verify deliberately rather than something you observe.

## Requirements are PHP, Postgres, Apache and a build chain

FOSSology should work with many Linux distributions, and the requirements section lists what it needs. PHP 7.3 and later are supported. PostgreSQL is required as the database server and Apache HTTP Server 2.4 or later as the web server. The system dependencies are installed by the utils/fo-installdeps script, and the Python dependencies are installed by install/fo-install-pythondeps, so a source install is a matter of running the project's own scripts rather than assembling a dependency list by hand. The build itself is CMake based, with a CMakeLists.txt at the top level and a cmake/ directory, and the Dockerfile reflects that: the builder stage installs git, php8.4-cli, cmake and ninja-build on debian:trixie-slim. For a quick prototype there is a GitPod setup, where the environment opens with two terminals, one running the scheduler and one running the installation, plus a set of helper aliases, conffoss to reconfigure cmake, buildfoss to build, installfoss to install and fossrun to run the scheduler. A Vagrantfile is also provided for an isolated environment, requiring Vagrant 2.x and VirtualBox 5.2.x or later.

## Two limits: it is not advice, and the demo resets nightly

The first limit is the one the project states itself. FOSSology does not give legal advice, so its output is a set of findings with recorded decisions attached, and a human still has to decide whether a GPL-2.0 obligation, an export control question or a copyright notice is satisfied. The second is the public test instance at fossology.osuosl.org, which the README describes as usable for a quick trial but explicitly not suitable for production use, because it can be deleted or reinstalled at any time, is not up to date with the latest release, and resets every night at 2 am UTC with all uploaded user data lost. The credentials there are again fossy and fossy. The licence is GPL-2.0 for the project itself, and the top level tree carries a NOTICES file, a NOTICES.spdx file and a LICENSES directory, which is what a GPL project distributing itself is expected to do and a useful reminder that a scanner's own output style is a good model to copy. The project publishes real releases, with 4.7.2 dated 2026-09-22 after 4.7.1 and 4.7.0, and the last push was on 2026-10-16.

## Conclusion

FOSSology fits a distributor or a company with a real obligation to inventory the licences in its shipped artefacts, since the scheduler, the web review queue and the SPDX export cover the workflow that a single command line scanner cannot. It does not fit a small team that only needs a one-off license check, and it does not fit anyone who expects the tool to decide what is allowed, because the project states plainly that it does not give legal advice. Before deploying the container, mount the PostgreSQL data directory on the path the Postgres image documents rather than a version specific path such as /var/lib/postgresql/16/data, set real database credentials instead of the default fossy account, and plan on the 4.7.2 release dated 2026-09-22 as your baseline given the last push was on 2026-10-16.

## FAQ

### What does FOSSology do?

FOSSology scans software for license, copyright and export control issues. It can be run as a command line toolkit, or as a system with a PostgreSQL database, a scheduler and a web interface that turn findings into a review workflow and produce SPDX files or a copyright notice ReadMe.

### How do I run FOSSology with Docker?

A pre-built image is on Docker Hub and runs with docker run -p 8081:80 fossology/fossology, with the default credentials user fossy and password fossy. For a full setup, docker-compose up starts the scheduler, web and db services defined in the compose file.

### What are the requirements for FOSSology?

PHP 7.3 or later, PostgreSQL as the database server and Apache HTTP Server 2.4 or later. System dependencies are installed with utils/fo-installdeps and the Python dependencies with install/fo-install-pythondeps.

### Why does FOSSology deduplication matter?

It means you can scan an entire distribution and later rescan a new version with only the changed files processed, which is what makes repeated compliance runs affordable on a large codebase.

### Can I use the public FOSSology instance in production?

No. The test instance at fossology.osuosl.org resets every night at 2 am UTC, deletes uploaded data, and is not kept up to date with the latest release. The README also notes that FOSSology does not give legal advice.

## Sources

- [fossology/fossology on GitHub](https://github.com/fossology/fossology)
- [License: GPL-2.0](https://github.com/fossology/fossology/blob/master/LICENSE)
- [Project website](https://fossology.github.io/)
- [README](https://github.com/fossology/fossology/blob/master/README.md)
- [Releases](https://github.com/fossology/fossology/releases)

---

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