Liwan Helm Chart
Deploy Liwan on Kubernetes with the official
ghcr.io/explodingcamera/liwan:1.8.0 image.
Liwan is a lightweight, privacy-focused web analytics application. It runs as a single Rust service and stores analytics
data in embedded DuckDB under /data.
Features
- Official upstream image pinned by tag
- Single-instance topology aligned with embedded DuckDB
- Persistent
/datavolume for analytics and runtime assets Recreaterollout strategy to avoid overlapping DuckDB writers- Public URL wiring through
LIWAN_BASE_URL - Ingress and Gateway API exposure options
- Dual-stack Service support
- Opt-in ingress NetworkPolicy with explicit peer support
- Non-root security context with token automount disabled
- Extra manifests, volumes, mounts, labels, and annotations for platform integration
Install
helm repo add helmforge https://repo.helmforge.dev
helm repo update
helm install liwan helmforge/liwan -f values.yaml
OCI registry:
helm install liwan oci://ghcr.io/helmforgedev/helm/liwan -f values.yaml
Production Example
liwan:
baseUrl: https://analytics.example.com
persistence:
enabled: true
size: 5Gi
resources:
requests:
cpu: 25m
memory: 64Mi
limits:
cpu: 250m
memory: 256Mi
ingress:
enabled: true
ingressClassName: traefik
annotations:
cert-manager.io/cluster-issuer: letsencrypt-prod
hosts:
- host: analytics.example.com
paths:
- path: /
pathType: Prefix
tls:
- secretName: liwan-tls
hosts:
- analytics.example.com
Architecture
The chart renders one Deployment, one Service, and a PVC by default. Liwan listens on container port 9042; the Service
exposes port 80.
The Deployment uses strategy.type: Recreate because the application stores data in embedded DuckDB. A rolling update
could briefly run two writers against the same data volume, so the chart prefers a short outage during upgrades over a
risky overlapping write window.
Set liwan.baseUrl to the public URL used by browsers and tracking scripts:
liwan:
baseUrl: https://analytics.example.com
Tracking Script
After installing Liwan, create a site in the UI and use the generated tracking snippet. A typical snippet looks like:
<script defer src="https://analytics.example.com/script.js" data-site-name="my-site"></script>
Keep liwan.baseUrl, Ingress hostnames, Gateway API hostnames, and TLS hosts aligned so generated URLs match the public
endpoint.
Examples
Values & Configuration Reference
All schema parameters, types, defaults, and allowed values are extracted directly from the chart repository. Filter and search them in the interactive reference below or customize in Values Studio.
| --- | --- | --- |
| image.repository | ghcr.io/explodingcamera/liwan | Liwan image repository. |
| image.tag | "1.8.0" | Liwan image tag. |
| liwan.port | 9042 | Application HTTP port. |
| liwan.baseUrl | "" | Public base URL for UI and tracking scripts. |
| liwan.extraEnv | [] | Extra environment variables for advanced upstream settings. |
| persistence.enabled | true | Persist /data. |
| persistence.size | 2Gi | PVC size. |
| service.port | 80 | Kubernetes Service port. |
| service.ipFamilyPolicy | null | Optional Service IP family policy. |
| service.ipFamilies | [] | Optional ordered IP families. |
| networkPolicy.enabled | false | Enable ingress isolation for the Liwan pod. |
| networkPolicy.ingressFrom | [] | Allowed peers; empty permits same-namespace pods. |
| ingress.enabled | false | Render an Ingress. |
| gatewayAPI.enabled | false | Render a Gateway API HTTPRoute. |
| serviceAccount.automountServiceAccountToken | false | Mount a Kubernetes API token into the pod. |
| extraManifests | [] | Additional Kubernetes resources to render with the release. |
Upgrade to 1.8
Liwan 1.8 retains the secure proxy contract introduced in 1.7: only loopback
proxies and X-Forwarded-For are trusted by default.
Behind an Ingress or Gateway, configure the actual proxy IPs or CIDRs through
liwan.extraEnv; otherwise analytics records the connecting proxy address.
For example, set LIWAN_TRUSTED_PROXIES to 10.42.0.0/16 only when that range
belongs to your trusted ingress proxies. Multiple entries are comma-separated.
Set LIWAN_TRUSTED_HEADERS when your proxy uses a different header. Do not
trust arbitrary client-controlled headers or use the unrestricted * proxy
setting. The removed LIWAN_USE_FORWARD_HEADERS setting now fails chart
validation with a migration message.
Review the upstream 1.8 release before upgrading. Back up the persistent data directory before the rollout and keep exactly one writer during recovery.
Network isolation
NetworkPolicy is disabled by default so upgrades preserve established ingress paths. Enable it only after identifying the namespace and Pod selectors used by your Ingress or Gateway controller:
networkPolicy:
enabled: true
ingressFrom:
- namespaceSelector:
matchLabels:
kubernetes.io/metadata.name: ingress-system
podSelector:
matchLabels:
app.kubernetes.io/name: ingress-controller
An empty ingressFrom permits same-namespace pods. Enforcement requires a CNI
that implements Kubernetes NetworkPolicy. Set podSelector labels to match the
actual edge controller. NetworkPolicies are additive, so inspect every policy
selecting the Liwan Pod before relying on this policy for isolation.
Operations
Check rollout:
kubectl rollout status deployment/liwan-liwan
kubectl get deployment,svc,pvc -l app.kubernetes.io/name=liwan,app.kubernetes.io/instance=liwan
Port-forward for local access:
kubectl port-forward svc/liwan-liwan 9042:80
Back up the PVC mounted at /data. For consistent snapshots, pause writes or scale the Deployment to zero before taking
a storage-level snapshot.
Security
Default security posture:
- ServiceAccount token automount disabled
- non-root UID/GID
1000 fsGroup: 1000fsGroupChangePolicy: OnRootMismatchseccompProfile.type: RuntimeDefaultallowPrivilegeEscalation: falsecapabilities.drop: [ALL]
Resource requests and limits are intentionally user-defined because Liwan traffic profiles vary by site. Set them for production to satisfy cluster policy and capacity planning.
Troubleshooting
- If the Pod is pending, confirm the PVC is bound and the requested StorageClass exists.
- If tracking records the proxy address, configure only the actual proxy CIDRs in
LIWAN_TRUSTED_PROXIESand verify the forwarded header name. - If NetworkPolicy blocks traffic, compare the edge Pod and namespace labels with
networkPolicy.ingressFrombefore widening access. - If data appears missing, verify the mounted claim and never start a second writer against the previous DuckDB directory.
Security Scan: liwan
| Framework | Score |
|---|---|
| Overall | 84.85% |
| MITRE | 100.00% |
| NSA | 80.00% |
| SOC2 | 80.00% |
Security posture acceptable. Remaining findings are resource limits, network policy, and immutable root filesystem, which are environment-specific choices for this chart.
Documentation
System Architecture
DESIGN.md SyncedVerified architecture contract rendered dynamically from GitHub DESIGN.md
flowchart LR browser[Dashboard browser] --> edge[Ingress or Gateway API] website[Tracked website] --> edge edge --> service[Liwan Service] service --> app[Single Liwan Deployment] app --> data[(Data PVC)] app --> geo[Upstream GeoIP and application endpoints] policy[Optional ingress NetworkPolicy] --> app operator[Quiesced backup process] --> data
Liwan Values Schema Reference
Official schema parameters, default values, and types extracted directly from the chart repository.
Global(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| global | object | - | Global settings shared by the chart. |
Name Override(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| nameOverride | string | "" | Chart configuration parameter |
Fullname Override(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| fullnameOverride | string | "" | Chart configuration parameter |
Common Labels(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| commonLabels | object | - | Chart configuration parameter |
Image(3)
| Parameter | Type | Default | Description |
|---|---|---|---|
| image.repository | string | ghcr.io/explodingcamera/liwan | Chart configuration parameter |
| image.tag | string | 1.8.0 | Chart configuration parameter |
| image.pullPolicy | string | IfNotPresent | Chart configuration parameter Allowed: AlwaysIfNotPresentNever |
Image Pull Secrets(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| imagePullSecrets | array | - | Chart configuration parameter |
Liwan(3)
| Parameter | Type | Default | Description |
|---|---|---|---|
| liwan.port | integer | 9042 | Application port |
| liwan.baseUrl | string | "" | Public base URL of the instance |
| liwan.extraEnv | array | - | Chart configuration parameter |
Persistence(5)
| Parameter | Type | Default | Description |
|---|---|---|---|
| persistence.enabled | boolean | true | Chart configuration parameter |
| persistence.size | string | 2Gi | Chart configuration parameter |
| persistence.storageClass | string | "" | Chart configuration parameter |
| persistence.accessModes | array | - | Chart configuration parameter |
| persistence.existingClaim | string | "" | Chart configuration parameter |
Service Account(4)
| Parameter | Type | Default | Description |
|---|---|---|---|
| serviceAccount.create | boolean | false | Chart configuration parameter |
| serviceAccount.name | string | "" | Chart configuration parameter |
| serviceAccount.annotations | object | - | Chart configuration parameter |
| serviceAccount.automountServiceAccountToken | boolean | false | Chart configuration parameter |
Service & Networking(5)
| Parameter | Type | Default | Description |
|---|---|---|---|
| service.type | string | ClusterIP | Chart configuration parameter Allowed: ClusterIPNodePortLoadBalancer |
| service.port | integer | 80 | Chart configuration parameter |
| service.annotations | object | - | Chart configuration parameter |
| service.ipFamilyPolicy | stringnull | - | Chart configuration parameter Allowed: SingleStackPreferDualStackRequireDualStacknull |
| service.ipFamilies | array | - | Chart configuration parameter |
Network Policy(2)
| Parameter | Type | Default | Description |
|---|---|---|---|
| networkPolicy.enabled | boolean | false | Chart configuration parameter |
| networkPolicy.ingressFrom | array | - | Chart configuration parameter |
Ingress(5)
| Parameter | Type | Default | Description |
|---|---|---|---|
| ingress.enabled | boolean | false | Chart configuration parameter |
| ingress.ingressClassName | string | traefik | Chart configuration parameter |
| ingress.annotations | object | - | Chart configuration parameter |
| ingress.hosts | array | - | Chart configuration parameter |
| ingress.tls | array | - | Chart configuration parameter |
Gateway API(5)
| Parameter | Type | Default | Description |
|---|---|---|---|
| gatewayAPI.enabled | boolean | false | Chart configuration parameter |
| gatewayAPI.parentRefs | array | - | Chart configuration parameter |
| gatewayAPI.hostnames | array | - | Chart configuration parameter |
| gatewayAPI.paths | array | - | Chart configuration parameter |
| gatewayAPI.annotations | object | - | Chart configuration parameter |
Health Probes(15)
| Parameter | Type | Default | Description |
|---|---|---|---|
| probes.startup.enabled | boolean | - | Chart configuration parameter |
| probes.startup.initialDelaySeconds | integer | - | Chart configuration parameter |
| probes.startup.periodSeconds | integer | - | Chart configuration parameter |
| probes.startup.timeoutSeconds | integer | - | Chart configuration parameter |
| probes.startup.failureThreshold | integer | - | Chart configuration parameter |
| probes.liveness.enabled | boolean | - | Chart configuration parameter |
| probes.liveness.initialDelaySeconds | integer | - | Chart configuration parameter |
| probes.liveness.periodSeconds | integer | - | Chart configuration parameter |
| probes.liveness.timeoutSeconds | integer | - | Chart configuration parameter |
| probes.liveness.failureThreshold | integer | - | Chart configuration parameter |
| probes.readiness.enabled | boolean | - | Chart configuration parameter |
| probes.readiness.initialDelaySeconds | integer | - | Chart configuration parameter |
| probes.readiness.periodSeconds | integer | - | Chart configuration parameter |
| probes.readiness.timeoutSeconds | integer | - | Chart configuration parameter |
| probes.readiness.failureThreshold | integer | - | Chart configuration parameter |
Resources(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| resources | object | - | Chart configuration parameter |
Pod Security(3)
| Parameter | Type | Default | Description |
|---|---|---|---|
| podSecurityContext.fsGroup | integer | - | Chart configuration parameter |
| podSecurityContext.fsGroupChangePolicy | string | - | Chart configuration parameter Allowed: AlwaysOnRootMismatch |
| podSecurityContext.seccompProfile.type | string | - | Chart configuration parameter |
Container Security(5)
| Parameter | Type | Default | Description |
|---|---|---|---|
| securityContext.runAsUser | integer | - | Chart configuration parameter |
| securityContext.runAsGroup | integer | - | Chart configuration parameter |
| securityContext.runAsNonRoot | boolean | - | Chart configuration parameter |
| securityContext.allowPrivilegeEscalation | boolean | - | Chart configuration parameter |
| securityContext.capabilities.drop | array | - | Chart configuration parameter |
Node Selector(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| nodeSelector | object | - | Chart configuration parameter |
Tolerations(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| tolerations | array | - | Chart configuration parameter |
Affinity(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| affinity | object | - | Chart configuration parameter |
Topology Spread Constraints(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| topologySpreadConstraints | array | - | Chart configuration parameter |
Priority Class Name(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| priorityClassName | string | "" | Chart configuration parameter |
Termination Grace Period Seconds(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| terminationGracePeriodSeconds | integer | 30 | Chart configuration parameter |
Pod Labels(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| podLabels | object | - | Chart configuration parameter |
Pod Annotations(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| podAnnotations | object | - | Chart configuration parameter |
Extra Volumes(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| extraVolumes | array | - | Chart configuration parameter |
Extra Volume Mounts(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| extraVolumeMounts | array | - | Chart configuration parameter |
Extra Manifests(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| extraManifests | array | - | Chart configuration parameter |
No schema parameters match your search
Try searching for a different keyword or reset the filter.