Ampache Raspberry Pi installation

In this Ampache Raspberry Pi installation you will learn how to setup a web based audio/video streaming application, which allow us to access our music and videos remotely. It is a completely open source project, written in PHP. The source code is hosted on github, and at the moment of writing, the latest available release is 4.4.3. In this tutorial we see how to install it on a Raspberry Pi OS, so to create a self-hosted media server.

In this tutorial you will learn:

  • How to install Ampache dependencies on Raspberry Pi OS
  • How to create a MariaDB database for Ampache
  • How to install and configure Ampache
Ampache Raspberry Pi installation
Ampache Raspberry Pi installation tutorial

Software requirements and conventions used

Software Requirements and Linux Command Line Conventions
Category Requirements, Conventions or Software Version Used
System Raspberry Pi OS
Software A working LAMP stack
Other Root permissions to install and configure software
Conventions # – requires given linux-commands to be executed with root privileges either directly as a root user or by use of sudo command
$ – requires given linux-commands to be executed as a regular non-privileged user

Installing dependencies

As we already said, Ampache is a web based streaming software written in PHP, therefore it needs a LAMP stack to work. We need to install a Web server (in this case we will use Apache and the mod-php module) and a Database server (we will use MariaDB). Apart from the just mentioned software we need also to install some PHP extensions and other packages which will let Ampache work with media files. As you know the Raspberry Pi Os is based on Debian, so we can obtain software using the apt package manager:

$ sudo apt-get update && sudo apt-get install \
  mariadb-server \
  cron \
  ffmpeg \
  flac \
  gosu \
  inotify-tools \
  lame \
  libavcodec-extra \
  libev-libevent-dev \
  libmp3lame-dev \
  libtheora-dev \
  libvorbis-dev \
  libvpx-dev \
  php \
  php-curl \
  php-gd  \
  php-json \
  php-ldap \
  php-mysql \
  php-xml \
  php-zip \
  php-intl \
  php-pdo \
  composer \
  vorbis-tools \
  zip \
  unzip \
  apache \

Please notice that we need to install the “composer” package only if we intend to install Ampache from the release tarball. We will talk about this in a moment. Once the packages we need are installed, we can proceed and download the Ampache source code directly from github, and install them on our system. Let’s see how.

Downloading Ampache and deploying the source code

We can obtain the Ampache source code latest release in two ways: the first one is by downloading the release tarball, extract it, and then run composer to satisfy the project dependencies; the second one is to download the file which already contains everything the project needs.

Using the tarball

The release tarball is available at the following link: We can download it via our web browser, or without leaving our terminal emulator, using curl:

$ curl -OL

The above command will download the tarball 4.4.3.tar.gz in our current working directory. You can notice we invoked curl with the -O option (short for --remote-name): this option is needed to make so that the downloaded file uses is named after its remote counterpart. We also provided the -L option, which is the short version of --location: this is needed to make Curl follow redirections: without it, in this case, the file would not be downloaded correctly.

Once the tarball is downloaded, we can extract the files:

$ sudo tar -xvzf 4.4.3.tar.gz

You should be already familiar with tar, which is an essential tool for a system administrator, however let’s briefly analyze the above command. The first option we used when we invoked tar, is -x. This option is the short form of --extract, which is the action we want to perform on the tarball. We then used the -v option (short for --verbose) which increases the command verbosity.

The -z option (--gzip), instead, specifies what compression method is used for the tarball. Finally, we used the -f option (short for --file) to specify the path of the archive we want to extract. At the end of the extraction all files should be found under the ampache-4.4.3 directory. Inside this directory we need to run composer:

$ composer install -d ampache-4.4.3

Notice how, above, we invoked composer with the -d option (short for --working-dir) and specified the path of that which should be considered as the working directory as argument: this is useful to run the program without having to change directory.

Once composer finishes installing the project dependencies we can transfer all the files and directories in the appropriate location so that they can be served by the Apache web server. What is that? On Debian-based distributions, the default Apache VirtualHost uses the /var/www/html directory as its DocumentRoot. We could create a dedicated VirtualHost for the project, but for the sake of simplicity, we will use the default one. To copy the files we can use rsync:

$ sudo rsync -av ampache-4.4.3/ /var/www/html --delete

The above command will copy all the files inside the ampache-4.4.3 directory in /var/www/html, without copying the ampache-4.4.3 directory itself. This is because we used a / after the source directory path. As you notice, we used also the --delete option: this will cause every file existing on destination but not on source to be deleted.

Using the zip file containing all dependencies

If we can’t or we just don’t want to use composer we can download the file, which already contains all the project dependencies:

$ curl -OL

To extract the files in the appropriate place from the command line, we can run the following command:

$ sudo unzip -d /var/www/html

In the above example, the -d option is used to specify in which directory the files should be extracted.

Changing Ampache files permissions

If you followed the steps above, all Ampache files should now be into the /var/www/html directory, and should be all owned by the root user and the root group. If there is a single user on the system which will manipulate them, we can assign their ownership to him/her, so we don’t have to use sudo each time we need to perform an operation, perhaps via an ftp client. Assuming said user is “egdoc”, we would run:

$ sudo chown -R egdoc:egdoc /var/www/html

To perform the configuration setup correctly the config directory in the Ampache installation root needs to be writable by the web server. On Debian-based distributions, the Apache web server runs as the www-data user, so we can either assign the ownership of the directory to this user, or assign the group-ownership to it and change permissions so that the directory is writable by the group. Here we will use this last strategy, so we run the following commands:

$ sudo chgrp www-data /var/www/html/config && sudo chmod 775 /var/www/html/config

For the web installer to work, we will also need to do the same thing for the following directories:

  • channel
  • rest
  • play

Apache Raspberry Pi configurations

For the sake of simplicity, in this tutorial, we are using the default Apache VirtualHost. For Ampache to work correctly, however, we need to modify its configuration so to allow directives inside .htaccess files to be effective. We open the VirtualHost configuration (/etc/apache2/sites-available/000-default.conf) with our favorite text editor, and we add the following before the
</VirtualHost> tag:

<Directory /var/www/html>
  AllowOverride All

After we saved the changes, we also need to make sure the mod_rewrite module is active:

$ sudo a2enmod rewrite

To activate the new configuration, we should restart the web server:

$ sudo systemctl restart apache2

PHP configurations

For a smooth Ampache user experience we need to change some PHP parameters which manages the max size of the files which can be uploaded. To tweak these settings we need to edit the php.ini configuration file for the version of PHP we are using. Since we are using PHP as Apache module (vs php-fpm), and more specifically the 7.3 version, we need to open the /etc/php/7.3/apache2/php.ini file with our favorite text editor and change the line 841 so that it looks like this:

upload_max_filesize = 20M

As you can see, the default value was 2M. For the sake of this example we changed it to 20M. Another option we need to change is post_max_size. The line is 689 and the default value is 8M. We need to change it to at least the same value we used for upload_max_filesize:

post_max_size = 20M

To make the changes effective we need to restart Apache again:

$ sudo systemctl restart apache2

Creating a database for Ampache

We now need to create the database which will be used by Ampache. We can do this in few easy steps. The first thing we need to do after installing the mariadb-server package, is to run the mysql_secure_installation script to secure our database server:

$ sudo mysql_secure_installation

We will be prompted to answer a series of questions. In the first prompt we are asked to provide the current root password. We can just press enter, for at this point none should be set:

Enter current password for root (enter for none):

After that, the script will ask us if we want to set a root password. We answer affirmatively, and provide one:

Set root password? [Y/n] Y
New password:
Re-enter new password:
Password updated successfully!
Reloading privilege tables..

The next question will be about removing the anonymous user which is created during the MariaDB installation: it is intended only for testing and should be removed on production. We answer affirmatively to this question:

Remove anonymous users? [Y/n] Y

In the next step we need to decide if the root user of the database should be allowed to connect from location other than localhost. It is a good security measure to disallow root login remotely, so we can answer affirmatively again:

Disallow root login remotely? [Y/n] Y

The next thing we need to decide is if we want to drop the test database which is created by default. Since it is accessible by anyone and intended only for testing, it is a good idea to remove it:

Remove test database and access to it? [Y/n] Y

Finally, we will be asked if we want to reload the privilege tables, so that the settings will be applied right away. We definitely want this, so we answer affirmatively again:

Reload privilege tables now? [Y/n] Y

At this point our MariaDB installation should be secure, so we can proceed and create the database which will be used by Ampache. To do so we need to access the MariaDB shell:

$ sudo mysql -u root -p

A brief note before we proceed further in the Ampache setup. You could notice that in the command above we prefixed the mysql invocation with sudo to access the database as the “root” user. Why is this necessary? By default, at least on Debian-based distributions, the __unix_socket plugin is used for the MariaDB root user authentication: this makes so that the authentication is allowed only if the Unix username which is running the mysql command matches the MariaDB user we are trying to login as. Since we are trying to access MariaDB as the “root” user we need to launch the command as the system__ root user: that’s why we prefixed the command with sudo. If we want to change this behavior we need to use the mysql_native_password plugin instead.

Back to Ampache. After running the above command we will be redirected to the MariaDB shell. From here we can issue the SQL commands needed to create a database (we will call it “ampache”) and an user other than root with full privileges on it:

MariaDB [(none)]> CREATE DATABASE ampache;
MariaDB [(none)]> GRANT ALL PRIVILEGES ON ampache.* to 'ampacheuser'@'localhost' IDENTIFIED BY 'ampacheuserpassword';

In this case we used ampacheuserpassword as the password for the ampacheuser, but in production you should choose something better. We can now exit the MariaDB shell:

MariaDB [(none)]> quit;

Configuring Ampache Raspberry Pi

At this point we can use the graphical installer to setup Ampache. In this case, since we used the default Apache VirtualHost, all we have to do is to navigate to http://localhost if browsing from the same machine Ampache is installed on, or use the machine IP otherwise. The first thing we need to set, is the language which should be used for the installation:

Ampache web installer - language selection
Ampache web installer – language selection

Once we confirm our choice, we will be redirected to a page where all the software dependencies are listed, and their status displayed:


Ampache web installer - checking dependencies
Ampache web installer – checking dependencies

Everything should be ok at this point, except for the PHP integer size option: that however, depends on the system architecture, so there is nothing we can do and we can ignore it. We click on the “Continue” button.

The next step consists in providing information about the database we created in the previous step. Since we already created the database we need to uncheck the “Create Database” checkbox:

Ampache web installer - database information
Ampache web installer – database information

In the next page we need enter some values in order for the ampache.cfg.php configuration file to be generated. Since we configured our web server so that Ampache is reachable at http://localhost, we don’t need to enter anything into the “Web Path” field, we can leave it blank. If, for example, Ampache would be reachable at http://localhost/music, we should have entered /music in the field.

In the “Installation Type” section, we will leave the “Default” option.

If we want to “Allow Transcoding” we should select “ffmpeg” from the dropdown menu in the dedicated section of the page. Transcoding is basically the ability of converting music from one format to another. Ampache Raspberry Pi supports transcoding based on the IP address, user, player, or available bandwith.

In the “Players” section, for the sake of simplicity, we will select only the “Subsonic” backend.

Ampache web installer - generating the configuration
Ampache web installer – generating the configuration

Once ready, we can click on the “Create config” button and the configuration file will be generated.

ampache raspberry pi web installer - creating admin account
Ampache Raspberry Pi web installer – creating admin account

In the next page, we will be prompted to create an Ampache Admin Account, by providing a username and a password. This will be the initial account:

The Ampache login page
The Ampache login page

Once we confirm our choices and click on the “Create account” button, the account will be created, and we will be redirected to the Ampache login page. Here inserting the same credentials, we will be able to perform the login:

Once logged in, we will be redirected to the main Ampache page. From this page we can perform various operations, such as adding a catalog, or managing users:

The Ampache main page
The Ampache main page


In this Ampache Raspberry Pi tutorial we saw how to setup a personal, self-hosted, media streaming service. The application is written in PHP, therefore we saw how to setup a LAMP environment to make it work. We saw how to install dependencies, how to download the Ampache source code, how to setup the web server and a database, and finally how to use the Ampache web installer.

Comments and Discussions
Linux Forum