mirror of
https://github.com/Akkudoktor-EOS/EOS.git
synced 2025-11-05 01:06:21 +00:00
feat: improve config backup and update and revert (#737)
Some checks failed
docker-build / platform-excludes (push) Has been cancelled
docker-build / build (push) Has been cancelled
docker-build / merge (push) Has been cancelled
pre-commit / pre-commit (push) Has been cancelled
Run Pytest on Pull Request / test (push) Has been cancelled
Some checks failed
docker-build / platform-excludes (push) Has been cancelled
docker-build / build (push) Has been cancelled
docker-build / merge (push) Has been cancelled
pre-commit / pre-commit (push) Has been cancelled
Run Pytest on Pull Request / test (push) Has been cancelled
Improve the backup of the EOS configuration on configuration migration from another version. Backup files now get a backup id based on date and time. Add the configuration backup listing and the revert to the backup to the EOS api. Add revert to backup to the EOSdash admin tab. Improve documentation about install, update and revert of EOS versions. Add EOS execution profiling to make commands and to test description in the development guideline. Signed-off-by: Bobby Noelte <b0661n0e17e@gmail.com>
This commit is contained in:
Bobby Noelte
GitHub
@@ -363,6 +363,25 @@ Returns:
|
||||
|
||||
---
|
||||
|
||||
## GET /v1/config/backup
|
||||
|
||||
**Links**: [local](http://localhost:8503/docs#/default/fastapi_config_backup_get_v1_config_backup_get), [eos](https://petstore3.swagger.io/?url=https://raw.githubusercontent.com/Akkudoktor-EOS/EOS/refs/heads/main/openapi.json#/default/fastapi_config_backup_get_v1_config_backup_get)
|
||||
|
||||
Fastapi Config Backup Get
|
||||
|
||||
```
|
||||
Get the EOS configuration backup identifiers and backup metadata.
|
||||
|
||||
Returns:
|
||||
dict[str, dict[str, Any]]: Mapping of backup identifiers to metadata.
|
||||
```
|
||||
|
||||
**Responses**:
|
||||
|
||||
- **200**: Successful Response
|
||||
|
||||
---
|
||||
|
||||
## PUT /v1/config/file
|
||||
|
||||
**Links**: [local](http://localhost:8503/docs#/default/fastapi_config_file_put_v1_config_file_put), [eos](https://petstore3.swagger.io/?url=https://raw.githubusercontent.com/Akkudoktor-EOS/EOS/refs/heads/main/openapi.json#/default/fastapi_config_file_put_v1_config_file_put)
|
||||
@@ -401,6 +420,31 @@ Returns:
|
||||
|
||||
---
|
||||
|
||||
## PUT /v1/config/revert
|
||||
|
||||
**Links**: [local](http://localhost:8503/docs#/default/fastapi_config_revert_put_v1_config_revert_put), [eos](https://petstore3.swagger.io/?url=https://raw.githubusercontent.com/Akkudoktor-EOS/EOS/refs/heads/main/openapi.json#/default/fastapi_config_revert_put_v1_config_revert_put)
|
||||
|
||||
Fastapi Config Revert Put
|
||||
|
||||
```
|
||||
Revert the configuration to a EOS configuration backup.
|
||||
|
||||
Returns:
|
||||
configuration (ConfigEOS): The current configuration after revert.
|
||||
```
|
||||
|
||||
**Parameters**:
|
||||
|
||||
- `backup_id` (query, required): EOS configuration backup ID.
|
||||
|
||||
**Responses**:
|
||||
|
||||
- **200**: Successful Response
|
||||
|
||||
- **422**: Validation Error
|
||||
|
||||
---
|
||||
|
||||
## GET /v1/config/{path}
|
||||
|
||||
**Links**: [local](http://localhost:8503/docs#/default/fastapi_config_get_key_v1_config__path__get), [eos](https://petstore3.swagger.io/?url=https://raw.githubusercontent.com/Akkudoktor-EOS/EOS/refs/heads/main/openapi.json#/default/fastapi_config_get_key_v1_config__path__get)
|
||||
|
||||
@@ -99,7 +99,7 @@ html_theme_options = {
|
||||
"logo_only": False,
|
||||
"titles_only": True,
|
||||
}
|
||||
html_css_files = ["eos.css"]
|
||||
html_css_files = ["eos.css"] # Make body size wider
|
||||
|
||||
# -- Options for autodoc -------------------------------------------------
|
||||
# https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html
|
||||
|
||||
@@ -322,10 +322,7 @@ interfere with the EOS server trying to start EOSdash.
|
||||
docker rm -f akkudoktoreos
|
||||
```
|
||||
|
||||
For detailed Docker instructions, refer to
|
||||
**[Method 3 & 4: Installation with Docker](install.md#method-3-installation-with-docker-dockerhub)**
|
||||
and
|
||||
**[Method 4: Docker Compose](install.md#method-4-installation-with-docker-docker-compose)**.
|
||||
For detailed Docker instructions, refer to [Installation Guideline](install-page)
|
||||
|
||||
### Step 4 - Create the changes
|
||||
|
||||
@@ -421,6 +418,30 @@ resources:
|
||||
make test-system
|
||||
```
|
||||
|
||||
To do profiling use:
|
||||
|
||||
```{eval-rst}
|
||||
.. tabs::
|
||||
|
||||
.. tab:: Windows
|
||||
|
||||
.. code-block:: powershell
|
||||
|
||||
python tests/single_test_optimization.py --profile
|
||||
|
||||
.. tab:: Linux
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
python tests/single_test_optimization.py --profile
|
||||
|
||||
.. tab:: Linux Make
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
make test-profile
|
||||
```
|
||||
|
||||
#### Step 4.5 - Commit the changes
|
||||
|
||||
Add the changed and new files to the commit.
|
||||
|
||||
@@ -3,28 +3,42 @@
|
||||
|
||||
# Installation Guide
|
||||
|
||||
This guide provides four different methods to install AkkudoktorEOS. Choose the method that best
|
||||
suits your needs.
|
||||
This guide provides different methods to install AkkudoktorEOS:
|
||||
|
||||
- Installation from Source (GitHub)
|
||||
- Installation from Release Package (GitHub)
|
||||
- Installation with Docker (DockerHub)
|
||||
- Installation with Docker (docker-compose)
|
||||
|
||||
Choose the method that best suits your needs.
|
||||
|
||||
:::{admonition} Tip
|
||||
:class: Note
|
||||
If you need to update instead, see the [Update Guideline](update-page). For reverting to a previous
|
||||
release see the [Revert Guideline](revert-page).
|
||||
:::
|
||||
|
||||
## Installation Prerequisites
|
||||
|
||||
Before installing, ensure you have the following:
|
||||
|
||||
- **For Source/Release Installation:**
|
||||
- Python 3.10 or higher
|
||||
- pip (Python package manager)
|
||||
- Git (for source installation)
|
||||
- Tar/Zip (for release package installation)
|
||||
### For Source / Release Installation
|
||||
|
||||
- **For Docker Installation:**
|
||||
- Docker Engine 20.10 or higher
|
||||
- Docker Compose (optional, but recommended)
|
||||
- Python 3.10 or higher
|
||||
- pip
|
||||
- Git (only for source)
|
||||
- Tar/Zip (for release package)
|
||||
|
||||
## Method 1: Installation from Source (GitHub)
|
||||
### For Docker Installation
|
||||
|
||||
This method is recommended for developers or users who want the latest features.
|
||||
- Docker Engine 20.10 or higher
|
||||
- Docker Compose (optional, recommended)
|
||||
|
||||
### M1-Step 1: Clone the Repository
|
||||
## Installation from Source (GitHub) (M1)
|
||||
|
||||
Recommended for developers or users wanting the latest updates.
|
||||
|
||||
### 1) Clone the Repository (M1)
|
||||
|
||||
```{eval-rst}
|
||||
.. tabs::
|
||||
@@ -44,7 +58,7 @@ This method is recommended for developers or users who want the latest features.
|
||||
cd EOS
|
||||
```
|
||||
|
||||
### M1-Step 2: Create a Virtual Environment and install dependencies
|
||||
### 2) Create a Virtual Environment and install dependencies (M1)
|
||||
|
||||
```{eval-rst}
|
||||
.. tabs::
|
||||
@@ -67,7 +81,7 @@ This method is recommended for developers or users who want the latest features.
|
||||
|
||||
```
|
||||
|
||||
### M1-Step 3: Run EOS
|
||||
### 3) Run EOS (M1)
|
||||
|
||||
```{eval-rst}
|
||||
.. tabs::
|
||||
@@ -86,8 +100,10 @@ This method is recommended for developers or users who want the latest features.
|
||||
|
||||
```
|
||||
|
||||
EOS should now be accessible at [http://localhost:8503/docs](http://localhost:8503/docs) and EOSdash
|
||||
should be available at [http://localhost:8504](http://localhost:8504).
|
||||
EOS is now available at:
|
||||
|
||||
- API: [http://localhost:8503/docs](http://localhost:8503/docs)
|
||||
- EOSdash: [http://localhost:8504](http://localhost:8504)
|
||||
|
||||
If you want to make EOS and EOSdash accessible from outside of your machine or container at this
|
||||
stage of the installation provide appropriate IP addresses on startup.
|
||||
@@ -111,43 +127,20 @@ stage of the installation provide appropriate IP addresses on startup.
|
||||
```
|
||||
<!-- pyml enable line-length -->
|
||||
|
||||
### M1-Step 4: Configure EOS
|
||||
### 4) Configure EOS (M1)
|
||||
|
||||
Use [EOSdash](http://localhost:8504) to configure EOS.
|
||||
Use EOSdash at [http://localhost:8504](http://localhost:8504) to configure EOS.
|
||||
|
||||
### Updating from Source
|
||||
|
||||
To update to the latest version:
|
||||
|
||||
```{eval-rst}
|
||||
.. tabs::
|
||||
|
||||
.. tab:: Windows
|
||||
|
||||
.. code-block:: powershell
|
||||
|
||||
git pull origin main
|
||||
.venv\Scripts\pip install -r requirements.txt --upgrade
|
||||
|
||||
.. tab:: Linux
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
git pull origin main
|
||||
.venv/bin/pip install -r requirements.txt --upgrade
|
||||
|
||||
```
|
||||
|
||||
## Method 2: Installation from Release Package (GitHub)
|
||||
## Installation from Release Package (GitHub) (M2)
|
||||
|
||||
This method is recommended for users who want a stable, tested version.
|
||||
|
||||
### M2-Step 1: Download the Latest Release
|
||||
### 1) Download the Latest Release (M2)
|
||||
|
||||
Visit the [Releases page](https://github.com/Akkudoktor-EOS/EOS/releases) and download the latest
|
||||
Visit the [Releases page](https://github.com/Akkudoktor-EOS/EOS/tags) and download the latest
|
||||
release package (e.g., `akkudoktoreos-v0.1.0.tar.gz` or `akkudoktoreos-v0.1.0.zip`).
|
||||
|
||||
### M2-Step 2: Extract the Package
|
||||
### 2) Extract the Package (M2)
|
||||
|
||||
```bash
|
||||
tar -xzf akkudoktoreos-v0.1.0.tar.gz # For .tar.gz
|
||||
@@ -157,15 +150,22 @@ unzip akkudoktoreos-v0.1.0.zip # For .zip
|
||||
cd akkudoktoreos-v0.1.0
|
||||
```
|
||||
|
||||
### Follow Step 2, 3 and 4 of Method 1: Installation from source
|
||||
### 3) Create a virtual environment and run and configure EOS (M2)
|
||||
|
||||
Installation from release package now needs the exact same steps 2, 3, 4 of method 1.
|
||||
Follow Step 2), 3) and 4) of method M1. Start at
|
||||
`2) Create a Virtual Environment and install dependencies`
|
||||
|
||||
## Method 3: Installation with Docker (DockerHub)
|
||||
### 4) Update the source code (M2)
|
||||
|
||||
To extract a new release to a new directory just proceed with method M2 step 1) for the new release.
|
||||
|
||||
You may remove the old release directory afterwards.
|
||||
|
||||
## Installation with Docker (DockerHub) (M3)
|
||||
|
||||
This method is recommended for easy deployment and containerized environments.
|
||||
|
||||
### M3-Step 1: Pull the Docker Image
|
||||
### 1) Pull the Docker Image (M3)
|
||||
|
||||
```bash
|
||||
docker pull akkudoktor/eos:latest
|
||||
@@ -174,10 +174,10 @@ docker pull akkudoktor/eos:latest
|
||||
For a specific version:
|
||||
|
||||
```bash
|
||||
docker pull akkudoktor/eos:v0.1.0
|
||||
docker pull akkudoktor/eos:v<version>
|
||||
```
|
||||
|
||||
### M3-Step 2: Run the Container
|
||||
### 2) Run the Container (M3)
|
||||
|
||||
**Basic run:**
|
||||
|
||||
@@ -199,7 +199,7 @@ docker run -d \
|
||||
akkudoktor/eos:latest
|
||||
```
|
||||
|
||||
### M3-Step 3: Verify the Container is Running
|
||||
### 3) Verify the Container is Running (M3)
|
||||
|
||||
```bash
|
||||
docker ps
|
||||
@@ -209,11 +209,50 @@ docker logs akkudoktoreos
|
||||
EOS should now be accessible at [http://localhost:8503/docs](http://localhost:8503/docs) and EOSdash
|
||||
should be available at [http://localhost:8504](http://localhost:8504).
|
||||
|
||||
### M3-Step 4: Configure EOS
|
||||
### 4) Configure EOS (M3)
|
||||
|
||||
Use [EOSdash](http://localhost:8504) to configure EOS.
|
||||
Use EOSdash at [http://localhost:8504](http://localhost:8504) to configure EOS.
|
||||
|
||||
### Docker Management Commands
|
||||
## Installation with Docker (docker-compose) (M4)
|
||||
|
||||
### 1) Get the akkudoktoreos source code (M4)
|
||||
|
||||
You may use either method M1 or method M2 to get the source code.
|
||||
|
||||
### 2) Build and run the container (M4)
|
||||
|
||||
```{eval-rst}
|
||||
.. tabs::
|
||||
|
||||
.. tab:: Windows
|
||||
|
||||
.. code-block:: powershell
|
||||
|
||||
docker compose up --build
|
||||
|
||||
.. tab:: Linux
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
docker compose up --build
|
||||
|
||||
```
|
||||
|
||||
### 3) Verify the Container is Running (M4)
|
||||
|
||||
```bash
|
||||
docker ps
|
||||
docker logs akkudoktoreos
|
||||
```
|
||||
|
||||
EOS should now be accessible at [http://localhost:8503/docs](http://localhost:8503/docs) and EOSdash
|
||||
should be available at [http://localhost:8504](http://localhost:8504).
|
||||
|
||||
### 4) Configure EOS
|
||||
|
||||
Use EOSdash at [http://localhost:8504](http://localhost:8504) to configure EOS.
|
||||
|
||||
## Helpful Docker Commands
|
||||
|
||||
**View logs:**
|
||||
|
||||
@@ -247,42 +286,3 @@ docker stop akkudoktoreos
|
||||
docker rm akkudoktoreos
|
||||
# Then run the container again with the run command
|
||||
```
|
||||
|
||||
## Method 4: Installation with Docker (docker-compose)
|
||||
|
||||
### M4-Step 1: Get the akkudoktoreos source code
|
||||
|
||||
You may use either method 1 or method 2 to get the source code.
|
||||
|
||||
### M4-Step 2: Build and run the container
|
||||
|
||||
```{eval-rst}
|
||||
.. tabs::
|
||||
|
||||
.. tab:: Windows
|
||||
|
||||
.. code-block:: powershell
|
||||
|
||||
docker compose up --build
|
||||
|
||||
.. tab:: Linux
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
docker compose up --build
|
||||
|
||||
```
|
||||
|
||||
### M4-Step 3: Verify the Container is Running
|
||||
|
||||
```bash
|
||||
docker ps
|
||||
docker logs akkudoktoreos
|
||||
```
|
||||
|
||||
EOS should now be accessible at [http://localhost:8503/docs](http://localhost:8503/docs) and EOSdash
|
||||
should be available at [http://localhost:8504](http://localhost:8504).
|
||||
|
||||
### M4-Step 4: Configure EOS
|
||||
|
||||
Use [EOSdash](http://localhost:8504) to configure EOS.
|
||||
|
||||
155
docs/develop/revert.md
Normal file
155
docs/develop/revert.md
Normal file
@@ -0,0 +1,155 @@
|
||||
% SPDX-License-Identifier: Apache-2.0
|
||||
(revert-page)=
|
||||
|
||||
# Revert Guide
|
||||
|
||||
This guide explains how to **revert AkkudoktorEOS to a previous version**.
|
||||
The exact methods and steps differ depending on how EOS was installed:
|
||||
|
||||
- M1/M2: Reverting when Installed from Source or Release Package
|
||||
- M3/M4: Reverting when Installed via Docker
|
||||
|
||||
:::{admonition} Important
|
||||
:class: warning
|
||||
Before reverting, ensure you have a backup of your `EOS.config.json`.
|
||||
EOS also maintains internal configuration backups that can be restored after a downgrade.
|
||||
:::
|
||||
|
||||
:::{admonition} Tip
|
||||
:class: Note
|
||||
If you need to update instead, see the [Update Guideline](update-page).
|
||||
:::
|
||||
|
||||
## Revert to a Previous Version of EOS
|
||||
|
||||
You can revert to a previous version using the same installation method you originally selected.
|
||||
See: [Installation Guideline](install-page)
|
||||
|
||||
## Reverting when Installed from Source or Release Package (M1/M2)
|
||||
|
||||
### 1) Locate the target version (M2)
|
||||
|
||||
Go to the GitHub Releases page:
|
||||
|
||||
> <https://github.com/Akkudoktor-EOS/EOS/tags>
|
||||
|
||||
### 2) Download or check out that version (M1/M2)
|
||||
|
||||
#### Git (source) (M1)
|
||||
|
||||
```bash
|
||||
git fetch
|
||||
git checkout v<version>
|
||||
````
|
||||
|
||||
Example:
|
||||
|
||||
```bash
|
||||
git checkout v0.1.0
|
||||
```
|
||||
|
||||
Then reinstall dependencies:
|
||||
|
||||
```bash
|
||||
.venv/bin/pip install -r requirements.txt --upgrade
|
||||
```
|
||||
|
||||
#### Release package (M2)
|
||||
|
||||
Download and extract the desired ZIP or TAR release.
|
||||
Refer to **Method 2** in the [Installation Guideline](install-page).
|
||||
|
||||
### 3) Restart EOS (M1/M2)
|
||||
|
||||
```bash
|
||||
.venv/bin/python -m akkudoktoreos.server.eos
|
||||
```
|
||||
|
||||
### 4) Restore configuration (optional) (M1/M2)
|
||||
|
||||
If your configuration changed since the downgrade, you may restore a previous backup:
|
||||
|
||||
- via **EOSdash**
|
||||
|
||||
Admin → configuration → Revert to backup
|
||||
|
||||
or
|
||||
|
||||
Admin → configuration → Import from file
|
||||
|
||||
- via **REST**
|
||||
|
||||
```bash
|
||||
curl -X PUT "http://<host>:8503/v1/config/revert?backup_id=<backup>"
|
||||
```
|
||||
|
||||
## Reverting when Installed via Docker (M3/M4)
|
||||
|
||||
### 1) Pull the desired image version (M3/M4)
|
||||
|
||||
```bash
|
||||
docker pull akkudoktor/eos:v<version>
|
||||
```
|
||||
|
||||
Example:
|
||||
|
||||
```bash
|
||||
docker pull akkudoktor/eos:v0.1.0
|
||||
```
|
||||
|
||||
### 2) Stop and remove the current container (M3/M4)
|
||||
|
||||
```bash
|
||||
docker stop akkudoktoreos
|
||||
docker rm akkudoktoreos
|
||||
```
|
||||
|
||||
### 3) Start a container with the selected version (M3/M4)
|
||||
|
||||
Start EOS as usual, using your existing `docker run` or `docker compose` setup
|
||||
(see Method 3 or Method 4 in the [Installation Guideline](install-page)).
|
||||
|
||||
### 4) Restore configuration (optional) (M3/M4)
|
||||
|
||||
In many cases configuration will migrate automatically.
|
||||
If needed, you may restore a configuration backup:
|
||||
|
||||
- via **EOSdash**
|
||||
|
||||
Admin → configuration → Revert to backup
|
||||
|
||||
or
|
||||
|
||||
Admin → configuration → Import from file
|
||||
|
||||
- via **REST**
|
||||
|
||||
```bash
|
||||
curl -X PUT "http://<host>:8503/v1/config/revert?backup_id=<backup>"
|
||||
```
|
||||
|
||||
## About Configuration Backups
|
||||
|
||||
EOS keeps configuration backup files next to your active `EOS.config.json`.
|
||||
|
||||
You can list and restore backups:
|
||||
|
||||
- via **EOSdash UI**
|
||||
- via **REST API**
|
||||
|
||||
### List available backups
|
||||
|
||||
```bash
|
||||
GET /v1/config/backups
|
||||
```
|
||||
|
||||
### Restore backup
|
||||
|
||||
```bash
|
||||
PUT /v1/config/revert?backup_id=<id>
|
||||
```
|
||||
|
||||
:::{admonition} Important
|
||||
:class: warning
|
||||
If no backup file is available, create or copy a previously saved `EOS.config.json` before reverting.
|
||||
:::
|
||||
@@ -27,6 +27,9 @@ develop/getting_started.md
|
||||
:caption: How-To Guides
|
||||
|
||||
develop/CONTRIBUTING.md
|
||||
develop/install.md
|
||||
develop/update.md
|
||||
develop/revert.md
|
||||
|
||||
```
|
||||
|
||||
@@ -53,8 +56,6 @@ akkudoktoreos/api.rst
|
||||
:maxdepth: 2
|
||||
:caption: Development
|
||||
|
||||
develop/CONTRIBUTING.md
|
||||
develop/install.md
|
||||
develop/develop.md
|
||||
develop/release.md
|
||||
develop/CHANGELOG.md
|
||||
|
||||
Reference in New Issue
Block a user