chore: improve error msg on home assistant add-on port config

When running as a Home Assistant add-on the ports shall not be changed
as this would break config.yaml that is used by Home Assistant. Prevent
the change and return an error message.

Also fix date file setup.

Signed-off-by: Bobby Noelte <b0661n0e17e@gmail.com>

Author: b0661

.env

@@ -11,7 +11,7 @@ DOCKER_COMPOSE_DATA_DIR=${HOME}/.local/share/net.akkudoktor.eos
 # -----------------------------------------------------------------------------
 # Image / build
 # -----------------------------------------------------------------------------
-VERSION=0.3.0.dev2603180781250771
+VERSION=0.3.0.dev2603271452975993
 PYTHON_VERSION=3.13.9
 
 # -----------------------------------------------------------------------------

config.yaml

@@ -6,7 +6,7 @@
 # the root directory (no add-on folder as usual).
 
 name: "Akkudoktor-EOS"
-version: "0.3.0.dev2603180781250771"
+version: "0.3.0.dev2603271452975993"
 slug: "eos"
 description: "Akkudoktor-EOS add-on"
 url: "https://github.com/Akkudoktor-EOS/EOS"

docs/_generated/configserver.md

@@ -7,11 +7,11 @@
 
 | Name | Environment Variable | Type | Read-Only | Default | Description |
 | ---- | -------------------- | ---- | --------- | ------- | ----------- |
-| eosdash_host | `EOS_SERVER__EOSDASH_HOST` | `Optional[str]` | `rw` | `None` | EOSdash server IP address. Defaults to EOS server IP address. |
-| eosdash_port | `EOS_SERVER__EOSDASH_PORT` | `Optional[int]` | `rw` | `None` | EOSdash server IP port number. Defaults to EOS server IP port number + 1. |
+| eosdash_host | `EOS_SERVER__EOSDASH_HOST` | `str` | `rw` | `127.0.0.1` | EOSdash server IP address. Defaults to EOS server IP address. |
+| eosdash_port | `EOS_SERVER__EOSDASH_PORT` | `int` | `rw` | `8504` | EOSdash server IP port number. Defaults to 8504. |
 | eosdash_supervise_interval_sec | `EOS_SERVER__EOSDASH_SUPERVISE_INTERVAL_SEC` | `int` | `rw` | `10` | Supervision interval for EOS server to supervise EOSdash [seconds]. |
-| host | `EOS_SERVER__HOST` | `Optional[str]` | `rw` | `127.0.0.1` | EOS server IP address. Defaults to 127.0.0.1. |
-| port | `EOS_SERVER__PORT` | `Optional[int]` | `rw` | `8503` | EOS server IP port number. Defaults to 8503. |
+| host | `EOS_SERVER__HOST` | `str` | `rw` | `127.0.0.1` | EOS server IP address. Defaults to 127.0.0.1. |
+| port | `EOS_SERVER__PORT` | `int` | `rw` | `8503` | EOS server IP port number. Defaults to 8503. |
 | reload | `EOS_SERVER__RELOAD` | `Optional[bool]` | `rw` | `False` | Enable server auto-reload for debugging or development. Default is False. Monitors the package directory for changes and reloads the server. |
 | run_as_user | `EOS_SERVER__RUN_AS_USER` | `Optional[str]` | `rw` | `None` | The name of the target user to switch to. If ``None`` (default), the current effective user is used and no privilege change is attempted. |
 | startup_eosdash | `EOS_SERVER__STARTUP_EOSDASH` | `Optional[bool]` | `rw` | `True` | EOS server to start EOSdash server. Defaults to True. |

docs/_generated/openapi.md

@@ -1,6 +1,6 @@
 # Akkudoktor-EOS
 
-**Version**: `v0.3.0.dev2603180781250771`
+**Version**: `v0.3.0.dev2603271452975993`
 
 <!-- pyml disable line-length -->
 **Description**: This project provides a comprehensive solution for simulating and optimizing an energy system based on renewable energy sources. With a focus on photovoltaic (PV) systems, battery storage (batteries), load management (consumer requirements), heat pumps, electric vehicles, and consideration of electricity price data, this system enables forecasting and optimization of energy flow and costs over a specified period.

openapi.json

@@ -8,7 +8,7 @@
       "name": "Apache 2.0",
       "url": "https://www.apache.org/licenses/LICENSE-2.0.html"
     },
-    "version": "v0.3.0.dev2603180781250771"
+    "version": "v0.3.0.dev2603271452975993"
   },
   "paths": {
     "/v1/admin/cache/clear": {
@@ -8327,14 +8327,7 @@
       "ServerCommonSettings": {
         "properties": {
           "host": {
-            "anyOf": [
-              {
-                "type": "string"
-              },
-              {
-                "type": "null"
-              }
-            ],
+            "type": "string",
             "title": "Host",
             "description": "EOS server IP address. Defaults to 127.0.0.1.",
             "default": "127.0.0.1",
@@ -8344,14 +8337,7 @@
             ]
           },
           "port": {
-            "anyOf": [
-              {
-                "type": "integer"
-              },
-              {
-                "type": "null"
-              }
-            ],
+            "type": "integer",
             "title": "Port",
             "description": "EOS server IP port number. Defaults to 8503.",
             "default": 8503,
@@ -8386,32 +8372,20 @@
             "default": true
           },
           "eosdash_host": {
-            "anyOf": [
-              {
-                "type": "string"
-              },
-              {
-                "type": "null"
-              }
-            ],
+            "type": "string",
             "title": "Eosdash Host",
             "description": "EOSdash server IP address. Defaults to EOS server IP address.",
+            "default": "127.0.0.1",
             "examples": [
               "127.0.0.1",
               "localhost"
             ]
           },
           "eosdash_port": {
-            "anyOf": [
-              {
-                "type": "integer"
-              },
-              {
-                "type": "null"
-              }
-            ],
+            "type": "integer",
             "title": "Eosdash Port",
-            "description": "EOSdash server IP port number. Defaults to EOS server IP port number + 1.",
+            "description": "EOSdash server IP port number. Defaults to 8504.",
+            "default": 8504,
             "examples": [
               8504
             ]

scripts/update_version.py

@@ -10,7 +10,7 @@
 import sys
 from datetime import timezone
 from pathlib import Path
-from typing import List
+from typing import List, Optional
 
 PROJECT_ROOT = Path(__file__).parent.parent
 PACKAGE_DIR = PROJECT_ROOT / "src" / "akkudoktoreos"
@@ -102,7 +102,7 @@ def repl(match):
     return file_would_be_updated
 
 
-def update_version_date_file() -> str:
+def update_version_date_file() -> Optional[str]:
     """Write current version date to _version_date.py, only if changed."""
     from akkudoktoreos.core.version import VERSION_DATE_FILE, _version_date_hash
     version_date, _ = _version_date_hash()
@@ -112,7 +112,7 @@ def update_version_date_file() -> str:
 
     if VERSION_DATE_FILE.exists() and VERSION_DATE_FILE.read_text(encoding="utf-8") == new_content:
         print(f"No change to {VERSION_DATE_FILE}")
-        return str(VERSION_DATE_FILE)
+        return None
 
     VERSION_DATE_FILE.write_text(new_content, encoding="utf-8")
     print(f"Updated {VERSION_DATE_FILE} with UTC date {version_date_str}")
@@ -134,18 +134,12 @@ def main(version: str, files: List[str]):
         if update_version_in_file(path, version):
             updated_files.append(str(path))
 
+    version_date_file = update_version_date_file()
+    if version_date_file:
+        updated_files.append(version_date_file)
+
     if updated_files:
         print(f"Updated files: {', '.join(updated_files)}")
-
-        # Only update VERSION_DATE_FILE if a real package file was touched
-        # Exclude VERSION_DATE_FILE itself to avoid a self-referencing loop
-        from akkudoktoreos.core.version import VERSION_DATE_FILE
-        package_files_updated = any(
-            str(PACKAGE_DIR) in f and Path(f).resolve() != VERSION_DATE_FILE.resolve()
-            for f in updated_files
-        )
-        if package_files_updated:
-            updated_files.append(update_version_date_file())
     else:
         print("No files updated.")
 

src/akkudoktoreos/core/_version_date.py

@@ -1 +1 @@
-VERSION_DATE = "2026-02-24T16:58:00Z"
+VERSION_DATE = "2026-03-27T14:59:30+00:00"

src/akkudoktoreos/server/server.py

@@ -7,13 +7,13 @@
 import re
 import socket
 import time
-from typing import Optional
+from typing import Any, Optional
 
 import psutil
 from loguru import logger
 from pydantic import Field, field_validator
 
-from akkudoktoreos.config.configabc import SettingsBaseModel
+from akkudoktoreos.config.configabc import SettingsBaseModel, is_home_assistant_addon
 from akkudoktoreos.core.coreabc import get_config
 
 
@@ -22,6 +22,11 @@ def get_default_host() -> str:
     return "127.0.0.1"
 
 
+def get_default_port() -> int:
+    """Default port for EOS."""
+    return 8503
+
+
 def get_host_ip() -> str:
     """IP address of the host machine.
 
@@ -326,15 +331,15 @@ def fix_data_directories_permissions(run_as_user: Optional[str] = None) -> None:
 class ServerCommonSettings(SettingsBaseModel):
     """Server Configuration."""
 
-    host: Optional[str] = Field(
+    host: str = Field(
         default=get_default_host(),
         json_schema_extra={
             "description": "EOS server IP address. Defaults to 127.0.0.1.",
             "examples": ["127.0.0.1", "localhost"],
         },
     )
-    port: Optional[int] = Field(
-        default=8503,
+    port: int = Field(
+        default=get_default_port(),
         json_schema_extra={
             "description": "EOS server IP port number. Defaults to 8503.",
             "examples": [
@@ -349,17 +354,17 @@ class ServerCommonSettings(SettingsBaseModel):
         default=True,
         json_schema_extra={"description": "EOS server to start EOSdash server. Defaults to True."},
     )
-    eosdash_host: Optional[str] = Field(
-        default=None,
+    eosdash_host: str = Field(
+        default=get_default_host(),
         json_schema_extra={
             "description": "EOSdash server IP address. Defaults to EOS server IP address.",
             "examples": ["127.0.0.1", "localhost"],
         },
     )
-    eosdash_port: Optional[int] = Field(
-        default=None,
+    eosdash_port: int = Field(
+        default=get_default_port() + 1,
         json_schema_extra={
-            "description": "EOSdash server IP port number. Defaults to EOS server IP port number + 1.",
+            "description": "EOSdash server IP port number. Defaults to 8504.",
             "examples": [
                 8504,
             ],
@@ -406,12 +411,34 @@ def validate_server_host(cls, value: Optional[str]) -> Optional[str]:
             value = validate_ip_or_hostname(value)
         return value
 
-    @field_validator("port", "eosdash_port")
-    def validate_server_port(cls, value: Optional[int]) -> Optional[int]:
-        if value is not None and not (1024 <= value <= 49151):
+    @field_validator("port", mode="before")
+    def validate_server_port(cls, value: Any) -> int:
+        default_port = get_default_port()
+        if value is None:
+            return default_port
+        value = int(value)
+        if is_home_assistant_addon() and value != default_port:
+            raise ValueError(
+                f"Server port number `{default_port}` for Home Assistant add-on can not be changed."
+            )
+        if not (1024 <= value <= 49151):
             raise ValueError("Server port number must be between 1024 and 49151.")
         return value
 
+    @field_validator("eosdash_port", mode="before")
+    def validate_eosdash_port(cls, value: Any) -> int:  # ← unique name
+        default_port = get_default_port() + 1
+        if value is None:
+            return default_port
+        value = int(value)
+        if is_home_assistant_addon() and value != default_port:
+            raise ValueError(
+                f"EOSdash port number `{default_port}` for Home Assistant add-on can not be changed."
+            )
+        if not (1024 <= value <= 49151):
+            raise ValueError("EOSdash port number must be between 1024 and 49151.")
+        return value
+
     @field_validator("run_as_user")
     def validate_user(cls, value: Optional[str]) -> Optional[str]:
         if value is not None:

tests/test_server.py

@@ -11,9 +11,16 @@
 import requests
 from conftest import cleanup_eos_eosdash
 from loguru import logger
+from pydantic import ValidationError
 
+from akkudoktoreos.config.configabc import is_home_assistant_addon
 from akkudoktoreos.core.version import __version__
-from akkudoktoreos.server.server import get_default_host, wait_for_port_free
+from akkudoktoreos.server.server import (
+    ServerCommonSettings,
+    get_default_host,
+    get_default_port,
+    wait_for_port_free,
+)
 
 
 class TestServer:
@@ -45,6 +52,38 @@ def test_server_setup_for_class(self, server_setup_for_class):
         assert str(data_ouput_path).startswith(eos_dir)
 
 
+class TestServerSettingsValidation:
+    """Test the port restrictions in ServerCommonSettings when running as HA addon."""
+
+    def test_ha_addon_default_ports_ok(self, config_eos, monkeypatch):
+        """Default ports are accepted in HA addon mode."""
+        monkeypatch.setattr('akkudoktoreos.server.server.is_home_assistant_addon', lambda: True)
+        assert config_eos.server.port == get_default_port()           # 8503
+        assert config_eos.server.eosdash_port == get_default_port() + 1  # 8504
+
+    def test_server_port_restriction_in_ha_addon(self, config_eos, monkeypatch):
+        """Server port must be the default (8503) in HA addon mode."""
+        monkeypatch.setattr('akkudoktoreos.server.server.is_home_assistant_addon', lambda: True)
+        with pytest.raises(ValidationError) as excinfo:
+            config_eos.server.port = 9000
+        assert "Server port number `8503` for Home Assistant add-on can not be changed" in str(excinfo.value)
+
+    def test_eosdash_port_restriction_in_ha_addon(self, config_eos, monkeypatch):
+        """EOSdash port must be the default (8504) in HA addon mode."""
+        monkeypatch.setattr('akkudoktoreos.server.server.is_home_assistant_addon', lambda: True)
+        with pytest.raises(ValidationError) as excinfo:
+            config_eos.server.eosdash_port = 9001
+        assert "EOSdash port number `8504` for Home Assistant add-on can not be changed" in str(excinfo.value)
+
+    def test_ports_allowed_when_not_ha_addon(self, config_eos):
+        """Custom ports are allowed when not in HA addon mode."""
+        # is_home_assistant_addon() returns False by default in this test environment
+        config_eos.server.port = 9000
+        config_eos.server.eosdash_port = 9001
+        assert config_eos.server.port == 9000
+        assert config_eos.server.eosdash_port == 9001
+
+
 class TestServerStartStop:
 
     @pytest.mark.asyncio