Chrome Setup Guide - ajgillis04/GillisDockerDepot GitHub Wiki

Chrome (noVNC) Service Overview

Provides a full, containerized Google Chrome desktop environment accessible via any modern web browser using noVNC or standard VNC clients.

This service is designed for remote browsing over restricted networks (e.g., corporate filters or guest Wi-Fi) via a Cloudflare Tunnel or local proxy. All web traffic routes through your home network, maintaining complete privacy while preserving user extension profiles and settings.

---

Prerequisites & Configuration Breakdown

• Persistent User Profile: Mapped to ${DOCKERDIR}/chrome:/config to ensure extensions, bookmarks, browsing history, and logins persist across container restarts.
• Shared Memory Allocation (shm_size: "2g"): Essential for modern web browsers like Chrome to prevent tab crashing (e.g., Aw, Snap!) or out-of-memory errors on heavy websites or video playback.
• Security Optimization: Utilizes no-new-privileges:true to prevent child processes from gaining elevated privileges inside the container.
• Service Ports:
  • 3000: HTTP Web UI (noVNC streaming over web browser).
  • 5900: Native VNC port (optional for traditional VNC clients).

---

Step 1: Copy Service Template

Copy the Chrome template from your templates/ directory to create your service definition:

# Copy template file to your active stack directory
cp templates/chrome.yaml compose/chrome.yaml

---

Step 2: Add to Master Compose File

Include the Chrome service inside your primary master configuration file (docker-compose-${HOST_NAME}.yaml):

# Include under your main services definition
include:
  - compose/chrome.yaml

Alternatively, if appending service definitions directly into your master file:

# ------------------------------------------------------------------------------
# chrome - Full Google Chrome Browser (noVNC / VNC)
# ------------------------------------------------------------------------------
# Provides a complete Chrome desktop environment accessible through any browser.
# Ideal for remote browsing from work or restricted networks via Cloudflare Tunnel.
# Runs as a non-root user (PUID/PGID) with persistent profiles and extensions.
# Traffic exits through your home network, bypassing corporate filtering entirely.
# ------------------------------------------------------------------------------
services:
  chrome:
    container_name: chrome.${HOST_NAME}
    hostname: chrome.${HOST_NAME}.lan
    image: ghcr.io/linuxserver/chrome:latest
    environment:
      TZ: ${TZ}
      PUID: ${PUID}
      PGID: ${PGID}
    networks:
      - mediaserver
    ports:
      - ${CHROME_PORT}:3000   # noVNC web UI
      - ${CHROME_VNC_PORT}:5900
    volumes:
      - ${DOCKERDIR}/chrome:/config
    shm_size: "2g"
    restart: always
    security_opt:
      - no-new-privileges:true
    labels:
      ## Watchtower enabled?
      - "com.centurylinklabs.watchtower.enable=true"
      ## Homepage Labels
      - "homepage.group=Infrastructure"
      - "homepage.name=chrome"
      - "homepage.icon=chrome.png"
      - "homepage.href=https://chrome.${DOMAINNAME}/"
      - "homepage.description=Full Chrome browser (noVNC/VNC)"

---

Environmental Variables (.env)

Ensure the corresponding ports are declared in your environment file:

# Chrome Ports
CHROME_PORT=3000
CHROME_VNC_PORT=5900

---

Deployment Commands

Launch or update the container using your project stack flag:

• Deploy Service:

  docker compose -p mediaserver -f docker-compose-${HOST_NAME}.yaml up -d chrome
  

• Force Recreate Container:

  docker compose -p mediaserver -f docker-compose-${HOST_NAME}.yaml up -d --force-recreate chrome
  

• View Logs:

  docker compose -p mediaserver -f docker-compose-${HOST_NAME}.yaml logs -f chrome