---
icon: material/docker
title: Headless Chrome
hide:
- tags
tags:
- chrome
- browser
- headless
saltbox_automation:
app_links:
- name: Manual
url:
type: manual
- name: Releases
url: https://console.cloud.google.com/artifacts/docker/zenika-hub/us/gcr.io/alpine-chrome
type: releases
- name: Community
url:
type: community
project_description:
name: Headless Chrome
summary: |-
a way to run the Chrome browser in a headless environment.
link: https://developer.chrome.com/blog/headless-chrome
---
# Headless Chrome
## Overview
[Headless Chrome](https://developer.chrome.com/blog/headless-chrome) is a way to run the Chrome browser in a headless environment.
[:fontawesome-solid-book-open:**Manual**](){ .md-button .md-button--stretch }
[:fontawesome-solid-newspaper:**Releases**](https://console.cloud.google.com/artifacts/docker/zenika-hub/us/gcr.io/alpine-chrome){ .md-button .md-button--stretch }
[:fontawesome-solid-comments:**Community**](){ .md-button .md-button--stretch }
---
!!! note "This was created for use with Hoarder which calls for a specific version (124)"
## Deployment
```shell
sb install sandbox-chrome
```
## Usage
Call as a backend from automation tools like Hoarder and Puppeteer.
## Role Defaults
Variables can be customized using the [Inventory](/saltbox/inventory/index.md#overriding-variables){ data-preview }. (1)
{ .annotate .sb-annotated }
1. !!! example "Example override"
```yaml
chrome_name: "custom_value"
```
!!! warning "Avoid overriding variables ending in `_default`"
When overriding variables that end in `_default` (like `chrome_docker_envs_default`), you replace the entire default configuration. Future updates that add new default values will not be applied to your setup, potentially breaking functionality.
Instead, use the corresponding `_custom` variable (like `chrome_docker_envs_custom`) to add your changes. Custom values are merged with defaults, ensuring you receive updates.
=== "Basics"
??? variable string "`chrome_name`"
```yaml
# Type: string
chrome_name: chrome
```
=== "Docker"
Container
??? variable string "`chrome_role_docker_container`"
```yaml
# Type: string
chrome_role_docker_container: "{{ chrome_name }}"
```
Image
??? variable bool "`chrome_role_docker_image_pull`"
```yaml
# Type: bool (true/false)
chrome_role_docker_image_pull: true
```
??? variable string "`chrome_role_docker_image_repo`"
```yaml
# Type: string
chrome_role_docker_image_repo: "gcr.io/zenika-hub/alpine-chrome"
```
??? variable string "`chrome_role_docker_image_tag`"
```yaml
# Type: string
chrome_role_docker_image_tag: "124"
```
??? variable string "`chrome_role_docker_image`"
```yaml
# Type: string
chrome_role_docker_image: "{{ lookup('role_var', '_docker_image_repo', role='chrome') }}:{{ lookup('role_var', '_docker_image_tag', role='chrome') }}"
```
Envs
??? variable dict "`chrome_role_docker_envs_default`"
```yaml
# Type: dict
chrome_role_docker_envs_default:
TZ: "{{ tz }}"
PUID: "{{ uid }}"
PGID: "{{ gid }}"
```
??? variable dict "`chrome_role_docker_envs_custom`"
```yaml
# Type: dict
chrome_role_docker_envs_custom: {}
```
Commands
??? variable list "`chrome_role_docker_commands_default`"
```yaml
# Type: list
chrome_role_docker_commands_default:
- "--no-sandbox"
- "--disable-gpu"
- "--disable-dev-shm-usage"
- "--remote-debugging-address=0.0.0.0"
- "--remote-debugging-port=9222"
- "--hide-scrollbars"
```
??? variable list "`chrome_role_docker_commands_custom`"
```yaml
# Type: list
chrome_role_docker_commands_custom: []
```
Hostname
??? variable string "`chrome_role_docker_hostname`"
```yaml
# Type: string
chrome_role_docker_hostname: "{{ chrome_name }}"
```
Networks
??? variable string "`chrome_role_docker_networks_alias`"
```yaml
# Type: string
chrome_role_docker_networks_alias: "{{ chrome_name }}"
```
??? variable list "`chrome_role_docker_networks_default`"
```yaml
# Type: list
chrome_role_docker_networks_default: []
```
??? variable list "`chrome_role_docker_networks_custom`"
```yaml
# Type: list
chrome_role_docker_networks_custom: []
```
Restart Policy
??? variable string "`chrome_role_docker_restart_policy`"
```yaml
# Type: string
chrome_role_docker_restart_policy: unless-stopped
```
State
??? variable string "`chrome_role_docker_state`"
```yaml
# Type: string
chrome_role_docker_state: started
```
=== "Docker+"
The following advanced options are available via create_docker_container but are not defined in the role. See: [docker_container module](https://docs.ansible.com/ansible/latest/collections/community/docker/docker_container_module.html)
Resource Limits
??? variable int "`chrome_role_docker_blkio_weight`"
```yaml
# Type: int
chrome_role_docker_blkio_weight:
```
??? variable int "`chrome_role_docker_cpu_period`"
```yaml
# Type: int
chrome_role_docker_cpu_period:
```
??? variable int "`chrome_role_docker_cpu_quota`"
```yaml
# Type: int
chrome_role_docker_cpu_quota:
```
??? variable int "`chrome_role_docker_cpu_shares`"
```yaml
# Type: int
chrome_role_docker_cpu_shares:
```
??? variable string "`chrome_role_docker_cpus`"
```yaml
# Type: string
chrome_role_docker_cpus:
```
??? variable string "`chrome_role_docker_cpuset_cpus`"
```yaml
# Type: string
chrome_role_docker_cpuset_cpus:
```
??? variable string "`chrome_role_docker_cpuset_mems`"
```yaml
# Type: string
chrome_role_docker_cpuset_mems:
```
??? variable string "`chrome_role_docker_kernel_memory`"
```yaml
# Type: string
chrome_role_docker_kernel_memory:
```
??? variable string "`chrome_role_docker_memory`"
```yaml
# Type: string
chrome_role_docker_memory:
```
??? variable string "`chrome_role_docker_memory_reservation`"
```yaml
# Type: string
chrome_role_docker_memory_reservation:
```
??? variable string "`chrome_role_docker_memory_swap`"
```yaml
# Type: string
chrome_role_docker_memory_swap:
```
??? variable int "`chrome_role_docker_memory_swappiness`"
```yaml
# Type: int
chrome_role_docker_memory_swappiness:
```
??? variable string "`chrome_role_docker_shm_size`"
```yaml
# Type: string
chrome_role_docker_shm_size:
```
Security & Devices
??? variable list "`chrome_role_docker_cap_drop`"
```yaml
# Type: list
chrome_role_docker_cap_drop:
```
??? variable string "`chrome_role_docker_cgroupns_mode`"
```yaml
# Type: string
chrome_role_docker_cgroupns_mode:
```
??? variable list "`chrome_role_docker_device_cgroup_rules`"
```yaml
# Type: list
chrome_role_docker_device_cgroup_rules:
```
??? variable list "`chrome_role_docker_device_read_bps`"
```yaml
# Type: list
chrome_role_docker_device_read_bps:
```
??? variable list "`chrome_role_docker_device_read_iops`"
```yaml
# Type: list
chrome_role_docker_device_read_iops:
```
??? variable list "`chrome_role_docker_device_requests`"
```yaml
# Type: list
chrome_role_docker_device_requests:
```
??? variable list "`chrome_role_docker_device_write_bps`"
```yaml
# Type: list
chrome_role_docker_device_write_bps:
```
??? variable list "`chrome_role_docker_device_write_iops`"
```yaml
# Type: list
chrome_role_docker_device_write_iops:
```
??? variable list "`chrome_role_docker_devices`"
```yaml
# Type: list
chrome_role_docker_devices:
```
??? variable list "`chrome_role_docker_groups`"
```yaml
# Type: list
chrome_role_docker_groups:
```
??? variable bool "`chrome_role_docker_privileged`"
```yaml
# Type: bool (true/false)
chrome_role_docker_privileged:
```
??? variable list "`chrome_role_docker_security_opts`"
```yaml
# Type: list
chrome_role_docker_security_opts:
```
??? variable string "`chrome_role_docker_user`"
```yaml
# Type: string
chrome_role_docker_user:
```
??? variable string "`chrome_role_docker_userns_mode`"
```yaml
# Type: string
chrome_role_docker_userns_mode:
```
Networking
??? variable list "`chrome_role_docker_dns_opts`"
```yaml
# Type: list
chrome_role_docker_dns_opts:
```
??? variable list "`chrome_role_docker_dns_search_domains`"
```yaml
# Type: list
chrome_role_docker_dns_search_domains:
```
??? variable list "`chrome_role_docker_dns_servers`"
```yaml
# Type: list
chrome_role_docker_dns_servers:
```
??? variable string "`chrome_role_docker_domainname`"
```yaml
# Type: string
chrome_role_docker_domainname:
```
??? variable list "`chrome_role_docker_exposed_ports`"
```yaml
# Type: list
chrome_role_docker_exposed_ports:
```
??? variable dict "`chrome_role_docker_hosts`"
```yaml
# Type: dict
chrome_role_docker_hosts:
```
??? variable bool "`chrome_role_docker_hosts_use_common`"
```yaml
# Type: bool (true/false)
chrome_role_docker_hosts_use_common:
```
??? variable string "`chrome_role_docker_ipc_mode`"
```yaml
# Type: string
chrome_role_docker_ipc_mode:
```
??? variable list "`chrome_role_docker_links`"
```yaml
# Type: list
chrome_role_docker_links:
```
??? variable string "`chrome_role_docker_network_mode`"
```yaml
# Type: string
chrome_role_docker_network_mode:
```
??? variable string "`chrome_role_docker_pid_mode`"
```yaml
# Type: string
chrome_role_docker_pid_mode:
```
??? variable list "`chrome_role_docker_ports`"
```yaml
# Type: list
chrome_role_docker_ports:
```
??? variable string "`chrome_role_docker_uts`"
```yaml
# Type: string
chrome_role_docker_uts:
```
Storage
??? variable bool "`chrome_role_docker_keep_volumes`"
```yaml
# Type: bool (true/false)
chrome_role_docker_keep_volumes:
```
??? variable list "`chrome_role_docker_mounts`"
```yaml
# Type: list
chrome_role_docker_mounts:
```
??? variable dict "`chrome_role_docker_storage_opts`"
```yaml
# Type: dict
chrome_role_docker_storage_opts:
```
??? variable list "`chrome_role_docker_tmpfs`"
```yaml
# Type: list
chrome_role_docker_tmpfs:
```
??? variable string "`chrome_role_docker_volume_driver`"
```yaml
# Type: string
chrome_role_docker_volume_driver:
```
??? variable list "`chrome_role_docker_volumes`"
```yaml
# Type: list
chrome_role_docker_volumes:
```
??? variable list "`chrome_role_docker_volumes_from`"
```yaml
# Type: list
chrome_role_docker_volumes_from:
```
??? variable bool "`chrome_role_docker_volumes_global`"
```yaml
# Type: bool (true/false)
chrome_role_docker_volumes_global:
```
??? variable string "`chrome_role_docker_working_dir`"
```yaml
# Type: string
chrome_role_docker_working_dir:
```
Monitoring & Lifecycle
??? variable bool "`chrome_role_docker_auto_remove`"
```yaml
# Type: bool (true/false)
chrome_role_docker_auto_remove:
```
??? variable bool "`chrome_role_docker_cleanup`"
```yaml
# Type: bool (true/false)
chrome_role_docker_cleanup:
```
??? variable string "`chrome_role_docker_force_kill`"
```yaml
# Type: string
chrome_role_docker_force_kill:
```
??? variable dict "`chrome_role_docker_healthcheck`"
```yaml
# Type: dict
chrome_role_docker_healthcheck:
```
??? variable int "`chrome_role_docker_healthy_wait_timeout`"
```yaml
# Type: int
chrome_role_docker_healthy_wait_timeout:
```
??? variable bool "`chrome_role_docker_init`"
```yaml
# Type: bool (true/false)
chrome_role_docker_init:
```
??? variable string "`chrome_role_docker_kill_signal`"
```yaml
# Type: string
chrome_role_docker_kill_signal:
```
??? variable string "`chrome_role_docker_log_driver`"
```yaml
# Type: string
chrome_role_docker_log_driver:
```
??? variable dict "`chrome_role_docker_log_options`"
```yaml
# Type: dict
chrome_role_docker_log_options:
```
??? variable bool "`chrome_role_docker_oom_killer`"
```yaml
# Type: bool (true/false)
chrome_role_docker_oom_killer:
```
??? variable int "`chrome_role_docker_oom_score_adj`"
```yaml
# Type: int
chrome_role_docker_oom_score_adj:
```
??? variable bool "`chrome_role_docker_output_logs`"
```yaml
# Type: bool (true/false)
chrome_role_docker_output_logs:
```
??? variable bool "`chrome_role_docker_paused`"
```yaml
# Type: bool (true/false)
chrome_role_docker_paused:
```
??? variable bool "`chrome_role_docker_recreate`"
```yaml
# Type: bool (true/false)
chrome_role_docker_recreate:
```
??? variable int "`chrome_role_docker_restart_retries`"
```yaml
# Type: int
chrome_role_docker_restart_retries:
```
??? variable string "`chrome_role_docker_stop_signal`"
```yaml
# Type: string
chrome_role_docker_stop_signal:
```
??? variable int "`chrome_role_docker_stop_timeout`"
```yaml
# Type: int
chrome_role_docker_stop_timeout:
```
Other Options
??? variable list "`chrome_role_docker_capabilities`"
```yaml
# Type: list
chrome_role_docker_capabilities:
```
??? variable string "`chrome_role_docker_cgroup_parent`"
```yaml
# Type: string
chrome_role_docker_cgroup_parent:
```
??? variable int "`chrome_role_docker_create_timeout`"
```yaml
# Type: int
chrome_role_docker_create_timeout:
```
??? variable string "`chrome_role_docker_entrypoint`"
```yaml
# Type: string
chrome_role_docker_entrypoint:
```
??? variable string "`chrome_role_docker_env_file`"
```yaml
# Type: string
chrome_role_docker_env_file:
```
??? variable dict "`chrome_role_docker_labels`"
```yaml
# Type: dict
chrome_role_docker_labels:
```
??? variable bool "`chrome_role_docker_labels_use_common`"
```yaml
# Type: bool (true/false)
chrome_role_docker_labels_use_common:
```
??? variable bool "`chrome_role_docker_read_only`"
```yaml
# Type: bool (true/false)
chrome_role_docker_read_only:
```
??? variable string "`chrome_role_docker_runtime`"
```yaml
# Type: string
chrome_role_docker_runtime:
```
??? variable list "`chrome_role_docker_sysctls`"
```yaml
# Type: list
chrome_role_docker_sysctls:
```
??? variable list "`chrome_role_docker_ulimits`"
```yaml
# Type: list
chrome_role_docker_ulimits:
```
=== "Global Override Options"
??? variable bool "`chrome_role_autoheal_enabled`"
```yaml
# Enable or disable Autoheal monitoring for the container created when deploying
# Type: bool (true/false)
chrome_role_autoheal_enabled: true
```
??? variable string "`chrome_role_depends_on`"
```yaml
# List of container dependencies that must be running before the container start
# Type: string
chrome_role_depends_on: ""
```
??? variable string "`chrome_role_depends_on_delay`"
```yaml
# Delay in seconds before starting the container after dependencies are ready
# Type: string (quoted number)
chrome_role_depends_on_delay: "0"
```
??? variable string "`chrome_role_depends_on_healthchecks`"
```yaml
# Enable healthcheck waiting for container dependencies
# Type: string ("true"/"false")
chrome_role_depends_on_healthchecks:
```
??? variable bool "`chrome_role_diun_enabled`"
```yaml
# Enable or disable Diun update notifications for the container created when deploying
# Type: bool (true/false)
chrome_role_diun_enabled: true
```
??? variable bool "`chrome_role_docker_controller`"
```yaml
# Enable or disable Saltbox Docker Controller management for the container
# Type: bool (true/false)
chrome_role_docker_controller: true
```
??? variable list "`chrome_role_docker_networks_alias_custom`"
```yaml
# Type: list
chrome_role_docker_networks_alias_custom:
```
??? variable bool "`chrome_role_docker_volumes_download`"
```yaml
# Type: bool (true/false)
chrome_role_docker_volumes_download:
```