mrcolorrain/vnc-browser repository overview

⁠VNC-Browser

A Lightweight, Ready-to-Use Web Browsing Environment in Docker accessible via VNC or noVNC.

🌟 Leave a star here and on GitHub⁠ if you like this image! Thank you for your support. 🙂

⁠Overview 📖

VNC-Browser is a minimal, customizable, Linux-based Docker image designed to provide a lightweight environment for browsing the web via VNC.

Available variants:

• Debian-based with Chromium browser → mrcolorrain/vnc-browser:debian
• Alpine-based with Firefox browser → mrcolorrain/vnc-browser:alpine

The image bundles ✨:

• A TigerVNC (Xvnc) server
• Auto-starting web browser
• noVNC for browser access

Built for low resource consumption and high performance, suitable for both development and production.

⁠Prerequisites

• Docker installed

⁠Quick Start 🚀

⁠Docker CLI 🐳

docker run -d -p 5900:5900 -p 6080:6080 \
  --name vnc-browser \
  -e VNC_PASSWORD="mypassword" \
  mrcolorrain/vnc-browser:debian

⁠Docker Compose 🐳

version: "3.9"
services:
  vnc-browser:
    container_name: vnc-browser
    image: mrcolorrain/vnc-browser:debian
    ports:
      - "5900:5900"
      - "6080:6080"
    environment:
      VNC_PASSWORD: "mypassword"
    restart: unless-stopped

After starting it then you can connect by:

• Using a browser, you can connect to the noVNC client on localhost:6080 or from everywhere if properly configured using HOSTIP:6080
• Using a VNC Client, you can connect to localhost:5900 or from everywhere if properly configured using HOSTIP:5900

⁠Customization 🎨

You can customize the settings of the Docker container by passing environment variables during the Docker run command.
All current settings are printed in the container logs.

Examples:

• Setting the initial website URL: STARTING_WEBSITE_URL="https://www.google.com"
• Setting the VNC password: VNC_PASSWORD="mypassword"
• Setting the resolution: VNC_RESOLUTION="1280x720"
• Enabling/disabling auto-start for the browser: AUTO_START_BROWSER=true or false
• Enabling/disabling auto-start for xterm: AUTO_START_XTERM=true or false
• Enabling/disabling auto-start for window manager (fluxbox): AUTO_START_WM=true or false
• Enabling/disabling auto-start for TigerVNC (Xvnc): AUTO_START_VNC=true or false
• Enabling/disabling auto-start for noVNC (websockify): AUTO_START_NOVNC=true or false
• Adding browser options: BROWSER_OPTIONS="--start-fullscreen --incognito"
• Adding TigerVNC options: VNC_OPTIONS="-SecurityTypes None"
• Adding window manager options: WM_OPTIONS="-rc /app/fluxbox.conf"
• Adding noVNC options: NOVNC_OPTIONS="--heartbeat=10"
• Adding xterm options: XTERM_OPTIONS="-leftbar"

⁠Available Variables ⚙️

• Example:docker run -d -p 5900:5900 -p 6080:6080 -e STARTING_WEBSITE_URL="https://www.bing.com" -e VNC_PASSWORD="mypassword" -e VNC_RESOLUTION="1920x1080" -e AUTO_START_BROWSER=true -e AUTO_START_XTERM=true mrcolorrain/vnc-browser:alpine

⁠Adding Custom Entrypoints 📜

This image allows you to add custom scripts that will be executed when the container starts, provided customization is enabled.

⁠Instructions for Custom Entrypoints:

• Use this Image as a Base for Your Custom Image or Mount a Volume and Add Your Scripts to the custom entrypoints Directory:
  • Option 1: Create a new image using this image as the base and copy your custom scripts in the custom entrypoints directory.
  • Option 2: Mount a volume containing your custom scripts to the /app/custom_entrypoints_scripts directory.
    • Example:docker run -d -p 5900:5900 -p 6080:6080 -v /path/to/your/scripts:/app/custom_entrypoints_scripts -e CUSTOMIZE=true mrcolorrain/vnc-browser:debian
• More info on custom entrypoints:
  • To customize the image place your .sh (bash) or .py (Python) scripts in the directory and Set the environment variable CUSTOMIZE=true to enable custom scripts execution.
    • Ensure your scripts have the necessary permissions (e.g.: make scripts executable).
    • Ensure your scripts starts with the correct shebang (e.g.: #!/bin/bash or #!/usr/bin/env python3)
  • Execution Order:
    • All scripts in this directory will be executed in alphabetical order.
    • It's recommended to put a single bash entrypoint to keep the complexity low.
  • Logs:
    • The execution and output of these scripts can be reviewed in the container logs.

⁠Support

For support and issues, please use the GitHub repository's issue tracker here⁠.

⁠Contributing 🤲

Contributions to this Docker image are welcome. Please submit pull requests and issues to the GitHub repository here⁠.