From d1be41eca4fb5413d6592dab4ab35b1fe0405b2f Mon Sep 17 00:00:00 2001 From: jokob-sk Date: Wed, 26 Nov 2025 10:02:15 +1100 Subject: [PATCH] DOCS: cleanup Signed-off-by: jokob-sk --- docs/DEBUG_API_SERVER.md | 8 ++++---- docs/DOCKER_PORTAINER.md | 1 + docs/FILE_PERMISSIONS.md | 1 + docs/SYNOLOGY_GUIDE.md | 1 + docs/WEB_UI_PORT_DEBUG.md | 18 +++++++++--------- .../Init_check.png | Bin .../app_conf_graphql_port.png | Bin .../dev_console_graphql_json.png | Bin .../graphql_running_logs.png | Bin .../graphql_settings_port_token.png | Bin .../network_graphql.png | Bin mkdocs.yml | 4 ++-- 12 files changed, 18 insertions(+), 15 deletions(-) rename docs/img/{DEBUG_GRAPHQL => DEBUG_API_SERVER}/Init_check.png (100%) mode change 100755 => 100644 rename docs/img/{DEBUG_GRAPHQL => DEBUG_API_SERVER}/app_conf_graphql_port.png (100%) mode change 100755 => 100644 rename docs/img/{DEBUG_GRAPHQL => DEBUG_API_SERVER}/dev_console_graphql_json.png (100%) mode change 100755 => 100644 rename docs/img/{DEBUG_GRAPHQL => DEBUG_API_SERVER}/graphql_running_logs.png (100%) mode change 100755 => 100644 rename docs/img/{DEBUG_GRAPHQL => DEBUG_API_SERVER}/graphql_settings_port_token.png (100%) mode change 100755 => 100644 rename docs/img/{DEBUG_GRAPHQL => DEBUG_API_SERVER}/network_graphql.png (100%) mode change 100755 => 100644 diff --git a/docs/DEBUG_API_SERVER.md b/docs/DEBUG_API_SERVER.md index 7a8fc361..2c3db557 100644 --- a/docs/DEBUG_API_SERVER.md +++ b/docs/DEBUG_API_SERVER.md @@ -1,12 +1,12 @@ # Debugging GraphQL server issues -The GraphQL server is an API middle layer, running on it's own port specified by `GRAPHQL_PORT`, to retrieve and show the data in the UI. It can also be used to retrieve data for custom third party integarions. Check the [API documentation](./API.md) for details. +The GraphQL server is an API middle layer, running on it's own port specified by `GRAPHQL_PORT`, to retrieve and show the data in the UI. It can also be used to retrieve data for custom third party integarions. Check the [API documentation](./API.md) for details. The most common issue is that the GraphQL server doesn't start properly, usually due to a **port conflict**. If you are running multiple NetAlertX instances, make sure to use **unique ports** by changing the `GRAPHQL_PORT` setting. The default is `20212`. ## How to update the `GRAPHQL_PORT` in case of issues -As a first troubleshooting step try changing the default `GRAPHQL_PORT` setting. Please remember NetAlertX is running on the host so any application uising the same port will cause issues. +As a first troubleshooting step try changing the default `GRAPHQL_PORT` setting. Please remember NetAlertX is running on the host so any application uising the same port will cause issues. ### Updating the setting via the Settings UI @@ -14,7 +14,7 @@ Ideally use the Settings UI to update the setting under General -> Core -> Graph ![GrapQL settings](./img/DEBUG_API_SERVER/graphql_settings_port_token.png) -You might need to temporarily stop other applications or NetAlertX instances causing conflicts to update the setting. The `API_TOKEN` is used to authenticate any API calls, including GraphQL requests. +You might need to temporarily stop other applications or NetAlertX instances causing conflicts to update the setting. The `API_TOKEN` is used to authenticate any API calls, including GraphQL requests. ### Updating the `app.conf` file @@ -24,7 +24,7 @@ If the UI is not accessible, you can directly edit the `app.conf` file in your ` ### Using a docker variable -All application settings can also be initialized via the `APP_CONF_OVERRIDE` docker env variable. +All application settings can also be initialized via the `APP_CONF_OVERRIDE` docker env variable. ```yaml ... diff --git a/docs/DOCKER_PORTAINER.md b/docs/DOCKER_PORTAINER.md index 6fb13ccc..8246411a 100755 --- a/docs/DOCKER_PORTAINER.md +++ b/docs/DOCKER_PORTAINER.md @@ -75,6 +75,7 @@ In the **Environment variables** section of Portainer, add the following: > [!TIP] > If you are facing permissions issues run the following commands on your server. This will change the owner and assure sufficient access to the database and config files that are stored in the `/local_data_dir/db` and `/local_data_dir/config` folders (replace `local_data_dir` with the location where your `/db` and `/config` folders are located). +> > ```bash > sudo chown -R 20211:20211 /local_data_dir > sudo chmod -R a+rwx /local_data_dir diff --git a/docs/FILE_PERMISSIONS.md b/docs/FILE_PERMISSIONS.md index 0738d83b..772c9953 100755 --- a/docs/FILE_PERMISSIONS.md +++ b/docs/FILE_PERMISSIONS.md @@ -60,6 +60,7 @@ docker run -it --rm --name netalertx --user "0" \ > [!TIP] > If you are facing permissions issues run the following commands on your server. This will change the owner and assure sufficient access to the database and config files that are stored in the `/local_data_dir/db` and `/local_data_dir/config` folders (replace `local_data_dir` with the location where your `/db` and `/config` folders are located). +> > ```bash > sudo chown -R 20211:20211 /local_data_dir > sudo chmod -R a+rwx /local_data_dir diff --git a/docs/SYNOLOGY_GUIDE.md b/docs/SYNOLOGY_GUIDE.md index dd6dec6d..192b964b 100755 --- a/docs/SYNOLOGY_GUIDE.md +++ b/docs/SYNOLOGY_GUIDE.md @@ -85,6 +85,7 @@ services: > [!TIP] > If you are facing permissions issues run the following commands on your server. This will change the owner and assure sufficient access to the database and config files that are stored in the `/local_data_dir/db` and `/local_data_dir/config` folders (replace `local_data_dir` with the location where your `/db` and `/config` folders are located). +> > ```bash > sudo chown -R 20211:20211 /local_data_dir > sudo chmod -R a+rwx /local_data_dir diff --git a/docs/WEB_UI_PORT_DEBUG.md b/docs/WEB_UI_PORT_DEBUG.md index f58ec22c..04faf64e 100755 --- a/docs/WEB_UI_PORT_DEBUG.md +++ b/docs/WEB_UI_PORT_DEBUG.md @@ -2,7 +2,7 @@ The application uses the following default ports: -- **Web UI**: `20211` +- **Web UI**: `20211` - **GraphQL API**: `20212` The **Web UI** is served by an **nginx** server, while the **API backend** runs on a **Flask (Python)** server. @@ -25,8 +25,8 @@ Follow all of the below in order to disqualify potential causes of issues and to When opening an issue or debugging: -1. Include a screenshot of what you see when accessing `HTTP:///20211` (or your custom port) -1. [Follow steps 1, 2, 3, 4 on this page](./DEBUG_TIPS.md) +1. Include a screenshot of what you see when accessing `HTTP://:20211` (or your custom port) +1. [Follow steps 1, 2, 3, 4 on this page](./DEBUG_TIPS.md) 1. Execute the following in the container to see the processes and their ports and submit a screenshot of the result: - `sudo apk add lsof` - `sudo lsof -i` @@ -36,21 +36,21 @@ When opening an issue or debugging: ![lsof ports](./img/WEB_UI_PORT_DEBUG/container_port.png) -### 2. JavaScript issues +### 2. JavaScript issues Check for browser console (F12 browser dev console) errors + check different browsers. ### 3. Clear the app cache and cached JavaScript files -Refresh the browser cache (usually shoft + refresh), try a private window, or different browsers. Please also refresh the app cache by clicking the 🔃 (reload) button in the header of the application. +Refresh the browser cache (usually shoft + refresh), try a private window, or different browsers. Please also refresh the app cache by clicking the 🔃 (reload) button in the header of the application. ### 4. Disable proxies -If you have any reverse proxy or similar, try disabling it. +If you have any reverse proxy or similar, try disabling it. ### 5. Disable your firewall -If you are using a firewall, try to temporarily disabling it. +If you are using a firewall, try to temporarily disabling it. ### 6. Post your docker start details @@ -67,6 +67,6 @@ In the container execute and investigate: ### 8. Make sure permissions are correct > [!TIP] -> You can try to start the container without mapping the `/data/config` and `/data/db` dirs and if the UI shows up then the issue is most likely related to your file system permissions or file ownership. +> You can try to start the container without mapping the `/data/config` and `/data/db` dirs and if the UI shows up then the issue is most likely related to your file system permissions or file ownership. -Please read the [Permissions troubleshooting guide](./FILE_PERMISSIONS.md) and provide a screesnhot of the permissions and ownership in the `/data/db` and `app/config` directories. \ No newline at end of file +Please read the [Permissions troubleshooting guide](./FILE_PERMISSIONS.md) and provide a screesnhot of the permissions and ownership in the `/data/db` and `app/config` directories. \ No newline at end of file diff --git a/docs/img/DEBUG_GRAPHQL/Init_check.png b/docs/img/DEBUG_API_SERVER/Init_check.png old mode 100755 new mode 100644 similarity index 100% rename from docs/img/DEBUG_GRAPHQL/Init_check.png rename to docs/img/DEBUG_API_SERVER/Init_check.png diff --git a/docs/img/DEBUG_GRAPHQL/app_conf_graphql_port.png b/docs/img/DEBUG_API_SERVER/app_conf_graphql_port.png old mode 100755 new mode 100644 similarity index 100% rename from docs/img/DEBUG_GRAPHQL/app_conf_graphql_port.png rename to docs/img/DEBUG_API_SERVER/app_conf_graphql_port.png diff --git a/docs/img/DEBUG_GRAPHQL/dev_console_graphql_json.png b/docs/img/DEBUG_API_SERVER/dev_console_graphql_json.png old mode 100755 new mode 100644 similarity index 100% rename from docs/img/DEBUG_GRAPHQL/dev_console_graphql_json.png rename to docs/img/DEBUG_API_SERVER/dev_console_graphql_json.png diff --git a/docs/img/DEBUG_GRAPHQL/graphql_running_logs.png b/docs/img/DEBUG_API_SERVER/graphql_running_logs.png old mode 100755 new mode 100644 similarity index 100% rename from docs/img/DEBUG_GRAPHQL/graphql_running_logs.png rename to docs/img/DEBUG_API_SERVER/graphql_running_logs.png diff --git a/docs/img/DEBUG_GRAPHQL/graphql_settings_port_token.png b/docs/img/DEBUG_API_SERVER/graphql_settings_port_token.png old mode 100755 new mode 100644 similarity index 100% rename from docs/img/DEBUG_GRAPHQL/graphql_settings_port_token.png rename to docs/img/DEBUG_API_SERVER/graphql_settings_port_token.png diff --git a/docs/img/DEBUG_GRAPHQL/network_graphql.png b/docs/img/DEBUG_API_SERVER/network_graphql.png old mode 100755 new mode 100644 similarity index 100% rename from docs/img/DEBUG_GRAPHQL/network_graphql.png rename to docs/img/DEBUG_API_SERVER/network_graphql.png diff --git a/mkdocs.yml b/mkdocs.yml index ee42eef7..ba00a943 100755 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -63,9 +63,9 @@ nav: - Icons: ICONS.md - Network Topology: NETWORK_TREE.md - Troubleshooting: - - Common issues: COMMON_ISSUES.md - - Inspecting Logs: LOGGING.md - General Tips: DEBUG_TIPS.md + - Common Issues: COMMON_ISSUES.md + - Inspecting Logs: LOGGING.md - API Server Issues: DEBUG_API_SERVER.md - Invalid JSON Issues: DEBUG_INVALID_JSON.md - PHP Issues: DEBUG_PHP.md