Permalink
Browse files

Move documentation to a dedicated repository.

  • Loading branch information...
EugeneKay committed May 11, 2017
1 parent 45ef090 commit 56e2cc4575690e42989d87654e42ecf7a0873bee
View
@@ -0,0 +1,10 @@
<!--
# DOCUMENTATION.md
# Libresonic/player
-->
Documentation
=============
Documentation is stored in a [dedicated repository](https://github.com/Libresonic/documentation).
@@ -1,52 +0,0 @@
# Startup Configuration Guide
Libresonic has some system-wide configuration. These configurations are stored in the
`libresonic.properties` file. There are some exceptions, such as the `libresonic.home` parameter, which
are supplied as a Java System Property.
## libresonic.properties Parameters
These parameters are simple key-value pairs stored in a list. It is recommended that these parameters
are changed through the web interface settings page. However, they can also be modified directly. Shutdown
your server first, modify, then start it for changes to take effect.
## Java Parameters
These parameters are not modifiable through the web interface. See below for steps for setting Java Parameters.
#### `libresonic.home`
This parameter dictates the folder where Libresonic will store its logs,
settings, transcode binaries, index and database if using the default H2
database. As such it is recommended to backup this folder.
*default: `/var/libresonic` or `C:\\music`*
### Spring Boot/Standlone Specific Configs
The following configs only apply when running libresonic as a standalone package (i.e. without Tomcat or Jetty). These are only a subset of the connfigurations for spring-boot, the full list can be found [here](https://docs.spring.io/spring-boot/docs/1.4.5.RELEASE/reference/htmlsingle/#common-application-properties). Not that not all configurations apply to libresonic, but the important section is the `# EMBEDDED SERVER CONFIGURATION` section.
#### `server.port`
This property only applies for spring boot/standalone config. It changes the port that the standalone package listens on.
*default: 8080*
#### `server.address`
This property only applies for spring boot/standalone config. It changes the address that the standalone package listens on.
*default: not set and listens to all addresses*
### Setting Java Parameters on Tomcat
As described in the [RUNNING.txt](http://tomcat.apache.org/tomcat-8.0-doc/RUNNING.txt) doc provided by tomcat,
you can create a file named `setenv.sh` or for windows `setenv.bat` in the Tomcat home `bin` folder to modify the
java args.
Here is an example of a `setenv.sh` file (`setenv.bat` has slightly different syntax):
```
export JAVA_OPTS="$JAVA_OPTS -Dlibresonic.home=/home/andrew/.cache/libresonic-test"
```
### Setting Java Parameters for Standalone Package (SpringBoot)
When running the standalone package, add `-Dlibresonic.home=YOUR_PATH_HERE` to the `java` command line right before the
`-jar` argument. Here is an example for linux (windows users will want to use their OS specific path syntax i.e.
`C:\\your\path`)
```
java -Dlibresonic.home=/home/andrew/libresonichome -jar libresonic.war
```
View
@@ -1,90 +0,0 @@
# Database Selection
Libresonic is built with generic ANSI SQL (for the most part) and uses [Liquibase](http://www.liquibase.org/)
for database migrations in a database agnostic way and should be
able to run against a variety of databases. However, not all databases have been verified to
work and you may run into issues with the liquibase migrations or runtime SQL issues. Here is
a list of community tested setups:
| Database | Version | Liquibase | Runtime | Notes |
|:----------:|:-------:|:---------:|:-------:|:------:|
| HyperSQL | 1.8 | ✔ | ✔ | Default|
| HyperSQL | 2.X | ✕ | ✕ | No curent plans to support, look into SQLite instead? |
| PostgreSQL | 9.5 | ✔ | ✔ | |
| MariaDB | 10.2 | ✔ | ✔ | |
| MySQL | 5.7.17 | ✔ | ✕ | WIP |
If you wish to continue using the current hsql 1.8 database driver, no action is needed. If you wish to use another
database, read on.
# Database Configuration
*Before doing anything, make sure your database is properly backed up. Ensure your server is shutdown*
For those that wish to change their database, instructions differ based on
whether you wish for your database connection to be managed by your container (tomcat),
or whether you wish Libresonic to manage it for you. The former may offer some performance
gains in the case of many concurrent users with connection pooling while the latter is easiest.
We will refer to container managed configuration as jndi and libresonic managed configuration as embedded.
## Embedded
*Before doing anything, make sure your database is properly backed up. Ensure your server is shutdown*
In your libresonic.properties file, you will need to add the following settings (this is just an example):
```
DatabaseConfigType=embed
DatabaseConfigEmbedDriver=org.hsqldb.jdbcDriver
DatabaseConfigEmbedUrl=jdbc:hsqldb:file:/tmp/libre/db/libresonic
DatabaseConfigEmbedUsername=sa
DatabaseConfigEmbedPassword=
```
In addition, you will need to ensure that a jdbc driver suitable for your
database is on the
[classpath](https://docs.oracle.com/javase/8/docs/technotes/tools/windows/classpath.html).
*Note adding to the classpath is currently pretty difficult for spring-boot. Tomcat is easy, just copy into tomcat home
/lib. TODO: provide prebuilt artifacts with tested databases built in?*
## JNDI
*Before doing anything, make sure your database is properly backed up. Ensure your server is shutdown*
In your libresonic.properties file, you will need to add the following settings (this is just an example):
```
DatabaseConfigType=jndi
DatabaseConfigJNDIName=jdbc/libresonicDB
```
Then in your context.xml in your tomcat directory, add the jndi config:
```
<Resource name="jdbc/libresonicDB" auth="Container"
type="javax.sql.DataSource"
maxActive="20"
maxIdle="30"
maxWait="10000"
username="libresonic"
password="REDACTED"
driverClassName="com.mysql.jdbc.Driver"
url="jdbc:mysql://hostname/libresonic?sessionVariables=sql_mode=ANSI_QUOTES"/>
```
Finally, copy the jdbc driver from the database vendor website to the `lib` directory in your tomcat folder.
## Database Vendor Specific Notes
### PostgreSQL
`stringtype=unspecified` on your jdbc url string is necessary.
You will also need to add `DatabaseUsertableQuote=\"` to your properties
file. This is due to the fact that our `user` table is a keyword for postgres.
## Troubleshooting
In the event that you change these settings, restart your server and it fails to start, you can remedy this by reverting
to the LEGACY config by removing all `Database*` settings from your `libresonic.properties` file.
@@ -1,143 +0,0 @@
# Installing Libresonic on FreeBSD 10.3 and FreeNAS 9.10
### Preamble
This guide will wallk you through the process of deploying Libresonic on FreeBSD either in a Jail on on the main system. The prerequisites are you have root access on your FreeBSD machine (or jail), the ip address of the machine (or jail) and the Libresonic war available at the [Libresonic github page](https://github.com/Libresonic/libresonic/releases)
If on FreeNAS create a standard jail in the web interface and enter the shell.
### 1. Install Tomcat
To run Libresonic we need a server to run it in. Log into your machine and then run these commands either as root or with sudo
#pkg install tomcat8 nano
Hit y on all prompts to complete installation of Tomcat
### 2.Configure Tomcat
Edit Tomcat's user configuration file with your favourite text editor. We installed nano in step 1.
#rm /usr/local/apache-tomcat-8.0/conf/tomcat-users.xml
#nano /usr/local/apache-tomcat-8.0/conf/tomcat-users.xml
Copy this
<tomcat-users xmlns="http://tomcat.apache.org/xml"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://tomcat.apache.org/xml tomcat-users.xsd"
version="1.0">
<role rolename="manager-gui"/>
<role rolename="manager-script"/>
<role rolename="manager-jmx"/>
<role rolename="manager-status"/>
<role rolename="admin-gui"/>
<role rolename="admin-script"/>
<user username="admin" password="admin" roles="manager-gui,manager-script,manager-jmx,manager-status,admin-gui,admin-script"/>
</tomcat-users>
Use Ctrl-O to save and y to confirm. Ctrl-X to exit Nano.
If you wish to use a different username and password please append the second last line to contain your preferred username and password.
<user username="yourusername" password="yourpassword" roles="manager-gui,manager-script,manager-jmx,manager-status,admin-gui,admin-script"/>
### 3. Start and test Tomcat
#echo tomcat8_enable="YES" >> /etc/rc.conf
#service tomcat8 start
Test Tomcat is listening on port 8080
# netstat -an | grep 8080
It should return a line containing the IP address of your system (or jail). ie mine returns
tcp4 0 0 10.0.0.10.8080 *.* LISTEN
If in a jail it may also return the line "netstat: kvm not available: /dev/mem: No such file or directory" This can be ignored.
### 4. Create directories and set up permissions
#mkdir /var/libresonic
#chown -R www:www /var/libresonic
#chown -R www:www /usr/local/apache-tomcat-8.0/webapps
### 5. Deploy Libresonic
Open a web browser and enter your servers IP address in the url bar followed by :8080 eg
10.0.0.10:8080
You should be greeted by the Apache Tomcat page. Click on the Manager App button on the right of the page and enter the username and password used in step 3. Default was username: admin and password: admin
Scroll down to Deploy and the subheading "WAR file to deploy" hit choose file and select the libresonic.war downloaded in the preamble. After selecting press the deploy button. Scroll up and press start. When the page refreshes a message "OK - Started application at context path /libresonic-v6.1" should be visible.
### 6. Navigate to Libresonic
In a browser. Take your server IP address and port and append the the context path from above
ie if the War deployed was called libresonic-v6.1.war navigate to:
10.0.0.10:8080/libresonic-v6.1/
### 7. Log into Libresonic
Log in. The default is username: admin password: admin
Follow the prompts on the web page to change the password. This will log you out. Please re-login with your new password
### 8. Set up media
If you are on FreeBSD in a jail, consult the documentation for your Jail Manager tool on how to pass through storage. If using FreeNAS please use the FreeNAS webui to pass through the dataset containing your music.
In Libresonic click 2. Setup Media folders.
Name your media folder and put in the path to your music. Then click "Scan media folders now"
Congratulations you have set up Libresonic
##Transcoding Support
If you want transcoding and DON'T need mp3 support
#pkg install ffmpeg
#ln -s /usr/local/bin/ffmpeg /var/libresonic/transcode/ffmpeg
#service tomcat8 restart
Congratulations you have transcoding enabled
If you need mp3 support and most likely you will the process is more arduous as FreeBSD's ffmpeg doesn't contain mp3 support by default and must be configured and compiled by the user.
### 1. Install ffmpeg dependencies and Ports Tree
Install the dependencies required to build and use ffmpeg
#pkg install yasm binutils texi2html frei0r v4l_compat gmake pkgconf perl5 fontconfig freetype2 opencv-core schroedinger libtheora libv4l libva libvdpau libvorbis libvpx libx264 xvid gnutls libiconv
Now install the FreeBSD Ports Tree
#portsnap fetch
#portsnap extract
### 2. Build ffmpeg
Navigate to the ffmpeg port directory
#cd /usr/ports/multimedia/ffmpeg
Configure ffmpeg build
#make configure
This will bring up a menu. Scroll down using arrow keys to "LAME" and hit the spacebar to enable it. Press enter to continue.
The ffmpeg source files will automatically be downloaded then you will be presented with an additional prompt to install documentation. I uncheck with spacebar then press enter to continue.
Commence build and installation of ffmpeg
#make install clean
Building ffmpeg will take some time depending on the capabilities of your machine, please be patient.
Link ffmpeg to where Libresonic expects the transcoder to be.
#ln -s /usr/local/bin/ffmpeg /var/libresonic/transcode/ffmpeg
Finally restart tomcat
#service tomcat8 restart
Congratulations you have ffmpeg with mp3 support installed ready for Libresonic to use.
Oops, something went wrong.

0 comments on commit 56e2cc4

Please sign in to comment.