Fix deployment on Debian 13

CHANGELOG.md

@@ -2,6 +2,18 @@
 
 All changes that impact users of this module are documented in this file, in the [Common Changelog](https://common-changelog.org) format with some additional specifications defined in the CONTRIBUTING file. This codebase adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## Unreleased [patch]
+
+> Development of this release was supported by [Reset Tech](https://www.reset.tech).
+
+### Fixed
+
+- Replace NodeSource repository with native Node.js packages on Debian >= 13 to fix deployment failure caused by NodeSource GPG key using SHA-1, [rejected by apt since 2026-02-01](https://github.com/nodesource/distributions/issues/1908)
+
+### Added
+
+- Add `migrate` playbook for one-time changes on existing servers; run `ansible-playbook opentermsarchive.deployment.migrate` before `deploy` when upgrading
+
 ## 3.0.0 - 2025-12-19
 
 _Full changeset and discussions: [#58](https://github.com/OpenTermsArchive/deployment/pull/58)._

README.md

@@ -137,6 +137,14 @@ ansible-playbook playbook.yml --vault-password-file vault.key
 
 Please note that encrypted files will be decrypted and stored in plaintext on the deployment server. Always protect access to your production server.
 
+## Migrations
+
+Some updates require changes on existing servers before deploying. Run the `migrate` playbook before `deploy` when needed:
+
+```sh
+ansible-playbook opentermsarchive.deployment.migrate
+```
+
 ## Playbook execution refinement
 
 Use [tags](https://docs.ansible.com/ansible/latest/user_guide/playbooks_tags.html) to refine playbook execution. Example commands:

playbooks/migrate.yml

@@ -0,0 +1,52 @@
+---
+- name: Run migrations
+  hosts: all
+  tasks:
+    # Stop PM2 processes running in the default home (~/.pm2)
+    # since v3 uses a per-collection home (~/.pm2-{collection_id})
+    - name: Stop PM2 processes in default home
+      ansible.builtin.shell: pm2 kill 2>/dev/null || true
+      environment:
+        PM2_HOME: /home/{{ ansible_user }}/.pm2
+
+    - name: Remove PM2 startup script
+      ansible.builtin.shell: pm2 unstartup systemd 2>/dev/null || true
+      become: true
+
+    - name: Remove default PM2 home
+      ansible.builtin.file:
+        path: /home/{{ ansible_user }}/.pm2
+        state: absent
+
+    # Remove old nginx config (v2 used a single ota.conf,
+    # v3 uses ota-global.conf and per-app ota-rate-limit-{app_id}.conf)
+    - name: Remove old nginx config
+      ansible.builtin.file:
+        path: "{{ item }}"
+        state: absent
+      become: true
+      loop:
+        - /etc/nginx/conf.d/ota.conf
+        - /etc/nginx/sites-enabled/ota
+        - /etc/nginx/sites-available/ota
+
+    # See https://github.com/nodesource/distributions/issues/1908
+    - name: Remove NodeSource repository on Debian >= 13
+      when: ansible_distribution == 'Debian' and ansible_distribution_major_version | int >= 13
+      become: true
+      block:
+        - name: Remove NodeSource APT repository
+          ansible.builtin.file:
+            path: /etc/apt/sources.list.d/nodesource.list
+            state: absent
+
+        - name: Remove NodeSource GPG key
+          ansible.builtin.file:
+            path: /etc/apt/keyrings/nodesource.gpg
+            state: absent
+
+        - name: Remove NodeSource Node.js package
+          ansible.builtin.apt:
+            name: nodejs
+            state: absent
+            purge: true

roles/node/tasks/main.yml

@@ -1,25 +1,46 @@
 ---
-- name: Create keyrings directory
-  ansible.builtin.file:
-    path: /etc/apt/keyrings
-    state: directory
-    mode: "0755"
+# On Debian >= 13, use native Node.js packages since the NodeSource GPG key
+# uses SHA-1, rejected by apt. See https://github.com/nodesource/distributions/issues/1908
+# On older versions, use NodeSource to provide Node.js >= 20 as required by the engine.
 
-- name: Download and import the Nodesource GPG key
-  ansible.builtin.shell: set -o pipefail && curl -fsSL https://deb.nodesource.com/gpgkey/nodesource-repo.gpg.key | gpg --yes --dearmor -o /etc/apt/keyrings/nodesource.gpg
-  args:
-    executable: /bin/bash
+- name: Install Node.js and NPM on Debian >= 13
+  when: ansible_distribution == 'Debian' and ansible_distribution_major_version | int >= 13
+  block:
+    - name: Install Node.js and NPM
+      ansible.builtin.apt:
+        name:
+          - nodejs
+          - npm
+        state: present
+        update_cache: true
 
-- name: Create deb repository
-  ansible.builtin.shell: set -o pipefail && echo "deb [signed-by=/etc/apt/keyrings/nodesource.gpg] https://deb.nodesource.com/node_20.x nodistro main" | tee /etc/apt/sources.list.d/nodesource.list # Remember to update the major version of NPM when updating the major version of Node
-  args:
-    executable: /bin/bash
+    - name: Install NPM to latest version 10
+      ansible.builtin.command: npm install -g npm@10
 
-- name: Install NodeJS and NPM
-  ansible.builtin.apt:
-    name: nodejs
-    update_cache: true
-    state: latest # The major version of NodeJS is provided by the NodeSource repository defined in the task above
+- name: Install Node.js and NPM on Debian < 13
+  when: ansible_distribution != 'Debian' or ansible_distribution_major_version | int < 13
+  block:
+    - name: Create keyrings directory
+      ansible.builtin.file:
+        path: /etc/apt/keyrings
+        state: directory
+        mode: "755"
 
-- name: Update NPM to latest version 10
-  ansible.builtin.command: npm install -g npm@10
+    - name: Download and import the NodeSource GPG key
+      ansible.builtin.shell: set -o pipefail && curl -fsSL https://deb.nodesource.com/gpgkey/nodesource-repo.gpg.key | gpg --yes --dearmor -o /etc/apt/keyrings/nodesource.gpg
+      args:
+        executable: /bin/bash
+
+    - name: Add NodeSource APT repository
+      ansible.builtin.shell: set -o pipefail && echo "deb [signed-by=/etc/apt/keyrings/nodesource.gpg] https://deb.nodesource.com/node_20.x nodistro main" | tee /etc/apt/sources.list.d/nodesource.list # Remember to update the major version of NPM when updating the major version of Node
+      args:
+        executable: /bin/bash
+
+    - name: Install Node.js
+      ansible.builtin.apt:
+        name: nodejs
+        update_cache: true
+        state: latest # The major version of NodeJS is provided by the NodeSource repository defined in the task above
+
+    - name: Install NPM 10
+      ansible.builtin.command: npm install -g npm@10