PiCompose

KO | EN

gitlite — search

#javascript #python #ruby #dotfiles #shell #hacktoberfest #library #c-plus-plus #php #java #bash #email

★ 38 Open GitHub ↗

PiCompose is a ready-to-use Raspberry Pi image that automatically deploys docker-compose stacks from a folder. Just flash the image, drop your docker-compose.yml if needed files into the designated folder. We also have prebuild images for various hardware.

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# PiCompose

[![CI](https://github.com/florian-asche/PiCompose/actions/workflows/build-all.yml/badge.svg)](https://github.com/florian-asche/PiCompose/actions/workflows/build-image.yml) [![GitHub Release Version](https://img.shields.io/github/v/release/florian-asche/PiCompose?label=version)](https://github.com/florian-asche/PiCompose/releases) [![GitHub License](https://img.shields.io/github/license/florian-asche/PiCompose)](https://github.com/florian-asche/PiCompose/blob/main/LICENSE) [![GitHub last commit](https://img.shields.io/github/last-commit/florian-asche/PiCompose)](https://github.com/florian-asche/PiCompose/commits)

Ready to use Raspberry Pi Images with Docker for projects like [linux-voice-assistant](https://github.com/OHF-Voice/linux-voice-assistant) or [docker-snapcast](https://github.com/florian-asche/docker-snapcast).

## Overview

PiCompose uses the official [pi-gen](https://github.com/RPi-Distro/pi-gen) tool from Raspberry Pi to create a customized Raspberry Pi OS image.

The image is configured to:

1. Install needed drivers for the hardware (2-MicHat, Satellite1)
2. Start seeed-voicecard service (If you use 2-MicHat)
3. Start Pipewire service
4. Start Keep-Audio-Alive service (If you use Respeaker Lite)
5. Set system audio volume to 100%
6. Set hostname
7. Search for Docker Compose files in a special directory on the main partition
   💡 **Note:** If you use the Linux-Voice-Assistant Image LVA and Snapcast will be included in the project directory.
8. Automatically deploy each Docker Compose project found
9. Optionally set up regular re-deployments via Crontab

This repository contains fully prepared images for specific voice hardware of Homeassistant with all needed drivers.

## Features

- Automated build of a customized Raspberry Pi OS image using GitHub Actions
- Easy addition of Docker Compose projects via the main partition (compose directory)
- Configurable regular re-deployments via a simple configuration file
- No manual configuration of the Raspberry Pi required
- Image prepared for audio usage with the pipewire server
- Prebuild images with drivers for various devices

## Usage

### Hardware

There is a separate page for the supported hardware. You can find the link to it in the list below, when you click on the Name.

### Images overview

Here is a Overview for the specific images of each hardware:

| Name | Hardware | What's in the Image? |
| ---------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Base Image** | If you use other hardware... | • Docker & Docker Compose (piCompose) • Automatic Docker Compose deployment • Pipewire Audio Server • SSH enabled (pi User) |
| **[Satellite1](docs/hardware_sattelite1.md)** | <img src="docs/sattelite1-hat.jpg" alt="ReSpeaker Lite Board" style="width: 200px; height: auto;"> | • * Everything from Base Image • Satellite1 Hat Driver • Linux-Voice-Assistant (OpenHomeFoundation) • Snapcast MultiRoom Audio Client • Pre-configured for Home Assistant |
| **[ReSpeaker 2-Mic HAT v1](docs/hardware_2mic_v1.md)** | <img src="docs/respeaker_2michats.webp" alt="ReSpeaker 2-Mics Pi HAT" style="width: 200px; height: auto;"> | • * Everything from Base Image • Seeed Voicecard Driver • Linux-Voice-Assistant (OpenHomeFoundation) • Snapcast MultiRoom Audio Client • Pre-configured for Home Assistant Current latest available build version is 1.1.1 See [#41](https://github.com/HinTak/seeed-voicecard/issues/41) |
| **[ReSpeaker 2-Mic HAT v2.0](docs/hardware_2mic_v2.md)** | <img src="docs/respeaker_2michats.webp" alt="ReSpeaker 2-Mics Pi HAT" style="width: 200px; height: auto;"> | • * Everything from Base Image • Seeed Voicecard Driver • Linux-Voice-Assistant (OpenHomeFoundation) • Snapcast MultiRoom Audio Client • Pre-configured for Home Assistant |
| **[ReSpeaker Lite](docs/hardware_respeaker_lite.md)** | <img src="docs/respeaker_lite.jpg" alt="ReSpeaker Lite Board" style="width: 200px; height: auto;"> | • * Everything from Base Image • Audio keep-alive service • Linux-Voice-Assistant (OpenHomeFoundation) • Snapcast MultiRoom Audio Client • Pre-configured for Home Assistant • Workaround for connectivity issues in combination with the Pi Zero 2W. |

### Installation

You can burn the image to your sd card with the [Raspberry Pi Imager tool](https://www.raspberrypi.com/documentation/computers/getting-started.html#imager-install). You can set wifi credentials, ssh public keys and other settings before you burn the image to your sd card. In order to use the feature where you can change the settings in the `Raspberry Pi Imager >= v2.0` you need to set a custom image repository.

💡 **Note:** If you use the Customisation" (sic) part of the "Raspberry Pi Imager tool", the "User" must be set to "pi".

Windows, macOS, and Linux are supported. On macOS, you can use the Raspberry Pi Imager application or install it via Homebrew.

Windows

```sh
"C:\Program Files\Raspberry Pi Ltd\Imager\rpi-imager.exe" --repo https://github.com/florian-asche/PiCompose/releases/download/rpi-imager-json/rpi-imager.json
```

Linux

```sh
rpi-imager --repo https://github.com/florian-asche/PiCompose/releases/download/rpi-imager-json/rpi-imager.json
```

macOS

```sh
rpi-imager --repo https://github.com/florian-asche/PiCompose/releases/download/rpi-imager-json/rpi-imager.json
```

You can also put the [URL](https://github.com/florian-asche/PiCompose/releases/download/rpi-imager-json/rpi-imager.json) in Settings - Image Repository - Use own URL.

If you don't want to use the Raspberry Pi Imager tool you can also [download](https://github.com/florian-asche/PiCompose/releases) the image and configure keyboard, timezone and wifi credentials with the [`raspi-config` tool](https://www.raspberrypi.com/documentation/computers/configuration.html#raspi-config). If you don't use the Raspberry Pi Imager customization, you'll need to connect a monitor, keyboard, and mouse to access the Pi initially to configure SSH and WiFi via `raspi-config`.

### Configuration

You can customize the PiCompose configuration in the `/compose` directory on the root filesystem. You can change how it is updated, how it is handling a reboot and you can remove `snapcast` if you dont want to use it.

You can also add your own docker-compose projects to the system:

1. Create directories for your Docker Compose projects in the `compose` folder on the main partition.
2. Place your `docker-compose.yml` files and associated configurations like `.env` in the appropriate subdirectories (see the `example` directory)
3. Configure the `picompose.conf` file to include your projects.

#### Configurationfile

The configuration file is named `picompose.conf` and is located in specific application directories.

```ini
# Disable this deployment
DISABLED=false

# Configure if piCompose should run on boot
# When it runs without image pull, it does a docker compose down and up.
BOOT_ENABLED=false

# Configure if piCompose should update the docker image on boot
# BOOT_ENABLED needs to be true
BOOT_IMAGE_PULL=false

# Configure if piCompose should run periodically via cron
# When it runs without image pull, it does a docker compose down and up.
CRON_ENABLED=true

# Cron schedule for automatic re-deployments
# Format: Minute Hour Day Month Weekday
# Examples:
# "0 4 * * *"     - Every day at 4 AM
# "0 */6 * * *"   - Every 6 hours
# "0 0 * * 0"     - Every Sunday at midnight
CRON_SCHEDULE="0 4 * * *"

# Configure if piCompose should update the docker image on cron run
# CRON_ENABLED needs to be true
CRON_IMAGE_PULL=true
```

### First start's

Make sure, that you configured your wifi credentials before the first boot. You can do this with the RPI-Imager tool when burning the image to your sd card.

On the first boot in will create new ssh server public keys for the ssh serve. You can see that if you have a monitor connected to your system. 
The system will automatically reboot and install the audio drivers. After that you can login with the user `pi`. You can change the password `raspberry` if you didnt change it before with the imager tool.

You will notice that the hardware is not visible if you run `aplay -L`. 
❗ *You need to manually reboot one more time.*

After that `aplay -L` should show the `seeed2micvoicec`, `Lite`, or `Satellite1` soundcard depending on your hardware.

piCompose should download and install the containers.
You can watch the `/var/log/picompose.log` logfile if you want to monitor the process.
The process can take some time, since it downloads images from the internet!

Snapcast is disabled by default. You can change that in the `picompose.conf` and reboot.

## Development

See [DEVELOPMENT.md](DEVELOPMENT.md) for information on the development and build process.

### Example projects, that you can run on this:

- [docker-snapcast](https://github.com/florian-asche/docker-snapcast) - A Docker image for Snapcast server and client, providing multi-room audio streaming capabilities
- [linux-voice-assistant](https://github.com/OHF-Voice/linux-voice-assistant) - A remote voice satellite implementation using the ESPHome protocol

## License

This project is released under the [BSD-3-Clause License](LICENSE).

PiCompose

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README