Stream Ansible Playbooks

Manage Plate Recognizer Stream deployments at scale using Ansible playbooks. From a single control machine, you can install, upgrade, start, or stop Stream containers on one or many remote hosts in a single command — no need to SSH into each machine individually.

The playbooks are fully idempotent: re-running them is safe and will only apply changes when needed.

Section	Description
Dependencies	Required software for the control machine and remote hosts.
Project Structure	Overview of the Ansible project layout.
Configuration	Set up inventory, host variables, and group defaults.
Secrets Management	Secure handling of LICENSE_KEY and TOKEN.
Running the Playbooks	Install, start, or stop Stream on remote hosts.
Overriding Variables at Runtime	Apply per-run overrides with -e.

Dependencies

Ansible (Control Machine)

Linux / macOS

Inside Terminal

pip install ansible

Windows (WSL)

Inside WSL

pip install ansible

Native Windows support for Ansible is limited. WSL is strongly recommended.

Required Ansible Collection

ansible-galaxy collection install community.docker

sshpass

Required only when authenticating with passwords instead of SSH keys.

Ubuntu / Debian / WSL

sudo apt install sshpass

macOS

brew install hudochenkov/sshpass/sshpass

Require brew to install sshpass on macOS.

Remote Hosts

Docker and Docker Compose must be installed on each remote host before running any playbook.

Project Structure

After meeting the requirements and installing the necessary dependencies, locate the project in our GitHub repository and either clone it or download the ZIP file to a folder of your choice.

ansible/
├── group_vars/
│   └── all.yml                # Shared defaults for all hosts
├── host_vars/
│   ├── example_site_1.yaml    # Per-host credentials and license key
│   ├── example_site_2.yaml
│   └── example_site_3.yaml
├── templates/
│   ├── docker-compose.yml.j2  # Docker Compose template
│   └── .env.j2                # Secrets template (LICENSE_KEY, TOKEN)
├── inventory.ini              # Host inventory
├── install_stream.yaml        # Install or upgrade Stream
├── run_stream.yaml            # Start the container
└── stop_stream.yaml           # Stop and remove the container

Configuration

1. Inventory

Edit inventory.ini to define your hosts:

[group_1]
example_site_1 ansible_host=192.168.1.10
example_site_2 ansible_host=192.168.1.11

[group_2]
example_site_3 ansible_host=192.168.1.20

2. Host Variables

Create a file in host_vars/ for each host with its credentials and Stream license key:

# host_vars/example_site_1.yaml
ansible_user: "ssh_user"
ansible_password: "your_ssh_password"
ansible_become_password: "your_sudo_password"
license: "YOUR_STREAM_LICENSE_KEY"

info

Replace YOUR_STREAM_LICENSE_KEY with your license key from Plate Recognizer Stream. Never commit this value to source control.

tip

Prefer SSH key authentication over passwords:

ansible_ssh_private_key_file: ~/.ssh/id_rsa

On Windows/WSL, copy the key to the WSL home directory (e.g., ~/.ssh/id_rsa) and set permissions with chmod 600 ~/.ssh/id_rsa.

3. Group Variables

Edit group_vars/all.yml and set your PlateRecognizer API token:

token: "YOUR_PLATERECOGNIZER_TOKEN"

# Defaults — override at runtime with -e if needed
stream_dir: /opt/stream
image_name: platerecognizer/alpr-stream
container_name: stream
stream_version: latest

info

Replace YOUR_PLATERECOGNIZER_TOKEN with your API token from Plate Recognizer. Never commit this value to source control.

Secrets Management

Secrets (LICENSE_KEY and TOKEN) are kept out of docker-compose.yml and instead written to a .env file on the remote host by the templates/.env.j2 template:

LICENSE_KEY="{{ license }}"
TOKEN="{{ token }}"

The file is deployed to {{ stream_dir }}/.env with mode 0600 (owner-readable only), so it is never world-readable on the host. The docker-compose.yml references it via env_file: .env and contains no secrets itself.

Improving Security Further

The default setup stores license and token as plain text in host_vars/ and group_vars/.

tip

For production environments, consider Ansible Vault — secrets stay in the repository but are AES-256 encrypted.

Running the Playbooks

Use --limit to target a specific host or group. Omit it to run against all hosts.

Install or Upgrade Stream

Deploys configuration, pulls the image, and starts (or recreates) the container. Re-running this playbook is safe — it is fully idempotent.

# Install with the default version (latest)
ansible-playbook -i inventory.ini install_stream.yaml

# Install or upgrade to a specific version
ansible-playbook -i inventory.ini install_stream.yaml -e stream_version=1.2.3

# Target a specific group or host
ansible-playbook -i inventory.ini install_stream.yaml --limit group_1
ansible-playbook -i inventory.ini install_stream.yaml --limit site_a

Start Stream

Starts the container without pulling a new image.

ansible-playbook -i inventory.ini run_stream.yaml
ansible-playbook -i inventory.ini run_stream.yaml --limit site_a

Stop Stream

Stops and removes the container.

ansible-playbook -i inventory.ini stop_stream.yaml
ansible-playbook -i inventory.ini stop_stream.yaml --limit site_a

Overriding Variables at Runtime

Any variable from group_vars/all.yml can be overridden per-run using -e:

ansible-playbook -i inventory.ini install_stream.yaml -e stream_dir=/custom/path
ansible-playbook -i inventory.ini install_stream.yaml -e stream_version=1.2.3 --limit group_2