falling-sky: the source behind a network of mirrored web pages

A site source, and a network of mirrors configured in one file

The repository description is short: main source for falling-sky, mostly HTML and JavaScript. The tree explains the rest. There are templates/ for the pages themselves, images/ and icons/ for the artwork, translations/ for the localised strings, sites/ for the mirror configuration, and support/ for the helper scripts that the build uses. The Go module is minimal, module github.com/falling-sky/source with go 1.18 and no dependencies listed, which tells you that the Go code in this repository is not the application itself but a set of helper programs and the module definition that lets them run. The heart of the deployment topology is the sites directory. The maintainer notes say that if there are mirror updates to be made you edit sites.json, and that if an entry is for Other Sites rather than a full mirror you specify mirror: false. So a single JSON file describes which hosts serve the content and how each of them participates, and the build both reads it and produces a parsed JavaScript version of it, sites_parsed.js, from a template. The build therefore knows which hosts to check and which to suppress, and the site itself can read the same list.

fsbuilder does the actual building, and it is not in this repository

The build tool is a separate project. The README states that the project depends on fsbuilder and says to use make fsbuilder to make it, and the Makefile's build target runs the tool directly through the Go module runner:

go run github.com/falling-sky/fsbuilder@latest

That single line is the whole compilation step, and it has two consequences. The first is that the build is not hermetic in the usual sense: the @latest tag means the tool version is not pinned by this repository, so two builds of the same commit can use different versions of the builder. The second is that the Dockerfile treats it the same way, installing it with go install github.com/falling-sky/fsbuilder@latest in the builder stage. Everything the project produces lands in an output/ directory, which the Makefile then rsyncs to the various hosts. The Makefile also makes a point of reminding the human in the loop, since the build, beta and mtest targets each echo DO NOT FORGET TO RUN MAKE UPLOAD after the transfer. That is an unusual and honest piece of workflow design: the rsync step and the upload step are deliberately separate, so a build can be inspected on the target before the translation upload is triggered.

The CI container publishes over rsync and then discards itself

The Dockerfile is written for CI and CD, and says so in a comment: docker is used as a build method, but no docker artifacts are shipped. The final stage is FROM scratch with a single copy of /bin/true, so the image that finishes is not the site at all, it is an empty shell used to run the publish step. The builder stage is golang:alpine with make, git, rsync, curl and openssh-client, and it copies the repository in, installs fsbuilder, validates the sites file by running the parser with a skip flag, and conditionally runs the parser again in full when a release manifest exists. The publishing step is an rsync over SSH with an explicit key and a non-standard port:

rsync -a -e "ssh -o StrictHostKeyChecking=no  -i cicd_release -p 222"  output/. [email protected]:stable/content/.

A second rsync handles the internationalised variant against cicd_i18n, into an i18n/content/ directory. The keys come from files in the repository, which is why the .ssh/ directory exists at the top level. A note in the Dockerfile explains that the resulting output is not kept, so if you want the artefacts you have to map output/ to a mount or add a second stage that copies it, which is exactly what a self-hosted user would do.

Translations come from Crowdin, and they block the build when they are fresh

Localisation is handled through Crowdin, and the build integrates it in two steps. The README states that reading and writing the latest translations from Crowdin depends on credentials and on crowdin-cli, and that if you are working with the cached .po files in git, building will not block on crowdin. That conditional is the key operational detail. In the Dockerfile the download step runs only if translations/crowdin.json is non-empty, and the same guard appears around the upload step, which is the Makefile's upload target that calls make crowdin-upload inside the translations directory. So the pipeline has two modes. With credentials and a fresh manifest, the build fetches the latest translations, which is what a release needs, and a failure there fails the build rather than silently shipping stale strings. Without them, the build uses the .po files committed to the repository, which is what a contributor or an offline environment needs. The maintainer notes make the human side explicit: check the latest Crowdin translations, spot check recent changes with Google Translate, and look for evil JavaScript in the incoming translations.

The maintainer checklist is the real documentation

The README's second half is a list of tasks for the people who look after the project, and it is the most useful thing in the file. The author says they have asked a couple of people to step in and help with care and feeding, and then enumerates the work. Spot check recent translation changes. Check for support related issues. Handle mirror updates by editing sites.json, with mirror: false for Other Sites entries. And, if translations changed and nothing else did, give the build system a gratuitous kick, because the builds push to the live site and to the distribution server, and the maintainer notes that builds take about two minutes, check all mirrors, and suppress any that are unreachable. The reference to the Travis build badge in the README suggests this continuous integration path predates the GitHub Actions setups many projects moved to, and the mention of a gratuitious kick implies the pipeline is triggered by a commit rather than by a schedule. Two details stand out for anyone judging the project today. The last push to the repository was on 2026-06-06, and the repository publishes no GitHub releases, so the commit history is the only version marker. And the README says the project depends on Go 1.6, with newer versions may work but are untested, while go.mod declares go 1.18. The module file is the authoritative statement, and the README sentence is a leftover that will send a reader down the wrong path.

Where this project is the wrong tool

The limits are structural. This is a site repository with a build pipeline, not a library, a service or a framework, so there is nothing here to import and nothing here to deploy on its own. The build depends on an external tool fetched at @latest, which means the build is not reproducible from the commit alone and a change in fsbuilder can change the output of an unchanged tree. The deployment targets are hardcoded to hosts the project controls, with specific accounts, paths and a port, so nobody else can run the publish step as written. The Go version documentation is contradictory, which will bite someone building on an old toolchain. The site validation is skipped in the container path with a flag and only performed in full when a release manifest exists, so a broken sites.json can pass a routine build. And the human process is a checklist in a README rather than automation: the evil JavaScript check on incoming translations and the spot check with Google Translate are things a person has to remember to do. For a project of this size that is a defensible arrangement. For anything you intend to rely on unattended, it is not.

Editorial conclusion

Adopt falling-sky if you are maintaining the falling-sky mirror network or want to see how a small static site project wires together a separate build tool, a machine-readable mirror list and a translation platform. Do not adopt it as a framework or a reusable component, because the build depends on a specific external tool, fsbuilder, and the deployment targets are fixed hosts that the project controls. Before you touch it, read the Makefile as the project asks, check the Go version discrepancy between the README and go.mod, and remember that a translation change only reaches the live site once a build has been triggered.

Frequently asked questions

Official sources

1. falling-sky/source on GitHub
2. Issues
3. License: MIT
4. README