From 681dd8d32fbb4fdb67a4b82125179bd40d03edbd Mon Sep 17 00:00:00 2001 From: Mark Monteiro Date: Tue, 17 Mar 2020 14:21:00 +0100 Subject: [PATCH 01/10] Add recommended extensions to VS Code configuration --- .vscode/extensions.json | 14 ++++++++++++++ 1 file changed, 14 insertions(+) create mode 100644 .vscode/extensions.json diff --git a/.vscode/extensions.json b/.vscode/extensions.json new file mode 100644 index 0000000000..59d9452fed --- /dev/null +++ b/.vscode/extensions.json @@ -0,0 +1,14 @@ +{ + // See https://go.microsoft.com/fwlink/?LinkId=827846 to learn about workspace recommendations. + // Extension identifier format: ${publisher}.${name}. Example: vscode.csharp + + // List of extensions which should be recommended for users of this workspace. + "recommendations": [ + "ms-dotnettools.csharp", + "editorconfig.editorconfig" + ], + // List of extensions recommended by VS Code that should not be recommended for users of this workspace. + "unwantedRecommendations": [ + + ] +} From 751dff09dc6f57be14f071346a79a23f33fa48c5 Mon Sep 17 00:00:00 2001 From: Mark Monteiro Date: Tue, 17 Mar 2020 14:21:24 +0100 Subject: [PATCH 02/10] Add development instructions to README with details on running from source --- README.md | 89 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 89 insertions(+) diff --git a/README.md b/README.md index ea54b8c8b0..74042d8d83 100644 --- a/README.md +++ b/README.md @@ -63,3 +63,92 @@ Most of the translations can be found in the web client but we have several othe Detailed Translation Status + +## Development + +These instructions will help you get set up with a local development environment in order to contribute to this repository. Before you start, please be sure to completely read our [guidelines on development contributions](https://jellyfin.org/docs/general/contributing/development.html). Note that this project is supported on all major operating systems (Windows, Mac and Linux). + +### Prerequisites + +The following software prerequisites are required to be installed locally before the project can be built and executed. + +* [.NET Core 3.1 SDK](https://dotnet.microsoft.com/download) +* [Visual Studio](https://visualstudio.microsoft.com/downloads/) (at least version 2017) or [Visual Studio Code](https://code.visualstudio.com/Download) + +### Cloning the Repository + +After dependencies are installed you will need to clone a local copy of this repository. If you just want to run the server from source you can clone this repository directly, but if you are intending to contribute code changes to the project, you should [set up your own fork](https://jellyfin.org/docs/general/contributing/development.html#set-up-your-copy-of-the-repo) of the repository. The following example shows how you can clone the repository directly over HTTPS. + +```bash +git clone https://github.com/jellyfin/jellyfin.git +``` + +### Installing the Web Client + +By default, the server is configured to host the static files required for the [web client](https://github.com/jellyfin/jellyfin-web) in addition to serving the backend API. before you can run the server, you will need to get a copy of the web client files since they are not included in this repository directly. + +Note that it is also possible to [host the web client separately](#hosting-the-web-client-separately) from the web server with some additional configuration, in which case you can skip this step. + +There are two options to get the files for the web client: + +1. Build them from source following the instructions on the [jellyfin-web repository](https://github.com/jellyfin/jellyfin-web) +2. Get the pre-built files from an existing installation of the server. For example, with a Windows server installation the client files are located here: `C:\Program Files\Jellyfin\Server\jellyfin-web` + +Once you have a copy of the built web client files, you need to copy them into the build output directory of the web server project. For example: `\Jellyfin.Server\bin\Debug\netcoreapp3.1\jellyfin-web` + +### Running The Server + +The following instructions will help you get the project up and running via the command line, or your preferred IDE. + +#### Running With Visual Studio + +To run the project with Visual Studio you can open the Solution (`.sln`) file and then press `F5` to run the server. + +#### Running With Visual Studio Code + +To run the project with Visual Studio Code you will first need to open the repository directory with Visual Studio Code using the `Open Folder...` option. + +Second, you need to [install the recommended extensions for the workspace](https://code.visualstudio.com/docs/editor/extension-gallery#_recommended-extensions). Note that extension recommendations are classified as either "Workspace Recommendations" or "Other Recommendations", but only the "Workspace Recommendations" are required. + +After the required extensions are installed, you can can run the server by pressing `F5`. + +#### Running From The Command Line + +To run the server from the command line you can use the `dotnet run` command. The example below shows how to do this if you have cloned the repository into a directory named `jellyfin` (the default directory name) and should work on all operating systems. + +```bash +cd jellyfin # Move into the repository directory +cd Jellyfin.Server # Move into the server startup project directory +dotnet run # Run the server startup project +``` + +A second option is to build the project and then run the resulting executable file directly. When running the executable directly you can easily add command line options. Add the `--help` flag to list details on all the supported command line options. + +1. Build the project + + ```bash + dotnet build # Build the project + cd bin/Debug/netcoreapp3.1 # Change into the build output directory + ``` + +2. Execute the build output. On Linux, Mac, etc. use `./jellyfin` and on Windows use `jellyfin.exe`. + +### Running The Tests + +This repository also includes several unit test projects that are used to validate functionality as part of a CI process. These are several ways to run these tests: + +1. Run tests from the command line using `dotnet test` +2. Run tests in Visual Studio using the [Test Explorer](https://docs.microsoft.com/en-us/visualstudio/test/run-unit-tests-with-test-explorer) +3. Run individual tests in Visual Studio Code using the associated [CodeLens annotation](https://github.com/OmniSharp/omnisharp-vscode/wiki/How-to-run-and-debug-unit-tests) + +### Advanced Configuration + +The following sections describe some more advanced scenarios for running the server from source that build upon the standard instructions above. + +#### Hosting The Web Client Separately + +It is not necessary to host the frontend web client as part of the backend server. Hosting these two components separately may be useful for front-end developers who would prefer to host the client in a separate webpack development server for a tighter development loop (see the [jellyfin-web](https://github.com/jellyfin/jellyfin-web#getting-started) repo for instructions on how to do this). + +To instruct the server not to host the web content, there is a `nowebcontent` configuration flag that must be set. This can specified using the command line switch `--nowebcontent` or the environment variable `JELLYFIN_NOWEBCONTENT=true`. + +Since this is a common scenario, there is also a separate launch profile defined for Visual Studio called `Jellyfin.Server (nowebcontent)` that can be selected from the 'Start Debugging' dropdown in the main toolbar. From 48f33f9a9669d0a237c85278a0cac3d3240a7c49 Mon Sep 17 00:00:00 2001 From: Mark Monteiro Date: Fri, 20 Mar 2020 12:21:20 +0100 Subject: [PATCH 03/10] Reword prerequisite section so that IDEs are listed as optional --- README.md | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 74042d8d83..d7f2da7900 100644 --- a/README.md +++ b/README.md @@ -70,10 +70,9 @@ These instructions will help you get set up with a local development environment ### Prerequisites -The following software prerequisites are required to be installed locally before the project can be built and executed. +Before the the project can be built, you must first install the [.NET Core 3.1 SDK](https://dotnet.microsoft.com/download) on your system. -* [.NET Core 3.1 SDK](https://dotnet.microsoft.com/download) -* [Visual Studio](https://visualstudio.microsoft.com/downloads/) (at least version 2017) or [Visual Studio Code](https://code.visualstudio.com/Download) +Instructions to run this project from the command line are included here, but you will also need to install an IDE if you want to debug the server while it is running. Any IDE that supports .NET Core development will work, but explicit instructions for [Visual Studio](https://visualstudio.microsoft.com/downloads/) (at least 2017) and [Visual Studio Code](https://code.visualstudio.com/Download) are included here. ### Cloning the Repository From cd34115e9981185e6a4f286d81f10160990e3f7c Mon Sep 17 00:00:00 2001 From: Mark Monteiro Date: Fri, 20 Mar 2020 12:35:01 +0100 Subject: [PATCH 04/10] Remove duplicate text Co-Authored-By: artiume --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index d7f2da7900..95659e8a8c 100644 --- a/README.md +++ b/README.md @@ -70,7 +70,7 @@ These instructions will help you get set up with a local development environment ### Prerequisites -Before the the project can be built, you must first install the [.NET Core 3.1 SDK](https://dotnet.microsoft.com/download) on your system. +Before the project can be built, you must first install the [.NET Core 3.1 SDK](https://dotnet.microsoft.com/download) on your system. Instructions to run this project from the command line are included here, but you will also need to install an IDE if you want to debug the server while it is running. Any IDE that supports .NET Core development will work, but explicit instructions for [Visual Studio](https://visualstudio.microsoft.com/downloads/) (at least 2017) and [Visual Studio Code](https://code.visualstudio.com/Download) are included here. From 3fd245ba8789e862a67f41d5c481ccab6a49fb33 Mon Sep 17 00:00:00 2001 From: Mark Monteiro Date: Sat, 21 Mar 2020 23:03:00 +0100 Subject: [PATCH 05/10] Add instructions for serving content over HTTPS --- README.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/README.md b/README.md index 95659e8a8c..7b08723d6a 100644 --- a/README.md +++ b/README.md @@ -151,3 +151,9 @@ It is not necessary to host the frontend web client as part of the backend serve To instruct the server not to host the web content, there is a `nowebcontent` configuration flag that must be set. This can specified using the command line switch `--nowebcontent` or the environment variable `JELLYFIN_NOWEBCONTENT=true`. Since this is a common scenario, there is also a separate launch profile defined for Visual Studio called `Jellyfin.Server (nowebcontent)` that can be selected from the 'Start Debugging' dropdown in the main toolbar. + +#### Serving Over HTTPS + +The .NET Core SDK includes a certificate that can be used to serve content over HTTPS while developing. When running from Visual Studio, VS Code, or using `dotnet run`, this behavior is automatically enabled by setting the environment variable `ASPNETCORE_ENVIRONMENT=Development` and you can access the HTTPS version of the site at https://localhost:8920. + +By default, the development certificate is not trusted so you will see a security warning when you browse to the site over HTTPS. On most browsers you can easily bypass this warning and continue to the site. However, if you want to get rid of the warning, you can configure your machine to trust the development certificate by following the instructions in the [ASP.NET Core documentation](https://docs.microsoft.com/en-us/aspnet/core/security/enforcing-ssl#trust-the-aspnet-core-https-development-certificate-on-windows-and-macos). From 499deb4fe591731f4c8542cf8afa8f93e7e68f8a Mon Sep 17 00:00:00 2001 From: Mark Monteiro Date: Fri, 3 Apr 2020 20:05:58 -0400 Subject: [PATCH 06/10] Add section describing the repository with a link to contribution docs --- README.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 7b08723d6a..2e8687bdc3 100644 --- a/README.md +++ b/README.md @@ -64,7 +64,11 @@ Most of the translations can be found in the web client but we have several othe Detailed Translation Status -## Development +## Jellyfin Server + +This repository contains the code for Jellyfin's back-end server. Note that this is only one of many projects/repositories under the Jellyfin GitHub [organization](https://github.com/jellyfin/). If you want to contribute, can start by checking out our [documentation](https://jellyfin.org/docs/general/contributing/index.html) to see what to work on. + +## Server Development These instructions will help you get set up with a local development environment in order to contribute to this repository. Before you start, please be sure to completely read our [guidelines on development contributions](https://jellyfin.org/docs/general/contributing/development.html). Note that this project is supported on all major operating systems (Windows, Mac and Linux). From 7ced986e0b73d45b243ede518f9166464af3de0d Mon Sep 17 00:00:00 2001 From: Mark Monteiro Date: Fri, 3 Apr 2020 20:06:53 -0400 Subject: [PATCH 07/10] Remove section on serving over HTTPS This functionality has not been merged yet --- README.md | 6 ------ 1 file changed, 6 deletions(-) diff --git a/README.md b/README.md index 2e8687bdc3..de5ea3f301 100644 --- a/README.md +++ b/README.md @@ -155,9 +155,3 @@ It is not necessary to host the frontend web client as part of the backend serve To instruct the server not to host the web content, there is a `nowebcontent` configuration flag that must be set. This can specified using the command line switch `--nowebcontent` or the environment variable `JELLYFIN_NOWEBCONTENT=true`. Since this is a common scenario, there is also a separate launch profile defined for Visual Studio called `Jellyfin.Server (nowebcontent)` that can be selected from the 'Start Debugging' dropdown in the main toolbar. - -#### Serving Over HTTPS - -The .NET Core SDK includes a certificate that can be used to serve content over HTTPS while developing. When running from Visual Studio, VS Code, or using `dotnet run`, this behavior is automatically enabled by setting the environment variable `ASPNETCORE_ENVIRONMENT=Development` and you can access the HTTPS version of the site at https://localhost:8920. - -By default, the development certificate is not trusted so you will see a security warning when you browse to the site over HTTPS. On most browsers you can easily bypass this warning and continue to the site. However, if you want to get rid of the warning, you can configure your machine to trust the development certificate by following the instructions in the [ASP.NET Core documentation](https://docs.microsoft.com/en-us/aspnet/core/security/enforcing-ssl#trust-the-aspnet-core-https-development-certificate-on-windows-and-macos). From 644ddfad00e2a4b42da89badca70474aef2464ff Mon Sep 17 00:00:00 2001 From: Mark Monteiro Date: Mon, 6 Apr 2020 19:36:44 -0400 Subject: [PATCH 08/10] Apply code review changes --- README.md | 24 ++++++++++++++---------- 1 file changed, 14 insertions(+), 10 deletions(-) diff --git a/README.md b/README.md index de5ea3f301..d74ec47669 100644 --- a/README.md +++ b/README.md @@ -66,17 +66,17 @@ Most of the translations can be found in the web client but we have several othe ## Jellyfin Server -This repository contains the code for Jellyfin's back-end server. Note that this is only one of many projects/repositories under the Jellyfin GitHub [organization](https://github.com/jellyfin/). If you want to contribute, can start by checking out our [documentation](https://jellyfin.org/docs/general/contributing/index.html) to see what to work on. +This repository contains the code for Jellyfin's backend server. Note that this is only one of many projects under the Jellyfin GitHub [organization](https://github.com/jellyfin/) on GitHub. If you want to contribute, you can start by checking out our [documentation](https://jellyfin.org/docs/general/contributing/index.html) to see what to work on. ## Server Development -These instructions will help you get set up with a local development environment in order to contribute to this repository. Before you start, please be sure to completely read our [guidelines on development contributions](https://jellyfin.org/docs/general/contributing/development.html). Note that this project is supported on all major operating systems (Windows, Mac and Linux). +These instructions will help you get set up with a local development environment in order to contribute to this repository. Before you start, please be sure to completely read our [guidelines on development contributions](https://jellyfin.org/docs/general/contributing/development.html). Note that this project is supported on all major operating systems except FreeBSD, which is still incompatible. ### Prerequisites Before the project can be built, you must first install the [.NET Core 3.1 SDK](https://dotnet.microsoft.com/download) on your system. -Instructions to run this project from the command line are included here, but you will also need to install an IDE if you want to debug the server while it is running. Any IDE that supports .NET Core development will work, but explicit instructions for [Visual Studio](https://visualstudio.microsoft.com/downloads/) (at least 2017) and [Visual Studio Code](https://code.visualstudio.com/Download) are included here. +Instructions to run this project from the command line are included here, but you will also need to install an IDE if you want to debug the server while it is running. Any IDE that supports .NET Core development will work, but two options are recent versions of [Visual Studio](https://visualstudio.microsoft.com/downloads/) (at least 2017) and [Visual Studio Code](https://code.visualstudio.com/Download). ### Cloning the Repository @@ -88,16 +88,20 @@ git clone https://github.com/jellyfin/jellyfin.git ### Installing the Web Client -By default, the server is configured to host the static files required for the [web client](https://github.com/jellyfin/jellyfin-web) in addition to serving the backend API. before you can run the server, you will need to get a copy of the web client files since they are not included in this repository directly. +The server is configured to host the static files required for the [web client](https://github.com/jellyfin/jellyfin-web) in addition to serving the backend by default. Before you can run the server, you will need to get a copy of the web client since they are not included in this repository directly. Note that it is also possible to [host the web client separately](#hosting-the-web-client-separately) from the web server with some additional configuration, in which case you can skip this step. -There are two options to get the files for the web client: +There are three options to get the files for the web client. -1. Build them from source following the instructions on the [jellyfin-web repository](https://github.com/jellyfin/jellyfin-web) -2. Get the pre-built files from an existing installation of the server. For example, with a Windows server installation the client files are located here: `C:\Program Files\Jellyfin\Server\jellyfin-web` +1. Download one of the finished builds from the [Azure DevOps pipeline](https://dev.azure.com/jellyfin-project/jellyfin/_build?definitionId=11). You can download the build for a specific release by looking at the [branches tab](https://dev.azure.com/jellyfin-project/jellyfin/_build?definitionId=11&_a=summary&repositoryFilter=6&view=branches) of the pipelines page. +2. Build them from source following the instructions on the [jellyfin-web repository](https://github.com/jellyfin/jellyfin-web) +3. Get the pre-built files from an existing installation of the server. For example, with a Windows server installation the client files are located at `C:\Program Files\Jellyfin\Server\jellyfin-web` -Once you have a copy of the built web client files, you need to copy them into the build output directory of the web server project. For example: `\Jellyfin.Server\bin\Debug\netcoreapp3.1\jellyfin-web` +Once you have a copy of the built web client files, you need to copy them into the build output directory of the web server project. + +* `/jellyfin-web` +* `/Jellyfin.Server/bin/Debug/netcoreapp3.1/jellyfin-web` ### Running The Server @@ -138,7 +142,7 @@ A second option is to build the project and then run the resulting executable fi ### Running The Tests -This repository also includes several unit test projects that are used to validate functionality as part of a CI process. These are several ways to run these tests: +This repository also includes unit tests that are used to validate functionality as part of a CI pipeline on Azure. There are several ways to run these tests. 1. Run tests from the command line using `dotnet test` 2. Run tests in Visual Studio using the [Test Explorer](https://docs.microsoft.com/en-us/visualstudio/test/run-unit-tests-with-test-explorer) @@ -150,7 +154,7 @@ The following sections describe some more advanced scenarios for running the ser #### Hosting The Web Client Separately -It is not necessary to host the frontend web client as part of the backend server. Hosting these two components separately may be useful for front-end developers who would prefer to host the client in a separate webpack development server for a tighter development loop (see the [jellyfin-web](https://github.com/jellyfin/jellyfin-web#getting-started) repo for instructions on how to do this). +It is not necessary to host the frontend web client as part of the backend server. Hosting these two components separately may be useful for frontend developers who would prefer to host the client in a separate webpack development server for a tighter development loop. See the [jellyfin-web](https://github.com/jellyfin/jellyfin-web#getting-started) repo for instructions on how to do this. To instruct the server not to host the web content, there is a `nowebcontent` configuration flag that must be set. This can specified using the command line switch `--nowebcontent` or the environment variable `JELLYFIN_NOWEBCONTENT=true`. From 0a9b7c868e798769196e2c93e4359f176f2ceb12 Mon Sep 17 00:00:00 2001 From: Mark Monteiro Date: Tue, 7 Apr 2020 10:42:16 -0400 Subject: [PATCH 09/10] Specify the directory for jellyfin-web correctly --- README.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index d74ec47669..6007aa3cb9 100644 --- a/README.md +++ b/README.md @@ -98,10 +98,11 @@ There are three options to get the files for the web client. 2. Build them from source following the instructions on the [jellyfin-web repository](https://github.com/jellyfin/jellyfin-web) 3. Get the pre-built files from an existing installation of the server. For example, with a Windows server installation the client files are located at `C:\Program Files\Jellyfin\Server\jellyfin-web` -Once you have a copy of the built web client files, you need to copy them into the build output directory of the web server project. +Once you have a copy of the built web client files, you need to copy them into a specific directory. -* `/jellyfin-web` -* `/Jellyfin.Server/bin/Debug/netcoreapp3.1/jellyfin-web` +> `/Mediabrowser.WebDashboard/jellyfin-web` + +As part of the build process, this folder will be copied to the build output directory, where it can be accessed by the server. ### Running The Server From 6039c6200f78e6ae174d33efc3c3437cb94fa633 Mon Sep 17 00:00:00 2001 From: Mark Monteiro Date: Sun, 19 Apr 2020 18:18:53 -0400 Subject: [PATCH 10/10] Update instructions for running with the dotnet cli --- README.md | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 6007aa3cb9..7a81db6552 100644 --- a/README.md +++ b/README.md @@ -125,9 +125,8 @@ After the required extensions are installed, you can can run the server by press To run the server from the command line you can use the `dotnet run` command. The example below shows how to do this if you have cloned the repository into a directory named `jellyfin` (the default directory name) and should work on all operating systems. ```bash -cd jellyfin # Move into the repository directory -cd Jellyfin.Server # Move into the server startup project directory -dotnet run # Run the server startup project +cd jellyfin # Move into the repository directory +dotnet run --project Jellyfin.Server # Run the server startup project ``` A second option is to build the project and then run the resulting executable file directly. When running the executable directly you can easily add command line options. Add the `--help` flag to list details on all the supported command line options.