Install with Docker

The easiest install on Linux, including every Raspberry Pi. The image brings its own Node.js, so the host's version doesn't matter.

Images are published on registry.gitlab.com/jlaramie/alexa-chromecast for amd64, arm64, arm/v7 and arm/v6. Use a version tag such as 2.0.3, not latest, so an update happens only when you choose it.

Before you start, have the certificate files and config.json in one folder. This page uses ~/.config/alexa-chromecast.

Start the container

C="$HOME/.config/alexa-chromecast"
docker run -d --name alexa-chromecast --network host --restart unless-stopped \
  -v "$C/config.json:/app/config.json:ro" \
  -v "$C/server.crt:/app/server.crt:ro" \
  -v "$C/server.key:/app/server.key:ro" \
  registry.gitlab.com/jlaramie/alexa-chromecast:2.0.3
  • --network host lets the client find your Chromecasts over mDNS. It only works on Linux: on macOS and Windows, install directly on Node.js instead.
  • ca.crt: if config.json names a serverCA or clientCA, mount it too: -v "$C/ca.crt:/app/ca.crt:ro".
  • Don't pass a command: the image's entrypoint starts the client.

Check it:

docker ps                          # STATUS shows "(healthy)" once the client is listening
docker logs -f alexa-chromecast    # one JSON line per event

You should see discovery: device added for each Chromecast within a few seconds.

Docker Compose

services:
  alexa-chromecast:
    image: registry.gitlab.com/jlaramie/alexa-chromecast:2.0.3
    network_mode: host
    restart: unless-stopped
    volumes:
      - ./config.json:/app/config.json:ro
      - ./server.crt:/app/server.crt:ro
      - ./server.key:/app/server.key:ro
      # - ./ca.crt:/app/ca.crt:ro      # with serverCA or clientCA

Run docker compose up -d from the folder that holds compose.yaml, config.json and the certificates.

File permissions

The container runs as the user node (uid 1000, gid 1000), so it must be able to read the mounted files:

sudo chown 1000:1000 "$C"/config.json "$C"/server.key "$C"/server.crt
chmod 600 "$C"/config.json "$C"/server.key
chmod 644 "$C"/server.crt

If the files must stay owned by another account, run the container as that account instead: add --user 1001:1001 (or user: "1001:1001" in Compose) with that account's uid and gid.

An unreadable file stops the client with a message naming the file and the uid, such as Cannot read serverKey file /app/server.key (EACCES) as uid 1000.

Updating

docker pull registry.gitlab.com/jlaramie/alexa-chromecast:<new version>
docker rm -f alexa-chromecast
# then the same docker run command with the new tag

With Compose, change the tag and run docker compose up -d.

To go back, start the previous tag again: your config.json and certificates are untouched. After an update that adds device features, say "Alexa, discover devices".

Watchtower can update the container for you: it follows the tag the container uses, so it picks up a re-published tag but never jumps to a new version.

Certificates with Docker

You can run the certificate generator from the image, with nothing else installed:

cd ~/.config/alexa-chromecast
docker run --rm --entrypoint node -v "$PWD:/out" registry.gitlab.com/jlaramie/alexa-chromecast:2.0.3 \
  /opt/acc/certs.mjs --host home.example.net --out /out

When a renewed certificate replaces server.crt and server.key, run docker restart alexa-chromecast: the client reads its certificate only when it starts.

Next

Connect it on the settings site and link the skill.