# giof71/audirvana-docker architecture

> Architecture diagram of the GitHub repository giof71/audirvana-docker, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/giof71/audirvana-docker
- Repository: https://github.com/giof71/audirvana-docker

## Overview

#### Purpose and Entry Points

This repository builds and runs self-built Docker images for proprietary Audirvana Studio or Audirvana Origin on Linux amd64 and arm64 hosts. It deliberately does not distribute images containing Audirvana binaries.

Primary operator entry points are `build-origin.sh`, `build-studio.sh`, and Compose startup through `docker-compose.yaml`. Builder-enabled alternatives are `docker-compose-origin.yaml` and `docker-compose-studio.yaml`.

#### Image Build Pipeline

The common image recipe is `build/Dockerfile`. Root build scripts select the desired Audirvana variant and invoke Docker image builds:

- `build-origin.sh`
- `build-studio.sh`
- `build/Dockerfile`

The build incorporates the current proprietary application binary into a locally produced image. Rebuilding is the intended update mechanism when Audirvana releases a new version.

#### Container Bootstrap and Application Installation

The image contains an application-management script set under `build/app/bin/`. Installation is separated from normal execution, reflecting the design choice to install binaries during image build rather than incur startup-time download/install latency.

Key stages are represented by:

- `build/app/bin/install-dep.sh` — installs runtime dependencies.
- `build/app/bin/install-util.sh` — installs supporting utilities.
- `build/app/bin/install-app.sh` — installs the selected Audirvana application.
- `build/app/bin/cleanup.sh` — removes build/install artifacts.
- `build/app/bin/run.sh` — container runtime launcher.

`build/Dockerfile` orchestrates these scripts into the final runtime image.

#### Variant Selection Boundary

Audirvana type is an explicit configuration boundary: `BINARY_TYPE` must identify `studio` or `origin`. Dedicated build scripts and Compose files provide ergonomic paths for each variant, while the generic Compose path expects the configured image/application selection.

Relevant paths:

- `build-origin.sh`
- `build-studio.sh`
- `docker-compose-origin.yaml`
- `docker-compose-studio.yaml`
- `docker-compose.yaml`

#### Runtime Configuration and Host Integration

Compose injects runtime settings from a local `.env`, seeded from `sample.env`. The principal boundary is between the containerized service and host-owned identity, audio devices, and music storage:

- `PUID` / `PGID` run the application under a host-compatible user.
- `AUDIO_GID` grants optional access to host ALSA/audio-group resources.
- `MUSIC_DIRECTORY` is mounted into the container at `/music`.
- `ACCEPT_EULA` is an explicit mandatory gate.

Paths: `sample.env`, `docker-compose.yaml`, `music/.placeholder`.

#### Infrastructure and External Dependencies

Docker and Docker Compose are required on the host; the repository targets Linux systems, including 64-bit Raspberry Pi environments. The container depends on Audirvana-provided binaries obtained during local build and may use host audio hardware through ALSA-related group access. At runtime, Audirvana can act as a music server/controller and can integrate with external UPnP renderers; renderer services are not implemented in this repository.

#### Operational Flow

1. Operator configures `.env` from `sample.env`, including EULA acceptance, app type, host IDs, and music mount.
2. Operator builds a Studio or Origin image via root scripts, or lets the variant-specific Compose file build it.
3. Docker executes `build/Dockerfile`, installs dependencies/utilities and the selected Audirvana binary, then cleans intermediate artifacts.
4. Compose starts the container; `build/app/bin/run.sh` launches Audirvana using mounted music and optional host audio access.

Main entry points: [`build/Dockerfile`](https://github.com/giof71/audirvana-docker/blob/main/build/Dockerfile) (Image recipe), [`docker-compose.yaml`](https://github.com/giof71/audirvana-docker/blob/main/docker-compose.yaml) (Generic Compose), [`build/app/bin/install-app.sh`](https://github.com/giof71/audirvana-docker/blob/main/build/app/bin/install-app.sh) (Install Audirvana), [`build-origin.sh`](https://github.com/giof71/audirvana-docker/blob/main/build-origin.sh) (Origin build)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_build["Local image build"]
  node_build_origin["Origin build<br/>build script<br/>[build-origin.sh]"]
  node_build_studio["Studio build<br/>build script<br/>[build-studio.sh]"]
  node_dockerfile["Image recipe<br/>Dockerfile"]
  node_install_dep["Install dependencies<br/>build stage<br/>[install-dep.sh]"]
  node_install_util["Install utilities<br/>build stage<br/>[install-util.sh]"]
  node_install_app["Install Audirvana<br/>build stage<br/>[install-app.sh]"]
  node_cleanup["Clean artifacts<br/>build stage<br/>[cleanup.sh]"]
  node_local_image["Local Audirvana image<br/>Docker image"]
end

subgraph group_runtime["Container runtime"]
  node_sample_env["Environment template<br/>env template<br/>[sample.env]"]
  node_env["Local .env<br/>runtime config"]
  node_compose["Generic Compose<br/>Compose definition"]
  node_compose_origin["Origin Compose build<br/>Compose definition"]
  node_compose_studio["Studio Compose build<br/>Compose definition"]
  node_container["Audirvana container<br/>container service"]
  node_run["Runtime launcher<br/>entrypoint script<br/>[run.sh]"]
end

node_operator(("Operator<br/>actor"))
node_music[("Host music library<br/>host volume<br/>[.placeholder]")]
node_audio["Host ALSA audio<br/>host hardware"]
node_audirvana_binary["Audirvana binary source<br/>external proprietary binary"]
node_renderers["UPnP renderers<br/>external service"]

node_operator -->|"copies and configures"| node_sample_env
node_sample_env -->|"seeds"| node_env
node_operator -->|"builds Origin"| node_build_origin
node_operator -->|"builds Studio"| node_build_studio
node_build_origin -->|"selects origin"| node_dockerfile
node_build_studio -->|"selects studio"| node_dockerfile
node_dockerfile -->|"runs"| node_install_dep
node_install_dep -->|"then"| node_install_util
node_install_util -->|"then"| node_install_app
node_audirvana_binary -->|"installed during build"| node_install_app
node_install_app -->|"then"| node_cleanup
node_cleanup -->|"produces"| node_local_image
node_compose_origin -->|"builds Origin image"| node_dockerfile
node_compose_studio -->|"builds Studio image"| node_dockerfile
node_env -->|"injects settings"| node_compose
node_compose -->|"uses configured image"| node_local_image
node_local_image -->|"runs as"| node_container
node_compose -->|"starts"| node_container
node_container -->|"executes"| node_run
node_music -->|"mounted at /music"| node_container
node_audio -.->|"optional ALSA access"| node_container
node_container -.->|"may integrate via UPnP"| node_renderers

click node_sample_env "https://github.com/giof71/audirvana-docker/blob/main/sample.env"
click node_build_origin "https://github.com/giof71/audirvana-docker/blob/main/build-origin.sh"
click node_build_studio "https://github.com/giof71/audirvana-docker/blob/main/build-studio.sh"
click node_dockerfile "https://github.com/giof71/audirvana-docker/blob/main/build/Dockerfile"
click node_install_dep "https://github.com/giof71/audirvana-docker/blob/main/build/app/bin/install-dep.sh"
click node_install_util "https://github.com/giof71/audirvana-docker/blob/main/build/app/bin/install-util.sh"
click node_install_app "https://github.com/giof71/audirvana-docker/blob/main/build/app/bin/install-app.sh"
click node_cleanup "https://github.com/giof71/audirvana-docker/blob/main/build/app/bin/cleanup.sh"
click node_compose "https://github.com/giof71/audirvana-docker/blob/main/docker-compose.yaml"
click node_compose_origin "https://github.com/giof71/audirvana-docker/blob/main/docker-compose-origin.yaml"
click node_compose_studio "https://github.com/giof71/audirvana-docker/blob/main/docker-compose-studio.yaml"
click node_run "https://github.com/giof71/audirvana-docker/blob/main/build/app/bin/run.sh"
click node_music "https://github.com/giof71/audirvana-docker/blob/main/music/.placeholder"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_build_origin,node_build_studio,node_dockerfile,node_install_dep,node_install_util,node_install_app,node_cleanup,node_local_image toneBlue
class node_sample_env,node_env,node_compose,node_compose_origin,node_compose_studio,node_container,node_run toneAmber
class node_operator,node_music,node_audio,node_audirvana_binary,node_renderers toneNeutral
```

## Components

### Local image build

Builds a private image containing the selected Audirvana binary.

- [Origin build](https://github.com/giof71/audirvana-docker/blob/main/build-origin.sh): build script · `build-origin.sh`
- [Studio build](https://github.com/giof71/audirvana-docker/blob/main/build-studio.sh): build script · `build-studio.sh`
- [Image recipe](https://github.com/giof71/audirvana-docker/blob/main/build/Dockerfile): Dockerfile · Orchestrates installation into the final runtime image. · `build/Dockerfile`
- [Install dependencies](https://github.com/giof71/audirvana-docker/blob/main/build/app/bin/install-dep.sh): build stage · `build/app/bin/install-dep.sh`
- [Install utilities](https://github.com/giof71/audirvana-docker/blob/main/build/app/bin/install-util.sh): build stage · `build/app/bin/install-util.sh`
- [Install Audirvana](https://github.com/giof71/audirvana-docker/blob/main/build/app/bin/install-app.sh): build stage · Installs the selected Studio or Origin binary. · `build/app/bin/install-app.sh`
- [Clean artifacts](https://github.com/giof71/audirvana-docker/blob/main/build/app/bin/cleanup.sh): build stage · `build/app/bin/cleanup.sh`
- **Local Audirvana image**: Docker image · Locally built; proprietary binaries are not distributed by the repository.

### Container runtime

Compose configures and starts Audirvana with host integration.

- [Environment template](https://github.com/giof71/audirvana-docker/blob/main/sample.env): env template · Defines EULA, variant, identity, audio, and music settings. · `sample.env`
- **Local .env**: runtime config · Operator-specific Compose environment values.
- [Generic Compose](https://github.com/giof71/audirvana-docker/blob/main/docker-compose.yaml): Compose definition · Starts the configured image and injects runtime settings. · `docker-compose.yaml`
- [Origin Compose build](https://github.com/giof71/audirvana-docker/blob/main/docker-compose-origin.yaml): Compose definition · Builder-enabled Origin path. · `docker-compose-origin.yaml`
- [Studio Compose build](https://github.com/giof71/audirvana-docker/blob/main/docker-compose-studio.yaml): Compose definition · Builder-enabled Studio path. · `docker-compose-studio.yaml`
- **Audirvana container**: container service · Runs with host-compatible identity and optional audio-group access.
- [Runtime launcher](https://github.com/giof71/audirvana-docker/blob/main/build/app/bin/run.sh): entrypoint script · Launches Audirvana after image installation is complete. · `build/app/bin/run.sh`

### Other components

- **Operator**: actor
- [Host music library](https://github.com/giof71/audirvana-docker/blob/main/music/.placeholder): host volume · Mounted into the container at /music. · `music/.placeholder`
- **Host ALSA audio**: host hardware · Optional access through AUDIO_GID.
- **Audirvana binary source**: external proprietary binary · Obtained during the local image build.
- **UPnP renderers**: external service · Optional runtime integration; not implemented here.

## Connections

- Operator → Environment template: copies and configures
- Environment template → Local .env: seeds
- Operator → Origin build: builds Origin
- Operator → Studio build: builds Studio
- Origin build → Image recipe: selects origin
- Studio build → Image recipe: selects studio
- Image recipe → Install dependencies: runs
- Install dependencies → Install utilities: then
- Install utilities → Install Audirvana: then
- Audirvana binary source → Install Audirvana: installed during build
- Install Audirvana → Clean artifacts: then
- Clean artifacts → Local Audirvana image: produces
- Origin Compose build → Image recipe: builds Origin image
- Studio Compose build → Image recipe: builds Studio image
- Local .env → Generic Compose: injects settings
- Generic Compose → Local Audirvana image: uses configured image
- Local Audirvana image → Audirvana container: runs as
- Generic Compose → Audirvana container: starts
- Audirvana container → Runtime launcher: executes
- Host music library → Audirvana container: mounted at /music
- Host ALSA audio → Audirvana container: optional ALSA access
- Audirvana container → UPnP renderers: may integrate via UPnP