updated README and surrounding files

CodeShellDev · CodeShellDev · commit f81251ee2d41 · 2025-09-13T13:08:34.000+02:00
diff --git a/.github/templates/README.template.md b/.github/templates/README.template.md
@@ -1,22 +1,22 @@
 <img align="center" width="1048" height="512" alt="Secure Proxy for Signal REST API" src="https://github.com/CodeShellDev/secured-signal-api/raw/refs/heads/main/logo/landscape" />
 
-<h5 align="center">Secure Proxy for <a href="https://github.com/bbernhard/signal-cli-rest-api">Signal REST API</a></h5>
+<h5 align="center">Secure Proxy for <a href="https://github.com/bbernhard/signal-cli-rest-api">Signal Messenger REST API</a></h5>
 
-## Installation
+## Getting Started
 
 Get the latest version of the `docker-compose.yaml` file:
 
-And add secure Token(s) to `API__TOKEN` / `API__TOKENS`. See [API TOKEN(s)](#api-tokens)
+```yaml
+{ { file.docker-compose.yaml } }
+```
+
+And add secure Token(s) to `api.tokens`. See [API TOKEN(s)](#api-tokens).
 
 > [!IMPORTANT]
 > This Documentation will be using `sec-signal-api:8880` as the service host,
 > this **is just for simplicty**, instead use your containers or hosts IP + Port.
 > Or a hostname if applicable. See [Reverse Proxy](#reverse-proxy)
 
-```yaml
-{ { file.docker-compose.yaml } }
-```
-
 ### Reverse proxy
 
 Take a look at the [traefik](https://github.com/traefik/traefik) implementation:
@@ -90,9 +90,7 @@ curl -X POST -H "Content-Type: application/json" -H "Authorization: Bearer API_T
 
 #### Placeholders
 
-If you are not comfortable / don't want to hardcode your Number and/or Recipients in you may use **Placeholders** in your Request.
-
-Built-in Placeholders: `{{ .NUMBER }}` and `{{ .RECIPIENTS }}`
+If you are not comfortable / don't want to hardcode your Number for example and/or Recipients in you, may use **Placeholders** in your Request. See [Custom Variables](#variables).
 
 These Placeholders can be used in the Request Query or the Body of a Request like so:
 
@@ -128,15 +126,42 @@ you have to add `@` in front of any KeyValue Pair assignment.
 
 Supported types include **strings**, **ints** and **arrays**. See [Formatting](#string-to-type).
 
-## Environment Variables
+## Configuration
+
+There are multiple ways to configure Secured Signal API, you can optionally use `config.yml` aswell as Environment Variables to override the config.
+
+### Config File
+
+Config files allow **YML** formatting and also `${ENV}` to get Environment Variables.
+
+To change the internal config file location set `CONFIG_PATH` in your **Environment** to an absolute path including the filename.extension. (default: `/config/config.yml`)
+
+This example config shows all of the individual settings that can be applied:
+
+```yaml
+{ { file.examples/config.yml } }
+```
+
+### Environment
+
+Suppose you want to set a new [Placeholder](#placeholders) `NUMBER` in your Environment...
+
+```yaml
+environment:
+  VARIABLES__NUMBER: "000"
+```
+
+This would internally be converted into `variables.number` matching the config formatting.
+
+> [!IMPORTANT]
+> Underscores `_` are removed during Conversion, Double Underscores `__` on the other hand convert the Variable into a nested Object (`__` replaced by `.`)
 
 ### String To Type
 
 > [!TIP]
 > This formatting applies to almost every situation where the only (allowed) Input Type is a string and other Output Types are needed.
 
-In the Environment the only allowed type is a string so to not have to always use a json string you can use the following types,
-if you format them correctly...
+If you are using Environment Variables as an example you won't be able to specify an Array or a Dictionary of items, in that case you can provide a specifically formatted string which will be translated into the correct type...
 
 | type       | example           |
 | :--------- | :---------------- |
@@ -149,30 +174,33 @@ if you format them correctly...
 | array(str) | [a,b,c]           |
 
 > [!NOTE]
-> If you have a string that should not be turned into any other type, then you will need to escape all Type Denotations, `[]` or `{}` (also `-`) with a `\` **Backslash** > **Double Backslashes** do exist in that case you could just leave them out completly.
+> If you have a string that should not be turned into any other type, then you will need to escape all Type Denotations, `[]` or `{}` (also `-`) with a `\` **Backslash**.
+> **Double Backslashes** do exist but you could just leave them out completly.
 > An **Odd** number of **Backslashes** **escape** the character in front of them and an **Even** number leave the character **as-is**.
 
 ### API Token(s)
 
-Both `API__TOKEN` and `API__TOKENS` support multiple Tokens seperated by a `,` **Comma** and `[]` **Brackets**. See [Formatting](#string-to-type).
 During Authentication Secured Signal API will try to match the given Token against the list of Tokens inside of these Variables.
 
+> [!NOTE]
+> Both `api.token` and `api.tokens` support multiple Tokens.
+
 ```yaml
-environment:
-  API__TOKEN: [token1, token2, token3]
-  API__TOKENS: [token1, token2, token3]
+api:
+  token: [token1, token2, token3]
+  tokens: [token1, token2, token3]
 ```
 
 > [!IMPORTANT]
-> It is highly recommended to set this Environment Variable
+> It is highly recommended use API Tokens
 
 > _What if I just don't?_
 
 Secured Signal API will still work, but important Security Features won't be available
 like Blocked Endpoints and any sort of Auth.
 
 > [!NOTE]
-> Blocked Endpoints can be reactivated by manually setting them in the Environment
+> Blocked Endpoints can be reactivated by manually configuring them
 
 ### Blocked Endpoints
 
@@ -189,53 +217,27 @@ Because Secured Signal API is just a Proxy you can use all of the [Signal REST A
 | **/v1/accounts**      |
 | **/v1/contacts**      |
 
-These Endpoints are blocked by default due to Security Risks, but can be modified by setting `BLOCKED_ENDPOINTS` to a Comma seperated List:
+These Endpoints are blocked by default due to Security Risks, but can be modified by setting `blockedEndpoints` in your config:
 
 ```yaml
-environment:
-  BLOCKED_ENDPOINTS: |
-    /v1/register,
-    /v1/unregister,
-    /v1/qrcodelink,
-    /v1/contacts,
+blockedEndpoints: [/v1/register, /v1/unregister, /v1/qrcodelink, /v1/contacts]
 ```
 
-#### Variables
-
-By default Secured Signal API provides the following Placeholders:
+### Variables
 
-- **NUMBER** = _ENV_: `NUMBER`
-- **RECIPIENTS** = _ENV_: `RECIPIENTS`
+Placeholders can be added under `variables` and can then be referenced in the Body, Query or URL.
+See [Placeholders](#placeholders).
 
-### Customization
-
-Placeholders can be added by setting `VARIABLES` inside your Environment.
-
-```yaml
-environment:
-  VARIABLES: |
-    "NUMBER2": "002",
-    "GROUP_CHAT_1": [
-      "user.id", "000", "001", "group.id"
-    ]
-```
-
-### Recipients
-
-Set this Environment Variable to automatically provide default Recipients:
+> [!NOTE]
+> Every Placeholder Key will be converted into an Uppercase String.
+> Example: `number` becomes `NUMBER` in `{{.NUMBER}}`
 
 ```yaml
-environment:
-  RECIPIENTS: |
-    [ user.id, 000, 001, group.id ]
-```
-
-example:
-
-```json
-{
-	"recipients": "{{.RECIPIENTS}}"
-}
+variables:
+  number: "001",
+  recipients: [
+    "user.id", "000", "001", "group.id"
+  ]
 ```
 
 ### Message Aliases
@@ -256,18 +258,33 @@ To improve compatibility with other services Secured Signal API provides aliases
 
 Secured Signal API will pick the best scoring Message Alias (if available) to extract the correct message from the Request Body.
 
-Message Aliases can be added by setting `MESSAGE_ALIASES` to a valid json array containing dictionaries of `alias`, the json key to be used for lookup (use `.` dots for using values from a nested dictionary and `[i]` to get values from an array):
+Message Aliases can be added by setting `messageAliases` in your config:
 
 ```yaml
-environment:
-  MESSAGE_ALIASES: |
-    [
-      { "alias": "msg", "score": 80 }, 
-      { "alias": "data.message", "score": 79 },
-      { "alias": "array[0].message", "score": 78 },
-    ]
+messageAliases:
+  [
+    { alias: "msg", score: 80 },
+    { alias: "data.message", score: 79 },
+    { alias: "array[0].message", score: 78 },
+  ]
 ```
 
+### Port
+
+To change the Port which Secured Signal API uses, you need to set `server.port` in your config. (default: `8880`)
+
+### Log Level
+
+To change the Log Level set `logLevel` to: (default: `info`)
+
+| Level   |
+| ------- |
+| `info`  |
+| `debug` |
+| `warn`  |
+| `error` |
+| `fatal` |
+
 ## Contributing
 
 Found a bug? Want to change or add something?
diff --git a/Dockerfile b/Dockerfile
@@ -1,7 +1,7 @@
 FROM alpine:latest
 RUN apk --no-cache add ca-certificates
 
-ENV SERVER_PORT=8880
+ENV SERVER__PORT=8880
 
 ENV DEFAULTS_PATH=/app/config/defaults.yml
 
diff --git a/config/defaults.yml b/config/defaults.yml
@@ -1,7 +1,7 @@
 server:
   port: 8880
 
-logLevel: "INFO"
+logLevel: INFO
 
 messageAliases:
   [
diff --git a/docker-compose.yaml b/docker-compose.yaml
@@ -21,8 +21,8 @@ services:
           - secured-signal-api
     environment:
       API__URL: http://signal-api:8080
-      RECIPIENTS: 000,001,002
-      NUMBER: 123456789
+      VARIABLES__RECIPIENTS: 000,001,002
+      VARIABLES__NUMBER: 123456789
       API__TOKENS: LOOOOOONG_STRING
     ports:
       - "8880:8880"
diff --git a/examples/config.yml b/examples/config.yml
@@ -0,0 +1,17 @@
+# Example Config (all configurations shown)
+
+api:
+  port: 8880
+  url: http://signal-api:8080
+  tokens: [token1, token2]
+
+logLevel: INFO
+
+variables:
+  number: "000"
+  recipients: ["001", "group.id", "user.id"]
+
+messageAliases: [{ alias: "msg", score: 100 }]
+
+blockedEndpoints:
+  - /v1/about

Original file line number	Diff line number	Diff line change
`@@ -1,7 +1,7 @@`
`1`	`1`	`server:`
`2`	`2`	`port: 8880`
`3`	`3`
`4`		`-logLevel: "INFO"`
	`4`	`+logLevel: INFO`
`5`	`5`
`6`	`6`	`messageAliases:`
`7`	`7`	`[`