Table of contents

retroarch-web-games: Packaging an emulator for a static web server

retroarch-web-games is an archived container setup around a web build of RetroArch. The repository combines browser runtime files with scripts and container assembly. Hosting the player and supplying game content are separate concerns.

Application and tools Archived Docker

Updated 2026-10-23
59
HTML · 46.67%
MIT

View source README Markdown

Languages: 5Code breakdown
Documented components: 2Explore modules
Source documents: 1Read the instructions

Repository languagesHTML 46.67%5

Shares calculated from GitHub Linguist bytes.

HTML46.67%

46.67%19,054 bytes

JavaScript23.61%

23.61%9,638 bytes

Python13.72%

13.72%5,600 bytes

Shell11.62%

11.62%4,742 bytes

Language	%	Bytes
HTML	46.67%	19,054
JavaScript	23.61%	9,638
Python	13.72%	5,600
Shell	11.62%	4,742
Dockerfile	4.38%	1,789

GitHub README Language statistics

1. Overview

1.1. Why it exists

Containerized WebAssembly RetroArch emulator bundle ready to run in any browser with zero installation.

1.2. Best fit

Zero-friction retro gaming via Docker on desktop, mobile, or smart TVs.

2. Use cases

Docker image that self-hosts the RetroArch web player behind nginx, with game folders fetched at build time.

People on the left, external systems on the right; each oval is a use case backed by the files cited below.

Install RetroArch web build: Self-hosterOnline file sources
setup_retroarch.sh downloads the previous day's emscripten build from buildbot.libretro.com, extracts it into /var/www/html and unpacks the frontend bundle.
Download game sets: Self-hosterOnline file sources
InternetArchive.py (typer, rich, requests) scrapes the listed archive pages for .zip and .7z files in parallel and saves them under downloads/<system name>.
Sort games by first letter: Self-hoster
sort_mkdir.sh moves each file into a 0-9 or A-Z subfolder; the Dockerfile runs it for every Nintendo system folder.
Run the container: Self-hoster
docker-compose up -d builds the image and maps port 8080 to nginx; entrypoint.sh regenerates the .index-xhr file lists before starting nginx.
Play in the browser: Browser player
The player opens http://localhost:8080, picks a core and loads a game in the RetroArch Web Player page shipped with the nightly build (the repository keeps a copy as index.html, not copied by the Dockerfile).
Publish multi-arch images: Self-hoster
.github/workflows/retroarch-web-games.yaml builds with Docker Buildx for amd64, arm64 and arm/v7 and pushes antoinebou12/retroarch-web-games to Docker Hub.

2.1. Scenario: Host a retro game player on a home server

Clone the repository and check there is room for an image of about 10 GB, as the README warns.
Run docker-compose up -d; the build runs setup_retroarch.sh, InternetArchive.py and sort_mkdir.sh.
When the container starts, entrypoint.sh indexes the cores and bundle, then nginx serves the site.
Open http://localhost:8080 and load a game from the sorted downloads folders.

Files readREADME.mdDockerfiledocker-compose.ymlentrypoint.shsetup_retroarch.shInternetArchive.pyInternetArchive.shsort_mkdir.sh.github/workflows/retroarch-web-games.yaml

3. Getting started

These commands come from the repository documentation. They were not run during this review.

README.md · Warning

docker-compose up -d

4. Repository references

Excerpts from the repository’s guides, in their original language. Links open the inspected source revision.

Prerequisites and first run

4.1. Retroarch Web with Installed Games

README.md

This repository provides a self-hosted RetroArch web player with a collection of games for NES, SNES, Genesis, and Gameboy. Run the Docker image to quickly set up and host your own RetroArch web player and enjoy classic games on your browser.

Read the full instructions ↗

Source documentation

README.md

1 documents read from 1 candidates.

5. Features and components 2

Container assembly: The Dockerfile prepares the web-serving environment and installation material. entrypoint.sh controls container startup, while index.html and libretro.js belong to the browser-facing runtime.
Runtime and content: The browser loads the emulator runtime and its associated assets. Game files must match the expected core and format. Repository download scripts describe content acquisition separately from running the web interface.

6. Architecture

Expand a component to follow its connections, or explore the full diagram.

System components Context

Docker build
- To Static server files
Static server files
- From Docker build
- To Browser emulator runtime
Browser emulator runtime
- From Static server files
- From User-provided game content
User-provided game content
- To Browser emulator runtime

Mermaid Interactive diagram

System overview of the components and connections verified in the repository.

Static architecture view for retroarch-web-games — Static preview. The interactive diagram replaces it after Mermaid loads.

flowchart LR
  n0["Docker build"]
  n1["Static server files"]
  n2["Browser emulator runtime"]
  n3["User-provided game content"]
  n0 --> n1
  n1 --> n2
  n3 --> n2

Text version of the diagram

Docker build → Static server files
Static server files → Browser emulator runtime
User-provided game content → Browser emulator runtime

Follow one path through the code

Read the Dockerfile alongside entrypoint.sh to separate image-build downloads from runtime serving. An image that builds successfully may still lack a browser-compatible core or the assets needed by a selected game.

7. Technical dossier

Built from the source at commit 71b41f9 (11 files). Each item comes from a pattern match in the code, so open the linked file before relying on it.

7.1. Layers and modules

Folders are sorted into layers by name, from the user interface down to data access. Because the sorting uses names only, the diagram says nothing about calls between layers.

Mermaid Layered view

flowchart TB
  subgraph L_presentation["Presentation"]
    direction TB
    presentation_0["(root)<br/>1 file"]
  end
  subgraph L_core["Core source"]
    direction TB
    core_0["(root)<br/>6 files"]
  end
  subgraph L_hosting["Build, CI and hosting"]
    direction TB
    hosting_0["(root)<br/>2 files"]
    hosting_1[".github<br/>2 files"]
  end
  L_presentation ~~~ L_core
  L_core ~~~ L_hosting

Modules and their main layer
Module	Layer	Files	Types	Extensions
`(root)`	Core source	7	0	.sh .py .html

7.2. C4 model

From system context to code declarations. Each level reflects the available source evidence.

UML 1 · System context

The widest C4 view: who uses the project and which outside systems and data stores it relies on. Rendered with uml-mcp.

PlantUML source

@startuml
!include <C4/C4_Context>
LAYOUT_LEFT_RIGHT()
Person(P_cli, "CLI user")
System(SYS, "retroarch-web-games", "retroarch-web-games is an archived container setup around a web build…")
Rel(P_cli, SYS, "Uses")
@enduml

UML 2 · Containers

One level closer: the parts that run separately inside the project, their main language and how calls flow between them. Rendered with uml-mcp.

PlantUML source

@startuml
!include <C4/C4_Container>
LAYOUT_LEFT_RIGHT()
Person(P_cli, "CLI user")
System_Boundary(SYS, "retroarch-web-games") {
  Container(APP, "retroarch-web-games", "HTML")
}
Rel(P_cli, APP, "Uses")
@enduml

UML 3 · Components and layers

Modules grouped by source-layer classification. Boundaries show organization, not runtime isolation or call relationships. Rendered with uml-mcp.

PlantUML source

@startuml
!include <C4/C4_Component>
LAYOUT_TOP_DOWN()
System_Boundary(SYS, "retroarch-web-games") {
Boundary(L0, "Presentation", "layer") {
Component(M0_0, "(root)", "HTML", "1 files")
}
Boundary(L1, "Core source", "layer") {
Component(M1_0, "(root)", ".sh, Python, JavaScript", "6 files")
}
Boundary(L2, "Build, CI and hosting", "layer") {
Component(M2_0, "(root)", "Dockerfile, .yml", "2 files")
Component(M2_1, ".github", ".yml, .yaml", "2 files")
}
}
@enduml

UML 4 · Code

Selected declarations, fields and methods grouped by source file. No inheritance or call edges are inferred. Rendered with uml-mcp.

PlantUML source

@startuml
skinparam backgroundColor transparent
skinparam shadowing false
skinparam roundCorner 10
skinparam defaultFontName Arial
skinparam defaultFontSize 13
skinparam ArrowColor #4e6070
skinparam ArrowFontColor #3d4f5f
skinparam titleFontSize 14
skinparam actorBorderColor #006a62
skinparam actorBackgroundColor #e9f3f4
skinparam usecaseBorderColor #006a62
skinparam usecaseBackgroundColor #e9f3f4
skinparam componentBorderColor #006a62
skinparam componentBackgroundColor #e9f3f4
skinparam interfaceBorderColor #006a62
skinparam interfaceBackgroundColor #ffffff
skinparam nodeBorderColor #4e6070
skinparam nodeBackgroundColor #f4f8fb
skinparam databaseBorderColor #006a62
skinparam databaseBackgroundColor #ffffff
skinparam cloudBorderColor #4e6070
skinparam cloudBackgroundColor #f0f5fa
skinparam artifactBorderColor #006a62
skinparam artifactBackgroundColor #ffffff
skinparam rectangleBorderColor #b0c2d3
skinparam activityBorderColor #006a62
skinparam activityBackgroundColor #e9f3f4
skinparam partitionBorderColor #b0c2d3
skinparam stereotypeCBackgroundColor #ffffff
top to bottom direction
hide empty members
package "retroarch-web-games" {
object "libretro.js" as FN0 {
  cleanupStorage()
  idbfsInit()
  idbfsSyncComplete()
  appInitialized()
  preLoadingComplete()
  setupFileSystem()
}
object "InternetArchive.py" as FN1 {
  simplify_filename()
  download_file()
  download_files()
  download()
}
object "InternetArchive.sh" as FN2 {
  download_7z_files()
  download_zip_files()
}
}
@enduml

7.3. Public interface

Outside code can use everything listed here. The project also declares 0 public types.

Command line 1

download

7.4. Business logic

No classes were extracted, so these are the largest source files and their functions.

libretro.js: cleanupStorage, idbfsInit, idbfsSyncComplete, appInitialized, preLoadingComplete, setupFileSystem
InternetArchive.py: simplify_filename, download_file, download_files, download
setup_retroarch.sh: No named functions.
InternetArchive.sh: download_7z_files, download_zip_files
sort_mkdir.sh: No named functions.
entrypoint.sh: No named functions.

7.5. Database and persistence

7.6. External integrations

HTTP clients

requests

Hosts named in the code

archive.org 2 files InternetArchive.py:86
myrient.erista.me 2 files InternetArchive.py:104
buildbot.libretro.com 1 files setup_retroarch.sh:16

7.7. CI/CD pipeline

1 GitHub Actions workflow, 1 job. Each box is a job; double-bordered boxes publish or deploy, and arrows follow needs.

Mermaid Pipeline flow

flowchart LR
  subgraph wf0["Build and Push RetroArch Web Games"]
    direction LR
    wf0_build_and_push[["build-and-push<br/>ubuntu-latest"]]
  end
  t0(["push · pull request"])
  t0 --> wf0_build_and_push

Workflows, triggers, jobs and targets
Workflow	Triggers	Jobs	Publishes to
Build and Push RetroArch Web Games `.github/workflows/retroarch-web-games.yaml`	push, pull request	build-and-push `ubuntu-latest` Checkout repository · Setup QEMU and Docker Buildx · Setup Docker Buildx · Login to Docker Hub · Build and Push Docker Image	—

7.8. Deployment

Mermaid Deployment diagram

flowchart LR
  repo[("GitHub repository")]
  ci[["GitHub Actions<br/>1 workflow"]]
  image["Docker image<br/>FROM debian:bullseye"]
  repo -->|"push or pull request"| ci
  ci -->|"docker build"| image

UML Deployment

The outer node is where the code runs. Each base image points to what it builds, solid arrows lead to databases and dashed ones to outside services. Rendered with uml-mcp.

PlantUML source

@startuml
skinparam backgroundColor transparent
skinparam shadowing false
skinparam roundCorner 10
skinparam defaultFontName Arial
skinparam defaultFontSize 13
skinparam ArrowColor #4e6070
skinparam ArrowFontColor #3d4f5f
skinparam titleFontSize 14
skinparam actorBorderColor #006a62
skinparam actorBackgroundColor #e9f3f4
skinparam usecaseBorderColor #006a62
skinparam usecaseBackgroundColor #e9f3f4
skinparam componentBorderColor #006a62
skinparam componentBackgroundColor #e9f3f4
skinparam interfaceBorderColor #006a62
skinparam interfaceBackgroundColor #ffffff
skinparam nodeBorderColor #4e6070
skinparam nodeBackgroundColor #f4f8fb
skinparam databaseBorderColor #006a62
skinparam databaseBackgroundColor #ffffff
skinparam cloudBorderColor #4e6070
skinparam cloudBackgroundColor #f0f5fa
skinparam artifactBorderColor #006a62
skinparam artifactBackgroundColor #ffffff
skinparam rectangleBorderColor #b0c2d3
skinparam activityBorderColor #006a62
skinparam activityBackgroundColor #e9f3f4
skinparam partitionBorderColor #b0c2d3
skinparam stereotypeCBackgroundColor #ffffff
node "Docker image" as H {
  artifact "retroarch-web-games" as APP
}
artifact "FROM debian:bullseye" as IMG0
IMG0 ..> APP : builds
@enduml

Where it runs

Docker base images

debian:bullseye

7.9. Security

Supply chain

Renovate updates

Nothing found for: Private interface, Services, Entities, Stack and dependencies, Monitoring, Testing.

8. Deployment and operations

The ports, storage, and startup relationships below come from the repository configuration. depends_on records startup order, not service readiness.

9. Reference

8 / 8 eligible files read (15 in the tree); 0 oversized, 0 failed reads and 0 syntax diagnostics.

What the scan covers

Known dependency/build folders, credential files and binaries are excluded. The scan covers READMEs, recognized manifests and parser-supported source files.

Linguist statistics cover the whole repository and may include other languages.

11. Files to read 3

12. Glossary

Repository

The versioned source files, configuration, and history of a project.

README

The repository’s entry document, usually covering its purpose and initial setup.

Dependency

A library, tool, or service that another component needs to build or run.

Container

An isolated process environment created from an image. Persistent data needs storage outside the container’s disposable filesystem.

Published port

A host port mapped to a service’s container port. Publishing a port can expose that service beyond its container network.

CLI

A text interface in which commands and arguments select operations. Exit codes let scripts detect success or failure.

Build

The steps that turn source files and dependencies into a runnable program or distributable artifact.

13. References

antoinebou12. (2026, November 5). retroarch-web-games. [Software repository] github.com.
antoinebou12. (2026, November 5). retroarch-web-games: README. [Repository documentation] github.com.
antoinebou12. (2026, November 5). Dockerfile. [Source file] github.com.
antoinebou12. (2026, November 5). entrypoint.sh. [Source file] github.com.
antoinebou12. (2026, November 5). index.html. [Source file] github.com.
Boucher, A. (2026, October 23). retroarch-web-games: Packaging an emulator for a static web server. [Project article] antoineboucher.info.
Boucher, A. (2024, January 1). RetroArch Web Games. [Project article] antoineboucher.info.

Sources without a publication date show the date they were last checked, November 5, 2026. File links retain the inspected revision where available.