Poznote

Deploy Poznote on Kubernetes as a self-hosted note-taking and documentation platform.

Overview

The HelmForge Poznote chart uses the official ghcr.io/timothepoznanski/poznote:6.121.0 image. The container serves the web frontend and API on port 80 by default, and stores SQLite, notes, attachments and configuration under /var/www/html/data.

Poznote is designed for personal and small-team use. Data persistence relies on a single PVC. Scaling beyond one replica is not supported because SQLite does not handle concurrent writes from multiple instances.

Configuration Reference

Core runtime:

image.repository, image.tag, image.pullPolicy: official pinned Poznote image and pull behavior.
replicaCount: pod count. The chart rejects values greater than 1 because Poznote uses SQLite.
app.timezone, app.debug.
containerPorts.http: Nginx listener inside the application container.
commonLabels, nameOverride, fullnameOverride.

Secrets:

secrets.existingSecret: existing Secret for Poznote OIDC credentials.
secrets.oidcClientIdKey, secrets.oidcClientId: OIDC client ID source.
secrets.oidcClientSecretKey, secrets.oidcClientSecret: OIDC client secret source.

OIDC:

poznote.oidc.disableNormalLogin: force SSO-only mode, hiding the local login form.

Sharing:

poznote.sharing.hideRestrictUsers: hide the “Restrict to specific users” controls in note, folder, and workspace sharing dialogs. Existing restrictions continue to work.

Persistence:

persistence.data: SQLite database, notes, attachments, and configuration. Single PVC, 5Gi default.

Exposure and operations:

service.type, service.port, service.annotations, service.ipFamilyPolicy, service.ipFamilies. The Service port is independent from the application listener.
ingress.enabled, ingress.ingressClassName, ingress.annotations, ingress.hosts, ingress.tls.
gatewayAPI.enabled, gatewayAPI.httpRoutes.
externalSecrets.enabled, externalSecrets.items.
networkPolicy.enabled, networkPolicy.ingressFrom, networkPolicy.egress.
probes.startup, probes.liveness, probes.readiness.
resources, podSecurityContext, securityContext.
serviceAccount, pdb, nodeSelector, tolerations, affinity, topologySpreadConstraints.
priorityClassName, terminationGracePeriodSeconds, podLabels, podAnnotations, extraVolumes, extraVolumeMounts, extraManifests.

Installation

helm repo add helmforge https://repo.helmforge.dev
helm repo update
helm install poznote helmforge/poznote

OCI install:

helm install poznote oci://ghcr.io/helmforgedev/helm/poznote

Production Example

secrets:
  existingSecret: poznote-oidc

persistence:
  data:
    size: 10Gi

ingress:
  enabled: true
  ingressClassName: traefik
  hosts:
    - host: notes.example.com
      paths:
        - path: /
          pathType: Prefix
  tls:
    - secretName: notes-tls
      hosts:
        - notes.example.com

networkPolicy:
  enabled: true

Listener and Service Ports

The Service targets the named http container port. To move the real Nginx listener while keeping port 80 for clients:

containerPorts:
  http: 8080
service:
  port: 80

The chart passes containerPorts.http to the official image through POZNOTE_LISTEN_PORT. Changing service.port alone does not change Nginx.

Create the OIDC Secret before enabling SSO:

apiVersion: v1
kind: Secret
metadata:
  name: poznote-oidc
type: Opaque
stringData:
  oidc-client-id: your-oidc-client-id
  oidc-client-secret: your-oidc-client-secret

Default login credentials are admin_change_me / admin. Change them immediately after first login.

Gateway API

gatewayAPI:
  enabled: true
  httpRoutes:
    - parentRefs:
        - name: public
          namespace: gateway-system
      hostnames:
        - notes.example.com

External Secrets

secrets:
  existingSecret: poznote-oidc

externalSecrets:
  enabled: true
  items:
    - fullnameOverride: poznote-oidc
      spec:
        secretStoreRef:
          kind: ClusterSecretStore
          name: production
        target:
          name: poznote-oidc
          creationPolicy: Owner
        data:
          - secretKey: oidc-client-id
            remoteRef:
              key: poznote/oidc
              property: client-id
          - secretKey: oidc-client-secret
            remoteRef:
              key: poznote/oidc
              property: client-secret

Backup

Back up the data PVC regularly. It contains the SQLite database, all notes, attachments, and application configuration. Use your storage provider’s snapshot mechanism or a tool like Velero. Poznote also supports data export from the web interface (Settings > Export).

Upgrade Notes

Poznote 6.121.0 includes bug fixes, stability, and performance improvements. Review the official 6.121.0 release, back up the complete data PVC, and verify restoration in a separate instance before upgrading production.

The upgrade range from Poznote 6.100.0 through 6.115.0 adds scheduled local backup archives, revisions, richer Markdown editing and repeating tasks. The 6.115.0 release adds dash lists and an optional login-screen bypass. Only enable “Open without login” when network access is restricted to the account owner or a trusted reverse proxy provides authentication; the API continues to require credentials. This upgrade range also includes upstream security hardening and Alpine package updates. Review the official release. Since 6.80.0, upstream fixes stored XSS and backup streaming with custom themes, adds app passwords, and changes REST errors from HTTP 200 to actual error status codes. Integrations must handle HTTP 404 for inaccessible or missing IDs and 409/423 for conflicting writes. The PHP worker default increases from 5 to 10; set POZNOTE_PHP_FPM_MAX_CHILDREN through app.env when sizing a smaller pod. POZNOTE_PHP_MEMORY_LIMIT is also configurable through app.env (upstream default: 512 MB). Dictation requires an operator-configured speech service; this chart does not deploy one. Keep the pod running until a backup or restore job completes; verify its final status before downloading or relying on the archive. Back up the complete data PVC and test restoration in a separate instance before upgrading production. For existing S3 integrations, confirm attachment access during export and restore.

Shared links default to read-only. API integrations should retain the returned note version and pass if_version or If-Match when saving to detect concurrent edits. MCP user selection and optional POZNOTE_MCP_AUTH_TOKEN configure the separate MCP server, which this chart does not deploy or expose. Review the upstream releases before upgrading integrations.

The upstream rootless image is not the chart default because it requires the mounted data directory itself to be owned by UID/GID 1000. This is not guaranteed for new PVCs or upgrades from the standard image without a recursive ownership migration. Follow the Backup section above before upgrading production workloads.