Ceph: what a build manual, a licence inventory and 1457 backport issues tell you

The README is a build manual and admits it in the first line

The ceph/ceph README opens with the project name, a one-line description as a scalable distributed storage system, and then an instruction to go elsewhere for current information: see https://ceph.com/ for current information about Ceph. That single sentence is the correct shape for this file. The repository is where engineers work, and its README is written for engineers who are about to compile the thing, not for someone deciding whether to deploy it.

What follows is a developer build guide with real precision. There is a Checking out the source section that gives both an SSH clone and an HTTPS alternative for people who are not github users, then tells you to move into the cloned directory and run git submodule update --init --recursive --progress. That last step is not optional and not decorative, because a Ceph checkout without its submodules is a checkout that configures and then fails.

There are two status badges and both are meaningful. The first is an OpenSSF Best Practices badge pointing at project 2220 on bestpractices.dev. The second is an Issue Backporting badge wired to a GitHub Actions workflow named create-backport-trackers.yml. Hold onto that second one, because it explains the single most surprising number in this repository and there is a whole section about it below.

So the honest description of this README is that it is three documents wearing one filename. The build instructions are genuinely good. The contributing instructions are strict and specific, covering signed-off-by requirements and copyright assignment. And the licence discussion is not a summary but an audit trail. Nothing here is marketing, which is exactly why it is useful to read.

CMake and Ninja, with a memory budget stated in gigabytes

Ceph does not use a hand-written Makefile at the top level. The process is do_cmake.sh, then Ninja. You run ./do_cmake.sh, change into the build directory, and run Ninja there. The commands are short enough to be worth quoting exactly, because the sequence is the thing people get wrong:

cd build
ninja -j3
ninja install

The third command is the one with a specific purpose: it installs the vstart cluster, which is the single-node development environment Ceph uses for testing. That is the difference between building Ceph and running Ceph locally.

The IMPORTANT callout beside the build step is where the practical advice lives. Ninja job count defaults to the number of CPU cores, and the -j option exists so you can cap it, because each parallel job needs on average approximately 2.5 GiB of RAM. The failure mode is named explicitly: if you see g++: fatal error: Killed signal terminated program cc1plus, you have run out of memory, and the fix is to pass a -j value appropriate to the machine. This is a more useful sentence than most projects manage, because it connects a cryptic compiler error to a specific remedy. On a large workstation, -j3 will feel slow, and the README is telling you to use it anyway.

Two further knobs are documented. Extra CMake arguments can be set through ARGS before invoking the script, with the example ARGS="-DCMAKE_C_COMPILER=gcc-7" ./do_cmake.sh for building against an older compiler. And if your build directory is not a subdirectory of the checkout, you point CEPH_GIT_DIR at the right path rather than moving the tree. Both are the kind of detail that only gets written down after someone lost an afternoon to it.

A debug build can cost you four fifths of your performance

The Build Types section is short and carries the most quotable claim in the entire README. By default do_cmake.sh creates a debug build, assuming .git exists, and a Debug build runtime performance may be as little as 20 percent of that of a non-debug build. Pass -DCMAKE_BUILD_TYPE=RelWithDebInfo to get a non-debug build. Once .git does not exist, RelWithDebInfo becomes the default instead.

That .git-conditional default is a small piece of design worth understanding. The build system infers what you are doing from whether you have a source checkout, which means a developer running ./do_cmake.sh gets assertions they want and someone building from an exported tarball gets a release configuration without asking for it. It also means the difference between a fast build and a slow one is invisible unless you read this section, which is exactly why the performance figure is stated as a number rather than as advice.

The build type table shows what changes underneath. Debug gives you debug info, -Og optimizations, no sanitizers, and both ceph_assert and assert checks, for gdb and development. RelWithDebInfo gives you debug info, -O2 with -DNDEBUG, no sanitizers, and ceph_assert only, for production. So debug information survives in both modes, which is why the second mode is the one you want for field diagnosis: you keep the symbols and lose the assertions.

The next section, CMake Options, is where the dependency story gets interesting. Ceph has several bundled dependencies such as Boost, RocksDB and Arrow, and by default cmake builds these from source rather than using libraries already installed on the system. That default is a deliberate trade: it guarantees a consistent dependency set on any machine, and it costs a great deal of build time and disk. The escape hatches are per-dependency options such as -DWITH_SYSTEM_BOOST=ON, and cmake -LH lists them all. The related options include building without the RADOS Gateway with -DWITH_RADOSGW=OFF, which matters if you have no use for the object store.

Why the licence metadata says nothing useful

Ceph is one of the more permissively licensed large infrastructure projects, and the metadata in this repository's record reads NOASSERTION, which sounds alarming until you read the README. It is not a licence problem. It is an expression problem.

The actual position is stated in the Contributing Code section. Most of Ceph is dual-licensed under the LGPL version 2.1 or 3.0. Some miscellaneous code is either public domain or licensed under a BSD-style licence. The documentation is licensed under Creative Commons Attribution Share Alike 3.0, which is CC-BY-SA-3.0. And some headers included in the ceph/ceph repository are licensed under the GPL. The instruction for anyone who needs to know precisely is to see the file COPYING for a full inventory of licences by file.

That last sentence is the right architecture. A project this size, with this much code carried across two decades and multiple contributors, cannot honestly be summarised by one string, so it ships an inventory instead. The root tree carries COPYING alongside COPYING-GPL2, COPYING-LGPL2.1 and COPYING-LGPL3, which are the texts rather than the map, plus AUTHORS and a .mailmap for attribution. If you are shipping Ceph in a product, the LGPL obligations attach to how you link it rather than to the fact of using it, and COPYING is the file that lets your legal team answer that without guessing.

The contribution rules are strict in a specific way. All code contributions must include a valid Signed-off-by line, with SubmittingPatches.rst explaining how to generate and submit one. Assignment of copyright is not required, and code is contributed under the terms of the applicable licence. The tree also carries SubmittingPatches-backports.rst and SubmittingPatches-kernel.rst, which means the project recognises that stable branches and kernel trees have different rules from trunk.

1457 open issues, and the workflow that creates them

The repository has 1457 open issues against 17060 stars and 6506 forks. For a project of this age that ratio invites a guess, and the guess would be wrong. The badge at the top of the README points at create-backport-trackers.yml, a GitHub Actions workflow whose name says what it does: it opens an issue for each backport that needs tracking.

So a meaningful fraction of those 1457 open issues are not defects. They are work items that exist to track a change being carried from a development branch onto one or more stable branches. A project with a long support matrix has to produce that bookkeeping, and generating it as issues makes it visible and assignable rather than living in a wiki page nobody reads. The maintainers clearly considered this important enough to automate and to advertise, and the PendingReleaseNotes file in the root is the other piece of the same apparatus, holding notes for the release in progress.

That also reframes how the numbers should be read generally. 6506 forks is very high, and for an infrastructure project that number partly reflects distributions vendoring the source rather than developers proposing patches. 17060 stars is a measure of interest, not adoption. Neither figure tells you how many production clusters exist, and no figure in this repository would. What the repository does tell you is that it is actively worked: the last push was 2026-09-21, and there is no sign of an archived or abandoned project here.

The examples directory is small and pointed, which is a good sign rather than a thin one. There are examples for libfdb, librados, librbd, rbd-replay and rgw, covering the block, object and filesystem client libraries plus a block replay tool. Sitting at the repository root are ceph-object-corpus and ceph-erasure-code-corpus, which are test fixtures for the object store and erasure coding rather than documentation, and the presence of erasure-code corpus data in the root tree tells you that erasure coding is tested as a first-class path. The qa directory and fusetrace directory extend the same idea into integration testing and FUSE-level tracing.

Ports, packaging, and a dependency section dated 2024

The root tree is a decent map of how broad this project is. Platform-specific READMEs exist for FreeBSD, AIX, Solaris and Windows, and the build scripts follow that spread: do_freebsd.sh and mingw_conf.sh sit next to do_cmake.sh, with CephBuild documentation in ContainerBuild.md and a Dockerfile.build for containerised builds.

Packaging is a first-class concern rather than an afterthought. The tree has debian/, ceph.spec.in for RPM, make-debs.sh, make-srpm.sh and a make-dist script, and the README tells you something practical about it: the instructions you are reading are meant for developers compiling for development and testing, and if you want binaries suitable for installation you should build .deb or .rpm packages instead, or refer to ceph.spec.in or debian/rules to see which configuration options are specified for production builds. That is the correct and often-skipped instruction, because a hand-run cmake install and a production package are configured differently on purpose.

There is also a documentation build (doc/, mkdocs-style config, .readthedocs.yml), infrastructure-adjacent directories such as mirroring/, monitoring/, admin/, man/, etc/, keys/, and a set of contributor tooling files that I have not seen in many projects: .peoplemap, .organizationmap, .githubmap and .gitleaks.toml. The maps are an unusual convention for tracking people and organisations across a large contributor base, and the gitleaks configuration suggests a deliberate policy around secret scanning in a repository that holds release signing material.

The one thing I would not rely on is the Build Prerequisites section, which carries the note section last updated 06 Sep 2024, roughly two years before the last push. It gives apt install curl, then ./install-deps.sh, then apt install python3-routes. That sequence is almost certainly still directionally right, and install-deps.sh is the piece that matters because it encodes the real dependency set for your distribution. But a section dated 06 Sep 2024 in a repository pushed on 2026-09-21 is a signal to run the script and read its output rather than to trust the prose above it. The same honesty applies to the small quality-of-life details at the end of the README, such as preserving diagnostic colours with -DDIAGNOSTICS_COLOR=always and then piping through ninja | less -R, which are the kind of touches that appear once someone has lost a long compile log to readability problems.

Editorial conclusion

Reading this repository tells you something useful about Ceph that a product page would not. There are no GitHub releases in this data, which is correct rather than alarming, because Ceph versions its work through named branches and package builds rather than through tags on github.com. The build path is documented to an unusual degree, down to the point where each parallel Ninja job needs roughly 2.5 GiB of RAM and a Debug build can run at 20 percent of release performance, so a machine that looks adequate for a C++ project may not be adequate for this one. The licensing is genuinely per file, with COPYING acting as the inventory that the metadata field cannot express. And the 1457 open issues are explained by a workflow that opens a tracker for each backport rather than by a project in trouble. Two things to carry into any evaluation. The Build Prerequisites section is dated 06 Sep 2024, so treat install-deps.sh as the source of truth for your distribution rather than the surrounding prose. And read the bundled dependency list, since Boost, RocksDB and Arrow are compiled from source by default unless you pass an option such as -DWITH_SYSTEM_BOOST=ON.

Frequently asked questions

Official sources

1. ceph/ceph on GitHub
2. Issues
3. Project website
4. README