Skip to content
MediKeep icon
v2.1.2App: v0.72.0Pinned DigestS3 Backup Ready

Production Helm chart • Apache-2.0 • Zero-Root • Verified on Kubernetes v1.33-v1.36+

MediKeep Helm Chart

Deploy MediKeep, a self-hosted personal medical records application built with React and FastAPI.

This chart packages the official ghcr.io/afairgiant/medikeep:v0.72.0 image with PostgreSQL, persistent uploads and backups, Kubernetes Ingress, Gateway API, NetworkPolicy, and External Secrets Operator integration.

Upgrade Notes

MediKeep v0.72.0 adds visit relationships, broader advanced search and report controls, and fixes health responses, SSO user identification, user-scoped tag reads and attachment filenames. It does not change the service port, uploads path or authentication environment contract. See authentication configuration and the upstream release. Back up PostgreSQL and uploaded records before upgrading.

The legacy app.port value has been removed. The pinned upstream entrypoint always starts Uvicorn on container port 8000, so that value changed only Kubernetes metadata and could break traffic. Do not use --reuse-values for this migration because it can retain the removed default. Export the user-supplied values, remove app.port from the exported file, and reset old defaults during the upgrade:

helm get values medikeep --namespace medikeep -o yaml > medikeep-user-values.yaml
# Remove app.port from medikeep-user-values.yaml if it is present.
helm upgrade medikeep helmforge/medikeep --namespace medikeep \
  --reset-values -f medikeep-user-values.yaml

Use service.port when clients need a different Kubernetes Service port; the Service continues to target the fixed named http listener.

Install

helm repo add helmforge https://repo.helmforge.dev
helm install medikeep helmforge/medikeep

MediKeep exposes HTTP on port 8000. For local access:

kubectl port-forward svc/medikeep 8000:8000

Configuration

The chart keeps the fixed upstream listener separate from the Kubernetes Service port. This example exposes Service port 8080 while MediKeep continues to listen on container port 8000:

service:
  port: 8080

app:
  timezone: America/New_York
  logLevel: INFO
  debug: false
  enableApiDocs: false

Common configuration groups are:

  • image, app, and probes for the pinned image and application runtime.
  • secrets and medikeep.sso for authentication and stable credentials.
  • postgresql or database.external for the database topology.
  • persistence for uploads, generated backups, and optional persistent logs.
  • service, ingress, and gatewayAPI for exposure.
  • networkPolicy, resources, securityContext, and podSecurityContext for production controls.

See Authentication and Secrets, Exposure, Production, and Storage for complete examples and operational boundaries.

Security and Production Notes

MediKeep stores personal health data. Treat the database, uploads PVC, backups PVC, logs, and Kubernetes Secrets as sensitive.

On fresh installs, upstream creates an admin user with the default password admin123 unless ADMIN_DEFAULT_PASSWORD is set before first startup. For production, set a strong secrets.adminDefaultPassword during the first install or provide secrets.existingSecret with the key configured by secrets.adminDefaultPasswordKey, then rotate the password in the UI. The chart rejects an inline admin123 value for public exposure. Helm cannot inspect the contents of an existing Secret, so operators must ensure that its administrator password key exists and contains a strong value. For public exposure, the pod will not start when that key is missing.

secrets:
  existingSecret: medikeep-runtime
  secretKeyKey: secret-key
  adminDefaultPasswordKey: admin-password

The Secret must contain:

apiVersion: v1
kind: Secret
metadata:
  name: medikeep-runtime
type: Opaque
stringData:
  secret-key: replace-with-a-long-random-secret
  admin-password: replace-with-a-strong-initial-password

PostgreSQL

The chart enables the HelmForge PostgreSQL subchart by default:

postgresql:
  enabled: true
  auth:
    database: medical_records
    username: medapp
    existingSecret: medikeep-postgresql
    existingSecretPostgresPasswordKey: postgres-password
    existingSecretUserPasswordKey: user-password

The referenced Secret must contain the PostgreSQL superuser and application password keys shown above.

To use an external PostgreSQL instance:

postgresql:
  enabled: false

database:
  external:
    host: postgres.example.com
    name: medical_records
    username: medapp
    existingSecret: medikeep-db
    existingSecretPasswordKey: password

Persistence

MediKeep writes to three paths:

  • /app/uploads for uploaded lab files, patient photos, and record attachments.
  • /app/backups for backups generated by the app dashboard or CLI.
  • /app/logs for application logs.

Uploads and backups are persisted by default. Logs use emptyDir by default to avoid retaining sensitive data unless explicitly requested.

persistence:
  uploads:
    size: 20Gi
  backups:
    size: 20Gi
  logs:
    enabled: true
    size: 2Gi

Exposure

Ingress:

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

Gateway API:

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

Validation

make validate-chart CHART=medikeep

Security Scan: medikeep

Framework Score
MITRE + NSA + SOC2 92.42424%

Security posture acceptable.

Documentation

System Architecture

DESIGN.md Synced

Verified architecture contract rendered dynamically from GitHub DESIGN.md

flowchart LR
  User[User] --> Service[ClusterIP Service]
  Service --> App[MediKeep pod<br/>React and FastAPI<br/>TCP 8000]
  App --> Uploads[(Uploads PVC)]
  App --> Backups[(Backups PVC)]
  App --> Logs[Ephemeral logs]
  App --> PostgreSQL[(Bundled PostgreSQL)]
  App --> Secret[Application Secret]
Official Contractvalues.schema.json

MediKeep Values Schema Reference

Official schema parameters, default values, and types extracted directly from the chart repository.

74 parametersValues Studio

Global(1)

ParameterTypeDefaultDescription
globalobject-Chart configuration parameter

Name Override(1)

ParameterTypeDefaultDescription
nameOverridestring-Chart configuration parameter

Fullname Override(1)

ParameterTypeDefaultDescription
fullnameOverridestring-Chart configuration parameter

Common Labels(1)

ParameterTypeDefaultDescription
commonLabelsany-Chart configuration parameter

Image(3)

ParameterTypeDefaultDescription
image.repositorystring-Chart configuration parameter
image.tagstring-Chart configuration parameter
image.pullPolicystring-Chart configuration parameter
Allowed:AlwaysIfNotPresentNever

Image Pull Secrets(1)

ParameterTypeDefaultDescription
imagePullSecretsarray-Chart configuration parameter

Replica Count(1)

ParameterTypeDefaultDescription
replicaCountinteger-Chart configuration parameter

App(9)

ParameterTypeDefaultDescription
app.timezonestring-Chart configuration parameter
app.logLevelstring-Chart configuration parameter
Allowed:INFODEBUG
app.debugboolean-Chart configuration parameter
app.enableApiDocsboolean-Chart configuration parameter
app.enableSslboolean-Chart configuration parameter
app.commandarray-Chart configuration parameter
app.argsarray-Chart configuration parameter
app.envarray-Chart configuration parameter
app.envFromarray-Chart configuration parameter

Secrets(7)

ParameterTypeDefaultDescription
secrets.existingSecretstring-Chart configuration parameter
secrets.secretKeyKeystring-Chart configuration parameter
secrets.secretKeystring-Chart configuration parameter
secrets.adminDefaultPasswordKeystring-Chart configuration parameter
secrets.adminDefaultPasswordstring-Chart configuration parameter
secrets.ssoClientSecretKeystring-Chart configuration parameter
secrets.ssoClientSecretstring-Chart configuration parameter

Database(7)

ParameterTypeDefaultDescription
database.external.hoststring-Chart configuration parameter
database.external.portstring-Chart configuration parameter
database.external.namestring-Chart configuration parameter
database.external.usernamestring-Chart configuration parameter
database.external.passwordstring-Chart configuration parameter
database.external.existingSecretstring-Chart configuration parameter
database.external.existingSecretPasswordKeystring-Chart configuration parameter

Medikeep(6)

ParameterTypeDefaultDescription
medikeep.sso.enabledboolean-Chart configuration parameter
medikeep.sso.providerTypestring-Chart configuration parameter
Allowed:oidcgithubgoogle
medikeep.sso.clientIdstring-Chart configuration parameter
medikeep.sso.issuerUrlstring-Chart configuration parameter
medikeep.sso.redirectUristring-Chart configuration parameter
medikeep.sso.allowedDomainsstring-Chart configuration parameter

Persistence(3)

ParameterTypeDefaultDescription
persistence.uploadsany-Chart configuration parameter
persistence.backupsany-Chart configuration parameter
persistence.logsany-Chart configuration parameter

Service Account(1)

ParameterTypeDefaultDescription
serviceAccountany-Chart configuration parameter

Service & Networking(1)

ParameterTypeDefaultDescription
serviceany-Chart configuration parameter

Ingress(1)

ParameterTypeDefaultDescription
ingressany-Chart configuration parameter

Gateway API(1)

ParameterTypeDefaultDescription
gatewayAPIany-Chart configuration parameter

External Secrets(1)

ParameterTypeDefaultDescription
externalSecretsany-Chart configuration parameter

Health Probes(1)

ParameterTypeDefaultDescription
probesany-Chart configuration parameter

Resources(1)

ParameterTypeDefaultDescription
resourcesany-Chart configuration parameter

Wait For Database(2)

ParameterTypeDefaultDescription
waitForDatabase.imageany-Chart configuration parameter
waitForDatabase.resourcesany-Chart configuration parameter

Pod Security(3)

ParameterTypeDefaultDescription
podSecurityContext.fsGroupinteger-Chart configuration parameter
podSecurityContext.fsGroupChangePolicystring-Chart configuration parameter
Allowed:AlwaysOnRootMismatch
podSecurityContext.seccompProfileany-Chart configuration parameter

Container Security(7)

ParameterTypeDefaultDescription
securityContext.allowPrivilegeEscalationboolean-Chart configuration parameter
securityContext.capabilitiesobject-Chart configuration parameter
securityContext.readOnlyRootFilesystemboolean-Chart configuration parameter
securityContext.runAsNonRootboolean-Chart configuration parameter
securityContext.runAsUserinteger-Chart configuration parameter
securityContext.runAsGroupinteger-Chart configuration parameter
securityContext.seccompProfileany-Chart configuration parameter

Pdb(1)

ParameterTypeDefaultDescription
pdbany-Chart configuration parameter

Network Policy(1)

ParameterTypeDefaultDescription
networkPolicyany-Chart configuration parameter

Node Selector(1)

ParameterTypeDefaultDescription
nodeSelectorany-Chart configuration parameter

Tolerations(1)

ParameterTypeDefaultDescription
tolerationsarray-Chart configuration parameter

Affinity(1)

ParameterTypeDefaultDescription
affinityobject-Chart configuration parameter

Topology Spread Constraints(1)

ParameterTypeDefaultDescription
topologySpreadConstraintsarray-Chart configuration parameter

Priority Class Name(1)

ParameterTypeDefaultDescription
priorityClassNamestring-Chart configuration parameter

Termination Grace Period Seconds(1)

ParameterTypeDefaultDescription
terminationGracePeriodSecondsinteger-Chart configuration parameter

Pod Labels(1)

ParameterTypeDefaultDescription
podLabelsany-Chart configuration parameter

Pod Annotations(1)

ParameterTypeDefaultDescription
podAnnotationsany-Chart configuration parameter

Extra Volumes(1)

ParameterTypeDefaultDescription
extraVolumesarray-Chart configuration parameter

Extra Volume Mounts(1)

ParameterTypeDefaultDescription
extraVolumeMountsarray-Chart configuration parameter

Extra Manifests(1)

ParameterTypeDefaultDescription
extraManifestsarray-Chart configuration parameter

Postgresql(1)

ParameterTypeDefaultDescription
postgresqlobject-Values passed to the HelmForge PostgreSQL dependency.