linux-insides: a kernel book you build with Docker and read chapter by chapter

What linux-insides is, and the reader it assumes

The README states the goal plainly: to share knowledge about the Linux kernel internals and related low-level topics. That places it in a narrow category. It is not a tutorial that gets you to a working driver in an afternoon, and it is not an API reference. It walks through kernel source, which means the reader needs the two prerequisites the README lists: prior knowledge of assembly language and proficiency in C. The README also points to the Intel Software Developer Manuals for x86_64 details, which tells you how far down the stack the text goes.

The book is organized as a set of top-level directories, one per topic: Booting, Initialization, Interrupts, SysCall, Timers, SyncPrim, MM, Cgroups, DataStructures, KernelStructures, X86, Toolchain, Contributing, and Concepts. SUMMARY.md is the table of contents. If you want to know whether a topic is covered at all, that file answers faster than the README does. The intended audience is someone who can follow a page of C and a page of assembler side by side and wants to know why the kernel does what it does, not someone looking for a configuration guide.

Chapter status is the first thing to check, not the last

The README carries a chapter status list against kernel v7.2.0, and exactly one entry is checked: Booting, updated for v7.2.0. The other fourteen, from Initialization through Contributing to the Linux kernel, are marked pending a v6.18.0 review. The author explains why: the series began when the latest kernel was 3.18, and the content is being revised to reflect modern kernels (v6.18+).

This is the single most useful fact on the page, and it is easy to skim past. A chapter that has not been reviewed against a modern kernel may still describe structures and call paths that have since been reorganized. The prose is not necessarily wrong in its reasoning, but the source excerpts it quotes can be stale. Read the status list as a freshness map: Booting is the chapter the author currently stands behind, and everything else is on a queue with no dates attached. If you are deciding where to spend an evening, that list makes the decision for you.

How the book is built and served with GitBook

The repository is a GitBook project. The Dockerfile is short and pins the toolchain: it builds from kyselejsyrecek/gitbook:3.2.3, copies the repository into /srv/gitbook, exposes port 4000, and sets the working directory there. The container command is /usr/local/bin/gitbook serve. Two commented lines in the same file show the other outputs the image can produce, gitbook pdf and gitbook epub.

The Makefile wraps that container in targets. make image builds the image tagged linux-insides-book:latest, preferring a build with --squash and falling back to a plain build if that fails. make run stops any container named linux-insides-book, then runs a detached container publishing port 4000 and naming the host linux-insides-book. make start, make sh, make logs, and make rm handle the rest of the lifecycle. The data flow is simple: Markdown files in the chapter directories are read by GitBook at serve time, and the browser renders them. There is no compilation step for the prose itself. The one non-trivial piece is the export target, which walks the tree for .svg files and converts them to PNG through Inkscape before the e-book build, so image assets are produced on demand rather than committed as PNG.

Running it locally and reading the first chapter

The repository ships a Makefile whose targets are documented through comments, so make help prints them. From a clone of the repository, the shortest path is to build the image and start the container. The image build may take a while the first time because it pulls the GitBook base image.

make image

After the image exists, this starts the server in the background on port 4000 and names the container linux-insides-book. The target stops any previous container with that name first, so it is safe to repeat.

make run

Open http://localhost:4000 in a browser. You should see the book rendered from SUMMARY.md, with the chapter list in the sidebar. To confirm the container is healthy, the Makefile provides a logs target, and an interactive shell target for poking around inside the running container.

make logs
make sh

For a first real read, open the Booting directory. It is the chapter the README marks as updated for v7.2.0, so it is the one place where the prose and the kernel version line up. If you want a PDF or EPUB instead of the served site, the export target runs the e-book generation inside the already running container, converting SVGs through Inkscape on the way.

make export

The Docker and Inkscape dependencies you inherit

Running the book means running someone else's container. The Dockerfile pins kyselejsyrecek/gitbook:3.2.3, a third-party image, not an official GitBook release, and GitBook 3.x is an old toolchain. That pin is a trade-off: it makes the build reproducible, but it also means the rendering stack moves only when someone edits the Dockerfile. If that image disappears from the registry, make image fails and the Makefile's fallback does not help, because the fallback only covers the --squash flag.

The export target has a second dependency the serve path does not: Inkscape. It converts every .svg under the chapter directories to PNG at 150 DPI before generating the e-book, skipping .github and _book. If Inkscape is not present in the container, export fails partway through. That is a real difference between reading the book and producing a distributable copy of it, and the README does not mention Inkscape at all. The Makefile is the only place this requirement is visible, which is worth knowing before you plan an offline PDF.

Translation forks and what they do not promise

The README lists seven translations maintained by volunteers: Brazilian Portuguese, Chinese, Japanese, Korean, Russian, Spanish, and Turkish, each pointing at a separate repository. A note directly above the list states that the translations may diverge from the original content. That is an honest warning and it should shape how you use them.

The upstream chapter status list applies to the original. A translation fork has its own commit history and its own lag, and nothing in this repository tracks how far behind any of them is. If you read Chinese or Russian because it is faster for you, you are reading a snapshot of a snapshot. For the Booting chapter, which is the one currently updated upstream, a translation may still reflect the older text. The practical consequence: when a translated passage and the English original disagree about a structure or a function, the original is the one being maintained. Use the translations for orientation and the original for the source-level detail.

Where a different book is the better choice

linux-insides is a bottom-up book. It starts at the boot path and works through interrupts, system calls, timers, and memory, quoting kernel source as it goes. That approach is excellent for building a mental model of how the kernel is put together, and poor for answering a question today about a specific subsystem's current API.

If you need to write a driver against a current kernel, or look up how a particular allocation function behaves now, a task-oriented reference or the kernel's own documentation tree will serve you better; they are updated with the code they describe, while this book's chapters wait in a review queue. If you want a guided tour of the boot process with the reasoning spelled out, this is closer to what you want. The difference is not quality, it is direction: one is organized around the source tree's history and structure, the other around the problem in front of you. The README's requirement of assembly and C fluency is the honest signal of which one this is. A reader who cannot yet read a page of x86 assembly will spend more time on prerequisites than on the book, and the README itself points such readers to the author's separate assembly series.

Licence, contribution, and the cost of keeping up

The project is licensed under BY-NC-SA Creative Commons, which the README links to version 4.0. The NonCommercial term matters if you were thinking of packaging the text into paid training material; the ShareAlike term matters if you plan to publish a modified version. The repository has a LICENSE file at the top level. This is a description of what the README states, not legal advice; check the licence text yourself for your use case.

Maintenance is a moving target by design. The last push to the default branch was on 2026-08-19, and the README describes an ongoing revision from kernel 3.18-era content toward v6.18 and beyond. The upgrade cost is therefore not a version bump you perform; it is waiting for the author to work through the pending review list, and re-reading a chapter when its checkbox changes. Contributions go through the guide in CONTRIBUTING.md and the code of conduct, and issues or email are the listed channels. There is also a Google group, [email protected], reached by sending mail to [email protected] or by joining through the archive page. For a book whose value is tied to kernel source, that mailing list is arguably as useful as the text.

Editorial conclusion

Adopt linux-insides if you already read C and x86 assembly and want the boot path traced through real kernel source, starting with the Booting chapter that the README marks as updated for v7.2.0. Do not adopt it as a current reference for memory management, cgroups, or synchronization, because those chapters are still pending a v6.18.0 review, and do not treat the translations as equivalent to the original. Before relying on any chapter, check the checkbox list in README.md for its status, and open a specific file such as Booting/ to confirm the code it quotes still matches the kernel you are targeting.

Frequently asked questions

Official sources

1. Official documentation
2. Official README
3. Project repository