Skip to content

Latest commit

 

History

History
156 lines (105 loc) · 8.89 KB

README.md

File metadata and controls

156 lines (105 loc) · 8.89 KB
Raw

BookBrainz Site

Build Status Dependency Status devDependency Status Code Climate

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.

Contributing

We welcome any and all contributions ! Whether you want to add or improve entries on bookbrainz.org, fix an issue on the website or provide new functionnality, we'll be happy to have your help and count you part of our ranks ! If you are new to open source contribution workflows, have a look at this beginner's guide and our contribution guidelines. Looking for existing issues, or to report a new bug you found? Head to our ticket tracker at https://tickets.metabrainz.org/projects/BB ! Still not sure what to start with? Have a look at tickets tagged good-first-bug

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 --recurse-submodules https://github.com/bookbrainz/bookbrainz-site.git

Since this project makes use of git submodules, you need to use git clone --recurse-submodules to clone it. Alternatively, to manually initialize submodules, run these two commands:

git submodule init
git submodule update

Currently used submodule:

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 web 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.

Running the API

As described above for running the web server, you can easily start the API with Docker by running ./develop-api.sh.

Point you browser to localhost:9099/1/api-docs to pull up the documentation and try out the api endpoints.

Don't forget to run ./stop.sh once you are done developing to stop the dependencies that are running in the background.

Advanced users and debugging

Once you get into serious work on the project, we recommend you use a debugger and run the NodeJS server locally (while still running dependencies in Docker for simplicity). Using a debugger will allow you to pause and inspect the server code as it is being executed.

If you do not want to use Docker at all, you can also install the database and search dependencies on your machine

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 -h localhost
  • psql -c 'CREATE EXTENSION "uuid-ossp"; CREATE SCHEMA musicbrainz; CREATE SCHEMA bookbrainz;' -d bookbrainz_test -U postgres -h localhost
  • psql -f sql/schemas/musicbrainz.sql -d bookbrainz_test -U postgres -h localhost
  • psql -f sql/schemas/bookbrainz.sql -d bookbrainz_test -U postgres -h localhost
  • psql -f sql/scripts/create_triggers.sql -d bookbrainz_test -U postgres -h localhost

If you are running these commands from inside the bookbrainz-site docker container, replace -h localhost with -h postgres.