DIERCKI — sternprodukt atlas

A world atlas in the manner of the Diercke classic, but of the Sternprodukt kind. Blätter on Romania and Brandenburg, a legend after the atlas model, and a QGIS map set.

Inhalt.dc.html is the same table of contents in the Sternprodukt look — grouped, linked, with the notes you need while looking something up. This file stays the machine-readable version.

A note on language. Prose here is English; the cartographic and project vocabulary stays German and untranslated — Blatt, Signatur, Schummerung, Quellenregister, belegt / abgeleitet / unbelegt. That is the rule in CLAUDE.md, and a Signatur is not a „symbol“. It covers terms that carry cartographic meaning, not every German word in reach: legend and map set are plain technical vocabulary and get translated. Filenames never do.

Two things in this file are read by the application and must not be translated: the three headings ## Blätter, ## Weitere Blätter and ## Präsentationen (Sources::Sheets::HEADINGS matches them literally), and the description cells of those tables (they appear on the Schaukasten cards). Change a heading and the sheet list goes empty.

Getting it running

A single Blatt needs nothing: open Rumaenien-Physisch.html in a browser and there it is. It will pull d3 and topojson from a CDN, though.

For the whole application — home page, Schaukasten, Blattschau, Namensregister, Werkstatt — there are two ways.

With Ruby, without Docker

Needs Ruby 3.4 (rbenv: rbenv install 3.4.2, .ruby-version sits next to this file).

bundle install                 # gems into .bundle/gems, not into the system
ruby bin/vendor.rb             # once: the nine vendored libraries into .vendor/
cp .env.example .env           # then fill in the two blanks it explains
bundle exec puma               # → http://localhost:9292/

Puma serves it, the same server the container runs, and it reads config.ru by itself. Not rackup: since Rack 3 that executable lives in a separate gem, which this project does not carry.

The application reads .env on the way up — docker compose does that by itself, puma does not, and it refuses to start without the three values. dry-system‘s settings provider does the reading, so the chain is the one dotenv defines; the first file that sets a name wins:

.env.<RACK_ENV>.local · .env.local (never in test) · .env.<RACK_ENV> · .env

A variable already in the environment wins over all of them. Nothing gets a default, and a value that is present but wrong — a .env with the bcrypt hash raw instead of base64 — stops the start just as loudly as a missing one, with all the faults named at once rather than one restart at a time.

bin/vendor.rb is the only step that needs a network. Everything after it works offline. It verifies the two SRI hashes on the way and aborts if a file is not byte-identical — otherwise the browser would refuse the script later without a word.

Tests: bundle exec ruby -Itest test/web_test.rb

With Docker

Needs no Ruby on the machine.

Same .env as above:

docker compose --profile local up dev       # → http://localhost:9292/

.env is the only file compose reads by itself — .env.local and .env.development are Node and Rails conventions and are ignored here. Git ignores .env; .env.example is the template and is versioned.

The hash is base64, and that is not a style choice: a bcrypt hash is made of $-fields, and both readers of a .env resolve those. Compose does it to every value it reads; dotenv does it to the same file when the application runs without Docker. Raw, the hash arrives mangled or empty and the correct password stops working with nothing to explain it. web/boot.rb refuses to start on a raw one.

dev mounts the working tree read-only: a change to a file is there on the next request, without a restart and without a build step. To check what would actually ship:

docker compose --profile local up preview   # → http://localhost:9293/, tree from the image

Both sit behind the local profile and never start on the server.

When it does not work

Blätter

Each Blatt is a standalone HTML file in the root, D3-based, with a Zeichenerklärung and its sources in the footer.

Weitere Blätter

In the root, following the same rules, but not part of the Kartenwerk.

Präsentationen

Layout

atlas/
  signaturen.js       Signaturenkatalog (SVG per map object)
  SIGNATUREN.md       how the catalogue is built, rules for adding to it
  typenscale.js       type scale — seven steps, lower bound 5.5 pt
  farben.js           colour system — the single source of hex values in the atlas
  farben-paletten.rb  generates the .gpl palettes from farben.js
  register.csv        Namensregister of the volume, maintained by hand
  blaetter.csv        Blattschlüssel — which Blattnummer means which file
  BLAETTER.md         the reasoning; the numbers are abgeleitet, not belegt
  marke/              logo and handwritten wordmark
  GLOSSAR.md          the Blätter's technical terms, alphabetically
  paletten/           .gpl palettes for QGIS/GIMP, derived from farben.js
  quellen/            Quellenregister per Blatt (belegt / abgeleitet / unbelegt)
  geodaten/           scripts that turn raw deliveries into map data
  qgis/               QGIS-Kartensatz: basis/ (theme-neutral) + themen/ (one folder per Blatt)
                      themen/brandenburg-hanf/ doubles as the QField package for
                      fieldwork (instructions in the README there)

bin/                  tools — sync-report.rb compares the clone against the ZIP export,
                      vendor.rb fetches the nine vendored libraries,
                      pruefe-blaetter.rb checks the Blattschlüssel against sheet content
web/                  the web application (Roda, dry-rb) and its design
  app.rb              routes
  auth.rb             the login: Rodauth as a middleware in front of everything
  boot.rb             container (dry-system), root path, vendor directory,
                      and the three required settings with their checks
  lib/atlas/          readers, transforms, middleware
  templates/          ERB templates — they mirror the class names of Muster.dc.html
  site.css            design — owned by the design UI
  Muster.dc.html      every building block once — owned by the design UI
  site.js             enhancement: place the Signaturen, filter the Register
  geschuetzt.csv      paths that require a login
test/                 minitest + rack-test
handarbeit/           only the human writes here — QGIS projects, survey GeoPackages
praesentationen/      decks (pitch, QField how-to) and wireframes
recherche/            research notes and recorded decisions
skills/               project-owned skills (belegstatus, atlas-kartenblatt, …)
uploads/              data and images the Blätter load at runtime
screenshots/          QA captures; three are embedded by "Kleiner Gruß aus der Küche"
wip/                  working store, including the ZIP export and the reference
                      scans of the printed Diercke — ignored by `.gitignore`
_ds/                  the bound Sternprodukt design system (do not touch)

config.ru             the Rack stack, outside in: auth, guard, rewrite, files, app
Dockerfile            the image — built by .github/workflows/ci.yml, published to ghcr
docker-compose.yml    the dev and preview profiles, and the production service
.env.example          template for the three required values; .env itself is ignored
github.md             repo binding and the log of syncs with the design UI

Not in the clone but in the design project: scans/ — the reference scans of the printed Diercke, around 60 MB. They are comparison material, no Blatt embeds them; whoever needs them takes them out of the export.

Where the rest is written down

Colours and Signaturen go through atlas/farben.js and atlas/signaturen.js and nowhere else — no new hex values, no ad-hoc symbols in individual Blätter. The .gpl palettes are derived from them (atlas/farben-paletten.rb) and are not maintained by hand.

Generated geodata is versioned

The scripts under atlas/geodaten/ build map data out of third-party deliveries. Their results live in the repo, not just the scripts — even though that contradicts the usual rule of not versioning what is generated.

The reason is the input side: CLC2018 arrives as several gigabytes through a portal, nested as Results/…geoPackage.zip/DATA/…gpkg; the GBIF and Overpass queries return something different depending on the day. A product whose input cannot be reliably obtained again is effectively a source, and is treated as one. Otherwise whoever clones pays the price: a Blatt that stays silently empty, and half a day spent looking for the reason.

This covers nutzung-*.geojson (nine area classes, 12 MB, read by Rumaenien-Wirtschaft.html), friedhof-freiburg.geojson and the datasets under atlas/qgis/themen/rumaenien-baer/daten/.

Only the intermediate stages stay out — raw deliveries, unpacked archives, working copies. What .gitignore excludes is justified there.

Lookup tables without a build step

Tables a human maintains are read at runtime — by the Blatt as it loads, by QGIS as an attribute join, by QField as a value list. No derived intermediate file that goes quietly stale when an export script did not run:

Where an entry is missing, nothing is guessed: the case gets a visible class of its own („ungeklärt“, „Ort nicht verifiziert“). Check scripts such as brandenburg/pruefe-hanf.rb and bin/pruefe-blaetter.rb only report — they generate nothing.

Sources and evidence

Every number on a map has a row in the Quellenregister (atlas/quellen/), with the status belegt, abgeleitet or unbelegt. Geometry from named datasets (Eurostat GISCO, OSM, GBIF) goes into the footer of the Blatt instead.

QGIS

The Kartensatz under atlas/qgis/ is split into theme-neutral (basis/) and per-Blatt (themen/<name>/). Setup and recipes are in QGIS-Kartensatz.dc.html; the working CRS is EPSG:3844 (Stereo 70).

Since 08/2026 the styles know about scale: a Bezugsmaßstab of 1:2 500 000 in every style (mm dimensions follow the output scale), selection by scale in punkt_ort.qml (rule-based, five settlement sizes with their own bounds), and a Beschriftungsrang laid out as a ladder from 10 down to 3 instead of arbitrary values. Type sizes come from atlas/typenscale.js, lower bound 5.5 pt.

Environment

• QFieldCloud is self-hosted. No 100 MB limit, no third-party storage. The object store underneath is S3-compatible and in our own hands; the WebDAV drop for attachments alone is therefore readily available. Reason about storage and syncing from that premise, not from app.qfield.cloud.
• Working CRS: EPSG:3844 (Stereo 70) for Romania, EPSG:25833 for Brandenburg.
• QGIS 4.2, QField „Coral Sea“.