# Core & Licensing (/configure/reference/core)



These are the foundational settings every KubeMQ server needs: the **license key** that
activates the server, the **log level** that controls how much it writes, and the **host
identity** it reports itself under. Each setting is shown for both deployment targets —
Docker single-node (`config.yaml` key · env var) and Kubernetes/Helm (`spec.*` path). A
dash (`—`) in the Helm/CRD column means the setting is not available on that surface.

## Licensing & identity [#licensing--identity]

The license is required on both targets. On Docker you can pass the key directly as an
env var, point at a license file, or embed the key in `config.yaml`; on Helm the chart
renders `key` (or `license`) straight into the CR.

| Setting           | Type   | Default          | Valid values                                              | Docker (config.yaml key · env var)              | Helm/CRD path  | Notes                                                                                                                                                                                                                                                                      |
| ----------------- | ------ | ---------------- | --------------------------------------------------------- | ----------------------------------------------- | -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| License token     | string | `""`             | activation UUID (online) **or** offline license-data blob | — · `KUBEMQ_TOKEN` (or `--key` flag)            | `spec.key`     | `License.KubeMQToken` — the value the runtime license service validates. Env/flag-only (`os.Getenv`); no config.yaml key, no viper binding. `spec.key` is consumed **by the operator** (activation + inventory metadata), **not** injected into the pod as `KUBEMQ_TOKEN`. |
| License data      | string | `""`             | license-data blob (base64/PEM)                            | `license.key.data` · `LICENSE_KEY_DATA`         | `spec.license` | `License.Key.Data`. Operator renders `spec.license` → `LICENSE_KEY_DATA` secret. Redacted in settings API.                                                                                                                                                                 |
| License from file | string | `""`             | filesystem path                                           | `license.key.filename` · `LICENSE_KEY_FILENAME` | —              | `License.Key.Filename`. Docker/on-disk only; `data` wins over `filename`.                                                                                                                                                                                                  |
| Host identity     | string | derived hostname | any host string                                           | `host` · `HOST`                                 | —              | `Config.Host`. Auto-derived from OS hostname when empty; explicit `viper.BindEnv("Host","HOST")`. No CRD field. ⚠️ **Changing it orphans the store** — see the warning below.                                                                                              |

<Callout type="error">
  **Changing `HOST` silently orphans the entire persistent store.** The store layout is
  `<storepath>/<host>/…`, so the host identity is part of the data path, not just a label.
  Point a running node at a new `HOST` and it **boots clean and completely healthy onto an
  empty directory**, with the previous store sitting intact beside it, untouched and
  unread. Nothing fails, nothing warns, and every health check passes — the messages are
  simply gone from the server's point of view.

  The same trap catches you from the other direction on Docker, where `HOST` is derived from
  the OS hostname: a container recreated without `--hostname` gets a fresh random one and
  lands on a new empty directory. See the
  [Docker configuration guide](/configure/docker).

  If you must change it, treat it as a **migration**: stop the server, move
  `<storepath>/<old-host>` to `<storepath>/<new-host>`, then start it. To recover from an
  accidental change, set `HOST` back to the original value — the old directory is still
  there.
</Callout>

<Callout type="info">
  `KUBEMQ_TOKEN` and `LICENSE_KEY_DATA` are two different fields, not aliases for the
  same setting. **License token** (`KUBEMQ_TOKEN`, `License.KubeMQToken`) is read
  directly from the environment — there is no `config.yaml` key and no viper binding —
  and it is the value the runtime license service validates. **License data**
  (`license.key.data` · `LICENSE_KEY_DATA`, `License.Key.Data`) is the license-data blob
  bound to `config.yaml`/Helm. On Kubernetes, `spec.key` is consumed **by the operator**
  for activation and inventory metadata; it is **not** injected into the pod as
  `KUBEMQ_TOKEN`. Only `spec.license` is delivered to the running server, rendered as the
  `LICENSE_KEY_DATA` secret.
</Callout>

<Callout type="warn">
  `LicenseConfig.Validate()` is dead code — `Config.Validate()` never calls it, so no
  startup-time check runs against the license fields above. The real gate is the license
  service, which validates `KUBEMQ_TOKEN` at runtime; a missing or invalid token fails
  there, not at config validation.
</Callout>

## Logging [#logging]

`Log level` controls verbosity — the same value on both targets, passed through to the
server unchanged. `Log to file` / `Log file path` enable and locate an on-disk log; both
are Docker / `config.yaml`-only (no Helm/CRD path).

| Setting       | Type                 | Default    | Valid values                                              | Docker (config.yaml key · env var)   | Helm/CRD path    | Notes                                                                                                                                          |
| ------------- | -------------------- | ---------- | --------------------------------------------------------- | ------------------------------------ | ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| Log level     | int (`LogLevelType`) | `2` (Info) | `0`=Trace `1`=Debug `2`=Info `3`=Warn `4`=Error `5`=Fatal | `log.level` · `LOG_LEVEL`            | `spec.log.level` | Higher = less. Validate rejects only negatives; a value >5 silently maps to the verbose default (Trace/Debug), not silent. CRD constrains 0–5. |
| Log to file   | bool                 | `false`    | `true` \| `false`                                         | `log.fileenable` · `LOG_FILE_ENABLE` | —                | When `true`, **Log file path** must be non-empty.                                                                                              |
| Log file path | string               | `""`       | filesystem path                                           | `log.filepath` · `LOG_FILE_PATH`     | —                | Required when file logging is enabled.                                                                                                         |

<Callout type="warn">
  The **0–5 scale above is authoritative** (`0`=Trace … `5`=Fatal, default `2`=Info). The
  operator passes the value through to the server **verbatim**. An older CRD annotation
  describes a different scale (`0`=silent / `1`=info / `2`=debug) — that annotation does
  **not** match the running server, so do not rely on it. Use the 0–5 enum above.
</Callout>

## Example [#example]

Set the log level on each target. This is a single-setting snippet — see the
[Docker guide](/configure/docker) and the
[Kubernetes guide](/configure/kubernetes) for complete, runnable configurations.

<Tabs items="[&#x22;Docker&#x22;, &#x22;Helm&#x22;]">
  <Tab value="Docker">
    ```yaml title="config.yaml"
    log:
      level: 2
    ```
  </Tab>

  <Tab value="Helm">
    ```yaml title="values.yaml"
    log:
      level: 2
    ```
  </Tab>
</Tabs>

For the full Docker delivery methods (env vars, mounted `config.yaml`, the `CONFIG`
variable) see the [Docker guide](/configure/docker); for `values.yaml` mapped to
the `KubemqCluster` spec see the [Kubernetes guide](/configure/kubernetes).