From 509fd8f6aaa153ace8fa3b2d46fe1dfa622ceaa7 Mon Sep 17 00:00:00 2001 From: Andrew DeMaria Date: Sat, 11 Mar 2017 18:24:32 -0700 Subject: [PATCH] Various documentation improvements - Remove duplicate and outdated INSTALL.md file - Clarity around supported platforms - Misc Signed-off-by: Andrew DeMaria --- INSTALL.md | 111 --------------------------------------- README.md | 13 +++-- documentation/INSTALL.md | 43 ++++++++++++--- 3 files changed, 45 insertions(+), 122 deletions(-) delete mode 100644 INSTALL.md diff --git a/INSTALL.md b/INSTALL.md deleted file mode 100644 index 40f97083..00000000 --- a/INSTALL.md +++ /dev/null @@ -1,111 +0,0 @@ - - -# Installing Libresonic - -This document is designed to explain how to install LibreSonic as a Tomcat module, on a computer running Linux. As the project expands, this guide will also expand to include other operating systems. - -## Installing From Pre-Compiled Package - -### Prerequisites - -In order to install and run Libresonic, you will need: - - * A JDK installation. 1.8.x series of OpenJDK or Oracle JDK 8+ should work. - * A running [Tomcat](http://tomcat.apache.org/) server. If you're unfamiliar with Tomcat, there are many [guides](https://www.linode.com/docs/websites/frameworks/apache-tomcat-on-ubuntu-16-04) on it. - - -### Download Libresonic - -Daily WAR files are built by Jenkins and available [here](https://jenkins.zifnab.net/job/libresonic/), curtesy of [zifnab06](https://github.com/zifnab06). - -1. Download the latest war file: - - wget https://jenkins.zifnab.net/job/libresonic/lastSuccessfulBuild/artifact/.repository/org/libresonic/player/libresonic-main/6.1.beta2/libresonic-main-6.1.beta2.war -O /var/lib/tomcat8/webapps/libresonic.war - - Note that this command copies the war file directly to the Tomcat webapps directory, and renames it to `libresonic.war`. - -2. Create the libresonic directory and assign ownership to the Tomcat system user (if running tomcat as a service): - - mkdir /var/libresonic - chown tomcat8:tomcat8 /var/libresonic/ - -3. Start Tomcat, or restart it if running as a service, as in the example below using Systemd: - - systemctl restart tomcat8.service - - Note that it may take ~30 seconds after the service restarts for Tomcat to fully deploy the app. You can monitor /var/log/tomcat8/catalina.out for the following message: - - INFO: Deployment of web application archive /var/lib/tomcat8/webapps/libresonic.war has finished in 46,192 ms - -4. In your web browser, navigate to `192.0.2.10:8080/libresonic/`, replacing `192.0.2.0` with your server's IP address, or `127.0.0.1` if installing locally. - -## Installing From Source - -### Prerequisites - -In order to build, install, and run Libresonic, you will need: - - * A recent version of [Maven](http://maven.apache.org/). - * A JDK installation. 1.8.x series of OpenJDK or Oracle JDK 8+ should work. - * A running [Tomcat](http://tomcat.apache.org/) server. If you're unfamiliar with Tomcat, there are many [guides](https://www.linode.com/docs/websites/frameworks/apache-tomcat-on-ubuntu-16-04) on it. - -On a Debian-based system, you can install all these prerequisites at once with: - - apt-get update; apt-get install tomcat8 openjdk-7-jdk maven - -### Test Your System - -1. Confirm your Maven installation: - - which mvn - -2. Confirm that the $JAVA_HOME environment variable is set: - - echo $JAVA_HOME - -3. If Java is installed, but the `JAVA_HOME` variable not set, be sure to [set it](http://www.cyberciti.biz/faq/linux-unix-set-java_home-path-variable/) before you continue. - - -### Download and Build Libresonic - -1. Clone the Libresonic repo: - - git clone git://github.com/Libresonic/libresonic.git - cd libresonic - - If you don't have a GitHub account, use https://github.com/Libresonic/libresonic.git instead. - -2. At the time of this writing, we reccomend building from the development branch, as Libresonic has not had a stable release since being forked. - - git checkout develop - -3. Using Maven, build Subsonic: - - mvn package - -4. You should know have a war file: - - ls libresonic-main/target/libresonic.war - libresonic-main/target/libresonic.war - -5. Copy the war file to the Tomcat webapps directory: - - cp libresonic-main/target/libresonic.war /var/lib/tomcat8/webapps - -6. Create the libresonic directory and assign ownership to the Tomcat system user (if running tomcat as a service): - - mkdir /var/libresonic - chown tomcat8:tomcat8 /var/libresonic/ - -7. Start Tomcat, or restart it if running as a service, as in the example below using Systemd: - - systemctl restart tomcat8.service - - Note that it may take ~30 seconds after the service restarts for Tomcat to fully deploy the app. You can monitor /var/log/tomcat8/catalina.out for the following message: - - INFO: Deployment of web application archive /var/lib/tomcat8/webapps/libresonic.war has finished in 46,192 ms - -8. In your web browser, navigate to `192.0.2.10:8080/libresonic/`, replacing `192.0.2.0` with your server's IP address, or `127.0.0.1` if installing locally. \ No newline at end of file diff --git a/README.md b/README.md index bf212d18..dcba1301 100644 --- a/README.md +++ b/README.md @@ -40,8 +40,15 @@ The [Subsonic source code](https://github.com/Libresonic/subsonic-svn) was relea Usage ----- -Libresonic can be downloaded from [Github](https://github.com/Libresonic/libresonic/releases) for personal usage. Packagers can reference the [release repository](https://libresonic.org/release/), but please contact the maintainer or wait until a [stable release policy](https://github.com/Libresonic/libresonic/issues/73) is available. +Libresonic can be downloaded from +[Github](https://github.com/Libresonic/libresonic/releases) for personal usage. +Packagers can also reference the [release repository](https://libresonic.org/release/). -Libresonic is packaged in [WAR format](https://en.wikipedia.org/wiki/WAR_(file_format)), suitable for deployment as a [webapp under Tomcat](https://tomcat.apache.org/tomcat-6.0-doc/deployer-howto.html). Comprehensive install documentation [is pending](https://github.com/Libresonic/libresonic/issues/64). +Please see the [INSTALL document](https://github.com/Libresonic/libresonic/blob/develop/INSTALL.md) for instructions on running Libresonic. -Please see the [INSTALL document](https://github.com/Libresonic/libresonic/blob/develop/INSTALL.md) for instructions on building from source. + +Community +--------- +Please see [Reddit](https://www.reddit.com/r/libresonic) or +[IRC](http://webchat.freenode.net?channels=%23libresonic) for community +discussion. diff --git a/documentation/INSTALL.md b/documentation/INSTALL.md index 3a0f591b..4afae5a0 100644 --- a/documentation/INSTALL.md +++ b/documentation/INSTALL.md @@ -5,25 +5,47 @@ # Installing Libresonic -This document is designed to explain how to install LibreSonic as a Tomcat module, on a computer running Linux. As the project expands, this guide will also expand to include other operating systems. +This document is designed to explain how to run Libresonic. Although the +commands here are tailored to Linux, these steps should be easy to also perform +on Windows. If you find something that could be improved in this documentation, please help +contribute on the github project at [https://github.com/Libresonic/libresonic](https://github.com/Libresonic/libresonic). + +This document aims to provide steps to install Libresonic in a quick fashion. +However, there are other documents detailing specifics on running Libresonic. +It is recommended to also read them after this document but before actually +running Libresonic. To list some of the important ones: + + * [PROXY](PROXY.md) - Recommended if you plan on exposing Libresonic to the internet + * [CONFIGURATION](CONFIGURATION.md) - Documents some startup configurations that cannot be changed in the Libresonic Settings Page + * [DATABASE](DATABASE.md) - Provides guidance on using a database other than HSQL 1.8. Strongly recommended for long term / heavy use. + * [MIGRATE](MIGRATE.md) - Documents upgrading from an old Subsonic installation + * [TRANSCODE](TRANSCODE.md) - Mandatory setup if you want Libresonic to convert between formats on the fly ## Installing From Pre-Compiled Package +Libresonic is packaged in a [WAR format](https://en.wikipedia.org/wiki/WAR_(file_format)). +This format is suitable for any OS running Java. Although the WAR format +typically requires an application container such as +[Tomcat](http://tomcat.apache.org/), Libresonic produces an executable WAR that +can be run standalone. + ### Prerequisites In order to install and run Libresonic, you will need: * A JDK installation. 1.8.x series of OpenJDK or Oracle JDK 8+ should work. - * A running [Tomcat](http://tomcat.apache.org/) server. If you're unfamiliar with Tomcat, there are many [guides](https://www.linode.com/docs/websites/frameworks/apache-tomcat-on-ubuntu-16-04) on it. For debian/ubuntu like distributions, you may need to ensure /etc/default/tomcat8 has the correct JAVA_HOME set. - ### Download Libresonic -Daily WAR files are built by Jenkins and available [here](https://jenkins.zifnab.net/job/libresonic/), curtesy of [zifnab06](https://github.com/zifnab06). +WAR files are available on the [Releases Page](https://github.com/Libresonic/libresonic/releases). Choose either stable or develop. + +### Tomcat Method + +You will need a running [Tomcat](http://tomcat.apache.org/) server. If you're unfamiliar with Tomcat, there are many [guides](https://www.linode.com/docs/websites/frameworks/apache-tomcat-on-ubuntu-16-04) on it. For debian/ubuntu like distributions, you may need to ensure /etc/default/tomcat8 has the correct JAVA\_HOME set. 1. Download the latest war file: - wget https://jenkins.zifnab.net/job/libresonic/lastSuccessfulBuild/artifact/.repository/org/libresonic/player/libresonic-main/6.1.beta2/libresonic-main-6.1.beta2.war -O /var/lib/tomcat8/webapps/libresonic.war + wget https://github.com/Libresonic/libresonic/releases/download/v6.2.beta1/libresonic-v6.2.beta1.war -O /var/lib/tomcat8/webapps/libresonic.war Note that this command copies the war file directly to the Tomcat webapps directory, and renames it to `libresonic.war`. @@ -42,15 +64,20 @@ Daily WAR files are built by Jenkins and available [here](https://jenkins.zifnab 4. In your web browser, navigate to `http://IP_ADDRESS:8080/libresonic/`, replacing `IP_ADDRESS` with your server's IP address, or `127.0.0.1` if installing locally. -## Alternative to Tomcat +### SpringBoot Alternative to Tomcat If you'd prefer not to use a Tomcat container, you can also run Libresonic as a standalone application. Note that, in that case, libresonic will available at `http://IP_ADDRESS:8080` (and not `IP_ADDRESS:8080/libresonic/`). -Download the Libresonic Pre-Compiled Package as explained above and put it anywhere. Then create the libresonic directory. +Download the Libresonic Pre-Compiled Package as explained above and put it +anywhere. Then create the libresonic directory. You may have to change the +permissions on the folder to align with the user you will run libresonic as. -Now you can simply run java against the libresonic.war package using a command like : +``` +mkdir /var/libresonic/ +``` +Now you can simply run java against the libresonic.war package using a command like: ``` java -jar libresonic.war