Knowledge Base

The Knowledge Base is a separate, optional product. FlowDesk works without it; enable it when you want a help centre your customers can read and articles your agents can attach to a request. It is shipped by the same Helm chart (shftco/flowdesk-kubernetes) under the knowledgeBase section of values.yaml, and it is off by default.

Three containers, three audiences

Container	What it is	Who reaches it
flowdesk-knowledge-base	The Knowledge Base API (port 8080). Three surfaces: /v1/admin (authoring), /v1/public (anonymous reading), /v1/integration (FlowDesk)	FlowDesk, and the two apps below
flowdesk-knowledge-base-site	The public help centre	Your customers, in a browser
flowdesk-knowledge-base-admin	The article authoring panel	Your editors, in a browser

The site and the admin app do not reach the API over the internet: each calls it from its own server-side layer over the in-cluster address, so their traffic never leaves the cluster. Only FlowDesk and browsers use the public hostnames.

The three images are versioned independently of each other and of the FlowDesk API. Pin all three; do not assume one tag covers the set.

Before you start

• Three DNS records, all pointing at your ingress. Create them before enabling the Knowledge Base: its hostnames get their own certificate, and cert-manager will keep retrying a challenge it cannot pass for a hostname that does not resolve.
• A database. The Knowledge Base has its own database, and its own Database:Provider (SqlServer or PostgreSql) independent of the FlowDesk API’s. Sharing one engine — a separate database on the same server — is the usual choice.
• A JWT keypair of its own. Separate products, separate signing keys: do not reuse the FlowDesk keypair.
• No Redis and no message broker. Unlike the FlowDesk API, this product needs neither.

SQL Server: the stock image is not enough

Article search uses SQL Server’s full-text search component, and the stock mcr.microsoft.com/mssql/server image does not ship it. Such an instance boots, migrates and then fails at the first article search. If you install on SQL Server, use an image with the full-text component installed, or choose PostgreSql, which needs nothing extra.

The JWT keypair secret

Generate a keypair and put it in its own Secret, named by knowledgeBase.jwtSecretName. The chart mounts it read-only at /app/keys; the token signer is built at startup and the pod will not start without it.

openssl genpkey -algorithm RSA -out private.pem -pkeyopt rsa_keygen_bits:2048
openssl rsa -in private.pem -pubout -out public.pem

kubectl create secret generic flowdesk-kb-jwt \
  --from-file=private.pem --from-file=public.pem -n flowdesk

Secret values

These live in the same Secret as the FlowDesk API’s values, not in values.yaml:

Key	What it is
KB_CONNECTION_STRING	Connection string for the Knowledge Base database, in the format of the engine you chose (see Configuration for both formats)
KB_TOKEN_ENCRYPTION_KEY	The key with which the Knowledge Base encrypts its own stored tokens. Independent of the FlowDesk API’s key
KB_SEED_ADMIN_PASSWORD	Password of the first administrator, the account you use for the first sign-in to the admin panel

values.yaml

The minimum: enable it, name the three hostnames, pin the three tags, choose the engine.

knowledgeBase:
  enabled: true
  databaseProvider: PostgreSql # or SqlServer
  seedAdminEmail: 'admin@yourcompany.com'
  jwtSecretName: flowdesk-kb-jwt
  image:
    tag: v0.1.34
  ingress:
    hosts:
      api: 'kbapi.yourcompany.com' # FlowDesk reads the integration surface from here
      help: 'kb.yourcompany.com' # the public help centre
      admin: 'kb-admin.yourcompany.com' # the authoring panel
  site:
    enabled: true
    image:
      tag: v0.1.36
  admin:
    enabled: true
    image:
      tag: v0.1.36

Write all three hostnames explicitly. The chart ships defaults for them, so an instance that overrides only api silently keeps the chart’s help and admin values — a rename has slipped through this way before. A hostname is instance data, never a chart default.

site.enabled and admin.enabled are separate switches and both default to false. The API can run alone: FlowDesk reads articles through the integration surface whether or not a help centre is published.

Other fields, all optional:

Field	Default	What it does
replicas	1	Replica count of the API (the site and admin blocks have their own)
applicationEnvironment	Production	ASP.NET environment name
persistence.enabled	true	A 2 Gi volume for uploaded media, mounted at /app/storage. Turn this off and every uploaded image is lost on restart
persistence.size	2Gi	Size of that volume
ingress.enabled	true	Renders the Knowledge Base’s own Ingress
ingress.clusterIssuer	letsencrypt-prod	cert-manager issuer for these three hostnames
ingress.tls.secretName	flowdesk-kb-tls	Its own certificate, deliberately not the FlowDesk one: sharing means one unresolvable hostname blocks renewal for the dashboard, the API and the tracker as well
probes, resources	see chart	Standard probe and resource settings

Everything else — the database provider, the connection string, the public address, the key paths — the chart derives from the fields above and passes to the container. There is nothing to set by hand as an environment variable.

What is exposed on the API hostname

Only what is needed, and it depends on which apps you deploy:

Path	When it is routed
/v1/integration	Always. This is what FlowDesk reads
/v1/public	Only when site.enabled is true
/v1/admin	Only when admin.enabled is true
/health	Always

Connecting FlowDesk to it

Installing the Knowledge Base does not connect it to FlowDesk. Do that from the dashboard, under Settings → Connected apps → Knowledge base:

Field	Value
Base URL	https://kbapi.yourcompany.com — where FlowDesk reads the content
Site URL	https://kb.yourcompany.com — where people read it. Optional; leave it empty if you publish no help centre
API token	An API key created in the Knowledge Base admin panel

Create the token in the admin panel under API keys, with the content:read scope: FlowDesk only reads. The key is shown once, at creation. It travels to the Knowledge Base in the X-Api-Key header and is stored encrypted; it is never returned in an API response or written to a log.

The Base URL must be https. FlowDesk refuses to dial a plain-http integration address as an SSRF control, so an in-cluster http:// address is rejected by the very feature it exists for — which is why the Knowledge Base needs a public hostname even when nothing human browses it. Use Test connection on the form to confirm the address and the token together.

Post-install checklist

• All three hostnames resolve, and the certificate has been issued for all three
• On SQL Server: the image includes the full-text component, and an article search returns results
• The JWT keypair secret exists, and the API pod is Running with /health answering
• The first sign-in to the admin panel with seedAdminEmail succeeds
• persistence.enabled is on, and an uploaded image survives a pod restart
• Test connection on the FlowDesk connected-app form succeeds
• A published article is visible on a request in the dashboard

Common situations

The connection test fails but the address is right. Check the token first: an API key without the content:read scope, or one that has been deleted, fails exactly like a wrong address. Then check that the address is https and that it is the API hostname, not the help-centre one.

The help centre answers nothing. Publishing is a setting inside the Knowledge Base, not a deployment flag: check Public site in the admin panel’s settings. site.enabled in values.yaml only decides whether the container is deployed.

Article search returns nothing while articles exist. On SQL Server this is the full-text component: see the warning above.

Uploaded images disappear. persistence.enabled is off, so media is written to a volume that does not survive the pod.