add upgrade page

Author: a-gave

docs/.vitepress/config.mts

@@ -49,6 +49,7 @@ export default defineConfig({
     search: {
       provider: 'local'
     },
+    outline: 'deep',
 
     nav: nav(),
 
@@ -75,10 +76,11 @@ function nav(): DefaultTheme.NavItem[] {
   return [
     { text: 'Guide', link: '/guide/packages-selection' },
     { text: 'Reference', link: '/reference/configuration' },  
-    { text: 'v2024.1',
+    { text: 'News',
       items: [
-        { text: 'v2020.4', link: '/news/2023-10-07' },
-        { text: 'News', link: '/news' },
+        { text: 'v2024.1', link: '/news/2023-10-07' },
+        { text: 'v2020.4', link: '/news/2025-05-04' },
+        { text: 'Latest News', link: '/news' },
         { text: 'Changelog', link: 'changelog'},
         { text: 'Issues', link: 'https://github.com/libremesh/lime-packages/issues'},
       ]
@@ -117,7 +119,8 @@ function sidebarGuide(): DefaultTheme.SidebarItem[] {
             { text: 'ImageBuilder', link: '/build/imagebuilder' },
             { text: 'lime-sdk', link: '/build/lime-sdk' },
             { text: 'Buildroot', link: '/build/buildroot'}
-        ]}
+        ]},
+        { text: 'Upgrade', link: '/guide/upgrade' },
       ]
     },
     { text: 'Configuration & Reference', link: '/reference/configuration'},
@@ -131,7 +134,7 @@ function sidebarGuide(): DefaultTheme.SidebarItem[] {
           link: '/development/hacking', 
           collapsed: true,
           items: [
-          { text: 'Kernel Vermagic', link: '/development/kernel_vermagic' }
+          { text: 'Kernel Vermagic', link: '/development/hacking/kernel_vermagic' }
         ] },
         { text: 'Contributing to lime-packages', link: '/development/contributing' },
       ]
@@ -143,7 +146,6 @@ function sidebarGuide(): DefaultTheme.SidebarItem[] {
         { text: 'Communication', link: '/communication' },
         { text: 'Contributors', link: '/contributors' },
         { text: 'Meetings', link: '/meetings' },
-        { text: 'News', link: '/news' },
       ]
     },
     {

docs/build/buildroot.md

@@ -28,13 +28,13 @@ Run all the above commands as normal user (do not use root).
 
 ::: code-group
 
-``` sh-vue [{{ openwrt.oldstable_version }}]
-git clone -b v{{ openwrt.oldstable_version }} --single-branch https://github.com/openwrt/openwrt
+``` sh-vue [{{ openwrt.stable_version }}]
+git clone -b v{{ openwrt.stable_version }} --single-branch https://github.com/openwrt/openwrt
 cd openwrt
 ```
 
-``` sh-vue [{{ openwrt.stable_version }}]
-git clone -b v{{ openwrt.stable_version }} --single-branch https://github.com/openwrt/openwrt
+``` sh-vue [{{ openwrt.oldstable_version }}]
+git clone -b v{{ openwrt.oldstable_version }} --single-branch https://github.com/openwrt/openwrt
 cd openwrt
 ```
 
@@ -43,24 +43,24 @@ cd openwrt
 Copy the defalt OpenWrt repositories file, and add the LibreMesh repositories
 
 ::: tip
-Use `2024.1` to build the latest LibreMesh release (compatible with OpenWrt 23.05.X)    
-Use `master` to build the latest LibreMesh code (compatible with OpenWrt 24.10.X or newer)
+Use `master` to build the latest LibreMesh code (compatible with openwrt-24.10 or newer)     
+Use `2024.1` to build the latest LibreMesh release (compatible with openwrt-24.10 and openwrt-23.05)    
 :::
 
 ::: code-group
 
-``` sh [2024.1]
+``` sh [master]
 cp feeds.conf.default feeds.conf
 cat << EOF >> feeds.conf
-src-git libremesh https://github.com/libremesh/lime-packages.git;v2024.1
+src-git libremesh https://github.com/libremesh/lime-packages.git;master
 src-git profiles https://github.com/libremesh/network-profiles.git
 EOF
 ```
 
-``` sh [master]
+``` sh [2024.1]
 cp feeds.conf.default feeds.conf
 cat << EOF >> feeds.conf
-src-git libremesh https://github.com/libremesh/lime-packages.git;master
+src-git libremesh https://github.com/libremesh/lime-packages.git;v2024.1
 src-git profiles https://github.com/libremesh/network-profiles.git
 EOF
 ```

docs/build/imagebuilder.md

@@ -60,10 +60,9 @@ Refers to the OpenWrt wiki [Using the Image Builder](https://openwrt.org/docs/gu
 
 ::: code-group
 
-
-```sh-vue [{{ openwrt.oldstable_version }}]
+```sh-vue [{{ openwrt.stable_version }} (stable)]
 FILE_HOST="{{build.file_host}}"
-DOWNLOAD_PATH="{{download_path(openwrt.oldstable_version)}}"
+DOWNLOAD_PATH="{{download_path(openwrt.stable_version)}}"
 DOWNLOAD_FILE="{{build.download_file}}"
 
 mkdir imagebuilder; cd imagebuilder
@@ -73,9 +72,9 @@ wget -nv "$FILE_HOST/$DOWNLOAD_PATH/$file_name"
 tar xf "$file_name" --strip=1 --no-same-owner -C .
 ```
 
-```sh-vue [{{ openwrt.stable_version }}]
+```sh-vue [{{ openwrt.oldstable_version }} (oldstable)]
 FILE_HOST="{{build.file_host}}"
-DOWNLOAD_PATH="{{download_path(openwrt.stable_version)}}"
+DOWNLOAD_PATH="{{download_path(openwrt.oldstable_version)}}"
 DOWNLOAD_FILE="{{build.download_file}}"
 
 mkdir imagebuilder; cd imagebuilder
@@ -106,25 +105,24 @@ Start an ImageBuilder of your choice, for example {{ build.target }} if your dev
 
 ::: code-group
 
-```sh-vue [{{ openwrt.oldstable_version }}]
+```sh-vue [{{ openwrt.stable_version }} (stable)]
 mkdir ./images/
 docker run -it \
     -e TARGET=$TARGET \
     -e ARCH=$ARCH \
     -v $(pwd)/config/:/builder/files/etc/config/ \
     -v $(pwd)/images:/images/ \
-    ghcr.io/openwrt/imagebuilder:$TARGET-v{{ openwrt.oldstable_version }}
+    ghcr.io/openwrt/imagebuilder:$TARGET-v{{ openwrt.stable_version }}
 ```
 
-
-```sh-vue [{{ openwrt.stable_version }}]
+```sh-vue [{{ openwrt.oldstable_version }} (oldstable)]
 mkdir ./images/
 docker run -it \
     -e TARGET=$TARGET \
     -e ARCH=$ARCH \
     -v $(pwd)/config/:/builder/files/etc/config/ \
     -v $(pwd)/images:/images/ \
-    ghcr.io/openwrt/imagebuilder:$TARGET-v{{ openwrt.stable_version }}
+    ghcr.io/openwrt/imagebuilder:$TARGET-v{{ openwrt.oldstable_version }}
 ```
 
 ```sh-vue [SNAPSHOT]
@@ -144,24 +142,27 @@ docker run -it \
 Within the container add the `lime-packages` feeds.
 ::: code-group
 
-```sh-vue [opkg - openwrt-23.05]
-cat << EOF >> repositories.conf
-src/gz libremesh_packages https://feed.libremesh.org/master/openwrt-23.05/x86_64
-src/gz libremesh_arch_packages https://feed.libremesh.org/master/openwrt-23.05/$ARCH
-src/gz profiles https://feed.libremesh.org/profiles/openwrt-23.05/x86_64
+
+```sh-vue [openwrt-{{ openwrt.stable_branch }} (stable)]
+cat << EOF >> repositories
+https://feed.libremesh.org/master/openwrt-{{ openwrt.stable_branch }}/x86_64/packages.adb
+https://feed.libremesh.org/master/openwrt-{{ openwrt.stable_branch }}/$ARCH/packages.adb
+https://feed.libremesh.org/profiles/openwrt-{{ openwrt.stable_branch }}/x86_64/packages.adb
 EOF
 
-cat << EOF > keys/a71b3c8285abd28b
-untrusted comment: signed by libremesh.org key a71b3c8285abd28b
-RWSnGzyChavSiyQ+vLk3x7F0NqcLa4kKyXCdriThMhO78ldHgxGljM/8
+cat << EOF > keys/libremesh.pem
+-----BEGIN PUBLIC KEY-----
+MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEdFJZ2qVti49Ol8LJZYuxgOCLowBS
+8bI86a7zqhSbs5yon3JON7Yee7CQOgqwPOX5eMALGOu8iFGAqIRx5YjfYA==
+-----END PUBLIC KEY-----
 EOF
 ```
 
-```sh-vue [opkg - openwrt-24.10]
+```sh-vue [openwrt-{{ openwrt.oldstable_branch }} (oldstable)]
 cat << EOF >> repositories.conf
-src/gz libremesh_packages https://feed.libremesh.org/master/openwrt-24.10/x86_64
-src/gz libremesh_arch_packages https://feed.libremesh.org/master/openwrt-24.10/$ARCH
-src/gz profiles https://feed.libremesh.org/profiles/openwrt-24.10/x86_64
+src/gz libremesh_packages https://feed.libremesh.org/master/openwrt-{{ openwrt.oldstable_branch }}/x86_64
+src/gz libremesh_arch_packages https://feed.libremesh.org/master/openwrt-{{ openwrt.oldstable_branch }}/$ARCH
+src/gz profiles https://feed.libremesh.org/profiles/openwrt-{{ openwrt.oldstable_branch }}/x86_64
 EOF
 
 cat << EOF > keys/a71b3c8285abd28b

docs/development/contributing.md

@@ -1,6 +1,3 @@
----
-outline: deep
----
 # Contributing
 
 When contributing to this repository, please first discuss the change you wish to make via issue,
@@ -101,7 +98,7 @@ The general workflow for branching is as follows:
 
     ```git checkout -b <branch name>```
 
-4. Run the tests: read [[Testing docs](TESTING.md)].
+4. Run the tests: read [[Testing docs](testing)].
 
 5. Make your changes, we encourage you to try to add a test.
 

docs/development/testing.md

@@ -1,6 +1,3 @@
----
-outline: deep
----
 # Testing guide
 
 LibreMesh has unit tests that help us add new features while keeping maintenance effort contained.

docs/getting-started.md

@@ -74,20 +74,4 @@ Install newer OpenWrt stable releases to keep updated the device:
 - Subscribe to the Newsletter [`OpenWrt Annouce`](https://lists.openwrt.org/mailman/listinfo/openwrt-announce).
 - Or follow the [`Openwrt Announcement-Bot`](https://social.tchncs.de/@openwrt) on Mastodon.
 
-Refers to the OpenWrt Wiki for details about the upgrade process:
-- [Upgrading OpenWrt firmware using LuCI and CLI](https://openwrt.org/docs/guide-user/installation/generic.sysupgrade)
-- [Preserving OpenWrt settings during firmware upgrade](https://openwrt.org/docs/guide-quick-start/admingui_sysupgrade_keepsettings)
-
-### Recommendations
-::: warning BEWARE
-From times to times it could be that some OpenWrt devices encounter issues upgrading, and result `bricked` or `soft-bricked`
-Be sure to have **read the OpenWrt release notes** for the `version`/`branch` you are installing.   
-
-In **production environments with multiple LibreMesh nodes** deployed, it is adviceable to keep at least one device, for each models you are using, to test that upgrades are ok. Or eventually recover it using an `USB Serial Adapter`.
-:::
-
-### Tools
-Tools to upgrade the base OpenWrt version and LibreMesh packages:
-- `eupgrade` - provide semi-automated upgrades checking if a new firmware is available from an https server.
-- `owut` - provides upgrades using an [`ASU`](https://github.com/openwrt/asu) (online imagebuilder) instance. Test it installing the package `profile-antennine.org-an-lime-owut`
-- `safe-upgrade` - Wrapper around `sysupgrade`. Requires large flash storage, at least the double of the firmware-size, to rollback in case something didn't work.
+Refers to the page [Upgrade](/guide/upgrade) for recommended operations with LibreMesh.

docs/guide/upgrade.md

@@ -0,0 +1,50 @@
+# Upgrade
+
+::: tip CAUTION
+From times to times it could be that some OpenWrt devices encounter issues upgrading, and result `bricked` or `soft-bricked`
+Be sure to have **read the OpenWrt release notes** for the `version`/`branch` you are installing.   
+
+In **production environments with multiple LibreMesh nodes** deployed, it is adviceable to keep at least one device, for each models you are using, to test that upgrades are ok. Or eventually recover it using an `USB Serial Adapter`.
+:::
+
+Refers to the OpenWrt Wiki for details about the upgrade process:
+- [Upgrading OpenWrt firmware using LuCI and CLI](https://openwrt.org/docs/guide-user/installation/generic.sysupgrade)
+- [Preserving OpenWrt settings during firmware upgrade](https://openwrt.org/docs/guide-quick-start/admingui_sysupgrade_keepsettings)
+
+
+## Examples
+
+### Upgrade to a new major OpenWrt release
+Example that keeps only `lime-node` and `dropbear`.
+
+Override the list of files to be preserved keeping only the essential.
+Recommended if the whole configuration is in the `lime-node`.
+```
+mkdir /tmp/keep.d; mv /lib/upgrade/keep.d/* /tmp/keep.d/
+mv /usr/lib/opkg/status /tmp/opkg_status
+for i in /etc/config/dropbear /etc/dropbear /etc/config/lime-node; do echo $i >> /etc/sysupgrade.conf; done
+sysupgrade -l
+```
+
+Download the sysupgrade file
+```
+wget -O /tmp/firmware.bin <sysupgrade_file>
+```
+syupgrade file url is for instance https://sysupgrade-01.antennine.org/store/45347ae7f75029abc37f0a4e41ebf9af72ef7b9ce8c93ff27a7d7ec5e9a54b2e/openwrt-25.12.0-82ccd0311e22-mediatek-filogic-cudy_wr3000s-v1-squashfs-sysupgrade.bin
+
+Upgrade the router
+```
+sysupgrade -v /tmp/firmware.bin
+```
+
+## Tools
+Tools to upgrade the base OpenWrt version and LibreMesh packages:
+
+### eupgrade
+provide semi-automated upgrades checking if a new firmware is available from an https server.
+
+### owut
+provides upgrades using an [`ASU`](https://github.com/openwrt/asu) (online imagebuilder) instance. Test it installing the package `profile-antennine.org-an-lime-owut`
+
+### safe-upgrade
+Wrapper around `sysupgrade`. Requires large flash storage, at least the double of the firmware-size, to rollback in case something didn't work.

docs/openwrt.data.js

@@ -1,15 +1,14 @@
-let json = {
-  "stable_version": "24.10.5",
-  "oldstable_version": "23.05.6",
-  "upcoming_version": "25.12.0-rc5",
-  "versions_list": ["25.12.0-rc5","25.12.0-rc4","25.12.0-rc3","25.12.0-rc2","25.12.0-rc1","24.10.5","24.10.4","24.10.3","24.10.2","24.10.1","24.10.0-rc7","24.10.0-rc6","24.10.0-rc5","24.10.0-rc4","24.10.0-rc3","24.10.0-rc2","24.10.0-rc1","24.10.0","23.05.6","23.05.5","23.05.4","23.05.3","23.05.2","23.05.1","23.05.0-rc4","23.05.0-rc3","23.05.0-rc2","23.05.0-rc1","23.05.0","22.03.7","22.03.6","22.03.5","22.03.4","22.03.3","22.03.2","22.03.1","22.03.0-rc6","22.03.0-rc5","22.03.0-rc4","22.03.0-rc1","22.03.0","21.02.7","21.02.6","21.02.5","21.02.4","21.02.3","21.02.2","21.02.1","21.02.0-rc4","21.02.0-rc3","21.02.0-rc2","21.02.0","19.07.10","19.07.9","19.07.8","19.07.7","19.07.6","19.07.5","19.07.4","19.07.3","19.07.2","19.07.1","19.07.0","18.06.9","18.06.8","18.06.7","18.06.6","18.06.5","18.06.4","18.06.3","18.06.2","18.06.1","18.06.0","17.01.7","17.01.6","17.01.5","17.01.4","17.01.3","17.01.2","17.01.1"]
-  }
+// let json = {
+//   "stable_version": "24.10.5",
+//   "oldstable_version": "23.05.6",
+//   "upcoming_version": "25.12.0-rc5",
+//   "versions_list": ["25.12.0-rc5","25.12.0-rc4","25.12.0-rc3","25.12.0-rc2","25.12.0-rc1","24.10.5","24.10.4","24.10.3","24.10.2","24.10.1","24.10.0-rc7","24.10.0-rc6","24.10.0-rc5","24.10.0-rc4","24.10.0-rc3","24.10.0-rc2","24.10.0-rc1","24.10.0","23.05.6","23.05.5","23.05.4","23.05.3","23.05.2","23.05.1","23.05.0-rc4","23.05.0-rc3","23.05.0-rc2","23.05.0-rc1","23.05.0","22.03.7","22.03.6","22.03.5","22.03.4","22.03.3","22.03.2","22.03.1","22.03.0-rc6","22.03.0-rc5","22.03.0-rc4","22.03.0-rc1","22.03.0","21.02.7","21.02.6","21.02.5","21.02.4","21.02.3","21.02.2","21.02.1","21.02.0-rc4","21.02.0-rc3","21.02.0-rc2","21.02.0","19.07.10","19.07.9","19.07.8","19.07.7","19.07.6","19.07.5","19.07.4","19.07.3","19.07.2","19.07.1","19.07.0","18.06.9","18.06.8","18.06.7","18.06.6","18.06.5","18.06.4","18.06.3","18.06.2","18.06.1","18.06.0","17.01.7","17.01.6","17.01.5","17.01.4","17.01.3","17.01.2","17.01.1"]
+//   }
 
 
 export default {
   async load() {
     // fetch remote data
-    return json
-    // return (await fetch('https://downloads.openwrt.org/.versions.json')).json()
+    return (await fetch('https://downloads.openwrt.org/.versions.json')).json()
   }
 }

prepare_data.js

@@ -293,9 +293,7 @@ async function addRepoDoc() {
   await copyFiles(from_dir, to_dir, 'CONTRIBUTING.md', 'contributing.md')
   await copyFiles(from_dir, './docs/', 'CHANGELOG.md', 'changelog.md')
 
-  let testing = await replaceInFile(to_dir+'testing.md', "# Testing", "---\noutline: deep\n---\n# Testing")
-  let contributing = await replaceInFile(to_dir+'contributing.md', "# Contributing", "---\noutline: deep\n---\n# Contributing")
-  contributing = await replaceInFile(to_dir+'contributing.md', /]\(TESTING.md\)/, "](testing)")
+  await replaceInFile(to_dir+'contributing.md', /]\(TESTING.md\)/, "](testing)")
 }
 
 // copy VIRTUALIZING.md TESTING.md HACKING.Md