You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
Robot 16cdfd111e
active on Thursday 02-February, 2023
1 day ago
.github/workflows Instead lets make that a manual update option. 7 months ago
conf Adds ChiNCVs to be part of the test build. 4 months ago
src Adds the new local book names to the build. 4 months ago
.active active on Thursday 02-February, 2023 1 day ago
.gitignore Added a testing option. Added the option to set config values from a file. Added a quiet option. Added completion message. Added a timer. 2 years ago
LICENSE Merged getBible changes into SWORD-to-JSON 2 years ago Updated the user setup script path. 2 years ago Made a few corrections. 1 year ago

V2 API Builder

These scripts are used to build the version 2 of the getBible API based on the Crosswire modules.

Before you continue reading the instructions...

You must please agree to the following few conventions:

  • Please run the script (as explained below) once a week to keep your repositories in sync with the Crosswire Modules.
  • Please do not remove the hash methods from the project as they are used to identify change for those using your scripture JSON API and HASH repositories.
  • Please do not host the repository that contains all the scripture JSON on a public repository like github (unless private), since if it gets forked those downstream repositories may go out of sync with any changes/fixes from the Crosswire Modules.
  • Should you expose the scripture JSON API to the public (like has done), please let us know by posting the details in an Issue on this repository.
  • Should you not be able to do (or continue doing) any of the above requests then please do not place any of the project produced JSON or HASH files in the public space or in any project.

You can still just use directly and do not need to run your own API.

You may ask Why?

Well, because we at getBible would like to comply with the Crosswire conventions to remain in sync with their modules all the way downstream from our project. Those who do not honor these agreements are responsible for Scripture Text (Digital) being incorrectly distributed with errors, as the digital versions of these Bibles may contain spelling mistakes, typos, or other errors like missing verses or chapters. So as they are discovered and fixed, Crosswire releases updates to their modules, and our commitment to the above agreed conventions ensure that these updates flow downstream. Should you have any further questions please do not hesitate to open an issue on this repository. Honestly, without these measures there is no getBible project... it is that serious.

We made this code public so those who use our API can see how it is build, and help improve and guide the project's code and future.

Okay, Lets get started... ˘Ô≈ôﺣ

Should you like to contribute any improvements either in code or conduct, just open an issue as the first step, and beginning of the conversation. ツ

Install Dependencies (only Ubuntu 20 *tested)

Install Python3.8+

$ sudo apt update
$ sudo apt install python3.8 python3-pip python3-requests

make sure the python3 version is 3.8 or higher so that the JSON order remains the same as found on our API, else your hash values will not be the same.

Install pysword (A native Python reader of the SWORD Project Bible Modules)

$ sudo pip3 install future
$ sudo pip3 install pysword

Setup the Builder

Clone this repository

$ git clone
$ cd v2_builder/

Run the Builder

Make sure that the following files are executable.

$ sudo chmod +x
$ sudo chmod +x src/
$ sudo chmod +x src/
$ sudo chmod +x src/
$ sudo chmod +x src/
$ sudo chmod +x src/

Start the Building process (this will take long)

$ ./

Help Menu

Usage: ./ [OPTION...]

You are able to change a few default behaviours in the getBible API builder
  ------ Passing no command options will fallback on the defaults -------

	Options ᒡ◯ᵔ◯ᒢ
	set the API target folders full path
		- target folders will be created using this path

	example: ./ --api=/home/bible/v2

	two folders will be created:
		- /home/bible/v2
		- /home/bible/v2_scripture

		- repo/v2
		- repo/v2_scripture

	(these are the target folders)
	set the path to the Bible config file
		- This file contains the list of Crosswire
		  Bible Modules that will be used to build
		  the JSON API files

	example: ./ --bconf=/home/bible/getbible.json

		- repo/conf/CrosswireModulesMap.json
	set all the config properties with a file

	example: ./ --conf=/home/bible/.config/getbible.conf

		- repo/conf/.config
	clone and/or pull target folders/repositories

	example: ./ --pull
	push changes to github (only if there are changes)
		- setup the target folders (see target folders)
		- linked them to github (your own repos)
		- must be able to push (ssh authentication needed)


	example: ./ --push
	set the ZIP target folder full path for the Crosswire Modules

	example: ./ --zip=/home/bible/sword_zip

		- repo/sword_zip
	Do not download all Crosswire Modules (helpful in testing)
	Only use this if you already have modules.

	example: ./ -d
	To only hash the existing JSON scripture files

	example: ./ --hashonly
	Trigger github workflow behaviour

	example: ./ --github
	Run a test with only three Bibles

	example: ./ --test
	To show all defaults, and not run the build

	example: ./ --dry
	Quiet mode that prevent whiptail from showing progress

	example: ./ -q
	example: ./ --quiet
	display this help menu

	example: ./ -h
	example: ./ --help
			getBible JSON API.v2

Setup Cron Job

To run this in a crontab

$ crontab -e

Then add the following line, update the time as needed

10 5 * * MON /home/username/v2_builder/ >> /home/username/v2_builder/builder.log 2>&1

Use GitHub Actions

You will need to setup a list of secrets in your fork of v2_builder.

The github user email being used to build


The github username being used to build


gpg -a --export-secret-keys >myprivatekeys.asc The whole key file text from the above myprivatekeys.asc This key must be linked to the github user being used


The name of the myprivatekeys.asc user


A OFFICIAL repository of the hash files like: the github user must have push/pull access to this repo


A TEST repository of the hash files like: the github user must have push/pull access to this repo


A OFFICIAL repository of the scripture files like: the github user must have push/pull access to this repo


A TEST repository of the scripture files like: the github user must have push/pull access to this repo


A id_ed25519 ssh private key liked to the github user account


A ssh public key liked to the github user account


All these secret values are needed to fully automate the build. Then you need to go to the actions are in your fork of v2_builder and activate the actions.

Don't Forget Our Agreement!

Free Software (with responsibility)

Llewellyn van der Merwe <>
Copyright (C) 2019. All Rights Reserved
GNU/GPL Version 2 or later -