From ccc0f92aa07869694a712682e3d5f4d61292a293 Mon Sep 17 00:00:00 2001 From: Claude Date: Fri, 11 Sep 2026 15:09:34 +0000 Subject: [PATCH 1/3] Move deployment docs to DEPLOYMENT.md and document the specref.org DNS The README's Deployment section only covered the Clever Cloud health check. Move it to a dedicated DEPLOYMENT.md that also describes how the website is published from docs/ with GitHub Pages, and how the specref.org zone points the apex and www at GitHub Pages and api at Clever Cloud. Co-Authored-By: Claude Fable 5.1 Claude-Session: https://claude.ai/code/session_014MHCXm9fYmK4oZ425YG7VZ --- DEPLOYMENT.md | 112 +++++++++++++++++++++++++++++++++++++++++++++++++ README.md | 6 +-- docs/README.md | 2 +- index.js | 2 +- 4 files changed, 115 insertions(+), 7 deletions(-) create mode 100644 DEPLOYMENT.md diff --git a/DEPLOYMENT.md b/DEPLOYMENT.md new file mode 100644 index 000000000..0c5dd527d --- /dev/null +++ b/DEPLOYMENT.md @@ -0,0 +1,112 @@ +# Deploying Specref + +Specref is made of two independently deployed parts, both served under the +`specref.org` domain: + +| Hostname | What it serves | Hosted on | +| ------------------------------------------ | ------------------------------------------- | ----------------------------------------------- | +| `https://www.specref.org` (+ `specref.org`) | The static website (search UI) in [`docs/`](./docs/) | [GitHub Pages](https://pages.github.com/) | +| `https://api.specref.org` | The JSON API ([`index.js`](./index.js)) | [Clever Cloud](https://www.clever-cloud.com/) | + +Both deploy automatically from the `main` branch of +[specinfra/specref](https://github.com/specinfra/specref), which is also what +the [hourly auto-update](./CONTRIBUTING.md#hourly-auto-updating) pushes to. +There is no manual deployment step. + +## Table of Contents + +* [API (Clever Cloud)](#api-clever-cloud) + * [Health check](#health-check) +* [Website (GitHub Pages)](#website-github-pages) +* [DNS for specref.org](#dns-for-specreforg) + * [Records](#records) + * [Changing the DNS](#changing-the-dns) + +## API (Clever Cloud) + +The API is a Node.js application (see the `engines` field in +[`package.json`](./package.json) for the required versions) hosted on +[Clever Cloud](https://www.clever-cloud.com/). It is started with `npm start` +(i.e. `node index.js`) and listens on the port given by the `PORT` +environment variable, which Clever Cloud sets automatically. + +The application is linked to the GitHub repository, so every push to `main` +triggers a new build and deployment. Once the new instance answers the +[health check](#health-check), traffic is switched over to it. + +### Health check + +The server exposes a lightweight health check endpoint at `/health` which +always responds with `200 OK` and `{ "status": "ok" }`, without touching the +reference database. + +Clever Cloud must be configured to poll this endpoint (rather than `/`, which +returns a 404) so that it can tell whether the instance is up during +deployment and while it is running, and only restarts it when it actually +stops responding. Set the following environment variable on the Clever Cloud +application: + + CC_HEALTH_CHECK_PATH=/health + +## Website (GitHub Pages) + +The website at [www.specref.org](https://www.specref.org/) is a static site +whose source lives in the [`docs/`](./docs/) directory. It is published by +[GitHub Pages](https://docs.github.com/en/pages) from the `main` branch. + +Repository settings (_Settings → Pages_): + +* **Source:** _Deploy from a branch_ +* **Branch:** `main`, folder `/docs` +* **Custom domain:** `www.specref.org` (this must match the content of + [`docs/CNAME`](./docs/CNAME), which GitHub Pages reads at build time; do not + delete or edit that file unless you are changing the domain) +* **Enforce HTTPS:** enabled + +The site is rendered by Jekyll. [`docs/_config.yml`](./docs/_config.yml) only +exists to make Jekyll include the `.well-known/` directory, which it would +otherwise skip because of the leading dot. + +The website talks to the API cross-origin (`https://api.specref.org`), which +is why [CORS is enabled for all origins](./README.md#cors) on the API. + +## DNS for specref.org + +The `specref.org` zone points at both hosting providers: the apex domain and +`www` go to GitHub Pages, and `api` goes to Clever Cloud. + +### Records + +| Name | Type | Value | Points to | +| --------------------- | ------- | -------------------------------------------------------------- | ------------ | +| `specref.org` | `A` | `185.199.108.153`
`185.199.109.153`
`185.199.110.153`
`185.199.111.153` | GitHub Pages | +| `specref.org` | `AAAA` | `2606:50c0:8000::153`
`2606:50c0:8001::153`
`2606:50c0:8002::153`
`2606:50c0:8003::153` | GitHub Pages | +| `www.specref.org` | `CNAME` | `specinfra.github.io` | GitHub Pages | +| `api.specref.org` | `CNAME` | the target shown under _Domain names_ in the Clever Cloud console (`domain.par.clever-cloud.com` for applications in the Paris zone) | Clever Cloud | + +Notes: + +* **GitHub Pages.** `www.specref.org` is the canonical hostname (it is the + custom domain configured in the repository settings and in `docs/CNAME`). + Because the apex `specref.org` also resolves to GitHub Pages, GitHub + automatically redirects `https://specref.org/…` to + `https://www.specref.org/…`. The IP addresses above are GitHub's documented + Pages addresses; check them against + [GitHub's documentation](https://docs.github.com/en/pages/configuring-a-custom-domain-for-your-github-pages-site/managing-a-custom-domain-for-your-github-pages-site) + before changing them. +* **Clever Cloud.** `api.specref.org` must also be added to the application's + _Domain names_ in the Clever Cloud console, otherwise Clever Cloud's load + balancers will not route requests for that hostname to the application. + Clever Cloud provisions and renews the TLS certificate for it + automatically once the DNS record resolves. See + [Clever Cloud's custom domain documentation](https://www.clever-cloud.com/developers/doc/administrate/domain-names/) + for the exact CNAME/A record targets of the zone the application runs in. +* Both providers only ever see the hostname they are responsible for, so + neither needs to know about the other. Moving one part (e.g. the API to a + different host) only requires changing that hostname's record. + +### Changing the DNS + +The zone is managed at the domain's registrar. Changes are not tracked in +this repository, so when you change a record, please open an issue or a pull +request updating the table above so it stays accurate. diff --git a/README.md b/README.md index d96a6f9c4..a9005c430 100644 --- a/README.md +++ b/README.md @@ -224,11 +224,7 @@ If you need to find a reference ID (for either bibliographic or cross-references ## Deployment -The API is hosted on [Clever Cloud](https://www.clever-cloud.com/). The server exposes a lightweight health check endpoint at `/health` which always responds with `200 OK` and `{ "status": "ok" }`, without touching the reference database. - -Clever Cloud must be configured to poll this endpoint (rather than `/`, which returns a 404) so that it can tell whether the instance is up during deployment and while it is running, and only restarts it when it actually stops responding. Set the following environment variable on the Clever Cloud application: - - CC_HEALTH_CHECK_PATH=/health +The website (www.specref.org) is hosted on GitHub Pages and the API (api.specref.org) on Clever Cloud. See [DEPLOYMENT.md](./DEPLOYMENT.md) for how both are deployed and how the `specref.org` DNS is set up. ## Contributing diff --git a/docs/README.md b/docs/README.md index f8e251dbc..67303f740 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,4 +1,4 @@ www.specref.org =============== -Source code for the static website hosted on www.specref.org. +Source code for the static website hosted on www.specref.org (published with GitHub Pages, see [DEPLOYMENT.md](../DEPLOYMENT.md)). diff --git a/index.js b/index.js index f62fc3410..df354d410 100644 --- a/index.js +++ b/index.js @@ -15,7 +15,7 @@ app.enable("etag"); // Health check. Registered before the IP filter, compression and body // parsing middleware so that it stays cheap and can never be blocked or // slowed down by them. Clever Cloud polls this path (see -// CC_HEALTH_CHECK_PATH in the README) both during deployment and while +// CC_HEALTH_CHECK_PATH in DEPLOYMENT.md) both during deployment and while // the app is running, and restarts the instance if it fails to respond // with a 2xx status code. app.get('/health', function (req, res) { From 215fb2e1005c2bad6b9b47c2da5cda4e6f2c4806 Mon Sep 17 00:00:00 2001 From: Claude Date: Fri, 11 Sep 2026 15:13:12 +0000 Subject: [PATCH 2/3] DEPLOYMENT.md: fix CORS rationale, drop DNS record table, name the registrar CORS is enabled so that anyone can consume the API as JSON from a browser, not for the website's benefit. The DNS record values would drift, so point at the providers' documentation instead. Note that the domain is hosted at Namecheap. Co-Authored-By: Claude Fable 5.1 Claude-Session: https://claude.ai/code/session_014MHCXm9fYmK4oZ425YG7VZ --- DEPLOYMENT.md | 72 +++++++++++++++++++++------------------------------ 1 file changed, 30 insertions(+), 42 deletions(-) diff --git a/DEPLOYMENT.md b/DEPLOYMENT.md index 0c5dd527d..a847442c0 100644 --- a/DEPLOYMENT.md +++ b/DEPLOYMENT.md @@ -19,8 +19,6 @@ There is no manual deployment step. * [Health check](#health-check) * [Website (GitHub Pages)](#website-github-pages) * [DNS for specref.org](#dns-for-specreforg) - * [Records](#records) - * [Changing the DNS](#changing-the-dns) ## API (Clever Cloud) @@ -34,6 +32,10 @@ The application is linked to the GitHub repository, so every push to `main` triggers a new build and deployment. Once the new instance answers the [health check](#health-check), traffic is switched over to it. +[CORS is enabled for all origins](./README.md#cors) so that anyone can use +the API directly as JSON from a browser, whatever the origin of their page. +The API is not restricted to the Specref website in any way. + ### Health check The server exposes a lightweight health check endpoint at `/health` which @@ -67,46 +69,32 @@ The site is rendered by Jekyll. [`docs/_config.yml`](./docs/_config.yml) only exists to make Jekyll include the `.well-known/` directory, which it would otherwise skip because of the leading dot. -The website talks to the API cross-origin (`https://api.specref.org`), which -is why [CORS is enabled for all origins](./README.md#cors) on the API. +The website is a plain client of the API: it fetches JSON from +`https://api.specref.org` from the browser like any other consumer would. ## DNS for specref.org -The `specref.org` zone points at both hosting providers: the apex domain and -`www` go to GitHub Pages, and `api` goes to Clever Cloud. - -### Records - -| Name | Type | Value | Points to | -| --------------------- | ------- | -------------------------------------------------------------- | ------------ | -| `specref.org` | `A` | `185.199.108.153`
`185.199.109.153`
`185.199.110.153`
`185.199.111.153` | GitHub Pages | -| `specref.org` | `AAAA` | `2606:50c0:8000::153`
`2606:50c0:8001::153`
`2606:50c0:8002::153`
`2606:50c0:8003::153` | GitHub Pages | -| `www.specref.org` | `CNAME` | `specinfra.github.io` | GitHub Pages | -| `api.specref.org` | `CNAME` | the target shown under _Domain names_ in the Clever Cloud console (`domain.par.clever-cloud.com` for applications in the Paris zone) | Clever Cloud | - -Notes: - -* **GitHub Pages.** `www.specref.org` is the canonical hostname (it is the - custom domain configured in the repository settings and in `docs/CNAME`). - Because the apex `specref.org` also resolves to GitHub Pages, GitHub - automatically redirects `https://specref.org/…` to - `https://www.specref.org/…`. The IP addresses above are GitHub's documented - Pages addresses; check them against - [GitHub's documentation](https://docs.github.com/en/pages/configuring-a-custom-domain-for-your-github-pages-site/managing-a-custom-domain-for-your-github-pages-site) - before changing them. -* **Clever Cloud.** `api.specref.org` must also be added to the application's - _Domain names_ in the Clever Cloud console, otherwise Clever Cloud's load - balancers will not route requests for that hostname to the application. - Clever Cloud provisions and renews the TLS certificate for it - automatically once the DNS record resolves. See - [Clever Cloud's custom domain documentation](https://www.clever-cloud.com/developers/doc/administrate/domain-names/) - for the exact CNAME/A record targets of the zone the application runs in. -* Both providers only ever see the hostname they are responsible for, so - neither needs to know about the other. Moving one part (e.g. the API to a - different host) only requires changing that hostname's record. - -### Changing the DNS - -The zone is managed at the domain's registrar. Changes are not tracked in -this repository, so when you change a record, please open an issue or a pull -request updating the table above so it stays accurate. +The `specref.org` domain is registered and its DNS zone hosted at +[Namecheap](https://www.namecheap.com/), on an account owned by Tobie Langel. + +The zone points at both hosting providers: + +* the apex `specref.org` and `www.specref.org` point at **GitHub Pages**. + `www.specref.org` is the canonical hostname (it is the custom domain + configured in the repository settings and in `docs/CNAME`); because the + apex also resolves to GitHub Pages, GitHub automatically redirects + `https://specref.org/…` to `https://www.specref.org/…`. +* `api.specref.org` points at **Clever Cloud**. The hostname must also be + added to the application's _Domain names_ in the Clever Cloud console, + otherwise Clever Cloud's load balancers will not route requests for it to + the application. Clever Cloud provisions and renews the TLS certificate + automatically once the record resolves. + +The exact record values are not listed here because they would drift: use +the ones each provider currently documents +([GitHub Pages](https://docs.github.com/en/pages/configuring-a-custom-domain-for-your-github-pages-site/managing-a-custom-domain-for-your-github-pages-site), +[Clever Cloud](https://www.clever-cloud.com/developers/doc/administrate/domain-names/)). + +Each provider only ever sees the hostname it is responsible for, so moving +one part (e.g. the API to a different host) only requires changing that +hostname's record at Namecheap. From d0bed2112973c190e0f08620df1b8200d4c77477 Mon Sep 17 00:00:00 2001 From: Claude Date: Fri, 11 Sep 2026 15:25:18 +0000 Subject: [PATCH 3/3] DEPLOYMENT.md: drop the note about DNS record values Co-Authored-By: Claude Fable 5.1 Claude-Session: https://claude.ai/code/session_014MHCXm9fYmK4oZ425YG7VZ --- DEPLOYMENT.md | 5 ----- 1 file changed, 5 deletions(-) diff --git a/DEPLOYMENT.md b/DEPLOYMENT.md index a847442c0..2ee4a6887 100644 --- a/DEPLOYMENT.md +++ b/DEPLOYMENT.md @@ -90,11 +90,6 @@ The zone points at both hosting providers: the application. Clever Cloud provisions and renews the TLS certificate automatically once the record resolves. -The exact record values are not listed here because they would drift: use -the ones each provider currently documents -([GitHub Pages](https://docs.github.com/en/pages/configuring-a-custom-domain-for-your-github-pages-site/managing-a-custom-domain-for-your-github-pages-site), -[Clever Cloud](https://www.clever-cloud.com/developers/doc/administrate/domain-names/)). - Each provider only ever sees the hostname it is responsible for, so moving one part (e.g. the API to a different host) only requires changing that hostname's record at Namecheap.