Addition of a basic Admin UI

src/.env.EXAMPLE

@@ -33,6 +33,11 @@ FLASK_RUN_HOST=api
 FLASK_RUN_PORT=5000
 FLASK_URL=http://${FLASK_RUN_HOST}:${FLASK_RUN_PORT}
 
+# Admin UI — don't change unless you know what you're doing
+UI_LOG_LEVEL=20
+UI_PORT=8080 # internal port that the bot and API communicate with it on
+UI_PORT_HOST=8080 # external mapping (Where you access it on localhost!)
+
 # The guild which controls the DB and moderation
 MASTER_GUILD=
 PISTON_API_TOKEN=null # for running >run commands. Received from EngineerMan's Piston project.

src/Dockerfile-ui

@@ -0,0 +1,33 @@
+FROM python:3.12-slim-bookworm
+
+ARG UI_PORT=8080
+
+ENV PYTHONUNBUFFERED=1 \
+ PYTHONDONTWRITEBYTECODE=1 \
+ UV_COMPILE_BYTECODE=1 \
+ UV_LINK_MODE=copy \
+ UV_PROJECT_ENVIRONMENT=/ui/.venv
+
+COPY --from=ghcr.io/astral-sh/uv:0.12.1 /uv /uvx /usr/local/bin/
+
+WORKDIR /ui
+
+COPY pyproject.toml uv.lock ./
+COPY src/ui/pyproject.toml src/ui/pyproject.toml
+
+RUN --mount=type=cache,target=/root/.cache/uv \
+ uv sync --frozen --no-install-project --no-dev --package eos-ui
+
+COPY src/ui ./src/ui
+
+RUN --mount=type=cache,target=/root/.cache/uv \
+ uv sync --frozen --no-dev --package eos-ui
+
+RUN useradd -r -M uiuser && chown -R uiuser:uiuser /ui
+USER uiuser
+
+ENV HOME="/ui" \
+ PATH="/ui/.venv/bin:$PATH"
+
+EXPOSE ${UI_PORT}
+CMD ["python", "-m", "src.ui.main"]

src/docker-compose.yml

@@ -21,6 +21,37 @@ services:
  max-size: "10m"
  max-file: "3"
 
+ ui:
+ container_name: ui
+ build:
+ context: ../
+ dockerfile: src/Dockerfile-ui
+ args:
+ UI_PORT: ${UI_PORT}
+ env_file: .env
+ image: eos-ui:latest
+ init: true
+ networks:
+ - eos
+ depends_on:
+ api:
+ condition: service_healthy
+ ports:
+ - "127.0.0.1:${UI_PORT_HOST:-8080}:${UI_PORT}"
+ healthcheck:
+ test: ["CMD-SHELL", "python -c \"import urllib.request; urllib.request.urlopen('http://localhost:${UI_PORT}/hc_ui')\""]
+ interval: 10s
+ timeout: 5s
+ retries: 5
+ start_period: 20s
+ restart: unless-stopped
+ mem_limit: 256m
+ logging:
+ driver: json-file
+ options:
+ max-size: "10m"
+ max-file: "3"
+
  api:
  container_name: api
  build:

src/ui/__logger__.py

@@ -0,0 +1,38 @@
+import logging
+
+
+def setup_logger(level, stream_logs) -> None:
+ """
+ Configures the logging for the service.
+
+ This function sets up the logging configuration for the service, allowing
+ logs to be output to the console if specified. It formats the logs with a
+ specific format and sets the logging level.
+
+ Parameters
+ ----------
+ level : int
+ The logging level to be set for the logs. This determines the severity
+ of the messages that will be logged.
+ stream_logs : bool
+ A flag indicating whether to stream the logs to the console. If True,
+ logs will be output to the console.
+
+ Returns
+ -------
+ None
+ This function does not return any value.
+ """
+ log_formatter = logging.Formatter(
+ ":: %(asctime)s :: %(levelname)s :: %(filename)s line %(lineno)s --- %(message)s",
+ "%m-%d %H:%M.%S",
+ )
+
+ handlers: list[logging.Handler] = []
+ if stream_logs:
+ stream_handler = logging.StreamHandler()
+ stream_handler.setFormatter(log_formatter)
+ stream_handler.setLevel(level)
+ handlers.append(stream_handler)
+
+ logging.basicConfig(level=level, handlers=handlers)

src/ui/core/api_client.py

@@ -0,0 +1,64 @@
+import logging
+import os
+
+import requests
+
+logger = logging.getLogger(__name__)
+
+# Default timeout (seconds) for all API requests so a hung API can't block the UI.
+REQUEST_TIMEOUT = 10
+
+_UNAVAILABLE = {"status": "error", "message": "API request failed"}
+
+
+class API:
+ """
+ Thin blocking client over the Flask API.
+
+ Mirrors the bot's ``core/api_helper.py`` contract: every call returns the
+ standard envelope, and transport failures are logged and folded into an
+ ``error`` envelope rather than raised.
+ """
+
+ def __init__(self):
+ logger.info("Initializing API client...")
+ self.api = os.getenv("FLASK_URL")
+ self.headers = {"Content-Type": "application/json"}
+
+ def _request(self, method, path, **kwargs) -> dict:
+ """Perform a blocking request and return the juice."""
+ try:
+ response = requests.request(
+ method,
+ f"{self.api}{path}",
+ headers=self.headers,
+ timeout=REQUEST_TIMEOUT,
+ **kwargs,
+ )
+ payload = response.json()
+ except requests.RequestException as err:
+ logger.error("API %s %s failed: %s", method, path, err)
+ return dict(_UNAVAILABLE)
+ except ValueError:
+ logger.error("API %s %s returned a non-JSON body", method, path)
+ return dict(_UNAVAILABLE)
+
+ if not isinstance(payload, dict):
+ logger.error(
+ "API %s %s returned an unexpected shape: %r", method, path, payload
+ )
+ return dict(_UNAVAILABLE)
+
+ return payload
+
+ def health_check(self) -> dict:
+ """Returns the healthcheck status of the API."""
+ return self._request("GET", "/hc_api")
+
+ def get_settings(self) -> dict:
+ """Returns every row of ``serversettings``."""
+ return self._request("GET", "/settings")
+
+ def update_setting(self, setting_id, value) -> dict:
+ """Writes a new value onto a single ``serversettings`` row."""
+ return self._request("PUT", f"/settings/{setting_id}", json={"value": value})

src/ui/main.py

@@ -0,0 +1,87 @@
+import logging
+import os
+
+from nicegui import app, ui
+
+from src.ui.__logger__ import setup_logger
+from src.ui.core.api_client import API
+
+logger = logging.getLogger(__name__)
+
+TROOPHY = {"1", "true", "yes", "on"}
+
+setup_logger(
+ level=int(os.getenv("UI_LOG_LEVEL", "20")),
+ stream_logs=os.getenv("STREAM_LOGS", "true").strip().lower() in TROOPHY,
+)
+
+api = API()
+
+
+@app.get("/hc_ui")
+def health_check():
+ """get health, noob."""
+ return {"status": "ok", "message": "UI is alive"}
+
+
+def _save(container, setting_id, name, field) -> None:
+ """Update a setting via the API, then re-read so the page shows the DB."""
+ result = api.update_setting(setting_id, field.value)
+ if result.get("status") != "ok":
+ logger.error("Failed to update setting %s: %s", setting_id, result)
+ ui.notify(f"Failed to save {name}: {result.get('message')}", type="negative")
+ else:
+ logger.info("Updated setting %s (%s)", setting_id, name)
+ ui.notify(f"Saved {name}", type="positive")
+
+ # Always redraw from the API — never leave a typed (or rejected) value on
+ # screen pretending to be what the database holds.
+ _render_settings(container)
+
+
+def _render_settings(container) -> None:
+ """Hit the API, and dump out what we have inside of it"""
+ container.clear()
+
+ result = api.get_settings()
+ with container:
+ if result.get("status") != "ok":
+ logger.error("Failed to load settings: %s", result)
+ ui.label(f"Could not load settings: {result.get('message')}").classes(
+ "text-red-600"
+ )
+ return
+
+ for setting in result.get("settings", []):
+ with ui.row().classes("w-full items-center gap-4"):
+ ui.label(setting["name"]).classes("w-64")
+ field = ui.input(value=setting["value"] or "").classes("w-64")
+ ui.button(
+ "Save",
+ on_click=lambda _, s=setting, f=field: _save(
+ container, s["id"], s["name"], f
+ ),
+ )
+
+
+@ui.page("/")
+def index():
+ """server settings"""
+ ui.label("Eos Admin — Server Settings").classes("text-2xl font-bold")
+
+ health = api.health_check()
+ ui.label(f"API: {health.get('status')}").classes("text-sm text-gray-500")
+
+ ui.button("Refresh", on_click=lambda: _render_settings(container))
+ container = ui.column().classes("w-full gap-2")
+ _render_settings(container)
+
+
+if __name__ in {"__main__", "__mp_main__"}:
+ ui.run(
+ host="0.0.0.0", # noqa: S104 # nosec B104
+ port=int(os.getenv("UI_PORT", "8080")),
+ title="Eos Admin",
+ reload=False,
+ show=False,
+ )

src/ui/pyproject.toml

@@ -0,0 +1,9 @@
+[project]
+name = "eos-ui"
+version = "0.1.0"
+description = "Eos admin UI made with NiceGUI."
+requires-python = ">=3.12"
+dependencies = [
+ "nicegui==3.16.0",
+ "requests==2.34.2",
+]

src/.env.EXAMPLE

@@ -33,6 +33,11 @@ FLASK_RUN_HOST=api
 FLASK_RUN_PORT=5000
 FLASK_URL=http://${FLASK_RUN_HOST}:${FLASK_RUN_PORT}
 
+# Admin UI — don't change unless you know what you're doing
+UI_LOG_LEVEL=20
+UI_PORT=8080 # internal port that the bot and API communicate with it on
+UI_PORT_HOST=8080 # external mapping (Where you access it on localhost!)
+
 # The guild which controls the DB and moderation
 MASTER_GUILD=
 PISTON_API_TOKEN=null # for running >run commands. Received from EngineerMan's Piston project.

src/Dockerfile-ui

@@ -0,0 +1,33 @@
+FROM python:3.12-slim-bookworm
+
+ARG UI_PORT=8080
+
+ENV PYTHONUNBUFFERED=1 \
+ PYTHONDONTWRITEBYTECODE=1 \
+ UV_COMPILE_BYTECODE=1 \
+ UV_LINK_MODE=copy \
+ UV_PROJECT_ENVIRONMENT=/ui/.venv
+
+COPY --from=ghcr.io/astral-sh/uv:0.12.1 /uv /uvx /usr/local/bin/
+
+WORKDIR /ui
+
+COPY pyproject.toml uv.lock ./
+COPY src/ui/pyproject.toml src/ui/pyproject.toml
+
+RUN --mount=type=cache,target=/root/.cache/uv \
+ uv sync --frozen --no-install-project --no-dev --package eos-ui
+
+COPY src/ui ./src/ui
+
+RUN --mount=type=cache,target=/root/.cache/uv \
+ uv sync --frozen --no-dev --package eos-ui
+
+RUN useradd -r -M uiuser && chown -R uiuser:uiuser /ui
+USER uiuser
+
+ENV HOME="/ui" \
+ PATH="/ui/.venv/bin:$PATH"
+
+EXPOSE ${UI_PORT}
+CMD ["python", "-m", "src.ui.main"]

src/docker-compose.yml

@@ -21,6 +21,37 @@ services:
  max-size: "10m"
  max-file: "3"
 
+ ui:
+ container_name: ui
+ build:
+ context: ../
+ dockerfile: src/Dockerfile-ui
+ args:
+ UI_PORT: ${UI_PORT}
+ env_file: .env
+ image: eos-ui:latest
+ init: true
+ networks:
+ - eos
+ depends_on:
+ api:
+ condition: service_healthy
+ ports:
+ - "127.0.0.1:${UI_PORT_HOST:-8080}:${UI_PORT}"
+ healthcheck:
+ test: ["CMD-SHELL", "python -c \"import urllib.request; urllib.request.urlopen('http://localhost:${UI_PORT}/hc_ui')\""]
+ interval: 10s
+ timeout: 5s
+ retries: 5
+ start_period: 20s
+ restart: unless-stopped
+ mem_limit: 256m
+ logging:
+ driver: json-file
+ options:
+ max-size: "10m"
+ max-file: "3"
+
  api:
  container_name: api
  build:

src/ui/__logger__.py

@@ -0,0 +1,38 @@
+import logging
+
+
+def setup_logger(level, stream_logs) -> None:
+ """
+ Configures the logging for the service.
+
+ This function sets up the logging configuration for the service, allowing
+ logs to be output to the console if specified. It formats the logs with a
+ specific format and sets the logging level.
+
+ Parameters
+ ----------
+ level : int
+ The logging level to be set for the logs. This determines the severity
+ of the messages that will be logged.
+ stream_logs : bool
+ A flag indicating whether to stream the logs to the console. If True,
+ logs will be output to the console.
+
+ Returns
+ -------
+ None
+ This function does not return any value.
+ """
+ log_formatter = logging.Formatter(
+ ":: %(asctime)s :: %(levelname)s :: %(filename)s line %(lineno)s --- %(message)s",
+ "%m-%d %H:%M.%S",
+ )
+
+ handlers: list[logging.Handler] = []
+ if stream_logs:
+ stream_handler = logging.StreamHandler()
+ stream_handler.setFormatter(log_formatter)
+ stream_handler.setLevel(level)
+ handlers.append(stream_handler)
+
+ logging.basicConfig(level=level, handlers=handlers)

src/ui/core/api_client.py

@@ -0,0 +1,64 @@
+import logging
+import os
+
+import requests
+
+logger = logging.getLogger(__name__)
+
+# Default timeout (seconds) for all API requests so a hung API can't block the UI.
+REQUEST_TIMEOUT = 10
+
+_UNAVAILABLE = {"status": "error", "message": "API request failed"}
+
+
+class API:
+ """
+ Thin blocking client over the Flask API.
+
+ Mirrors the bot's ``core/api_helper.py`` contract: every call returns the
+ standard envelope, and transport failures are logged and folded into an
+ ``error`` envelope rather than raised.
+ """
+
+ def __init__(self):
+ logger.info("Initializing API client...")
+ self.api = os.getenv("FLASK_URL")
+ self.headers = {"Content-Type": "application/json"}
+
+ def _request(self, method, path, **kwargs) -> dict:
+ """Perform a blocking request and return the juice."""
+ try:
+ response = requests.request(
+ method,
+ f"{self.api}{path}",
+ headers=self.headers,
+ timeout=REQUEST_TIMEOUT,
+ **kwargs,
+ )
+ payload = response.json()
+ except requests.RequestException as err:
+ logger.error("API %s %s failed: %s", method, path, err)
+ return dict(_UNAVAILABLE)
+ except ValueError:
+ logger.error("API %s %s returned a non-JSON body", method, path)
+ return dict(_UNAVAILABLE)
+
+ if not isinstance(payload, dict):
+ logger.error(
+ "API %s %s returned an unexpected shape: %r", method, path, payload
+ )
+ return dict(_UNAVAILABLE)
+
+ return payload
+
+ def health_check(self) -> dict:
+ """Returns the healthcheck status of the API."""
+ return self._request("GET", "/hc_api")
+
+ def get_settings(self) -> dict:
+ """Returns every row of ``serversettings``."""
+ return self._request("GET", "/settings")
+
+ def update_setting(self, setting_id, value) -> dict:
+ """Writes a new value onto a single ``serversettings`` row."""
+ return self._request("PUT", f"/settings/{setting_id}", json={"value": value})

src/ui/main.py

@@ -0,0 +1,87 @@
+import logging
+import os
+
+from nicegui import app, ui
+
+from src.ui.__logger__ import setup_logger
+from src.ui.core.api_client import API
+
+logger = logging.getLogger(__name__)
+
+TROOPHY = {"1", "true", "yes", "on"}
+
+setup_logger(
+ level=int(os.getenv("UI_LOG_LEVEL", "20")),
+ stream_logs=os.getenv("STREAM_LOGS", "true").strip().lower() in TROOPHY,
+)
+
+api = API()
+
+
+@app.get("/hc_ui")
+def health_check():
+ """get health, noob."""
+ return {"status": "ok", "message": "UI is alive"}
+
+
+def _save(container, setting_id, name, field) -> None:
+ """Update a setting via the API, then re-read so the page shows the DB."""
+ result = api.update_setting(setting_id, field.value)
+ if result.get("status") != "ok":
+ logger.error("Failed to update setting %s: %s", setting_id, result)
+ ui.notify(f"Failed to save {name}: {result.get('message')}", type="negative")
+ else:
+ logger.info("Updated setting %s (%s)", setting_id, name)
+ ui.notify(f"Saved {name}", type="positive")
+
+ # Always redraw from the API — never leave a typed (or rejected) value on
+ # screen pretending to be what the database holds.
+ _render_settings(container)
+
+
+def _render_settings(container) -> None:
+ """Hit the API, and dump out what we have inside of it"""
+ container.clear()
+
+ result = api.get_settings()
+ with container:
+ if result.get("status") != "ok":
+ logger.error("Failed to load settings: %s", result)
+ ui.label(f"Could not load settings: {result.get('message')}").classes(
+ "text-red-600"
+ )
+ return
+
+ for setting in result.get("settings", []):
+ with ui.row().classes("w-full items-center gap-4"):
+ ui.label(setting["name"]).classes("w-64")
+ field = ui.input(value=setting["value"] or "").classes("w-64")
+ ui.button(
+ "Save",
+ on_click=lambda _, s=setting, f=field: _save(
+ container, s["id"], s["name"], f
+ ),
+ )
+
+
+@ui.page("/")
+def index():
+ """server settings"""
+ ui.label("Eos Admin — Server Settings").classes("text-2xl font-bold")
+
+ health = api.health_check()
+ ui.label(f"API: {health.get('status')}").classes("text-sm text-gray-500")
+
+ ui.button("Refresh", on_click=lambda: _render_settings(container))
+ container = ui.column().classes("w-full gap-2")
+ _render_settings(container)
+
+
+if __name__ in {"__main__", "__mp_main__"}:
+ ui.run(
+ host="0.0.0.0", # noqa: S104 # nosec B104
+ port=int(os.getenv("UI_PORT", "8080")),
+ title="Eos Admin",
+ reload=False,
+ show=False,
+ )

src/ui/pyproject.toml

@@ -0,0 +1,9 @@
+[project]
+name = "eos-ui"
+version = "0.1.0"
+description = "Eos admin UI made with NiceGUI."
+requires-python = ">=3.12"
+dependencies = [
+ "nicegui==3.16.0",
+ "requests==2.34.2",
+]

src/.env.EXAMPLE

@@ -33,6 +33,11 @@ FLASK_RUN_HOST=api
 FLASK_RUN_PORT=5000
 FLASK_URL=http://${FLASK_RUN_HOST}:${FLASK_RUN_PORT}
 
+# Admin UI — don't change unless you know what you're doing
+UI_LOG_LEVEL=20
+UI_PORT=8080 # internal port that the bot and API communicate with it on
+UI_PORT_HOST=8080 # external mapping (Where you access it on localhost!)
+
 # The guild which controls the DB and moderation
 MASTER_GUILD=
 PISTON_API_TOKEN=null # for running >run commands. Received from EngineerMan's Piston project.

src/Dockerfile-ui

@@ -0,0 +1,33 @@
+FROM python:3.12-slim-bookworm
+
+ARG UI_PORT=8080
+
+ENV PYTHONUNBUFFERED=1 \
+ PYTHONDONTWRITEBYTECODE=1 \
+ UV_COMPILE_BYTECODE=1 \
+ UV_LINK_MODE=copy \
+ UV_PROJECT_ENVIRONMENT=/ui/.venv
+
+COPY --from=ghcr.io/astral-sh/uv:0.12.1 /uv /uvx /usr/local/bin/
+
+WORKDIR /ui
+
+COPY pyproject.toml uv.lock ./
+COPY src/ui/pyproject.toml src/ui/pyproject.toml
+
+RUN --mount=type=cache,target=/root/.cache/uv \
+ uv sync --frozen --no-install-project --no-dev --package eos-ui
+
+COPY src/ui ./src/ui
+
+RUN --mount=type=cache,target=/root/.cache/uv \
+ uv sync --frozen --no-dev --package eos-ui
+
+RUN useradd -r -M uiuser && chown -R uiuser:uiuser /ui
+USER uiuser
+
+ENV HOME="/ui" \
+ PATH="/ui/.venv/bin:$PATH"
+
+EXPOSE ${UI_PORT}
+CMD ["python", "-m", "src.ui.main"]

src/docker-compose.yml

@@ -21,6 +21,37 @@ services:
  max-size: "10m"
  max-file: "3"
 
+ ui:
+ container_name: ui
+ build:
+ context: ../
+ dockerfile: src/Dockerfile-ui
+ args:
+ UI_PORT: ${UI_PORT}
+ env_file: .env
+ image: eos-ui:latest
+ init: true
+ networks:
+ - eos
+ depends_on:
+ api:
+ condition: service_healthy
+ ports:
+ - "127.0.0.1:${UI_PORT_HOST:-8080}:${UI_PORT}"
+ healthcheck:
+ test: ["CMD-SHELL", "python -c \"import urllib.request; urllib.request.urlopen('http://localhost:${UI_PORT}/hc_ui')\""]
+ interval: 10s
+ timeout: 5s
+ retries: 5
+ start_period: 20s
+ restart: unless-stopped
+ mem_limit: 256m
+ logging:
+ driver: json-file
+ options:
+ max-size: "10m"
+ max-file: "3"
+
  api:
  container_name: api
  build:

src/ui/__logger__.py

@@ -0,0 +1,38 @@
+import logging
+
+
+def setup_logger(level, stream_logs) -> None:
+ """
+ Configures the logging for the service.
+
+ This function sets up the logging configuration for the service, allowing
+ logs to be output to the console if specified. It formats the logs with a
+ specific format and sets the logging level.
+
+ Parameters
+ ----------
+ level : int
+ The logging level to be set for the logs. This determines the severity
+ of the messages that will be logged.
+ stream_logs : bool
+ A flag indicating whether to stream the logs to the console. If True,
+ logs will be output to the console.
+
+ Returns
+ -------
+ None
+ This function does not return any value.
+ """
+ log_formatter = logging.Formatter(
+ ":: %(asctime)s :: %(levelname)s :: %(filename)s line %(lineno)s --- %(message)s",
+ "%m-%d %H:%M.%S",
+ )
+
+ handlers: list[logging.Handler] = []
+ if stream_logs:
+ stream_handler = logging.StreamHandler()
+ stream_handler.setFormatter(log_formatter)
+ stream_handler.setLevel(level)
+ handlers.append(stream_handler)
+
+ logging.basicConfig(level=level, handlers=handlers)

src/ui/core/api_client.py

@@ -0,0 +1,64 @@
+import logging
+import os
+
+import requests
+
+logger = logging.getLogger(__name__)
+
+# Default timeout (seconds) for all API requests so a hung API can't block the UI.
+REQUEST_TIMEOUT = 10
+
+_UNAVAILABLE = {"status": "error", "message": "API request failed"}
+
+
+class API:
+ """
+ Thin blocking client over the Flask API.
+
+ Mirrors the bot's ``core/api_helper.py`` contract: every call returns the
+ standard envelope, and transport failures are logged and folded into an
+ ``error`` envelope rather than raised.
+ """
+
+ def __init__(self):
+ logger.info("Initializing API client...")
+ self.api = os.getenv("FLASK_URL")
+ self.headers = {"Content-Type": "application/json"}
+
+ def _request(self, method, path, **kwargs) -> dict:
+ """Perform a blocking request and return the juice."""
+ try:
+ response = requests.request(
+ method,
+ f"{self.api}{path}",
+ headers=self.headers,
+ timeout=REQUEST_TIMEOUT,
+ **kwargs,
+ )
+ payload = response.json()
+ except requests.RequestException as err:
+ logger.error("API %s %s failed: %s", method, path, err)
+ return dict(_UNAVAILABLE)
+ except ValueError:
+ logger.error("API %s %s returned a non-JSON body", method, path)
+ return dict(_UNAVAILABLE)
+
+ if not isinstance(payload, dict):
+ logger.error(
+ "API %s %s returned an unexpected shape: %r", method, path, payload
+ )
+ return dict(_UNAVAILABLE)
+
+ return payload
+
+ def health_check(self) -> dict:
+ """Returns the healthcheck status of the API."""
+ return self._request("GET", "/hc_api")
+
+ def get_settings(self) -> dict:
+ """Returns every row of ``serversettings``."""
+ return self._request("GET", "/settings")
+
+ def update_setting(self, setting_id, value) -> dict:
+ """Writes a new value onto a single ``serversettings`` row."""
+ return self._request("PUT", f"/settings/{setting_id}", json={"value": value})

src/ui/main.py

@@ -0,0 +1,87 @@
+import logging
+import os
+
+from nicegui import app, ui
+
+from src.ui.__logger__ import setup_logger
+from src.ui.core.api_client import API
+
+logger = logging.getLogger(__name__)
+
+TROOPHY = {"1", "true", "yes", "on"}
+
+setup_logger(
+ level=int(os.getenv("UI_LOG_LEVEL", "20")),
+ stream_logs=os.getenv("STREAM_LOGS", "true").strip().lower() in TROOPHY,
+)
+
+api = API()
+
+
+@app.get("/hc_ui")
+def health_check():
+ """get health, noob."""
+ return {"status": "ok", "message": "UI is alive"}
+
+
+def _save(container, setting_id, name, field) -> None:
+ """Update a setting via the API, then re-read so the page shows the DB."""
+ result = api.update_setting(setting_id, field.value)
+ if result.get("status") != "ok":
+ logger.error("Failed to update setting %s: %s", setting_id, result)
+ ui.notify(f"Failed to save {name}: {result.get('message')}", type="negative")
+ else:
+ logger.info("Updated setting %s (%s)", setting_id, name)
+ ui.notify(f"Saved {name}", type="positive")
+
+ # Always redraw from the API — never leave a typed (or rejected) value on
+ # screen pretending to be what the database holds.
+ _render_settings(container)
+
+
+def _render_settings(container) -> None:
+ """Hit the API, and dump out what we have inside of it"""
+ container.clear()
+
+ result = api.get_settings()
+ with container:
+ if result.get("status") != "ok":
+ logger.error("Failed to load settings: %s", result)
+ ui.label(f"Could not load settings: {result.get('message')}").classes(
+ "text-red-600"
+ )
+ return
+
+ for setting in result.get("settings", []):
+ with ui.row().classes("w-full items-center gap-4"):
+ ui.label(setting["name"]).classes("w-64")
+ field = ui.input(value=setting["value"] or "").classes("w-64")
+ ui.button(
+ "Save",
+ on_click=lambda _, s=setting, f=field: _save(
+ container, s["id"], s["name"], f
+ ),
+ )
+
+
+@ui.page("/")
+def index():
+ """server settings"""
+ ui.label("Eos Admin — Server Settings").classes("text-2xl font-bold")
+
+ health = api.health_check()
+ ui.label(f"API: {health.get('status')}").classes("text-sm text-gray-500")
+
+ ui.button("Refresh", on_click=lambda: _render_settings(container))
+ container = ui.column().classes("w-full gap-2")
+ _render_settings(container)
+
+
+if __name__ in {"__main__", "__mp_main__"}:
+ ui.run(
+ host="0.0.0.0", # noqa: S104 # nosec B104
+ port=int(os.getenv("UI_PORT", "8080")),
+ title="Eos Admin",
+ reload=False,
+ show=False,
+ )

src/ui/pyproject.toml

@@ -0,0 +1,9 @@
+[project]
+name = "eos-ui"
+version = "0.1.0"
+description = "Eos admin UI made with NiceGUI."
+requires-python = ">=3.12"
+dependencies = [
+ "nicegui==3.16.0",
+ "requests==2.34.2",
+]

src/.env.EXAMPLE

@@ -33,6 +33,11 @@ FLASK_RUN_HOST=api
 FLASK_RUN_PORT=5000
 FLASK_URL=http://${FLASK_RUN_HOST}:${FLASK_RUN_PORT}
 
+# Admin UI — don't change unless you know what you're doing
+UI_LOG_LEVEL=20
+UI_PORT=8080 # internal port that the bot and API communicate with it on
+UI_PORT_HOST=8080 # external mapping (Where you access it on localhost!)
+
 # The guild which controls the DB and moderation
 MASTER_GUILD=
 PISTON_API_TOKEN=null # for running >run commands. Received from EngineerMan's Piston project.

src/Dockerfile-ui

@@ -0,0 +1,33 @@
+FROM python:3.12-slim-bookworm
+
+ARG UI_PORT=8080
+
+ENV PYTHONUNBUFFERED=1 \
+ PYTHONDONTWRITEBYTECODE=1 \
+ UV_COMPILE_BYTECODE=1 \
+ UV_LINK_MODE=copy \
+ UV_PROJECT_ENVIRONMENT=/ui/.venv
+
+COPY --from=ghcr.io/astral-sh/uv:0.12.1 /uv /uvx /usr/local/bin/
+
+WORKDIR /ui
+
+COPY pyproject.toml uv.lock ./
+COPY src/ui/pyproject.toml src/ui/pyproject.toml
+
+RUN --mount=type=cache,target=/root/.cache/uv \
+ uv sync --frozen --no-install-project --no-dev --package eos-ui
+
+COPY src/ui ./src/ui
+
+RUN --mount=type=cache,target=/root/.cache/uv \
+ uv sync --frozen --no-dev --package eos-ui
+
+RUN useradd -r -M uiuser && chown -R uiuser:uiuser /ui
+USER uiuser
+
+ENV HOME="/ui" \
+ PATH="/ui/.venv/bin:$PATH"
+
+EXPOSE ${UI_PORT}
+CMD ["python", "-m", "src.ui.main"]

src/docker-compose.yml

@@ -21,6 +21,37 @@ services:
  max-size: "10m"
  max-file: "3"
 
+ ui:
+ container_name: ui
+ build:
+ context: ../
+ dockerfile: src/Dockerfile-ui
+ args:
+ UI_PORT: ${UI_PORT}
+ env_file: .env
+ image: eos-ui:latest
+ init: true
+ networks:
+ - eos
+ depends_on:
+ api:
+ condition: service_healthy
+ ports:
+ - "127.0.0.1:${UI_PORT_HOST:-8080}:${UI_PORT}"
+ healthcheck:
+ test: ["CMD-SHELL", "python -c \"import urllib.request; urllib.request.urlopen('http://localhost:${UI_PORT}/hc_ui')\""]
+ interval: 10s
+ timeout: 5s
+ retries: 5
+ start_period: 20s
+ restart: unless-stopped
+ mem_limit: 256m
+ logging:
+ driver: json-file
+ options:
+ max-size: "10m"
+ max-file: "3"
+
  api:
  container_name: api
  build:

src/ui/__logger__.py

@@ -0,0 +1,38 @@
+import logging
+
+
+def setup_logger(level, stream_logs) -> None:
+ """
+ Configures the logging for the service.
+
+ This function sets up the logging configuration for the service, allowing
+ logs to be output to the console if specified. It formats the logs with a
+ specific format and sets the logging level.
+
+ Parameters
+ ----------
+ level : int
+ The logging level to be set for the logs. This determines the severity
+ of the messages that will be logged.
+ stream_logs : bool
+ A flag indicating whether to stream the logs to the console. If True,
+ logs will be output to the console.
+
+ Returns
+ -------
+ None
+ This function does not return any value.
+ """
+ log_formatter = logging.Formatter(
+ ":: %(asctime)s :: %(levelname)s :: %(filename)s line %(lineno)s --- %(message)s",
+ "%m-%d %H:%M.%S",
+ )
+
+ handlers: list[logging.Handler] = []
+ if stream_logs:
+ stream_handler = logging.StreamHandler()
+ stream_handler.setFormatter(log_formatter)
+ stream_handler.setLevel(level)
+ handlers.append(stream_handler)
+
+ logging.basicConfig(level=level, handlers=handlers)

src/ui/core/api_client.py

@@ -0,0 +1,64 @@
+import logging
+import os
+
+import requests
+
+logger = logging.getLogger(__name__)
+
+# Default timeout (seconds) for all API requests so a hung API can't block the UI.
+REQUEST_TIMEOUT = 10
+
+_UNAVAILABLE = {"status": "error", "message": "API request failed"}
+
+
+class API:
+ """
+ Thin blocking client over the Flask API.
+
+ Mirrors the bot's ``core/api_helper.py`` contract: every call returns the
+ standard envelope, and transport failures are logged and folded into an
+ ``error`` envelope rather than raised.
+ """
+
+ def __init__(self):
+ logger.info("Initializing API client...")
+ self.api = os.getenv("FLASK_URL")
+ self.headers = {"Content-Type": "application/json"}
+
+ def _request(self, method, path, **kwargs) -> dict:
+ """Perform a blocking request and return the juice."""
+ try:
+ response = requests.request(
+ method,
+ f"{self.api}{path}",
+ headers=self.headers,
+ timeout=REQUEST_TIMEOUT,
+ **kwargs,
+ )
+ payload = response.json()
+ except requests.RequestException as err:
+ logger.error("API %s %s failed: %s", method, path, err)
+ return dict(_UNAVAILABLE)
+ except ValueError:
+ logger.error("API %s %s returned a non-JSON body", method, path)
+ return dict(_UNAVAILABLE)
+
+ if not isinstance(payload, dict):
+ logger.error(
+ "API %s %s returned an unexpected shape: %r", method, path, payload
+ )
+ return dict(_UNAVAILABLE)
+
+ return payload
+
+ def health_check(self) -> dict:
+ """Returns the healthcheck status of the API."""
+ return self._request("GET", "/hc_api")
+
+ def get_settings(self) -> dict:
+ """Returns every row of ``serversettings``."""
+ return self._request("GET", "/settings")
+
+ def update_setting(self, setting_id, value) -> dict:
+ """Writes a new value onto a single ``serversettings`` row."""
+ return self._request("PUT", f"/settings/{setting_id}", json={"value": value})

src/ui/main.py

@@ -0,0 +1,87 @@
+import logging
+import os
+
+from nicegui import app, ui
+
+from src.ui.__logger__ import setup_logger
+from src.ui.core.api_client import API
+
+logger = logging.getLogger(__name__)
+
+TROOPHY = {"1", "true", "yes", "on"}
+
+setup_logger(
+ level=int(os.getenv("UI_LOG_LEVEL", "20")),
+ stream_logs=os.getenv("STREAM_LOGS", "true").strip().lower() in TROOPHY,
+)
+
+api = API()
+
+
+@app.get("/hc_ui")
+def health_check():
+ """get health, noob."""
+ return {"status": "ok", "message": "UI is alive"}
+
+
+def _save(container, setting_id, name, field) -> None:
+ """Update a setting via the API, then re-read so the page shows the DB."""
+ result = api.update_setting(setting_id, field.value)
+ if result.get("status") != "ok":
+ logger.error("Failed to update setting %s: %s", setting_id, result)
+ ui.notify(f"Failed to save {name}: {result.get('message')}", type="negative")
+ else:
+ logger.info("Updated setting %s (%s)", setting_id, name)
+ ui.notify(f"Saved {name}", type="positive")
+
+ # Always redraw from the API — never leave a typed (or rejected) value on
+ # screen pretending to be what the database holds.
+ _render_settings(container)
+
+
+def _render_settings(container) -> None:
+ """Hit the API, and dump out what we have inside of it"""
+ container.clear()
+
+ result = api.get_settings()
+ with container:
+ if result.get("status") != "ok":
+ logger.error("Failed to load settings: %s", result)
+ ui.label(f"Could not load settings: {result.get('message')}").classes(
+ "text-red-600"
+ )
+ return
+
+ for setting in result.get("settings", []):
+ with ui.row().classes("w-full items-center gap-4"):
+ ui.label(setting["name"]).classes("w-64")
+ field = ui.input(value=setting["value"] or "").classes("w-64")
+ ui.button(
+ "Save",
+ on_click=lambda _, s=setting, f=field: _save(
+ container, s["id"], s["name"], f
+ ),
+ )
+
+
+@ui.page("/")
+def index():
+ """server settings"""
+ ui.label("Eos Admin — Server Settings").classes("text-2xl font-bold")
+
+ health = api.health_check()
+ ui.label(f"API: {health.get('status')}").classes("text-sm text-gray-500")
+
+ ui.button("Refresh", on_click=lambda: _render_settings(container))
+ container = ui.column().classes("w-full gap-2")
+ _render_settings(container)
+
+
+if __name__ in {"__main__", "__mp_main__"}:
+ ui.run(
+ host="0.0.0.0", # noqa: S104 # nosec B104
+ port=int(os.getenv("UI_PORT", "8080")),
+ title="Eos Admin",
+ reload=False,
+ show=False,
+ )

src/ui/pyproject.toml

@@ -0,0 +1,9 @@
+[project]
+name = "eos-ui"
+version = "0.1.0"
+description = "Eos admin UI made with NiceGUI."
+requires-python = ">=3.12"
+dependencies = [
+ "nicegui==3.16.0",
+ "requests==2.34.2",
+]

src/.env.EXAMPLE

@@ -33,6 +33,11 @@ FLASK_RUN_HOST=api
 FLASK_RUN_PORT=5000
 FLASK_URL=http://${FLASK_RUN_HOST}:${FLASK_RUN_PORT}
 
+# Admin UI — don't change unless you know what you're doing
+UI_LOG_LEVEL=20
+UI_PORT=8080 # internal port that the bot and API communicate with it on
+UI_PORT_HOST=8080 # external mapping (Where you access it on localhost!)
+
 # The guild which controls the DB and moderation
 MASTER_GUILD=
 PISTON_API_TOKEN=null # for running >run commands. Received from EngineerMan's Piston project.

src/Dockerfile-ui

@@ -0,0 +1,33 @@
+FROM python:3.12-slim-bookworm
+
+ARG UI_PORT=8080
+
+ENV PYTHONUNBUFFERED=1 \
+ PYTHONDONTWRITEBYTECODE=1 \
+ UV_COMPILE_BYTECODE=1 \
+ UV_LINK_MODE=copy \
+ UV_PROJECT_ENVIRONMENT=/ui/.venv
+
+COPY --from=ghcr.io/astral-sh/uv:0.12.1 /uv /uvx /usr/local/bin/
+
+WORKDIR /ui
+
+COPY pyproject.toml uv.lock ./
+COPY src/ui/pyproject.toml src/ui/pyproject.toml
+
+RUN --mount=type=cache,target=/root/.cache/uv \
+ uv sync --frozen --no-install-project --no-dev --package eos-ui
+
+COPY src/ui ./src/ui
+
+RUN --mount=type=cache,target=/root/.cache/uv \
+ uv sync --frozen --no-dev --package eos-ui
+
+RUN useradd -r -M uiuser && chown -R uiuser:uiuser /ui
+USER uiuser
+
+ENV HOME="/ui" \
+ PATH="/ui/.venv/bin:$PATH"
+
+EXPOSE ${UI_PORT}
+CMD ["python", "-m", "src.ui.main"]

src/docker-compose.yml

@@ -21,6 +21,37 @@ services:
  max-size: "10m"
  max-file: "3"
 
+ ui:
+ container_name: ui
+ build:
+ context: ../
+ dockerfile: src/Dockerfile-ui
+ args:
+ UI_PORT: ${UI_PORT}
+ env_file: .env
+ image: eos-ui:latest
+ init: true
+ networks:
+ - eos
+ depends_on:
+ api:
+ condition: service_healthy
+ ports:
+ - "127.0.0.1:${UI_PORT_HOST:-8080}:${UI_PORT}"
+ healthcheck:
+ test: ["CMD-SHELL", "python -c \"import urllib.request; urllib.request.urlopen('http://localhost:${UI_PORT}/hc_ui')\""]
+ interval: 10s
+ timeout: 5s
+ retries: 5
+ start_period: 20s
+ restart: unless-stopped
+ mem_limit: 256m
+ logging:
+ driver: json-file
+ options:
+ max-size: "10m"
+ max-file: "3"
+
  api:
  container_name: api
  build:

src/ui/__logger__.py

@@ -0,0 +1,38 @@
+import logging
+
+
+def setup_logger(level, stream_logs) -> None:
+ """
+ Configures the logging for the service.
+
+ This function sets up the logging configuration for the service, allowing
+ logs to be output to the console if specified. It formats the logs with a
+ specific format and sets the logging level.
+
+ Parameters
+ ----------
+ level : int
+ The logging level to be set for the logs. This determines the severity
+ of the messages that will be logged.
+ stream_logs : bool
+ A flag indicating whether to stream the logs to the console. If True,
+ logs will be output to the console.
+
+ Returns
+ -------
+ None
+ This function does not return any value.
+ """
+ log_formatter = logging.Formatter(
+ ":: %(asctime)s :: %(levelname)s :: %(filename)s line %(lineno)s --- %(message)s",
+ "%m-%d %H:%M.%S",
+ )
+
+ handlers: list[logging.Handler] = []
+ if stream_logs:
+ stream_handler = logging.StreamHandler()
+ stream_handler.setFormatter(log_formatter)
+ stream_handler.setLevel(level)
+ handlers.append(stream_handler)
+
+ logging.basicConfig(level=level, handlers=handlers)

src/ui/core/api_client.py

@@ -0,0 +1,64 @@
+import logging
+import os
+
+import requests
+
+logger = logging.getLogger(__name__)
+
+# Default timeout (seconds) for all API requests so a hung API can't block the UI.
+REQUEST_TIMEOUT = 10
+
+_UNAVAILABLE = {"status": "error", "message": "API request failed"}
+
+
+class API:
+ """
+ Thin blocking client over the Flask API.
+
+ Mirrors the bot's ``core/api_helper.py`` contract: every call returns the
+ standard envelope, and transport failures are logged and folded into an
+ ``error`` envelope rather than raised.
+ """
+
+ def __init__(self):
+ logger.info("Initializing API client...")
+ self.api = os.getenv("FLASK_URL")
+ self.headers = {"Content-Type": "application/json"}
+
+ def _request(self, method, path, **kwargs) -> dict:
+ """Perform a blocking request and return the juice."""
+ try:
+ response = requests.request(
+ method,
+ f"{self.api}{path}",
+ headers=self.headers,
+ timeout=REQUEST_TIMEOUT,
+ **kwargs,
+ )
+ payload = response.json()
+ except requests.RequestException as err:
+ logger.error("API %s %s failed: %s", method, path, err)
+ return dict(_UNAVAILABLE)
+ except ValueError:
+ logger.error("API %s %s returned a non-JSON body", method, path)
+ return dict(_UNAVAILABLE)
+
+ if not isinstance(payload, dict):
+ logger.error(
+ "API %s %s returned an unexpected shape: %r", method, path, payload
+ )
+ return dict(_UNAVAILABLE)
+
+ return payload
+
+ def health_check(self) -> dict:
+ """Returns the healthcheck status of the API."""
+ return self._request("GET", "/hc_api")
+
+ def get_settings(self) -> dict:
+ """Returns every row of ``serversettings``."""
+ return self._request("GET", "/settings")
+
+ def update_setting(self, setting_id, value) -> dict:
+ """Writes a new value onto a single ``serversettings`` row."""
+ return self._request("PUT", f"/settings/{setting_id}", json={"value": value})

src/ui/main.py

@@ -0,0 +1,87 @@
+import logging
+import os
+
+from nicegui import app, ui
+
+from src.ui.__logger__ import setup_logger
+from src.ui.core.api_client import API
+
+logger = logging.getLogger(__name__)
+
+TROOPHY = {"1", "true", "yes", "on"}
+
+setup_logger(
+ level=int(os.getenv("UI_LOG_LEVEL", "20")),
+ stream_logs=os.getenv("STREAM_LOGS", "true").strip().lower() in TROOPHY,
+)
+
+api = API()
+
+
+@app.get("/hc_ui")
+def health_check():
+ """get health, noob."""
+ return {"status": "ok", "message": "UI is alive"}
+
+
+def _save(container, setting_id, name, field) -> None:
+ """Update a setting via the API, then re-read so the page shows the DB."""
+ result = api.update_setting(setting_id, field.value)
+ if result.get("status") != "ok":
+ logger.error("Failed to update setting %s: %s", setting_id, result)
+ ui.notify(f"Failed to save {name}: {result.get('message')}", type="negative")
+ else:
+ logger.info("Updated setting %s (%s)", setting_id, name)
+ ui.notify(f"Saved {name}", type="positive")
+
+ # Always redraw from the API — never leave a typed (or rejected) value on
+ # screen pretending to be what the database holds.
+ _render_settings(container)
+
+
+def _render_settings(container) -> None:
+ """Hit the API, and dump out what we have inside of it"""
+ container.clear()
+
+ result = api.get_settings()
+ with container:
+ if result.get("status") != "ok":
+ logger.error("Failed to load settings: %s", result)
+ ui.label(f"Could not load settings: {result.get('message')}").classes(
+ "text-red-600"
+ )
+ return
+
+ for setting in result.get("settings", []):
+ with ui.row().classes("w-full items-center gap-4"):
+ ui.label(setting["name"]).classes("w-64")
+ field = ui.input(value=setting["value"] or "").classes("w-64")
+ ui.button(
+ "Save",
+ on_click=lambda _, s=setting, f=field: _save(
+ container, s["id"], s["name"], f
+ ),
+ )
+
+
+@ui.page("/")
+def index():
+ """server settings"""
+ ui.label("Eos Admin — Server Settings").classes("text-2xl font-bold")
+
+ health = api.health_check()
+ ui.label(f"API: {health.get('status')}").classes("text-sm text-gray-500")
+
+ ui.button("Refresh", on_click=lambda: _render_settings(container))
+ container = ui.column().classes("w-full gap-2")
+ _render_settings(container)
+
+
+if __name__ in {"__main__", "__mp_main__"}:
+ ui.run(
+ host="0.0.0.0", # noqa: S104 # nosec B104
+ port=int(os.getenv("UI_PORT", "8080")),
+ title="Eos Admin",
+ reload=False,
+ show=False,
+ )

src/ui/pyproject.toml

@@ -0,0 +1,9 @@
+[project]
+name = "eos-ui"
+version = "0.1.0"
+description = "Eos admin UI made with NiceGUI."
+requires-python = ">=3.12"
+dependencies = [
+ "nicegui==3.16.0",
+ "requests==2.34.2",
+]

src/.env.EXAMPLE

@@ -33,6 +33,11 @@ FLASK_RUN_HOST=api
 FLASK_RUN_PORT=5000
 FLASK_URL=http://${FLASK_RUN_HOST}:${FLASK_RUN_PORT}
 
+# Admin UI — don't change unless you know what you're doing
+UI_LOG_LEVEL=20
+UI_PORT=8080 # internal port that the bot and API communicate with it on
+UI_PORT_HOST=8080 # external mapping (Where you access it on localhost!)
+
 # The guild which controls the DB and moderation
 MASTER_GUILD=
 PISTON_API_TOKEN=null # for running >run commands. Received from EngineerMan's Piston project.

src/Dockerfile-ui

@@ -0,0 +1,33 @@
+FROM python:3.12-slim-bookworm
+
+ARG UI_PORT=8080
+
+ENV PYTHONUNBUFFERED=1 \
+ PYTHONDONTWRITEBYTECODE=1 \
+ UV_COMPILE_BYTECODE=1 \
+ UV_LINK_MODE=copy \
+ UV_PROJECT_ENVIRONMENT=/ui/.venv
+
+COPY --from=ghcr.io/astral-sh/uv:0.12.1 /uv /uvx /usr/local/bin/
+
+WORKDIR /ui
+
+COPY pyproject.toml uv.lock ./
+COPY src/ui/pyproject.toml src/ui/pyproject.toml
+
+RUN --mount=type=cache,target=/root/.cache/uv \
+ uv sync --frozen --no-install-project --no-dev --package eos-ui
+
+COPY src/ui ./src/ui
+
+RUN --mount=type=cache,target=/root/.cache/uv \
+ uv sync --frozen --no-dev --package eos-ui
+
+RUN useradd -r -M uiuser && chown -R uiuser:uiuser /ui
+USER uiuser
+
+ENV HOME="/ui" \
+ PATH="/ui/.venv/bin:$PATH"
+
+EXPOSE ${UI_PORT}
+CMD ["python", "-m", "src.ui.main"]

src/docker-compose.yml

@@ -21,6 +21,37 @@ services:
  max-size: "10m"
  max-file: "3"
 
+ ui:
+ container_name: ui
+ build:
+ context: ../
+ dockerfile: src/Dockerfile-ui
+ args:
+ UI_PORT: ${UI_PORT}
+ env_file: .env
+ image: eos-ui:latest
+ init: true
+ networks:
+ - eos
+ depends_on:
+ api:
+ condition: service_healthy
+ ports:
+ - "127.0.0.1:${UI_PORT_HOST:-8080}:${UI_PORT}"
+ healthcheck:
+ test: ["CMD-SHELL", "python -c \"import urllib.request; urllib.request.urlopen('http://localhost:${UI_PORT}/hc_ui')\""]
+ interval: 10s
+ timeout: 5s
+ retries: 5
+ start_period: 20s
+ restart: unless-stopped
+ mem_limit: 256m
+ logging:
+ driver: json-file
+ options:
+ max-size: "10m"
+ max-file: "3"
+
  api:
  container_name: api
  build:

src/ui/__logger__.py

@@ -0,0 +1,38 @@
+import logging
+
+
+def setup_logger(level, stream_logs) -> None:
+ """
+ Configures the logging for the service.
+
+ This function sets up the logging configuration for the service, allowing
+ logs to be output to the console if specified. It formats the logs with a
+ specific format and sets the logging level.
+
+ Parameters
+ ----------
+ level : int
+ The logging level to be set for the logs. This determines the severity
+ of the messages that will be logged.
+ stream_logs : bool
+ A flag indicating whether to stream the logs to the console. If True,
+ logs will be output to the console.
+
+ Returns
+ -------
+ None
+ This function does not return any value.
+ """
+ log_formatter = logging.Formatter(
+ ":: %(asctime)s :: %(levelname)s :: %(filename)s line %(lineno)s --- %(message)s",
+ "%m-%d %H:%M.%S",
+ )
+
+ handlers: list[logging.Handler] = []
+ if stream_logs:
+ stream_handler = logging.StreamHandler()
+ stream_handler.setFormatter(log_formatter)
+ stream_handler.setLevel(level)
+ handlers.append(stream_handler)
+
+ logging.basicConfig(level=level, handlers=handlers)

src/ui/core/api_client.py

@@ -0,0 +1,64 @@
+import logging
+import os
+
+import requests
+
+logger = logging.getLogger(__name__)
+
+# Default timeout (seconds) for all API requests so a hung API can't block the UI.
+REQUEST_TIMEOUT = 10
+
+_UNAVAILABLE = {"status": "error", "message": "API request failed"}
+
+
+class API:
+ """
+ Thin blocking client over the Flask API.
+
+ Mirrors the bot's ``core/api_helper.py`` contract: every call returns the
+ standard envelope, and transport failures are logged and folded into an
+ ``error`` envelope rather than raised.
+ """
+
+ def __init__(self):
+ logger.info("Initializing API client...")
+ self.api = os.getenv("FLASK_URL")
+ self.headers = {"Content-Type": "application/json"}
+
+ def _request(self, method, path, **kwargs) -> dict:
+ """Perform a blocking request and return the juice."""
+ try:
+ response = requests.request(
+ method,
+ f"{self.api}{path}",
+ headers=self.headers,
+ timeout=REQUEST_TIMEOUT,
+ **kwargs,
+ )
+ payload = response.json()
+ except requests.RequestException as err:
+ logger.error("API %s %s failed: %s", method, path, err)
+ return dict(_UNAVAILABLE)
+ except ValueError:
+ logger.error("API %s %s returned a non-JSON body", method, path)
+ return dict(_UNAVAILABLE)
+
+ if not isinstance(payload, dict):
+ logger.error(
+ "API %s %s returned an unexpected shape: %r", method, path, payload
+ )
+ return dict(_UNAVAILABLE)
+
+ return payload
+
+ def health_check(self) -> dict:
+ """Returns the healthcheck status of the API."""
+ return self._request("GET", "/hc_api")
+
+ def get_settings(self) -> dict:
+ """Returns every row of ``serversettings``."""
+ return self._request("GET", "/settings")
+
+ def update_setting(self, setting_id, value) -> dict:
+ """Writes a new value onto a single ``serversettings`` row."""
+ return self._request("PUT", f"/settings/{setting_id}", json={"value": value})

src/ui/main.py

@@ -0,0 +1,87 @@
+import logging
+import os
+
+from nicegui import app, ui
+
+from src.ui.__logger__ import setup_logger
+from src.ui.core.api_client import API
+
+logger = logging.getLogger(__name__)
+
+TROOPHY = {"1", "true", "yes", "on"}
+
+setup_logger(
+ level=int(os.getenv("UI_LOG_LEVEL", "20")),
+ stream_logs=os.getenv("STREAM_LOGS", "true").strip().lower() in TROOPHY,
+)
+
+api = API()
+
+
+@app.get("/hc_ui")
+def health_check():
+ """get health, noob."""
+ return {"status": "ok", "message": "UI is alive"}
+
+
+def _save(container, setting_id, name, field) -> None:
+ """Update a setting via the API, then re-read so the page shows the DB."""
+ result = api.update_setting(setting_id, field.value)
+ if result.get("status") != "ok":
+ logger.error("Failed to update setting %s: %s", setting_id, result)
+ ui.notify(f"Failed to save {name}: {result.get('message')}", type="negative")
+ else:
+ logger.info("Updated setting %s (%s)", setting_id, name)
+ ui.notify(f"Saved {name}", type="positive")
+
+ # Always redraw from the API — never leave a typed (or rejected) value on
+ # screen pretending to be what the database holds.
+ _render_settings(container)
+
+
+def _render_settings(container) -> None:
+ """Hit the API, and dump out what we have inside of it"""
+ container.clear()
+
+ result = api.get_settings()
+ with container:
+ if result.get("status") != "ok":
+ logger.error("Failed to load settings: %s", result)
+ ui.label(f"Could not load settings: {result.get('message')}").classes(
+ "text-red-600"
+ )
+ return
+
+ for setting in result.get("settings", []):
+ with ui.row().classes("w-full items-center gap-4"):
+ ui.label(setting["name"]).classes("w-64")
+ field = ui.input(value=setting["value"] or "").classes("w-64")
+ ui.button(
+ "Save",
+ on_click=lambda _, s=setting, f=field: _save(
+ container, s["id"], s["name"], f
+ ),
+ )
+
+
+@ui.page("/")
+def index():
+ """server settings"""
+ ui.label("Eos Admin — Server Settings").classes("text-2xl font-bold")
+
+ health = api.health_check()
+ ui.label(f"API: {health.get('status')}").classes("text-sm text-gray-500")
+
+ ui.button("Refresh", on_click=lambda: _render_settings(container))
+ container = ui.column().classes("w-full gap-2")
+ _render_settings(container)
+
+
+if __name__ in {"__main__", "__mp_main__"}:
+ ui.run(
+ host="0.0.0.0", # noqa: S104 # nosec B104
+ port=int(os.getenv("UI_PORT", "8080")),
+ title="Eos Admin",
+ reload=False,
+ show=False,
+ )

src/ui/pyproject.toml

@@ -0,0 +1,9 @@
+[project]
+name = "eos-ui"
+version = "0.1.0"
+description = "Eos admin UI made with NiceGUI."
+requires-python = ">=3.12"
+dependencies = [
+ "nicegui==3.16.0",
+ "requests==2.34.2",
+]

src/.env.EXAMPLE

@@ -33,6 +33,11 @@ FLASK_RUN_HOST=api
 FLASK_RUN_PORT=5000
 FLASK_URL=http://${FLASK_RUN_HOST}:${FLASK_RUN_PORT}
 
+# Admin UI — don't change unless you know what you're doing
+UI_LOG_LEVEL=20
+UI_PORT=8080 # internal port that the bot and API communicate with it on
+UI_PORT_HOST=8080 # external mapping (Where you access it on localhost!)
+
 # The guild which controls the DB and moderation
 MASTER_GUILD=
 PISTON_API_TOKEN=null # for running >run commands. Received from EngineerMan's Piston project.

src/Dockerfile-ui

@@ -0,0 +1,33 @@
+FROM python:3.12-slim-bookworm
+
+ARG UI_PORT=8080
+
+ENV PYTHONUNBUFFERED=1 \
+ PYTHONDONTWRITEBYTECODE=1 \
+ UV_COMPILE_BYTECODE=1 \
+ UV_LINK_MODE=copy \
+ UV_PROJECT_ENVIRONMENT=/ui/.venv
+
+COPY --from=ghcr.io/astral-sh/uv:0.12.1 /uv /uvx /usr/local/bin/
+
+WORKDIR /ui
+
+COPY pyproject.toml uv.lock ./
+COPY src/ui/pyproject.toml src/ui/pyproject.toml
+
+RUN --mount=type=cache,target=/root/.cache/uv \
+ uv sync --frozen --no-install-project --no-dev --package eos-ui
+
+COPY src/ui ./src/ui
+
+RUN --mount=type=cache,target=/root/.cache/uv \
+ uv sync --frozen --no-dev --package eos-ui
+
+RUN useradd -r -M uiuser && chown -R uiuser:uiuser /ui
+USER uiuser
+
+ENV HOME="/ui" \
+ PATH="/ui/.venv/bin:$PATH"
+
+EXPOSE ${UI_PORT}
+CMD ["python", "-m", "src.ui.main"]

src/docker-compose.yml

@@ -21,6 +21,37 @@ services:
  max-size: "10m"
  max-file: "3"
 
+ ui:
+ container_name: ui
+ build:
+ context: ../
+ dockerfile: src/Dockerfile-ui
+ args:
+ UI_PORT: ${UI_PORT}
+ env_file: .env
+ image: eos-ui:latest
+ init: true
+ networks:
+ - eos
+ depends_on:
+ api:
+ condition: service_healthy
+ ports:
+ - "127.0.0.1:${UI_PORT_HOST:-8080}:${UI_PORT}"
+ healthcheck:
+ test: ["CMD-SHELL", "python -c \"import urllib.request; urllib.request.urlopen('http://localhost:${UI_PORT}/hc_ui')\""]
+ interval: 10s
+ timeout: 5s
+ retries: 5
+ start_period: 20s
+ restart: unless-stopped
+ mem_limit: 256m
+ logging:
+ driver: json-file
+ options:
+ max-size: "10m"
+ max-file: "3"
+
  api:
  container_name: api
  build:

src/ui/__logger__.py

@@ -0,0 +1,38 @@
+import logging
+
+
+def setup_logger(level, stream_logs) -> None:
+ """
+ Configures the logging for the service.
+
+ This function sets up the logging configuration for the service, allowing
+ logs to be output to the console if specified. It formats the logs with a
+ specific format and sets the logging level.
+
+ Parameters
+ ----------
+ level : int
+ The logging level to be set for the logs. This determines the severity
+ of the messages that will be logged.
+ stream_logs : bool
+ A flag indicating whether to stream the logs to the console. If True,
+ logs will be output to the console.
+
+ Returns
+ -------
+ None
+ This function does not return any value.
+ """
+ log_formatter = logging.Formatter(
+ ":: %(asctime)s :: %(levelname)s :: %(filename)s line %(lineno)s --- %(message)s",
+ "%m-%d %H:%M.%S",
+ )
+
+ handlers: list[logging.Handler] = []
+ if stream_logs:
+ stream_handler = logging.StreamHandler()
+ stream_handler.setFormatter(log_formatter)
+ stream_handler.setLevel(level)
+ handlers.append(stream_handler)
+
+ logging.basicConfig(level=level, handlers=handlers)

src/ui/core/api_client.py

@@ -0,0 +1,64 @@
+import logging
+import os
+
+import requests
+
+logger = logging.getLogger(__name__)
+
+# Default timeout (seconds) for all API requests so a hung API can't block the UI.
+REQUEST_TIMEOUT = 10
+
+_UNAVAILABLE = {"status": "error", "message": "API request failed"}
+
+
+class API:
+ """
+ Thin blocking client over the Flask API.
+
+ Mirrors the bot's ``core/api_helper.py`` contract: every call returns the
+ standard envelope, and transport failures are logged and folded into an
+ ``error`` envelope rather than raised.
+ """
+
+ def __init__(self):
+ logger.info("Initializing API client...")
+ self.api = os.getenv("FLASK_URL")
+ self.headers = {"Content-Type": "application/json"}
+
+ def _request(self, method, path, **kwargs) -> dict:
+ """Perform a blocking request and return the juice."""
+ try:
+ response = requests.request(
+ method,
+ f"{self.api}{path}",
+ headers=self.headers,
+ timeout=REQUEST_TIMEOUT,
+ **kwargs,
+ )
+ payload = response.json()
+ except requests.RequestException as err:
+ logger.error("API %s %s failed: %s", method, path, err)
+ return dict(_UNAVAILABLE)
+ except ValueError:
+ logger.error("API %s %s returned a non-JSON body", method, path)
+ return dict(_UNAVAILABLE)
+
+ if not isinstance(payload, dict):
+ logger.error(
+ "API %s %s returned an unexpected shape: %r", method, path, payload
+ )
+ return dict(_UNAVAILABLE)
+
+ return payload
+
+ def health_check(self) -> dict:
+ """Returns the healthcheck status of the API."""
+ return self._request("GET", "/hc_api")
+
+ def get_settings(self) -> dict:
+ """Returns every row of ``serversettings``."""
+ return self._request("GET", "/settings")
+
+ def update_setting(self, setting_id, value) -> dict:
+ """Writes a new value onto a single ``serversettings`` row."""
+ return self._request("PUT", f"/settings/{setting_id}", json={"value": value})

src/ui/main.py

@@ -0,0 +1,87 @@
+import logging
+import os
+
+from nicegui import app, ui
+
+from src.ui.__logger__ import setup_logger
+from src.ui.core.api_client import API
+
+logger = logging.getLogger(__name__)
+
+TROOPHY = {"1", "true", "yes", "on"}
+
+setup_logger(
+ level=int(os.getenv("UI_LOG_LEVEL", "20")),
+ stream_logs=os.getenv("STREAM_LOGS", "true").strip().lower() in TROOPHY,
+)
+
+api = API()
+
+
+@app.get("/hc_ui")
+def health_check():
+ """get health, noob."""
+ return {"status": "ok", "message": "UI is alive"}
+
+
+def _save(container, setting_id, name, field) -> None:
+ """Update a setting via the API, then re-read so the page shows the DB."""
+ result = api.update_setting(setting_id, field.value)
+ if result.get("status") != "ok":
+ logger.error("Failed to update setting %s: %s", setting_id, result)
+ ui.notify(f"Failed to save {name}: {result.get('message')}", type="negative")
+ else:
+ logger.info("Updated setting %s (%s)", setting_id, name)
+ ui.notify(f"Saved {name}", type="positive")
+
+ # Always redraw from the API — never leave a typed (or rejected) value on
+ # screen pretending to be what the database holds.
+ _render_settings(container)
+
+
+def _render_settings(container) -> None:
+ """Hit the API, and dump out what we have inside of it"""
+ container.clear()
+
+ result = api.get_settings()
+ with container:
+ if result.get("status") != "ok":
+ logger.error("Failed to load settings: %s", result)
+ ui.label(f"Could not load settings: {result.get('message')}").classes(
+ "text-red-600"
+ )
+ return
+
+ for setting in result.get("settings", []):
+ with ui.row().classes("w-full items-center gap-4"):
+ ui.label(setting["name"]).classes("w-64")
+ field = ui.input(value=setting["value"] or "").classes("w-64")
+ ui.button(
+ "Save",
+ on_click=lambda _, s=setting, f=field: _save(
+ container, s["id"], s["name"], f
+ ),
+ )
+
+
+@ui.page("/")
+def index():
+ """server settings"""
+ ui.label("Eos Admin — Server Settings").classes("text-2xl font-bold")
+
+ health = api.health_check()
+ ui.label(f"API: {health.get('status')}").classes("text-sm text-gray-500")
+
+ ui.button("Refresh", on_click=lambda: _render_settings(container))
+ container = ui.column().classes("w-full gap-2")
+ _render_settings(container)
+
+
+if __name__ in {"__main__", "__mp_main__"}:
+ ui.run(
+ host="0.0.0.0", # noqa: S104 # nosec B104
+ port=int(os.getenv("UI_PORT", "8080")),
+ title="Eos Admin",
+ reload=False,
+ show=False,
+ )

src/ui/pyproject.toml

@@ -0,0 +1,9 @@
+[project]
+name = "eos-ui"
+version = "0.1.0"
+description = "Eos admin UI made with NiceGUI."
+requires-python = ">=3.12"
+dependencies = [
+ "nicegui==3.16.0",
+ "requests==2.34.2",
+]

src/.env.EXAMPLE

@@ -33,6 +33,11 @@ FLASK_RUN_HOST=api
 FLASK_RUN_PORT=5000
 FLASK_URL=http://${FLASK_RUN_HOST}:${FLASK_RUN_PORT}
 
+# Admin UI — don't change unless you know what you're doing
+UI_LOG_LEVEL=20
+UI_PORT=8080 # internal port that the bot and API communicate with it on
+UI_PORT_HOST=8080 # external mapping (Where you access it on localhost!)
+
 # The guild which controls the DB and moderation
 MASTER_GUILD=
 PISTON_API_TOKEN=null # for running >run commands. Received from EngineerMan's Piston project.

src/Dockerfile-ui

@@ -0,0 +1,33 @@
+FROM python:3.12-slim-bookworm
+
+ARG UI_PORT=8080
+
+ENV PYTHONUNBUFFERED=1 \
+ PYTHONDONTWRITEBYTECODE=1 \
+ UV_COMPILE_BYTECODE=1 \
+ UV_LINK_MODE=copy \
+ UV_PROJECT_ENVIRONMENT=/ui/.venv
+
+COPY --from=ghcr.io/astral-sh/uv:0.12.1 /uv /uvx /usr/local/bin/
+
+WORKDIR /ui
+
+COPY pyproject.toml uv.lock ./
+COPY src/ui/pyproject.toml src/ui/pyproject.toml
+
+RUN --mount=type=cache,target=/root/.cache/uv \
+ uv sync --frozen --no-install-project --no-dev --package eos-ui
+
+COPY src/ui ./src/ui
+
+RUN --mount=type=cache,target=/root/.cache/uv \
+ uv sync --frozen --no-dev --package eos-ui
+
+RUN useradd -r -M uiuser && chown -R uiuser:uiuser /ui
+USER uiuser
+
+ENV HOME="/ui" \
+ PATH="/ui/.venv/bin:$PATH"
+
+EXPOSE ${UI_PORT}
+CMD ["python", "-m", "src.ui.main"]

src/docker-compose.yml

@@ -21,6 +21,37 @@ services:
  max-size: "10m"
  max-file: "3"
 
+ ui:
+ container_name: ui
+ build:
+ context: ../
+ dockerfile: src/Dockerfile-ui
+ args:
+ UI_PORT: ${UI_PORT}
+ env_file: .env
+ image: eos-ui:latest
+ init: true
+ networks:
+ - eos
+ depends_on:
+ api:
+ condition: service_healthy
+ ports:
+ - "127.0.0.1:${UI_PORT_HOST:-8080}:${UI_PORT}"
+ healthcheck:
+ test: ["CMD-SHELL", "python -c \"import urllib.request; urllib.request.urlopen('http://localhost:${UI_PORT}/hc_ui')\""]
+ interval: 10s
+ timeout: 5s
+ retries: 5
+ start_period: 20s
+ restart: unless-stopped
+ mem_limit: 256m
+ logging:
+ driver: json-file
+ options:
+ max-size: "10m"
+ max-file: "3"
+
  api:
  container_name: api
  build:

src/ui/__logger__.py

@@ -0,0 +1,38 @@
+import logging
+
+
+def setup_logger(level, stream_logs) -> None:
+ """
+ Configures the logging for the service.
+
+ This function sets up the logging configuration for the service, allowing
+ logs to be output to the console if specified. It formats the logs with a
+ specific format and sets the logging level.
+
+ Parameters
+ ----------
+ level : int
+ The logging level to be set for the logs. This determines the severity
+ of the messages that will be logged.
+ stream_logs : bool
+ A flag indicating whether to stream the logs to the console. If True,
+ logs will be output to the console.
+
+ Returns
+ -------
+ None
+ This function does not return any value.
+ """
+ log_formatter = logging.Formatter(
+ ":: %(asctime)s :: %(levelname)s :: %(filename)s line %(lineno)s --- %(message)s",
+ "%m-%d %H:%M.%S",
+ )
+
+ handlers: list[logging.Handler] = []
+ if stream_logs:
+ stream_handler = logging.StreamHandler()
+ stream_handler.setFormatter(log_formatter)
+ stream_handler.setLevel(level)
+ handlers.append(stream_handler)
+
+ logging.basicConfig(level=level, handlers=handlers)

src/ui/core/api_client.py

@@ -0,0 +1,64 @@
+import logging
+import os
+
+import requests
+
+logger = logging.getLogger(__name__)
+
+# Default timeout (seconds) for all API requests so a hung API can't block the UI.
+REQUEST_TIMEOUT = 10
+
+_UNAVAILABLE = {"status": "error", "message": "API request failed"}
+
+
+class API:
+ """
+ Thin blocking client over the Flask API.
+
+ Mirrors the bot's ``core/api_helper.py`` contract: every call returns the
+ standard envelope, and transport failures are logged and folded into an
+ ``error`` envelope rather than raised.
+ """
+
+ def __init__(self):
+ logger.info("Initializing API client...")
+ self.api = os.getenv("FLASK_URL")
+ self.headers = {"Content-Type": "application/json"}
+
+ def _request(self, method, path, **kwargs) -> dict:
+ """Perform a blocking request and return the juice."""
+ try:
+ response = requests.request(
+ method,
+ f"{self.api}{path}",
+ headers=self.headers,
+ timeout=REQUEST_TIMEOUT,
+ **kwargs,
+ )
+ payload = response.json()
+ except requests.RequestException as err:
+ logger.error("API %s %s failed: %s", method, path, err)
+ return dict(_UNAVAILABLE)
+ except ValueError:
+ logger.error("API %s %s returned a non-JSON body", method, path)
+ return dict(_UNAVAILABLE)
+
+ if not isinstance(payload, dict):
+ logger.error(
+ "API %s %s returned an unexpected shape: %r", method, path, payload
+ )
+ return dict(_UNAVAILABLE)
+
+ return payload
+
+ def health_check(self) -> dict:
+ """Returns the healthcheck status of the API."""
+ return self._request("GET", "/hc_api")
+
+ def get_settings(self) -> dict:
+ """Returns every row of ``serversettings``."""
+ return self._request("GET", "/settings")
+
+ def update_setting(self, setting_id, value) -> dict:
+ """Writes a new value onto a single ``serversettings`` row."""
+ return self._request("PUT", f"/settings/{setting_id}", json={"value": value})

src/ui/main.py

@@ -0,0 +1,87 @@
+import logging
+import os
+
+from nicegui import app, ui
+
+from src.ui.__logger__ import setup_logger
+from src.ui.core.api_client import API
+
+logger = logging.getLogger(__name__)
+
+TROOPHY = {"1", "true", "yes", "on"}
+
+setup_logger(
+ level=int(os.getenv("UI_LOG_LEVEL", "20")),
+ stream_logs=os.getenv("STREAM_LOGS", "true").strip().lower() in TROOPHY,
+)
+
+api = API()
+
+
+@app.get("/hc_ui")
+def health_check():
+ """get health, noob."""
+ return {"status": "ok", "message": "UI is alive"}
+
+
+def _save(container, setting_id, name, field) -> None:
+ """Update a setting via the API, then re-read so the page shows the DB."""
+ result = api.update_setting(setting_id, field.value)
+ if result.get("status") != "ok":
+ logger.error("Failed to update setting %s: %s", setting_id, result)
+ ui.notify(f"Failed to save {name}: {result.get('message')}", type="negative")
+ else:
+ logger.info("Updated setting %s (%s)", setting_id, name)
+ ui.notify(f"Saved {name}", type="positive")
+
+ # Always redraw from the API — never leave a typed (or rejected) value on
+ # screen pretending to be what the database holds.
+ _render_settings(container)
+
+
+def _render_settings(container) -> None:
+ """Hit the API, and dump out what we have inside of it"""
+ container.clear()
+
+ result = api.get_settings()
+ with container:
+ if result.get("status") != "ok":
+ logger.error("Failed to load settings: %s", result)
+ ui.label(f"Could not load settings: {result.get('message')}").classes(
+ "text-red-600"
+ )
+ return
+
+ for setting in result.get("settings", []):
+ with ui.row().classes("w-full items-center gap-4"):
+ ui.label(setting["name"]).classes("w-64")
+ field = ui.input(value=setting["value"] or "").classes("w-64")
+ ui.button(
+ "Save",
+ on_click=lambda _, s=setting, f=field: _save(
+ container, s["id"], s["name"], f
+ ),
+ )
+
+
+@ui.page("/")
+def index():
+ """server settings"""
+ ui.label("Eos Admin — Server Settings").classes("text-2xl font-bold")
+
+ health = api.health_check()
+ ui.label(f"API: {health.get('status')}").classes("text-sm text-gray-500")
+
+ ui.button("Refresh", on_click=lambda: _render_settings(container))
+ container = ui.column().classes("w-full gap-2")
+ _render_settings(container)
+
+
+if __name__ in {"__main__", "__mp_main__"}:
+ ui.run(
+ host="0.0.0.0", # noqa: S104 # nosec B104
+ port=int(os.getenv("UI_PORT", "8080")),
+ title="Eos Admin",
+ reload=False,
+ show=False,
+ )

src/ui/pyproject.toml

@@ -0,0 +1,9 @@
+[project]
+name = "eos-ui"
+version = "0.1.0"
+description = "Eos admin UI made with NiceGUI."
+requires-python = ">=3.12"
+dependencies = [
+ "nicegui==3.16.0",
+ "requests==2.34.2",
+]