docs/faq.md

Rama main · réplica de lectura del repositorio original.

# FAQ

## Setup

??? question "What Kubernetes distros are supported?"
    Any conformant distro with a LoadBalancer and a default StorageClass. Canonical K8s is recommended. See the [shopping list](setup/prerequisites.md#manual-setup) in prerequisites. Istio Ambient narrows this further: see [Enabling Istio](security/network.md#enabling-istio).

??? question "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.

??? question "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.

??? question "Can I use OpenTofu instead of Terraform?"
    The HCL modules are valid OpenTofu so `tofu init`/`apply`/`destroy` will usually work. That said, the Juju Terraform provider is third-party and has known intermittent issues under OpenTofu. Charmarr's docs, CI, and support are scoped to Terraform. If OpenTofu misbehaves, switch to Terraform.

## Storage

??? question "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](charms/storage.md) for details.

??? question "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.

??? question "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](setup/quickdeploy.md#storage) for configuration.

    One caveat: don't run the NFS server on the same node as Charmarr. Loopback NFS mounts can cause deadlocks.

## Networking

??? question "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](setup/quickdeploy.md#vpn) 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:**

    ```bash
    juju config qbittorrent unsafe-mode=true
    juju config sabnzbd unsafe-mode=true
    ```

    **Quick Deploy:**

    After deployment, remove the VPN relations and configure unsafe mode:

    ```bash
    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.**

??? question "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](setup/quickdeploy.md#vpn) and [Manual Deploy - VPN Gateway](setup/manual.md#vpn-gateway) for configuration examples.

??? question "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 and Charmarr ships with Traefik instead. Turning it on is a single `enable_istio = true`, but the cluster has to be able to take it: see [Enabling Istio](security/network.md#enabling-istio). 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](security/network.md) for what it does.

??? question "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](security/network.md) for details.

## Apps

??? question "How do I access the web UIs?"
    Each app is reachable through its ingress gateway. With the default Traefik gateways, the path is `/<model>-<app>`:

    - Radarr: `http://<ARR_INGRESS_IP>/charmarr-radarr`
    - Sonarr: `http://<ARR_INGRESS_IP>/charmarr-sonarr`
    - Prowlarr: `http://<ARR_INGRESS_IP>/charmarr-prowlarr`
    - qBittorrent: `http://<ARR_INGRESS_IP>/charmarr-qbittorrent`
    - Plex: `http://<PLEX_INGRESS_IP>`
    - Seerr: `http://<SEERR_INGRESS_IP>`

    Traefik owns those prefixes, so they change with your model and application names. Under Istio the prefix and port are yours instead, via the `ingress-path` and `ingress-port` config.

    See [Post-Deploy](setup/post-deploy.md) for details on finding ingress IPs.

??? question "Can I add more Radarr/Sonarr instances?"
    Yes. Deploy additional instances with unique names and variants. For example:

    ```bash
    juju deploy radarr-k8s --trust radarr-4k
    juju config radarr-4k variant=4k
    ```

    See [Manual Deploy](setup/manual.md#media-managers) for details.

??? question "What are my qBittorrent credentials?"
    Credentials are auto-created by the charm and stored as Juju secrets. See [qBittorrent](setup/post-deploy.md#qbittorrent-access-optional) for how to retrieve them.

??? question "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](https://github.com/charmarr/charmarr/issues) or contribute a charm yourself!

## Migration

??? question "I'm on Overseerr. How do I move to Seerr?"
    Upstream Overseerr has merged with Jellyseerr into a new project,
    **Seerr**. The `overseerr-k8s` charm is deprecated and will be removed
    in a future release.

    Both charms can coexist on `latest`: set `enable_seerr = true` to
    deploy Seerr alongside your existing Overseerr, follow the
    [migration runbook](migration/overseerr-to-seerr.md) to transfer your
    requests, users, and settings, then set `enable_overseerr = false` to
    decommission Overseerr.

??? question "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.

??? question "Can I use my existing media library?"
    Theoretically, yes. If your existing media folder follows the [TRaSH Guides](https://trash-guides.info/) 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:

    1. Deploy Charmarr and let it create the folder structure
    2. Copy your existing media into the appropriate folders
    3. 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

??? question "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.

??? question "My initial `terraform apply` misbehaved. What do I do?"
    The easiest solution is to destroy and reapply:

    ```bash
    terraform destroy
    terraform apply -auto-approve
    ```

    Charmarr follows a [reconciliation pattern](https://www.chainguard.dev/unchained/the-principle-of-reconciliation), so the order of connections shouldn't matter. However, `terraform apply` throws all connections at the Juju controller at once, which can occasionally cause unexpected states. A fresh apply usually resolves this.

??? question "An app is stuck in an error state. What do I do?"
    First, check the logs:

    ```bash
    kubectl logs -n charmarr deploy/<app-name>
    ```

    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.

    ```bash
    kubectl delete pod -n charmarr -l app.kubernetes.io/name=<app-name>
    ```

    If the issue persists, [open an issue](https://github.com/charmarr/charmarr/issues) with the logs.

??? question "How do I view logs?"
    Use kubectl:

    ```bash
    # App logs
    kubectl logs -n charmarr deploy/<app-name>

    # Charm logs
    kubectl logs -n charmarr deploy/<app-name> -c charm

    # Follow logs in real-time
    kubectl logs -n charmarr deploy/<app-name> -f
    ```