> ## Documentation Index
> Fetch the complete documentation index at: https://docs.musique.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Raspberry Pi

> Learn how to set up and manage Musique on Raspberry Pi devices using manual, script, or Ansible installation methods.

## 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:

<CardGroup>
  <Card title="Manual Installation" icon="wrench" href="#method-1%3A-manual-installation">
    **Best for:**

    * Learning and understanding each component
    * Custom configurations
    * Troubleshooting and development
    * Full control over the process
  </Card>

  <Card title="Automated Script" icon="file-code" href="#method-2%3A-automated-script-installation">
    **Best for:**

    * Quick POCs (Proof of Concepts)
    * Single device deployments
    * One-by-one installations
    * Simplified setup
  </Card>

  <Card title="Ansible Deployment" icon="server" href="#method-3%3A-ansible-deployment-coming-soon">
    **Best for:**

    * Bulk installations (10+ devices)
    * Fleet management
    * Standardized configurations
    * Massive deployments
  </Card>
</CardGroup>

***

## 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:

<CardGroup cols={2}>
  <Card title="Hardware" icon="microchip">
    * Raspberry Pi 4
    * Power supply
    * Audio output (3.5mm jack or HDMI)
    * SD card (16GB+ recommended)
  </Card>

  <Card title="Software" icon="code">
    * Debian-based OS (Ubuntu 24.04.3 LTS recommended)
    * ALSA audio system
    * PulseAudio
    * Docker
  </Card>
</CardGroup>

<Note>
  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.
</Note>

### Installation Steps

### Step 1: Install ALSA

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

<Steps>
  <Step title="Check if ALSA is installed">
    Run the following command to verify if ALSA is already present:

    ```bash theme={null}
    dpkg -l | grep alsa
    ```

    If you see a list of packages, ALSA is already installed.
  </Step>

  <Step title="Install ALSA (if needed)">
    If ALSA is not installed, run:

    ```bash theme={null}
    sudo apt update
    sudo apt install -y alsa-utils libasound2-plugins
    ```
  </Step>

  <Step title="Verify Installation">
    Check that audio devices are detected:

    ```bash theme={null}
    aplay -l
    ```

    You should see your audio output device listed.
  </Step>
</Steps>

### Step 2: Install PulseAudio

PulseAudio manages audio routing for the Musique Agent.

<Steps>
  <Step title="Check if PulseAudio is installed">
    Verify PulseAudio installation:

    ```bash theme={null}
    dpkg -l | grep pulseaudio
    ```
  </Step>

  <Step title="Install PulseAudio (if needed)">
    If not installed:

    ```bash theme={null}
    sudo apt update
    sudo apt install -y pulseaudio
    ```
  </Step>

  <Step title="Verify Installation">
    Start PulseAudio (should produce no output if successful):

    ```bash theme={null}
    pulseaudio --check || pulseaudio --start
    ```
  </Step>
</Steps>

### Step 3: Install Docker

Docker is used to run the Musique Agent container.

<Steps>
  <Step title="Check if Docker is installed">
    Verify Docker installation:

    ```bash theme={null}
    docker --version
    ```

    If you see a version number, Docker is installed.
  </Step>

  <Step title="Install Docker (if needed)">
    Install Docker and configure permissions:

    ```bash theme={null}
    sudo apt update
    sudo apt install docker.io
    sudo systemctl enable --now docker
    sudo usermod -aG docker $USER
    newgrp docker
    ```
  </Step>

  <Step title="Verify Installation">
    Confirm Docker is working:

    ```bash theme={null}
    docker --version
    ```
  </Step>
</Steps>

### Configuration

#### Configure ALSA for PulseAudio

Create an ALSA configuration file to route audio through PulseAudio.

<Steps>
  <Step title="Create Configuration File">
    Open the ALSA configuration file:

    ```bash theme={null}
    nano ~/.asoundrc
    ```
  </Step>

  <Step title="Add Configuration">
    Paste the following content:

    ```
    pcm.!default {
      type pulse
      fallback "sysdefault"
    }
    ctl.!default {
      type pulse
    }
    ```
  </Step>

  <Step title="Save and Exit">
    Press `Ctrl + X`, then `Y`, then `Enter` to save and exit.
  </Step>

  <Step title="Create Directories">
    Create the necessary directories for logs and configuration:

    ```bash theme={null}
    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
    ```
  </Step>

  <Step title="Create Credentials File">
    Create the credentials file:

    ```bash theme={null}
    sudo nano /opt/musique-agent/config/musique-agent.env
    ```
  </Step>

  <Step title="Add Credentials">
    Paste the following content:

    ```
    USERNAME=seu_utilizador
    PASSWORD=sua_password
    ```

    Save and exit by pressing `Ctrl + X`, then `Y`, then `Enter`.
  </Step>

  <Step title="Reboot">
    Reboot the Raspberry Pi to apply changes:

    ```bash theme={null}
    sudo reboot
    ```
  </Step>
</Steps>

### Install Musique Agent

#### Download Docker Image

<Steps>
  <Step title="Authenticate with GitHub Registry">
    Login to the GitHub Container Registry using your organization token:

    ```bash theme={null}
    echo [YOUR_GITHUB_TOKEN] | docker login ghcr.io -u musique-app --password-stdin
    ```

    <Warning>
      Replace `[YOUR_GITHUB_TOKEN]` with the read-only token provided by your Musique administrator.
    </Warning>
  </Step>

  <Step title="Pull the Image">
    Download the latest Musique Agent image:

    ```bash theme={null}
    docker pull ghcr.io/musique-app/musique-agent:latest
    ```
  </Step>
</Steps>

#### Run Musique Agent

<Steps>
  <Step title="Get Your User ID">
    Find your host user ID:

    ```bash theme={null}
    id -u
    ```

    Note the number (typically `1000`).
  </Step>

  <Step title="Run the Container">
    Start the Musique Agent:

    ```bash theme={null}
    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
    ```

    <Warning>
      Replace `xxxx` with your actual user ID from the previous step (typically `1000`).
    </Warning>
  </Step>

  <Step title="Verify Connection">
    The agent should connect to Musique servers and appear online in your Analytics dashboard.
  </Step>
</Steps>

### Enable Auto-Start on Boot

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

<Steps>
  <Step title="Create Systemd Service">
    Run the following command to create a systemd service (replace `xxxx` with your user ID):

    ```bash theme={null}
    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
    ```
  </Step>

  <Step title="Enable the Service">
    Enable and start the service:

    ```bash theme={null}
    sudo systemctl daemon-reload
    sudo systemctl enable musique-agent
    ```
  </Step>

  <Step title="Reboot and Test">
    Reboot to test auto-start:

    ```bash theme={null}
    sudo reboot
    ```

    After reboot, the agent should start automatically.
  </Step>
</Steps>

### Verify Installation

After installation, verify everything is working:

<AccordionGroup>
  <Accordion title="Check Agent Status">
    View the service status:

    ```bash theme={null}
    sudo systemctl status musique-agent
    ```

    Status should show "active (running)".
  </Accordion>

  <Accordion title="View Logs">
    Check agent logs for any issues:

    ```bash theme={null}
    sudo journalctl -u musique-agent -f
    ```

    Press `Ctrl + C` to exit.
  </Accordion>

  <Accordion title="Test Audio Playback">
    Verify audio output is working:

    ```bash theme={null}
    speaker-test -t wav -c 2
    ```

    You should hear test sounds. Press `Ctrl + C` to stop.
  </Accordion>

  <Accordion title="Check Online Status">
    * Log into your Musique dashboard
    * Navigate to Analytics
    * Verify the device appears as online
  </Accordion>
</AccordionGroup>

### Troubleshooting

<AccordionGroup>
  <Accordion title="No audio output">
    **Check audio device:**

    ```bash theme={null}
    aplay -l
    ```

    **Verify PulseAudio is running:**

    ```bash theme={null}
    pulseaudio --check || pulseaudio --start
    ```

    **Test audio directly:**

    ```bash theme={null}
    speaker-test -t wav -c 2
    ```
  </Accordion>

  <Accordion title="Agent not starting">
    **Check service status:**

    ```bash theme={null}
    sudo systemctl status musique-agent
    ```

    **View error logs:**

    ```bash theme={null}
    sudo journalctl -u musique-agent -n 50
    ```

    **Common issues:**

    * Incorrect username/password
    * Network connectivity issues
    * Docker not running: `sudo systemctl start docker`
  </Accordion>

  <Accordion title="Docker permission denied">
    **Add user to docker group:**

    ```bash theme={null}
    sudo usermod -aG docker $USER
    newgrp docker
    ```

    Log out and log back in for changes to take effect.
  </Accordion>

  <Accordion title="Device offline in dashboard">
    * 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`
  </Accordion>
</AccordionGroup>

### Managing the Agent

#### Service Commands

<CodeGroup>
  ```bash Start Service theme={null}
  sudo systemctl start musique-agent
  ```

  ```bash Stop Service theme={null}
  sudo systemctl stop musique-agent
  ```

  ```bash Restart Service theme={null}
  sudo systemctl restart musique-agent
  ```

  ```bash View Status theme={null}
  sudo systemctl status musique-agent
  ```

  ```bash View Logs theme={null}
  sudo journalctl -u musique-agent -f
  ```

  ```bash Disable Auto-Start theme={null}
  sudo systemctl disable musique-agent
  ```
</CodeGroup>

#### Update the Agent

To update to the latest version:

<Steps>
  <Step title="Stop the Service">
    ```bash theme={null}
    sudo systemctl stop musique-agent
    ```
  </Step>

  <Step title="Pull Latest Image">
    ```bash theme={null}
    docker pull ghcr.io/musique-app/musique-agent:latest
    ```
  </Step>

  <Step title="Restart the Service">
    ```bash theme={null}
    sudo systemctl start musique-agent
    ```
  </Step>
</Steps>

***

## 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

<CardGroup cols={2}>
  <Card title="Hardware" icon="microchip">
    * Raspberry Pi 4
    * Power supply
    * Audio output (3.5mm jack or HDMI)
    * SD card (16GB+ recommended)
  </Card>

  <Card title="Software" icon="code">
    * Debian-based OS (Ubuntu 24.04.3 LTS or Raspberry Pi OS recommended)
    * Internet connection
    * Root or sudo access
  </Card>
</CardGroup>

### Installation Steps

<Steps>
  <Step title="Switch to Root User (if needed)">
    If you're not logged in as root, switch to superuser mode:

    ```bash theme={null}
    sudo su -
    ```

    <Info>
      Running the installation script as root ensures all system-level configurations are applied correctly.
    </Info>
  </Step>

  <Step title="Download the Installation Script">
    Download the automated installation script from the Musique Agent repository:

    ```bash theme={null}
    curl -fsSL https://raw.githubusercontent.com/musique-app/musique-agent/refs/heads/master/docs/install.sh > install.sh
    ```
  </Step>

  <Step title="Make the Script Executable">
    Grant execution permissions to the script:

    ```bash theme={null}
    chmod a+x install.sh
    ```
  </Step>

  <Step title="Run the Installation Script">
    Execute the installation script:

    ```bash theme={null}
    ./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

    <Note>
      The installation process may take 5-15 minutes depending on your internet connection and system resources.
    </Note>
  </Step>
</Steps>

### 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.

<Warning>
  **Documentation In Progress**: The Ansible playbook and detailed deployment instructions are currently being developed. Check back soon for complete instructions.
</Warning>

### 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:

```bash theme={null}
# 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
```

<Info>
  For enterprise deployment assistance or to request priority access to the Ansible playbook, contact [support@musique.app](mailto:support@musique.app).
</Info>

***

## Best Practices

<CardGroup cols={2}>
  <Card title="Network Connection" icon="wifi">
    Use wired Ethernet connection for best stability and audio quality.
  </Card>

  <Card title="Power Supply" icon="plug">
    Use official Raspberry Pi power supply to prevent stability issues.
  </Card>

  <Card title="Audio Output" icon="volume-high">
    Test audio output before deploying to ensure proper configuration.
  </Card>

  <Card title="Regular Updates" icon="arrow-up">
    Keep the agent updated to receive latest features and bug fixes.
  </Card>

  <Card title="Monitor Status" icon="chart-line">
    Regularly check device status in Analytics dashboard.
  </Card>

  <Card title="Backup Config" icon="floppy-disk">
    Keep a copy of your systemd service file for easy redeployment.
  </Card>
</CardGroup>

## Next Steps

<CardGroup cols={2}>
  <Card title="Create Schedules" icon="calendar" href="/learn/scheduling">
    Set up audio schedules for your new Raspberry Pi device.
  </Card>

  <Card title="Monitor Performance" icon="chart-line" href="/learn/analytics">
    Track your device status and network quality in Analytics.
  </Card>

  <Card title="Test Network" icon="signal">
    Use the Speed Test tool to verify connection quality.
  </Card>

  <Card title="FAQ" icon="question" href="/essentials/faq">
    Find answers to common Raspberry Pi setup questions.
  </Card>
</CardGroup>