BookBrainz Site

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 .example suffix.
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.

Documentation

Auto-generated developer documentation can be found at our corresponding doclets site. Our contributing guide can be found here.

Beta and test subdomains

We have two separate subdomains for the purpose of testing and rolling out beta features. You can sign in with the same account as the one you use on the main website.

beta.bookbrainz.org uses the main database but with a newer version of the code that hasn't been released yet. It is used to test new features.

test.bookbrainz.org: all changes made to this subdomain are not in sync with the main database and vice versa. This domain is for you to tinker with all features of the website freely without having to verify the correctness of the data you enter. This comes in handy if that's all you need to do instead of having to set up BookBrainz locally. This subdomain is used for testing only and the data is not maintained or updated. It is not guaranteed that any of the data will be authentic.

Setting up a local BookBrainz server

BookBrainz depends on having PostgreSQL, Redis, Elasticsearch and NodeJS set up and running.

Running dependencies using Docker

The easiest way to get a local developement server running is using Docker. This will save you a fair amount of set up.

You'll need to install Docker and Docker-compose on your development machine:

When that is installed, clone the repository and follow the instructions below step by step.

Note: If you are using docker-toolbox you need to replace elasticsearch:9200 with ip address of your docker-machine in config.json. To get ip address of your docker machine use command docker-machine ip default for more infomation regarding finding ip address of docker-machine refer here

Cloning

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

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

Configuration

Create a copy of config/config.json.example and rename it to config.json. You can do this by running this command from the bookbrainz-site directory:

cp config/config.json.example config/config.json

If you want to be able to sign-up and edit, you will need to set up authentication under musicbrainz. To get the clientID and clientSecret tokens, head to the MusicBrainz website and register a new developer application. Make sure to enter the callback URL as http://localhost:<port>/cb(port: 9099 by default). You can then copy the tokens for that developer application and paste as strings in your config/config.json. The tokens and callback URL in your config/config.json needs to match exactly the one for the developer application.

Database set-up

When you first start working with BookBrainz, you will need to perform some initialization for PostgreSQL and import the latest BookBrainz database dump.

Luckily, we have a script that does just that: from the command line, in the bookbrainz-site folder, type and run ./scripts/database-init-docker.sh. The process may take a while as Docker downloads and builds the images. Let that run until the command returns.

The latest database dump can be found at this address

Running the server

If all went well, you will only need to run ./develop.sh in the command line from the bookbrainz-site folder. Press ctrl+c to stop the server. The dependencies will continue running in the background.

Wait until the console output gets quiet and this line appears: > cross-env SSR=true node ./lib/server/app.js. After a few seconds, you can then point your browser to localhost:9099.

Make changes to the code in the src folder and run ./develop.sh again to rebuild and run the server.

Once you are done developing, you can stop the dependencies running in docker in the background by running ./stop.sh.

Advanced users

If you do not want to use Docker, you can instead install the database and search dependencies on your machine, and/or run the NodeJS server locally while using dockerized dependencies. Running the NodeJS server locally would be easier if you want to use a debugger, for instance.

Advanced users may want to use Webpack to build, watch files and inject rebuilt pages without having to refresh the page, keeping the application state intact, for the prie of a longer compilation time.

For that, you will need to modify the docker-compose.yml file to mount the src folder and change the command to

npm run debug if you only want to change client files (in src/client)
npm run debug-watch-server if you also want to modify server files (in src/server)

For example:

service:
  bookbrainz-site:
    command: npm run debug
    volumes:
      - "./src:/home/bookbrainz/bookbrainz-site/src"

Testing

The test suite is built using Mocha and Chai. Before running the tests, you will need to set up a bookbrainz_test database in postgres. Here are the instructions to do so:

Run the following postgres commands to create and set up the bookbrainz_test database:

psql -c 'CREATE DATABASE bookbrainz_test;' -U postgres
psql -c 'CREATE EXTENSION "uuid-ossp"; CREATE SCHEMA musicbrainz; CREATE SCHEMA bookbrainz;' -d bookbrainz_test -U postgres
psql -f sql/schemas/musicbrainz.sql -d bookbrainz_test -U postgres
psql -f sql/schemas/bookbrainz.sql -d bookbrainz_test -U postgres
psql -f sql/scripts/create_triggers.sql -d bookbrainz_test -U postgres

bimalkant-lauhny/bookbrainz-site