Updated docs

2024-03-13 15:43:13 +01:00
parent f99728342b
commit a0597889c3
5 changed files with 215 additions and 147 deletions
@@ -0,0 +1,54 @@
+---
+title: Basic Example
+---
+
+This example does the following:
+
+- Runs a jellyfin server and exposes it to the internet with HTTPS support.
+- Runs the transmission torrent client through a vpn
+- Runs all "*Arrs" supported by this module
+
+```nix {.numberLines}
+  nixarr = {
+    enable = true;
+    # These two values are also the default, but you can set them to whatever
+    # else you want
+    # WARNING: Do _not_ set them to `/home/user/whatever`, it will not work!
+    mediaDir = "/data/media";
+    stateDir = "/data/media/.state/nixarr";
+
+    vpn = {
+      enable = true;
+      # WARNING: This file must _not_ be in the config git directory
+      # You can usually get this wireguard file from your VPN provider
+      wgConf = "/data/.secret/wg.conf";
+    };
+
+    jellyfin = {
+      enable = true;
+      # These options set up a nginx HTTPS reverse proxy, so you can access
+      # Jellyfin on your domain with HTTPS
+      expose.https = {
+        enable = true;
+        domainName = "your.domain.com";
+        acmeMail = "your@email.com"; # Required for ACME-bot
+      };
+    };
+
+    transmission = {
+      enable = true;
+      vpn.enable = true;
+      peerPort = 50000; # Set this to the port forwarded by your VPN
+    };
+
+    # It is possible for this module to run the *Arrs through a VPN, but it
+    # is generally not recommended, as it can cause rate-limiting issues.
+    bazarr.enable = true;
+    lidarr.enable = true;
+    prowlarr.enable = true;
+    radarr.enable = true;
+    readarr.enable = true;
+    sonarr.enable = true;
+  };
+```
+
@@ -0,0 +1,91 @@
+---
+title: Example Configuration where Port Forwarding is not an Option
+---
+
+An example where port forwarding is not an option. This is useful if,
+for example, you're living in a dorm that does not allow it. This
+example does the following:
+
+- Runs Jellyfin and exposes it to the internet on a set port
+- Starts openssh and runs it through the VPN so that it can be accessed
+  outside your home network
+- Runs all the supported "*Arrs"
+
+**Warning:** This is largely untested ATM!
+
+```nix {.numberLines}
+  nixarr = {
+    enable = true;
+
+    vpn = {
+      enable = true;
+      wgConf = "/data/.secret/wg.conf";
+    };
+
+    jellyfin = {
+      enable = true;
+      vpn.enable = true;
+
+      # Access the Jellyfin web-ui from the internet.
+      # Get this port from your VPN provider
+      expose.vpn = {
+        enable = true;
+        port = 12345;
+      };
+    };
+
+    # Setup SSH service that runs through VPN.
+    # Lets you connect through ssh from the internet without having access to
+    # port forwarding
+    openssh.expose.vpn.enable = true;
+
+    transmission = {
+      enable = true;
+      vpn.enable = true;
+      peerPort = 50000; # Set this to the port forwarded by your VPN
+    };
+
+    bazarr.enable = true;
+    sonarr.enable = true;
+    radarr.enable = true;
+    prowlarr.enable = true;
+    readarr.enable = true;
+    lidarr.enable = true;
+  };
+
+  # The `openssh.vpn.enable` option does not enable openssh, so we do that here:
+  # We disable password authentication as it's generally insecure.
+  services.openssh = {
+    enable = true;
+    settings.PasswordAuthentication = false;
+    # Get this port from your VPN provider
+    ports = [ 54321 ]
+  };
+  # Adds your public keys as trusted devices
+  users.extraUsers.username.openssh.authorizedKeys.keyFiles = [
+    ./path/to/public/key/machine.pub}
+  ];
+```
+
+This example uses SSH tunneling to expose most of your services. See the
+[expose](/wiki/expose) wiki page for more info on how to safely access
+your services.
+
+In this example, you don't have access to any services without being on your
+home network or accessing them through localhost. If you have SSH setup you
+can use SSH tunneling. Simply run:
+
+```sh
+  ssh -N user@ip \
+    -L 6001:localhost:9091 \
+    -L 6002:localhost:9696 \
+    -L 6003:localhost:8989 \
+    -L 6004:localhost:7878 \
+    -L 6005:localhost:8686 \
+    -L 6006:localhost:8787 \
+    -L 6007:localhost:6767
+```
+
+Replace `user` with your user and `ip` with the public ip, or domain if set
+up, of your server. This lets you access the services on `localhost:6001`
+through `localhost:6007`.
@@ -0,0 +1,54 @@
+---
+title: Exposing Services Safely
+---
+
+The concept of "exposing" will in this context mean to access your services
+outside your home network. The simplest and safest way to access your services
+is from inside your home network, please consider if this covers your
+needs. If not, keep reading.
+
+## VPN
+
+The safest way to expose your services is through
+a VPN. I suggest you use [tailscale](https://tailscale.com/) or to setup
+your own VPN [manually with wireguard](https://nixos.wiki/wiki/WireGuard).
+
+## SSH Tunneling
+
+A practically equally safe way to expose your services is with SSH tunneling.
+You will either need to port forward on your router, or [run the openssh
+service through a VPN](/options.html#nixarr.openssh.expose.vpn.enable),
+and port forward through your VPN-provider. Then you can access your services
+from a remote machine using the following command:
+
+```sh
+  ssh -N user@ip \
+    -L 6001:localhost:9091 \
+    -L 6002:localhost:9696 \
+    -L 6003:localhost:8989 \
+    -L 6004:localhost:7878 \
+    -L 6005:localhost:8686 \
+    -L 6006:localhost:8787 \
+    -L 6007:localhost:6767
+```
+
+Replace `user` with your user and `ip` with the public ip, or domain if set
+up, of your server. This lets you access the services on `localhost:6001`
+through `localhost:6007`. [Example 2](/wiki/examples/example-2) has an
+example configuration for this.
+
+**Warning:** Disable password authentication if you use SSH, it's insecure!
+
+## Without Authentication
+
+The most unsafe way, is to expose your services to the internet without SSH
+tunneling or VPN. This lets anyone on the internet connect to your services,
+and you rely solely on the security of said services, not the much more
+robust public key cryptogaphy of the solutions above! While it is not
+recommended, it may be necessary depending on your setup.
+
+The Jellyfin module, helpfully, has options for this, the
+[`nixarr.jellyfin.expose.https.enable`](/options.html#nixarr.jellyfin.expose.https.enable)
+and the
+[`nixarr.jellyfin.expose.vpn.enable`](/options.html#nixarr.jellyfin.expose.vpn.enable)
+options. Read the related documentation for more information.
@@ -7,6 +7,10 @@ This is an index of existing articles:
 - **[Recommended Secrets Management](/wiki/secrets)**
 - **DDNS**
  - **[Njalla](/wiki/ddns/njalla)**
+- **Examples**
+  - **[Basic Example](/wiki/examples/example-1)**
+  - **[Example Configuration where Port Forwading is not an Option](/wiki/examples/example-2)**
+- **[Exposing Services Safely](/wiki/expose)**

 For learning how to setup the "*Arrs", once running, refer to the [servarr
 wiki](https://wiki.servarr.com/)