Moviuro edited this page Jul 28, 2018 · 31 revisions



This document assumes that you have installed and configured all prerequisites listed in the README.


Release tarballs are available here. Depending on the feature and how recently it's changed, support might only be available for git HEAD.

Management of your deployment can be much easier if you use a git checkout rather than a tarball: git HEAD.


Whichever method you choose, place the extracted source tree somewhere served by your webserver. The details will depend on your precise setup and desired web path; it's fairly common to put it in a folder called ampache underneath the WWW root.

git checkout example (Gentoo)

cd /var/www/localhost/htdocs
git clone

tarball example (Fedora)

cd /var/tmp
tar -xvzf master.tar.gz
mv master /var/www/html/ampache


Since 3.8.1, Composer is used to manage dependencies. You should download it and install it (e.g: mv composer.phar /usr/local/bin/composer), then run composer install --prefer-source --no-interaction on Ampache directory.

If you cannot use Composer, you should download the release archive which contains all dependencies.

Web server configuration


Ampache is developed to work instantly with Apache without additional configuration except setting up a regular vhost.

Some features requires url rewriting to work correctly. It is highly recommended to enable it.

  • Be sure mod_rewrite is enable on your Apache installation. Otherwise install/activate it and restart your Apache service
  • Check that Ampache website is allowed to override Apache settings (AllowOverride All in vhost config file for instance).
  • After Ampache installation, check that .htaccess files are installed properly. If not, copy the following files as bellow and edit them to match your Ampache public address (eg., RewriteRule ^(/[^/]+|[^/]+/|/?)$ /play/index.php become RewriteRule ^(/[^/]+|[^/]+/|/?)$ /ampache/play/index.php if your Ampache public url is http://localhost/ampache/).
    • /rest/.htaccess.dist => /rest/.htaccess
    • /play/.htaccess.dist => /play/.htaccess
    • /channel/.htaccess.dist => /channel/.htaccess


Working Nginx configuration sample for Ampache. If Ampache is served behind a reverse proxy using SSL, you will have to uncomment fastcgi_param HTTPS on; to prevent mixed content to be served.

server {

    # listen to
    listen  [::]:used_port; #ssl; ipv6 optional with ssl enabled
    listen       used_port; #ssl; ipv4 optional with ssl enabled

    server_name my_server_name;
    charset utf-8;

    # Logging, error_log mode [notice] is necessary for rewrite_log on,
    # (very usefull if rewrite rules do not work as expected)

         error_log       /var/log/ampache/error.log; # notice;
       # access_log      /var/log/ampache/access.log;
       # rewrite_log     on;

    # Use secure SSL/TLS settings, see
    # ssl_protocols TLSv1.2;
    # ssl_prefer_server_ciphers on;
    # add_header Strict-Transport-Security max-age=15768000;
    # etc.

    # Use secure headers to avoid XSS and many other things
    add_header X-Content-Type-Options nosniff;
    add_header X-XSS-Protection "1; mode=block";
    add_header X-Robots-Tag none;
    add_header X-Download-Options noopen;
    add_header X-Permitted-Cross-Domain-Policies none;
    add_header X-Frame-Options "SAMEORIGIN" always;
    add_header Referrer-Policy "no-referrer";
    add_header Content-Security-Policy "script-src 'self' 'unsafe-inline' 'unsafe-eval'; frame-src 'self'; object-src 'self'";

    # Avoid information leak
    server_tokens off;
    fastcgi_hide_header X-Powered-By;

    root /path/to/ampache/root/directory;
    index index.php;

    # Somebody said this helps, in my setup it doesn't prevent temporary saving in files
    proxy_max_temp_file_size 0;

    # Rewrite rule for Subsonic backend
    if ( !-d $request_filename ) {
        rewrite ^/rest/(.*).view$ /rest/index.php?action=$1 last;
        rewrite ^/rest/fake/(.+)$ /play/$1 last;

    # Rewrite rule for Channels
    if (!-d $request_filename){
      rewrite ^/channel/([0-9]+)/(.*)$ /channel/index.php?channel=$1&target=$2 last;

    # Beautiful URL Rewriting
        rewrite ^/play/ssid/(\w+)/type/(\w+)/oid/([0-9]+)/uid/([0-9]+)/name/(.*)$ /play/index.php?ssid=$1&type=$2&oid=$3&uid=$4&name=$5 last;
        rewrite ^/play/ssid/(\w+)/type/(\w+)/oid/([0-9]+)/uid/([0-9]+)/client/(.*)/noscrobble/([0-1])/name/(.*)$ /play/index.php?ssid=$1&type=$2&oid=$3&uid=$4&client=$5&noscrobble=$6&name=$7 last;
        rewrite ^/play/ssid/(.*)/type/(.*)/oid/([0-9]+)/uid/([0-9]+)/client/(.*)/noscrobble/([0-1])/player/(.*)/name/(.*)$ /play/index.php?ssid=$1&type=$2&oid=$3&uid=$4&client=$5&noscrobble=$6&player=$7&name=$8 last;
        rewrite ^/play/ssid/(.*)/type/(.*)/oid/([0-9]+)/uid/([0-9]+)/client/(.*)/noscrobble/([0-1])/transcode_to/(w+)/bitrate/([0-9]+)/player/(.*)/name/(.*)$ /play/index.php?ssid=$1&type=$2&oid=$3&uid=$4&client=$5&noscrobble=$6&transcode_to=$7&bitrate=$8&player=$9&name=$10 last;
    # the following line was needed for me to get downloads of single songs to work
        rewrite ^/play/ssid/(.*)/type/(.*)/oid/([0-9]+)/uid/([0-9]+)/action/(.*)/name/(.*)$ /play/index.php?ssid=$1&type=$2&oid=$3&uid=$4action=$5&name=$6 last;
        location /play {
                if (!-e $request_filename) {
                rewrite ^/play/art/([^/]+)/([^/]+)/([0-9]+)/thumb([0-9]*)\.([a-z]+)$ /image.php?object_type=$2&object_id=$3&auth=$1 last;

        rewrite ^/([^/]+)/([^/]+)(/.*)?$ /play/$3?$1=$2;
        rewrite ^/(/[^/]+|[^/]+/|/?)$ /play/index.php last;

   location /rest {
      limit_except GET POST {
         deny all;

   location ^~ /bin/ {
      deny all;
      return 403;

   location ^~ /config/ {
      deny all;
      return 403;

   location / {
      limit_except GET POST HEAD{
         deny all;

   location ~ ^/.*.php {
        fastcgi_index index.php;

    # sets the timeout for requests in [s] , 60s are normally enough
        fastcgi_read_timeout 600s;

        include fastcgi_params;
        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;

    # Mitigate HTTPOXY
        fastcgi_param HTTP_PROXY "";

    # has to be set to on if encryption (https) is used:
        # fastcgi_param HTTPS on;

        fastcgi_split_path_info ^(.+?\.php)(/.*)$;

    # chose as your php-fpm is configured to listen on
        fastcgi_pass unix:/var/run/php5-fpm.sock;
        # fastcgi_pass;

   # Rewrite rule for WebSocket
   location /ws {
        rewrite ^/ws/(.*) /$1 break;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $host;


$HTTP["host"] == "" {
    server.document-root = "/srv/http/vhosts/"
    url.rewrite-if-not-file += (
        "^/(.*)\.(css|js|jpg|png|gif)$" => "$0",
        "^/rest/(.+)\.view$" => "/rest/index.php?ssaction=$1",
        "^/rest/fake/(.+)$" => "/play/$1",
        "^/play/art/([^/]+)/([^/]+)/([0-9]+)/thumb([0-9]*)\.([a-z]+)$" => "/image.php?object_type=$2&object_id=$3&auth=$1&thumb=$4&name=art.jpg",
        "^/play/([^/]+)/([^/]+)/([^/]+)/([^/]+)(/.*)?$" => "/play/$5?$1=$2&$3=$4",
        "^/play/([^/]+)/([^/]+)(/.*)?$" => "/play/$3?$1=$2",
        "^/play(/[^/]+|[^/]+/|/?)$" => "/play/index.php",
        "^/channel/([0-9]+)/(.*)$" => "/channel/index.php?channel=$1&target=$2"


Working caddy configuration sample for Ampache. It was converted using the nginx config. {
    root /home/caddy/web/

    log /home/caddy/web/log/ {
        rotate_size 100  # Rotate after 100 MB
        rotate_age  14   # Keep log files for 14 days
        rotate_keep 10   # keep maximum of 10 lof files

    errors /home/caddy/web/log/

    index index.php


    fastcgi / unix:/var/run/php/php7.0-fpm.sock php

    # Rewrite rules for Subsonic backend
    rewrite /rest {
        r ^/rest/(.*).view$
        to {path}/ /rest/index.php?action={1}
    rewrite /rest/fake {
        r ^/rest/fake/(.+)$
        to {path}/ /play/{1}

    # Rewrite rule for Channels
    rewrite /channel {
        r ^/channel/([0-9]+)/(.*)$
        to /channel/index.php?channel={1&}target={2} last;

    # Beautiful URL Rewriting
    rewrite /play/ssid {
        r ^/play/ssid/(\w+)/type/(\w+)/oid/([0-9]+)/uid/([0-9]+)/name/(.*)$
        to /play/index.php?ssid={1}&type={2}&oid={3}&uid={4}&name={5}

        r ^/play/ssid/(\w+)/type/(\w+)/oid/([0-9]+)/uid/([0-9]+)/client/(.*)/noscrobble/([0-1])/name/(.*)$
        to /play/index.php?ssid={1}&type={2}&oid={3}&uid={4}&client={5}&noscrobble={6}&name={7}

        r ^/play/ssid/(.*)/type/(.*)/oid/([0-9]+)/uid/([0-9]+)/client/(.*)/noscrobble/([0-1])/player/(.*)/name/(.*)$
        to /play/index.php?ssid={1}&type={2}&oid={3}&uid={4}&client={5}&noscrobble={6}&player={7}&name={8}

        r ^/play/ssid/(.*)/type/(.*)/oid/([0-9]+)/uid/([0-9]+)/client/(.*)/noscrobble/([0-1])/transcode_to/(w+)/bitrate/([0-9]+)/player/(.*)/name/(.*)$
        to /play/index.php?ssid={1}&type={2}&oid={3}&uid={4}&client={5&}noscrobble={6}&transcode_to={7}&bitrate={8}&player={9}&name={10}

        r ^/play/ssid/(.*)/type/(.*)/oid/([0-9]+)/uid/([0-9]+)/action/(.*)/name/(.*)$
        to /play/index.php?ssid={1}&type={2}&oid={3}&uid={4}action={5}&name={6}

    # the following line was needed for me to get downloads of single songs to work
    rewrite /play {
        r ^/play/art/([^/]+)/([^/]+)/([0-9]+)/thumb([0-9]*)\.([a-z]+)$
        to /image.php?object_type={2}&object_id={3}&auth={1}

        r ^/([^/]+)/([^/]+)(/.*)?$
        to /play/{3}?{1}={2}

        r ^/(/[^/]+|[^/]+/|/?)$ 
        to /play/index.php

    proxy /ws {
        without /ws

Web-based Installer

Assuming your web stack is set up properly and you chose the standard web path, this link should now take you to the first step of the online installer. If you set things up in a non-standard way, navigate to your chosen install root manually.

Any potential problems with your PHP installation should show up on this initial page.

Installation screenshot

Select a language and press "Start Configuration".

Installation screenshot

Check all errors and warnings about your environment.

Installation screenshot

Fill out the form with the database information.

Installation screenshot Installation screenshot

Fill out the form with the configuration information if needed (blank database password are not accepted). If PHP is able to write to the config/ directory, you will be able to write out the config file directly from this page. If not, or if you just prefer to do it manually, show File Insight and select "Download" and then copy it into the config/ directory manually. You also define on this screen the general Ampache behavior (installation type, transcoding default settings and player backends to enable) ; if you don't know about this at this stage, you can change this settings later in ampache.cfg.php and Ampache preferences.

Installation screenshot

The final step of installation is to create the initial administrative user.

You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.