FAQ¶
Setup¶
What Kubernetes distros are supported?
Depends on whether you enable Istio Ambient. See the shopping list and Ingress & Security in prerequisites.
What are the hardware requirements?
Charmarr has more overhead than a simple Docker Compose setup. Kubernetes and Juju add resource consumption. As someone smart once said, there's no free lunch. Charmarr's benefits come with a price to pay.
Minimum: 8 GB RAM, 4 vCPUs. More is better, especially during initial deployment.
Can I run Charmarr on a Raspberry Pi?
Untested. Theoretically possible on a Pi 5 with sufficient RAM, but expect performance constraints. The initial deployment is resource-intensive. If you try it, let me know how it goes.
Storage¶
Why do I need shared storage?
Shared storage enables hardlinks between download clients and media managers. When qBittorrent finishes downloading, Radarr/Sonarr can hardlink the file to your media library instead of copying it. This is instant and uses no extra disk space. See Storage for details.
What are hardlinks?
A hardlink is a filesystem feature where two filenames point to the same data on disk. Unlike copies, hardlinks use no additional space. Charmarr uses hardlinks to move completed downloads to your media library instantly without duplicating files.
Can I use my existing NFS share?
Yes. Configure the storage charm with backend-type=native-nfs and point it to your NFS server. See Storage for configuration.
One caveat: don't run the NFS server on the same node as Charmarr. Loopback NFS mounts can cause deadlocks.
Networking¶
Do I need a VPN subscription?
Recommended, but not required. Charmarr works best with a WireGuard-compatible VPN for traffic anonymization. ProtonVPN is recommended. See VPN Provider for supported providers.
To run without a VPN, set unsafe-mode to true for qBittorrent and SABnzbd. This is intentionally made hard because it's discouraged.
Manual Deploy:
Quick Deploy:
After deployment, remove the VPN relations and configure unsafe mode:
juju remove-relation gluetun qbittorrent
juju remove-relation gluetun sabnzbd
juju remove-relation gluetun prowlarr
juju config qbittorrent unsafe-mode=true
juju config sabnzbd unsafe-mode=true
Without a VPN, your real IP is exposed to torrent trackers and usenet providers.
Can I use OpenVPN instead of WireGuard?
Not officially. WireGuard is the supported protocol. However, you can use the custom-overrides config to enter override mode, which bypasses WireGuard validation and lets you pass arbitrary environment variables to Gluetun, including OpenVPN credentials.
Note that unlike the WireGuard private key (stored as a Juju secret, encrypted at rest), custom-overrides is plain text charm config. Credentials passed here are not encrypted.
See Quick Deploy - VPN and Manual Deploy - VPN Gateway for configuration examples.
Do I need the service mesh?
Probably not. It's enterprise-level network hardening made as simple as it can get for homelab use. Do I need it? Most likely not. But homelab is not a place where one does things one needs, it's a place where one does things one wants and can. Does Charmarr make service mesh accessible to any homelab user? Absolutely.
Istio is disabled by default. Enable with enable_istio = true and enable_mesh = true in Quick Deploy after checking the Compatibility Checklist. Charmarr works fine without it at homelab level.
Why include it? Partly to dogfood my own project from work, but also to expose it to a wider audience who are curious enough to try it. See Networking for what it does.
What happens if my VPN connection drops?
A two-way killswitch protects you. If the VPN drops, Gluetun's internal firewall blocks traffic. If the Gluetun pod dies, Kubernetes NetworkPolicies block traffic. Your real IP is never exposed. See Networking for details.
Apps¶
How do I access the web UIs?
With Istio ingress, each app is accessible via the ingress gateway. The URLs follow this pattern:
- Radarr:
http://<ARR_INGRESS_IP>/radarr - Sonarr:
http://<ARR_INGRESS_IP>/sonarr - Prowlarr:
http://<ARR_INGRESS_IP>/prowlarr - qBittorrent:
http://<ARR_INGRESS_IP>/qbittorrent - Plex:
http://<PLEX_INGRESS_IP> - Overseerr:
http://<OVERSEERR_INGRESS_IP>
The ingress port defaults to 80. If you changed it via ingress-port, append it to the URL (e.g., http://<IP>:8080/radarr).
Path prefixes default to the Juju app name. If you deployed with a custom name (e.g., radarr-4k), the path is /<app-name>. Override with the ingress-path config.
See Post-Deploy for details on finding ingress IPs. If you're not using Istio, find the URLs based on your ingress setup.
Can I add more Radarr/Sonarr instances?
Yes. Deploy additional instances with unique names and variants. For example:
See Manual Deploy for details.
What are my qBittorrent credentials?
Credentials are auto-created by the charm and stored as Juju secrets. See qBittorrent for how to retrieve them.
Can I use apps that Charmarr doesn't support?
Charmarr uses Juju relations as the single source of truth for declaratively reconciling the system. If you manually add an app or connection, Charmarr will likely remove it during the next reconciliation cycle. This is a conscious design decision to keep Charmarr robust and predictable.
Want to see your favorite *arr charmed? Open an issue or contribute a charm yourself!
Migration¶
Can I migrate from Docker Compose?
Yes. Charmarr delivers a complex architecture with simplicity. Setup and maintenance should be easier than managing Docker Compose files manually. However, migration paths from existing setups are not yet documented or tested.
Can I use my existing media library?
Theoretically, yes. If your existing media folder follows the TRaSH Guides folder structure (/data/media/movies, /data/media/tv, etc.), Charmarr should work with it. The charms add root folders additively and don't delete existing content.
The recommended approach:
- Deploy Charmarr and let it create the folder structure
- Copy your existing media into the appropriate folders
- Use Radarr/Sonarr's Library Import feature to add existing media
This is theoretical and expected behavior but currently untested. Proceed with caution and keep backups.
Troubleshooting¶
Why is my CPU usage high during initial deployment?
Quick Deploy throws many requests at the Juju controller simultaneously. This causes temporary CPU spikes. Once the deployment settles, CPU usage drops significantly. This is normal.
Manual Deploy should have lower CPU usage since it's a step-by-step process.
My initial tofu apply misbehaved. What do I do?
The easiest solution is to destroy and reapply:
Charmarr follows a reconciliation pattern, so the order of connections shouldn't matter. However, tofu apply throws all connections at the Juju controller at once, which can occasionally cause unexpected states. A fresh apply usually resolves this.
An app is stuck in an error state. What do I do?
First, check the logs:
If the error makes sense, address it. If not, delete the pod and let Kubernetes recreate it. Pods are ephemeral by design, deleting them is safe.
If the issue persists, open an issue with the logs.