Aleksei SviridkinandClaude
4a45dc998a
Add comprehensive troubleshooting documentation for inotify instance limit
errors that cause Jellyfin crashes in environments with many containers.
Changes:
- Add Troubleshooting section to README with inotify limits explanation
- Document proper solution: increase kernel limits via sysctl
- Provide workaround for managed clusters: DOTNET_USE_POLLING_FILE_WATCHER
- Add commented example in values.yaml for easy copy-paste
- Update Chart version from 2.5.0 to 2.5.1
- Add Artifact Hub changelog annotation
The proper solution is to increase inotify limits on Kubernetes nodes:
```bash
sysctl -w fs.inotify.max_user_instances=512
```
For managed Kubernetes where node access is restricted, users can use the
polling workaround (less efficient but functional):
```yaml
jellyfin:
env:
- name: DOTNET_USE_POLLING_FILE_WATCHER
value: "1"
```
This addresses the crash issue mentioned in #64.
Fixes: #64
Co-Authored-By: Claude <noreply@anthropic.com>
Signed-off-by: Aleksei Sviridkin <f@lex.la>
129 lines
3.4 KiB
Go Template
129 lines
3.4 KiB
Go Template
{{ template "chart.header" . }}
|
|
{{ template "chart.deprecationWarning" . }}
|
|
|
|
{{ template "chart.badgesSection" . }}
|
|
|
|
{{ template "chart.description" . }}
|
|
|
|
{{ template "chart.homepageLine" . }}
|
|
|
|
## Steps to Use a Helm Chart
|
|
|
|
### 1. Add a Helm Repository
|
|
|
|
Helm repositories contain collections of charts. You can add an existing repository using the following command:
|
|
|
|
```bash
|
|
helm repo add jellyfin https://jellyfin.github.io/jellyfin-helm
|
|
```
|
|
|
|
### 2. Install the Helm Chart
|
|
|
|
To install a chart, use the following command:
|
|
|
|
```bash
|
|
helm install my-jellyfin jellyfin/jellyfin
|
|
```
|
|
|
|
### 3. View the Installation
|
|
|
|
You can check the status of the release using:
|
|
|
|
```bash
|
|
helm status my-jellyfin
|
|
```
|
|
|
|
## Customizing the Chart
|
|
|
|
Helm charts come with default values, but you can customize them by using the --set flag or by providing a custom values.yaml file.
|
|
|
|
### 1. Using --set to Override Values
|
|
```bash
|
|
helm install my-jellyfin jellyfin/jellyfin --set key1=value1,key2=value2
|
|
```
|
|
|
|
### 2. Using a values.yaml File
|
|
You can create a custom values.yaml file and pass it to the install command:
|
|
|
|
```bash
|
|
helm install my-jellyfin jellyfin/jellyfin -f values.yaml
|
|
```
|
|
|
|
{{ template "chart.maintainersSection" . }}
|
|
|
|
{{ template "chart.sourcesSection" . }}
|
|
|
|
{{ template "chart.requirementsSection" . }}
|
|
|
|
{{ template "chart.valuesSection" . }}
|
|
|
|
{{ template "helm-docs.versionFooter" . }}
|
|
|
|
## Hardware acceleration
|
|
|
|
Out of the box the pod does not have the necessary permissions to enable hardware acceleration (HWA) in Jellyfin.
|
|
Adding the following Helm values should make it enable you to use hardware acceleration features.
|
|
Some settings may need to be tweaked depending on the type of device (Intel/AMD/NVIDIA/...) and your container runtime.
|
|
|
|
Please refer to the Jellyfin upstream documentation for more information about hardware acceleration: <https://jellyfin.org/docs/general/administration/hardware-acceleration/>
|
|
|
|
```yaml
|
|
securityContext:
|
|
capabilities:
|
|
add:
|
|
- "SYS_ADMIN"
|
|
drop:
|
|
- "ALL"
|
|
privileged: false
|
|
|
|
extraVolumes:
|
|
- name: hwa
|
|
hostPath:
|
|
path: /dev/dri
|
|
|
|
extraVolumeMounts:
|
|
- name: hwa
|
|
mountPath: /dev/dri
|
|
```
|
|
|
|
## Troubleshooting
|
|
|
|
### inotify Instance Limit Reached
|
|
|
|
**Problem:** Jellyfin crashes with error:
|
|
```
|
|
System.IO.IOException: The configured user limit (128) on the number of inotify instances has been reached
|
|
```
|
|
|
|
**Root cause:** The Linux kernel has a limit on inotify instances (file system watchers) per user. Jellyfin uses inotify to monitor media libraries for changes.
|
|
|
|
**Proper solution (recommended):**
|
|
|
|
Increase the inotify limit on the Kubernetes nodes:
|
|
|
|
```bash
|
|
# Temporary (until reboot)
|
|
sysctl -w fs.inotify.max_user_instances=512
|
|
|
|
# Permanent
|
|
echo "fs.inotify.max_user_instances=512" >> /etc/sysctl.conf
|
|
sysctl -p
|
|
```
|
|
|
|
Recommended values:
|
|
- `fs.inotify.max_user_instances`: 512 or higher
|
|
- `fs.inotify.max_user_watches`: 524288 or higher (if you have large media libraries)
|
|
|
|
**Workaround (if you cannot modify host settings):**
|
|
|
|
If you're running on a managed Kubernetes cluster where you cannot modify node-level settings, you can force Jellyfin to use polling instead of inotify. **Note: This is less efficient and may increase CPU usage and delay change detection.**
|
|
|
|
```yaml
|
|
jellyfin:
|
|
env:
|
|
- name: DOTNET_USE_POLLING_FILE_WATCHER
|
|
value: "1"
|
|
```
|
|
|
|
This workaround disables inotify file watching in favor of periodic polling, which doesn't require inotify instances but is less efficient.
|