DOCSEARCHbyAlgolia
Submit Docs

Browservice Documentation

repository·master·Indexed 23 days ago

https://github.com/ttalvitie/browservice

A 'Browser as a Service' proxy that renders modern web content as images using the Chromium Embedded Framework (CEF). It enables historical and legacy browsers on old hardware to access the modern web safely by serving compressed PNG or JPEG images of the browser viewport and forwarding user input via URL requests.

Tokens
10.9K
Snippets
18
Records
51
Agent score
79%

What's inside Browservice

  1. Core features of Browservice

    master

    Browservice provides a suite of features for immersive web browsing on legacy systems:

    • Interaction: Keyboard and mouse interaction with all web pages supported by Chromium (including web apps like YouTube, GitHub, etc.).
    • Multi-window: Support for multiple concurrent browser windows.
    • Clipboard: Shared text clipboard across all windows (via Ctrl+C/Ctrl+V) and a client-side form for clipboard access.
    • UI/UX: A control bar with a retro-style UI, an address field implemented on the proxy server, and page zooming.
    • File Handling: Support for file uploads and file downloads (with a security confirmation button on the control bar).
    • Navigation: Native Back/Forward/Refresh button forwarding from the client.
    • Search: Text search within the current page and bookmarks.
    • Customization: Selectable image compression quality (JPEG or PNG) and customizable font render parameters.

  2. What is Browservice?

    master

    Browservice is a web "proxy" server designed to enable modern web browsing on historical/legacy browsers.

    How it works:

    1. The Browservice server uses the Chromium Embedded Framework (CEF) to run a modern Chromium instance.
    2. It renders the browser viewport into an off-screen buffer.
    3. The view (including a control UI bar) is compressed as a PNG or JPEG image.
    4. The images are served to the client via an embedded HTTP server.
    5. A JavaScript application running on the client browser displays these images and forwards user input (keyboard/mouse events) back to the proxy via URL requests.

    This approach allows old hardware (e.g., ~1 GHz CPUs) to achieve usable performance (often >10 FPS) if the network connection between the proxy and client is fast (e.g., 100 Mbit/s Ethernet LAN).

  3. Understand the Vice plugin API

    master

    Browservice is split into two components:

    1. The main Browservice program: Manages the web browser using CEF.
    2. The Retrojsvice plugin: Serves the browser GUI to clients over HTTP.

    These components communicate via the vice plugin C API (defined in vice_plugin_api.h).

    Extending Browservice:

    • You can replace the Retrojsvice plugin with your own implementation to change how the browser is accessed (e.g., for native clients on historical OSs).
    • To select a plugin, use the --vice-plugin command line option.
    • Any command line options starting with --vice-opt- are passed directly to the selected vice plugin.

  4. Security considerations for Browservice

    master

    Using Browservice reduces the attack surface when browsing the modern web on outdated software, but it does not guarantee absolute security.

    Security Model:

    • Reduced Attack Surface: Untrusted web content reaches the client only as compressed images, file downloads, or explicitly requested clipboard data.
    • URL Privacy: The actual URLs of accessed pages are not sent to the client as text; the address bar is rendered on the server side.
    • Best Practices: To maximize security, keep the proxy server up to date and ensure the connection between the proxy and the client is made through a trusted, isolated network.

    Warning: You should still exercise caution and be aware of the risks when performing security-critical web browsing.

  5. Create an official Browservice binary distribution

    master

    To package a release manually:

    1. Rename the Release directory to browservice-v[VERSION]-windows[32|64].
    2. Copy the following redistributable DLLs from the MSVC redist folder of the correct architecture to your directory:
      • msvcp140.dll
      • vcruntime140.dll
      • vcruntime140_1.dll (64-bit builds ONLY)
    3. Compress the directory into a .zip file.

    Alternatively, use the automated script: tools/build_windows.py.

  6. Build patched CEF using Docker

    master

    To build the patched CEF manually, follow these steps to create a Docker image and run the build script.

    Note on Architectures: The command below creates an x86_64 build. Replace x86_64 with aarch64 for ARM64 or armhf for 32-bit ARM in the commands below.

    1. Clone the repository.
    2. Build the cefbuild Docker image.
    3. Prepare a build directory and copy the build script.
    4. Run the build inside the container.
    5. Copy the resulting tarball out of the build directory.
    # Clone the Browservice code repository
git clone https://github.com/ttalvitie/browservice.git

# Create the cefbuild Docker image
cd browservice/tools/linux_cef_build_docker_image/
sudo docker build -t cefbuild .

# Prepare a build directory
cd ..
mkdir build
chmod 777 build
cp build_patched_cef.py build/

# Build CEF (this takes a lot of time; run in screen if you are behind an unreliable SSH connection)
# This command creates a x86_64 build; replace x86_64 by aarch64 for ARM64 and armhf for 32-bit ARM
sudo docker run -v "${PWD}/build":/home/appuser cefbuild python3 /home/appuser/build_patched_cef.py /home/appuser/build /home/appuser/patched_cef_x86_64.tar.bz2 x86_64

# Copy the built patched CEF distribution away from the build directory
cp build/patched_cef_x86_64.tar.bz2 .

# Remove the build directory
sudo rm -r build

  7. Install and run the Browservice proxy on Linux

    master

    On Linux, the easiest way to run the Browservice proxy is using an AppImage.

    1. Download the appropriate browservice-RELEASE-ARCH.AppImage from the latest releases. Replace RELEASE with the version and ARCH with your architecture (e.g., x86_64, armhf, or aarch64).
    2. Make the file executable:
    chmod +x browservice-RELEASE-ARCH.AppImage
    1. Run the proxy as a normal user (do NOT use root):
    ./browservice-RELEASE-ARCH.AppImage

    Optional: Install Verdana font To improve the graphical user interface, you can install the Verdana font to $HOME/.browservice/appimage/fonts by running:

    ./browservice-RELEASE-ARCH.AppImage --install-verdana
    chmod +x browservice-RELEASE-ARCH.AppImage
./browservice-RELEASE-ARCH.AppImage

  8. Enable proprietary video codecs (H264/AAC)

    master

    By default, Browservice uses a CEF distribution that does not include proprietary codecs like H264 and AAC. To enable them, you must build your own CEF distribution with the following GN_DEFINES environment variable:

    proprietary_codecs=true ffmpeg_branding=Chrome

    After building CEF, you must build Browservice using your custom CEF distribution instead of the prebuilt one. (On Linux, copy your custom CEF distribution to cef.tar.bz2 before running the build process). Note that building CEF is resource-intensive and may require legal licensing for the codecs.

  10. Install Browservice dependencies via vcpkg

    master

    Browservice requires several dependencies managed via vcpkg. You must install both 32-bit (x86-windows) and 64-bit (x64-windows) versions of the packages. If you are only targeting one architecture, you can omit the others.

    vcpkg install openssl:x86-windows openssl:x64-windows
vcpkg install pango:x86-windows pango:x64-windows poco[netssl]:x86-windows poco[netssl]:x64-windows libjpeg-turbo:x86-windows libjpeg-turbo:x64-windows

  11. Install and run the Browservice proxy on Windows

    master

    On Windows, Browservice is distributed as a zip file browservice-RELEASE-windowsBITS.zip (use the 64-bit version for most modern PCs).

    1. Download the zip file from the latest releases.
    2. Extract the contents.
    3. Open a Command Prompt, navigate to the extracted directory, and run:
    browservice.exe

    Alternatively, you can double-click browservice.exe in File Explorer to open a console window with the logs. To pass command line options, use a shortcut or a batch file.

  12. Build the browservice project in Visual Studio

    master

    Once CMake has generated the solution:

    1. Open cef.sln located in the build subdirectory of the CEF directory using Visual Studio.
    2. Set the build configuration to Release (for production) or Debug.
    3. In the Solution Explorer, right-click the browservice project and select Build.
    4. The resulting binary will be in build\browservice\Release (or Debug).