diff --git a/docs/general/clients/jellyfin-vue.md b/docs/general/clients/jellyfin-vue.md new file mode 100644 index 000000000..8c1fde0f9 --- /dev/null +++ b/docs/general/clients/jellyfin-vue.md @@ -0,0 +1,185 @@ +--- +uid: jellyfin-vue +title: Jellyfin Vue +--- +## + +[Jellyfin Vue](https://github.com/jellyfin/jellyfin-vue) is an experimental, alternative browser-based web client for Jellyfin written using Vue.js. + +:::note +Jellyfin Vue is not planned or targeted to replace the main Jellyfin Web client, and is not feature-complete. +::: + +Below are concise instructions to get your own instance of Jellyfin Vue up and running. +If you identify with at least one of the following options: + +* Want to try it quickly for the first time +* Are not sure whether you want to deploy your own instance +* Don't need to go beyond user customization to change app-wide behaviour. +* Have a working HTTPS setup. + +You're probably better using [our hosted instance](https://jf-vue.pages.dev). +More info at [Jellyfin Vue's repository](https://github.com/jellyfin/jellyfin-vue). + +# Deployment # + +:::caution +Since Jellyfin Vue is just an interface for a Jellyfin server, all of these instructions assume that you already have a server up and running. +[Set it up now](../installation/index.mdx) if you haven't already. +::: + +## RECOMMENDED: Using Docker ## + +* In case you don't have Docker, follow [the official installation guide](https://docs.docker.com/engine/install) first. +Learning about [Compose](https://docs.docker.com/compose) is also recommended. +* Docker Compose is now shipped with Docker, so you don't need to install it. It's recommended that you uninstall +the old `docker-compose`. +* [`version` key is deprecated](https://docs.docker.com/reference/compose-file/version-and-name/#version-top-level-element-obsolete) +in Docker Compose, hence not included below. + +We're going to use the following `docker-compose.yml` as a starting point: + +```yaml +services: + jellyfin_vue: + container_name: jellyfin_vue + image: ghcr.io/jellyfin/jellyfin-vue:unstable + restart: always + ports: + - 8080:80 + labels: + - "com.centurylinklabs.watchtower.enable=true" + + watchtower: + container_name: watchtower + image: ghcr.io/containrrr/watchtower + volumes: + - /var/run/docker.sock:/var/run/docker.sock + environment: + TZ: Europe/Madrid + WATCHTOWER_CLEANUP: 1 + WATCHTOWER_INCLUDE_RESTARTING: 1 + WATCHTOWER_POLL_INTERVAL: 60 + WATCHTOWER_LABEL_ENABLE: 1 + # Needed so watchtower doesn't restart-loop when updating itself + restart: on-failure +``` + + + +:::success +Getting things up and running is as easy as doing `docker compose up -d` with your terminal +located where the `docker-compose.yml` file is. +::: + +With this compose file: + +* Jellyfin Vue will be accessible on `8080` port of the machine that's running the containers +* Watchtower takes care of updating the container to the latest commit available on the [repository](https://github.com/jellyfin/jellyfin-vue). +This is a good idea because: + * As of now, stable releases don't exist and there have only been prereleases that don't necessarily meet a quality criteria, but + [major development milestones](https://jellyfin.org/posts/vue-vue3/). + * Only the latest `unstable` image is supported. + +After accessing the instance in your browser of choice, you'll be prompted to add a server. You can use your own server or our demo +instance, located at `https://demo.jellyfin.org/stable` + +:::note +The server address you need to type is relative to the device you're accessing Jellyfin Vue. For instance, +if your Jellyfin Server is located at 192.168.0.10 and you have deployed Jellyfin Vue to that same server, +and your client is 192.168.0.20, the address you need to input is `http://192.168.0.10`, not +`http://127.0.0.1` or `http://localhost`. + +You can learn more about how the connection to your server works +[in Jellyfin's Vue repository privacy disclaimer](https://github.com/jellyfin/jellyfin-vue#privacy-disclaimer-) +::: + +### Using environment variables ### + +This is an example of how environment variables are set in the container by adding the +following keys to the `jellyfin_vue` definition in [the above `docker-compose.yml`](#recommended-using-docker): + +```yaml +environment: + HISTORY_ROUTER_MODE: 1 +``` + +See the [complete reference of environment variables available](https://github.com/jellyfin/jellyfin-vue/wiki/Configuration) +to further customize Jellyfin Vue to your liking at Jellyfin Vue's wiki. + +### Using your own webserver ### + +Since Jellyfin Vue is an SPA web application, you can use any web server to serve it: +Apache, nginx (the one used in Jellyfin's Vue docker image), Traefik, etc... + +If you already have a [reverse proxy](../networking/index.md) set up, do you want to do more complex stuff +that it's out of the scope of this documentation like serving at a subpath, in another subdomain, etc..., +you might want to have Jellyfin Vue served by your own webserver instead of the nginx instance shipped with +the Docker image. + +To achieve that, in the `jellyfin_vue` service definition of the [`docker-compose.yml` shown above](#recommended-using-docker): + +* Remove the `ports` key. +* Add the following keys, **replacing** `_path_` **with the folder** where your web server expects Jellyfin Vue's assets: + +```yaml +network_mode: none +volumes: + - _𝘱𝘢𝘵𝘩_:/dest +# This makes the container do nothing and sleep forever, +# frontend will be copied to _𝘱𝘢𝘵𝘩_ and will be served by your web server +# /setup.sh applies +entrypoint: /bin/sh -c '/setup.sh && rm -rf /dest/* && cp -r /usr/share/nginx/html/* /dest && sleep infinity' + +``` + +This approach: + +* Keeps the client always updated in a hassle-free way, as explained [above](#recommended-using-docker). +* In case you use [environment variables](#using-environment-variables), +they will still be applied. + +## Manually ## + +:::caution +Make sure you understand [the implications](#why-updates-needed) before using these methods first. +None of them are supported by Jellyfin Vue. +::: + +### `docker run` ### + +In case you don't want to use Docker Compose or automated updates, but still use Docker, this command is enough: + +```bash +docker run -d -p 8080:80 ghcr.io/jellyfin/jellyfin-vue:unstable +``` + +### From source / build output ### + +:::info +This might not be necessary if you just want to test a Pull Request. +Check [these instructions instead](../testing/web/index.md) +::: + +:::danger +By default, never trust any assets given by anyone outside the official channels if you can't inspect the source code first. +They might compromise your system or track your activity! +::: + +Since Jellyfin Vue is a web application, using it it's a matter of setting up your own web server +and pointing it to Jellyfin Vue's assets. You can get them: + +* By building your own version from our source. The repository's [wiki](https://github.com/jellyfin/jellyfin-vue/wiki) +has instructions for setting up the development environment. +* By getting them from [GitHub's Actions artifacts](https://github.com/jellyfin/jellyfin-vue/actions). + * Although those artifacts are built in our repository's CI/CD, + **some runs are sourced from Pull Requests created by external contributors that might not be good actors!** + * All artifacts generated by GitHub Actions are [built with provenances](https://github.com/jellyfin/jellyfin-vue/attestations). + * Our official Docker image is built from GitHub Actions and all the process is transparent and can be audited. + +## Other documentation ## + +* The rest of the documentation about Jellyfin Vue can be found on it's [wiki](https://github.com/jellyfin/jellyfin-vue/wiki). + +* You can check [GitHub Packages (GHCR)](https://github.com/jellyfin/jellyfin-vue/pkgs/container/jellyfin-vue) (recommended) +or [DockerHub](https://hub.docker.com/r/jellyfin/jellyfin-vue) for all the tagged Docker images. diff --git a/docs/general/testing/web/index.md b/docs/general/testing/web/index.md index 4160c0e44..e2e66923b 100644 --- a/docs/general/testing/web/index.md +++ b/docs/general/testing/web/index.md @@ -26,3 +26,11 @@ Each pull request of [Jellyfin Web](https://github.com/jellyfin/jellyfin-web) an :::caution Using a development version of clients may lead to data corruption or loss on the server. Please use a dedicated test server and make regular backups of [Jellyfin files](/docs/general/administration/configuration#server-paths). ::: + +:::danger +Although Cloudflare Pages deployments from Pull Requests are built into our CI/CD workflow +in a completely transparent and auditable manner, **some of them may come from external contributors that might not be good actors!**. + +By default, never trust any artifacts given by anyone outside the official channels if you can't inspect the source code first. +They might compromise your system or track your activity! +:::