{"id":20526483,"url":"https://github.com/gbdev/homebrewhub","last_synced_at":"2025-06-14T01:35:05.279Z","repository":{"id":41899733,"uuid":"95916620","full_name":"gbdev/homebrewhub","owner":"gbdev","description":"A digital repository of of homebrew games, patches, hackroms for old consoles. Provides community submission, tagging and rating features.","archived":false,"fork":false,"pushed_at":"2025-04-28T12:58:15.000Z","size":98,"stargazers_count":46,"open_issues_count":30,"forks_count":9,"subscribers_count":5,"default_branch":"main","last_synced_at":"2025-05-07T04:08:33.883Z","etag":null,"topics":["emulator","game-boy","hacktoberfest","homebrew","homebrew-hub","json-api","wiki"],"latest_commit_sha":null,"homepage":"https://hh.gbdev.io","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/gbdev.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null},"funding":{"open_collective":"gbdev"}},"created_at":"2017-06-30T19:07:36.000Z","updated_at":"2025-04-28T12:58:19.000Z","dependencies_parsed_at":"2023-12-16T05:42:31.848Z","dependency_job_id":"32720f07-50d0-40ea-b59f-3f0e0d90246f","html_url":"https://github.com/gbdev/homebrewhub","commit_stats":{"total_commits":87,"total_committers":7,"mean_commits":"12.428571428571429","dds":"0.26436781609195403","last_synced_commit":"b1e069c1d40572ff81271e86fb324e2ddea4425b"},"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gbdev%2Fhomebrewhub","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gbdev%2Fhomebrewhub/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gbdev%2Fhomebrewhub/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gbdev%2Fhomebrewhub/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/gbdev","download_url":"https://codeload.github.com/gbdev/homebrewhub/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252810273,"owners_count":21807759,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["emulator","game-boy","hacktoberfest","homebrew","homebrew-hub","json-api","wiki"],"created_at":"2024-11-15T23:14:21.518Z","updated_at":"2025-05-07T04:08:39.110Z","avatar_url":"https://github.com/gbdev.png","language":"Python","funding_links":["https://opencollective.com/gbdev"],"categories":[],"sub_categories":[],"readme":"# hhub\n\n[![uv](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/uv/main/assets/badge/v0.json)](https://github.com/astral-sh/uv)\n[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)\n![Github CI](https://github.com/gbdev/homebrewhub/actions/workflows/ci.yaml/badge.svg)\n\nThis repository provides the source code of the [Homebrew Hub backend](https://hh3.gbdev.io/api), which powers [Homebrew Hub](https://hh.gbdev.io), the largest digital collection of Game Boy and Game Boy Color homebrews, playable natively in your browser.\n\nTable of contents:\n\n- [API Documentation](#api-documentation)\n- [Local Development](#local-development)\n  - [1. Prerequisites](#1-prerequisites)\n  - [2. Pull the games databases](#2-pull-the-games-databases)\n  - [3A. Docker based requirements](#3a-docker-based-requirements)\n  - [3B. Manual requirements](#3b-manual-requirements)\n  - [4. Synchronising the database](#4-synchronising-the-database)\n  - [5. Get the frontend running](#5-get-the-frontend-running)\n- [Legacy](#legacy)\n\n## API Documentation\n\nDocumentation about the exposed API and how to interact with the Homebrew Hub instance over hh3.gbdev.io, see [API.md](API.md).\n\n## Local Development\n\n### 1. Prerequisites\n\nTo run a complete local instance of Homebrew Hub, let's start with:\n\n```sh\n# Cloning the repo locally\ngit clone https://github.com/gbdev/homebrewhub\n\n# Changing directory into the cloned repo\ncd homebrewhub\n```\n\nNow, no matter if you choose the local setup or the docker one, you will need a couple of pre-requirements on the system:\n\n- `pre-commit` \u003cbr\u003e\n  E.g. Install it from pip:\n  ```bash\n  python3 -m venv env\n  source env/bin/activate\n  pip install pre-commit\n  ```\n  After it's installed, run `pre-commit install` in the project root folder to see if everything gets initialised correctly. `pre-commit run --all-files` will run it against the whole repository.\n- (Optional) The `gbtoolsid` ([Game Boy Toolchain ID](https://github.com/bbbbbr/gbtoolsid)) executable must be available in the project root to populate toolchain details for the imported entries. Get a build on the [Releases](https://github.com/bbbbbr/gbtoolsid/releases/latest) page and extract the zip or run `make prepare-gbtid` from the root of the repository.\n\n### 2. Pull the games database(s)\n\nTo populate the database, we'll need some sources. Here's how to pull all the 'official' databases (you need at least one):\n\n```bash\n# Let's move to a subdirectory\ncd db-sources\n\n# GB/GBC\ngit clone https://github.com/gbdev/database/ db-sources/database-gb\n# GBA\ngit clone https://github.com/gbadev-org/games db-sources/database-gba\n# NES\ngit clone https://github.com/nesdev-org/homebrew-db db-sources/database-nes\n\n## or simply..\nmake init-db\n```\n\n### 3A. Docker based requirements\n\nFirst, install Docker ([download link](https://docs.docker.com/get-docker/)), and compose.\n\nAfter that, follow the steps below to get started running the project using containers:\n\n```bash\n# Start up backing services (web server, database and database admin)\n# NOTE: This command will also take care of synchronising the database (including migrations)\ndocker compose up --build\n\n# Once that's finished, from another shell, query the /api/all route to see if everything's there\ncurl http://localhost:8081/api/all\n```\n\n### 3B. Manual requirements\n\nYou need Python 3 and a couple of packages to build `psycopg2` (database driver).\n\nOn Linux, this command should install all requirements:\n\n```bash\napt install python3 libpq-dev python3-dev python3-venv\n```\n\nNext, install Postgres 12 ([download link](https://www.postgresql.org/download/)), create a user, password and a database named `hh`. Have it running in the background on port `5432`.\n\nAfter that, follow the steps below to get started running the project manually:\n\n```bash\n# Make sure you are in the cloned repository\ncd homebrewhub\n\n# Set up a virtual env\npython3 -m venv env\n\n# Activate it\nsource env/bin/activate\n\n# Install Python dependencies\npip install -r requirements.txt\n\n# Install Pre-Commit git hooks (for enforcing code style on git commit)\npre-commit install\n\n# Prepare migrations for our Entry model\npython3 manage.py makemigrations hhub\n\n# Sync the database for the first time\npython3 manage.py migrate\n\n# Populate with the entries from the database repository\nDATABASE_URL=postgres://yourpostgresuserhere:yourpostgrespasswordhere@localhost:5432/hh python3 manage.py runscript sync_db\n\n# Optional note: You can export the environment variable to avoid typing it each time:\nEXPORT DATABASE_URL=postgres://yourpostgresuserhere:yourpostgrespasswordhere@localhost:5432/hh\n\n# Start the Django app\nDATABASE_URL=postgres://yourpostgresuserhere:yourpostgrespasswordhere@localhost:5432/hh python3 manage.py runserver\n\n# In another terminal, query the /api/all route to see if everything's there\ncurl https://localhost:8000/api/all\n```\n\n### 4. Synchronising the database\n\nThe Homebrew Hub \"source\" database is simply a collection of folders, hosted as a git repository, each one containing an homebrew entry (ROM, screenshots, ..) and a \"game.json\" manifest file providing more details and metadata in a _consistent_ way (see the game.json JSON schema).\n\nFor more information check the [\"database\" repository](https://github.com/gbdev/database) documentation.\n\nThis enables the database to be \"community-maintained\", allowing everyone to add new entries (manually or by writing scrapers) or improve existing ones simply by opening Pull Requests.\n\nThe \"real\" database needs to be built (and updated when a commit gets pushed) from this collection of folders. This job is done by the **sync_db.py** script.\n\n\u003e Keep in mind that the two are not equivalent, as the Django database will keep additional values about each entry (e.g. simple analytics).\n\nEvery time you want to trigger a database sync (e.g. you pulled some updates on the games database), run:\n\n```bash\npython3 manage.py runscript sync_db\n```\n\n### 5. Get the frontend running\n\nNow that you have your Homebrew Hub backend up and running, you can check [Virens](https://github.com/gbdev/virens), our VueJS based frontend shipping web assembly builds of mGBA and binjgb to actually play all these entries directly on a browser :D\n\nRemember to set `BASE_API_URL=http://localhost:8081` so the API calls from Virens will point to the backend we just brought up.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgbdev%2Fhomebrewhub","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgbdev%2Fhomebrewhub","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgbdev%2Fhomebrewhub/lists"}