Skip to main content

​
Overview

Musique Agent runs on Raspberry Pi devices to provide reliable, dedicated audio playback for your locations. This guide covers three different installation methods to suit your deployment needs.

​
Choose Your Installation Method

Select the installation method that best fits your use case:

Manual Installation

Best for:
  • Learning and understanding each component
  • Custom configurations
  • Troubleshooting and development
  • Full control over the process

Automated Script

Best for:
  • Quick POCs (Proof of Concepts)
  • Single device deployments
  • One-by-one installations
  • Simplified setup

Ansible Deployment

Best for:
  • Bulk installations (10+ devices)
  • Fleet management
  • Standardized configurations
  • Massive deployments

​
Method 1: Manual Installation

This method provides complete, step-by-step manual installation of the Musique Agent. Choose this when you need full control over the installation process, want to understand each component, or need to customize your setup.

​
Requirements

Before you begin, ensure you have:

Hardware

  • Raspberry Pi 4
  • Power supply
  • Audio output (3.5mm jack or HDMI)
  • SD card (16GB+ recommended)

Software

  • Debian-based OS (Ubuntu 24.04.3 LTS recommended)
  • ALSA audio system
  • PulseAudio
  • Docker
This guide assumes you have a fresh installation of Ubuntu 24.04.3 LTS or Raspberry Pi OS (64-bit). Both Debian-based operating systems are recommended.

​
Installation Steps

​
Step 1: Install ALSA

ALSA (Advanced Linux Sound Architecture) is required for audio output.
1

Check if ALSA is installed

Run the following command to verify if ALSA is already present:
dpkg -l | grep alsa
If you see a list of packages, ALSA is already installed.
2

Install ALSA (if needed)

If ALSA is not installed, run:
sudo apt update
sudo apt install -y alsa-utils libasound2-plugins
3

Verify Installation

Check that audio devices are detected:
aplay -l
You should see your audio output device listed.

​
Step 2: Install PulseAudio

PulseAudio manages audio routing for the Musique Agent.
1

Check if PulseAudio is installed

Verify PulseAudio installation:
dpkg -l | grep pulseaudio
2

Install PulseAudio (if needed)

If not installed:
sudo apt update
sudo apt install -y pulseaudio
3

Verify Installation

Start PulseAudio (should produce no output if successful):
pulseaudio --check || pulseaudio --start

​
Step 3: Install Docker

Docker is used to run the Musique Agent container.
1

Check if Docker is installed

Verify Docker installation:
docker --version
If you see a version number, Docker is installed.
2

Install Docker (if needed)

Install Docker and configure permissions:
sudo apt update
sudo apt install docker.io
sudo systemctl enable --now docker
sudo usermod -aG docker $USER
newgrp docker
3

Verify Installation

Confirm Docker is working:
docker --version

​
Configuration

​
Configure ALSA for PulseAudio

Create an ALSA configuration file to route audio through PulseAudio.
1

Create Configuration File

Open the ALSA configuration file:
nano ~/.asoundrc
2

Add Configuration

Paste the following content:
pcm.!default {
  type pulse
  fallback "sysdefault"
}
ctl.!default {
  type pulse
}
3

Save and Exit

Press Ctrl + X, then Y, then Enter to save and exit.
4

Create Directories

Create the necessary directories for logs and configuration:
sudo mkdir -p /var/log/musique-agent
sudo mkdir -p /opt/musique-agent/config
sudo chmod -R 755 /var/log/musique-agent
sudo chmod -R 755 /opt/musique-agent
5

Create Credentials File

Create the credentials file:
sudo nano /opt/musique-agent/config/musique-agent.env
6

Add Credentials

Paste the following content:
USERNAME=seu_utilizador
PASSWORD=sua_password
Save and exit by pressing Ctrl + X, then Y, then Enter.
7

Reboot

Reboot the Raspberry Pi to apply changes:
sudo reboot

​
Install Musique Agent

​
Download Docker Image

1

Authenticate with GitHub Registry

Login to the GitHub Container Registry using your organization token:
echo [YOUR_GITHUB_TOKEN] | docker login ghcr.io -u musique-app --password-stdin
Replace [YOUR_GITHUB_TOKEN] with the read-only token provided by your Musique administrator.
2

Pull the Image

Download the latest Musique Agent image:
docker pull ghcr.io/musique-app/musique-agent:latest

​
Run Musique Agent

1

Get Your User ID

Find your host user ID:
id -u
Note the number (typically 1000).
2

Run the Container

Start the Musique Agent:
sudo docker run --rm \
  --name musique-agent \
  --device /dev/snd \
  -v /run/user/xxxx/pulse:/run/pulse \
  -v /var/log/musique-agent:/app/logs \
  -v /opt/musique-agent/config:/app/config \
  --env-file /opt/musique-agent/config/musique-agent.env \
  -e PULSE_SERVER=unix:/run/pulse/native \
  ghcr.io/musique-app/musique-agent:latest
Replace xxxx with your actual user ID from the previous step (typically 1000).
3

Verify Connection

The agent should connect to Musique servers and appear online in your Analytics dashboard.

​
Enable Auto-Start on Boot

Configure the Musique Agent to start automatically when the Raspberry Pi boots.
1

Create Systemd Service

Run the following command to create a systemd service (replace xxxx with your user ID):
echo "[Unit]
Description=Musique agent
After=network.target

[Service]
Restart=always
ExecStart=/usr/bin/docker run --rm \
  --name musique-agent \
  --device /dev/snd \
  -v /run/user/xxxx/pulse:/run/pulse \
  -v /var/log/musique-agent:/app/logs \
  -v /opt/musique-agent/config:/app/config \
  --env-file /opt/musique-agent/config/musique-agent.env \
  -e PULSE_SERVER=unix:/run/pulse/native \
  ghcr.io/musique-app/musique-agent:latest
ExecStop=/usr/bin/docker stop musique-agent

[Install]
WantedBy=multi-user.target" | sudo tee /etc/systemd/system/musique-agent.service > /dev/null
2

Enable the Service

Enable and start the service:
sudo systemctl daemon-reload
sudo systemctl enable musique-agent
3

Reboot and Test

Reboot to test auto-start:
sudo reboot
After reboot, the agent should start automatically.

​
Verify Installation

After installation, verify everything is working:
View the service status:
sudo systemctl status musique-agent
Status should show “active (running)”.
Check agent logs for any issues:
sudo journalctl -u musique-agent -f
Press Ctrl + C to exit.
Verify audio output is working:
speaker-test -t wav -c 2
You should hear test sounds. Press Ctrl + C to stop.
  • Log into your Musique dashboard
  • Navigate to Analytics
  • Verify the device appears as online

​
Troubleshooting

Check audio device:
aplay -l
Verify PulseAudio is running:
pulseaudio --check || pulseaudio --start
Test audio directly:
speaker-test -t wav -c 2
Check service status:
sudo systemctl status musique-agent
View error logs:
sudo journalctl -u musique-agent -n 50
Common issues:
  • Incorrect username/password
  • Network connectivity issues
  • Docker not running: sudo systemctl start docker
Add user to docker group:
sudo usermod -aG docker $USER
newgrp docker
Log out and log back in for changes to take effect.
  • Check internet connection
  • Verify credentials are correct
  • Check service is running: sudo systemctl status musique-agent
  • Review logs: sudo journalctl -u musique-agent -f
  • Test network connection: ping google.com

​
Managing the Agent

​
Service Commands

sudo systemctl start musique-agent

​
Update the Agent

To update to the latest version:
1

Stop the Service

sudo systemctl stop musique-agent
2

Pull Latest Image

docker pull ghcr.io/musique-app/musique-agent:latest
3

Restart the Service

sudo systemctl start musique-agent

​
Method 2: Automated Script Installation

The automated installation script provides a quick and easy way to install the Musique Agent on Raspberry Pi devices. This method is ideal for POCs (Proof of Concepts), single device deployments, and simplified setup.

​
Prerequisites

Hardware

  • Raspberry Pi 4
  • Power supply
  • Audio output (3.5mm jack or HDMI)
  • SD card (16GB+ recommended)

Software

  • Debian-based OS (Ubuntu 24.04.3 LTS or Raspberry Pi OS recommended)
  • Internet connection
  • Root or sudo access

​
Installation Steps

1

Switch to Root User (if needed)

If you’re not logged in as root, switch to superuser mode:
sudo su -
Running the installation script as root ensures all system-level configurations are applied correctly.
2

Download the Installation Script

Download the automated installation script from the Musique Agent repository:
curl -fsSL https://raw.githubusercontent.com/musique-app/musique-agent/refs/heads/master/docs/install.sh > install.sh
3

Make the Script Executable

Grant execution permissions to the script:
chmod a+x install.sh
4

Run the Installation Script

Execute the installation script:
./install.sh
The script will automatically handle:
  • System package updates
  • ALSA installation
  • PulseAudio installation and configuration
  • Docker installation
  • Audio routing configuration
  • Musique Agent Docker image download
  • Systemd service setup for auto-start
The installation process may take 5-15 minutes depending on your internet connection and system resources.

​
Post-Installation

The installation script automatically configures the Musique Agent to start on system boot. Use the same service management commands as described in the manual installation method.

​
Method 3: Ansible Deployment (Coming Soon)

Ansible deployment provides an automated, scalable solution for installing and managing the Musique Agent across multiple Raspberry Pi devices simultaneously.
Documentation In Progress: The Ansible playbook and detailed deployment instructions are currently being developed. Check back soon for complete instructions.

​
Overview

This method will be ideal for:
  • Fleet Management: Deploy to dozens or hundreds of devices at once
  • Standardized Configuration: Ensure consistent setup across all devices
  • Bulk Installations: Rapidly deploy Musique to multiple locations
  • Infrastructure as Code: Version-controlled, reproducible deployments

​
Planned Features

The Ansible playbook will automate:
  • System configuration and package updates
  • Dependency installation (ALSA, PulseAudio, Docker)
  • Agent deployment with encrypted credential management
  • Service configuration and verification

​
Prerequisites (When Available)

  • Ansible installed on your control machine
  • SSH access to all target Raspberry Pi devices
  • Network connectivity to all devices

​
Temporary Alternative

While the Ansible playbook is being developed, use the Automated Script method for multiple devices: 
# Example: Deploy to multiple devices via SSH
for host in 192.168.1.{101..110}; do
  echo "Deploying to $host..."
  ssh pi@$host "curl -fsSL https://raw.githubusercontent.com/musique-app/musique-agent/refs/heads/master/docs/install.sh > install.sh && chmod +x install.sh && sudo ./install.sh"
done
For enterprise deployment assistance or to request priority access to the Ansible playbook, contact support@musique.app.

​
Best Practices

Network Connection

Use wired Ethernet connection for best stability and audio quality.

Power Supply

Use official Raspberry Pi power supply to prevent stability issues.

Audio Output

Test audio output before deploying to ensure proper configuration.

Regular Updates

Keep the agent updated to receive latest features and bug fixes.

Monitor Status

Regularly check device status in Analytics dashboard.

Backup Config

Keep a copy of your systemd service file for easy redeployment.

​
Next Steps

Create Schedules

Set up audio schedules for your new Raspberry Pi device.

Monitor Performance

Track your device status and network quality in Analytics.

Test Network

Use the Speed Test tool to verify connection quality.

FAQ

Find answers to common Raspberry Pi setup questions.