This repository contains the code for the BookBrainz web site. The directories are arranged as follows:
config- the config to be used when running the site; copy the example files and edit, dropping the.examplesuffix.scripts- scripts used during the development and deployment of BookBrainz.src- node.js source files defining the site logic and user interface.static- static files which are served by node as part of the site.templates- Jade templates defining how the site looks - we're slowly replacing these with React.test- unit tests and functional tests for the site.
Additionally, after building the client JavaScript (see below), the following directories will exist:
static/stylesheets- the CSS generated from compiling the project LESS files (src/client/stylesheets).static/js- minified JavaScript files which are referred to by the site pages.
Auto-generated developer documentation can be found at our corresponding doclets site. Our contributing guide can be found here.
BookBrainz depends on having PostgreSQL, Redis and Elasticsearch and NodeJS set up and running.
To get PostgreSQL, use one of the following commands:
Debian-based OS
sudo apt-get install postgresql
Red Hat-based OS
sudo yum install postgresql-server
To install Redis, run similar commands to get the dependency from your package manager:
Debian-based OS
sudo apt-get install redis-server
Red Hat-based OS
sudo yum install redis
To install Elasticsearch, follow the instructions at https://www.elastic.co/guide/en/elasticsearch/reference/current/_installation.html
And finally, for NodeJS, choose the correct installation file, or view the instructions for package managers at https://nodejs.org/en/download/current/
No setup is required for Redis or Elasticsearch. However, it is necessary to perform some initialization for PostgreSQL and import the latest BookBrainz database dump.
Firstly, begin downloading the latest BookBrainz dump from https://bookbrainz.org/dumps/latest.tar.bz2.
Then, uncompress the latest.tar.bz2 file, using the bzip2 command:
bzip2 -d latest.tar.bz2
This will give you a file that you can restore into PostgreSQL, which will set up data identical to the data we have on the bookbrainz.org website. To do this, run:
sudo -u postgres pg_restore -e -C -O latest.tar -d postgres
At this point, the database is set up, and the following command should give you a list of usernames of BookBrainz editors (after entering the password from earlier):
sudo -u postgres psql bookbrainz -c "SELECT name FROM bookbrainz.editor"
Since this project makes use of
git submodules, you
need to use git clone --recursive to clone it. Alternatively you can follow
the directions in the documentation linked here to manually initialize
submodules.
Currently used submodules:
- MonkeyDo/lobes in
src/client/stylesheets/lobes
To clone the repository and point the local HEAD to the latest commit in the
stable branch, something like the following command should work:
git clone --recursive https://github.com/bookbrainz/bookbrainz-site.git
The site depends on a number of node packages which can be installed using npm:
cd bookbrainz-site/
npm install
This command will also compile the site LESS and JavaScript source files.
Create a copy of config.json.example and rename it to config.json. Then,
edit the values so that they are correct for your environment. If the prior
instructions have been followed, it should only be necessary to change
the PostgreSQL username and password.
A number of subcommands exist to manage the installation and run the server. These are described here; any commands not listed should not be called directly:
- start - start the server in production mode, with code built once
- debug - start the server in debug mode, with code watched for changes
- lint - check the code for syntax and style issues
- test - perform linting and attempt to compile the code
- jsdoc - build the documentation for JSDoc annotated functions within the code