Open Library

Open Library is an open, editable library catalog, building towards a web page for every book ever published.

Table of Contents

• Overview
• Installation
• Code Organization
• Architecture
  • The Frontend
  • The Backend
  • The Service Architecture
• Developer's Guide
• Running Tests
• Contributing
• Public APIs
• FAQs
• License

Overview

Open Library is an effort started in 2006 to create "one web page for every book ever published". It provides access to many public domain and out-of-print books, which can be read online.

• Learn more about the Open Library project
• The Vision (Dream) of OpenLibrary
• Visit the Blog

Installation

Docker

We're supporting Docker, moving forward. If you are a new contributor, especially on linux, please consider setting up using the Docker Instructions.

Our Docker environment is in active development. Want to contribute? Here's our top-level Docker todo-list and a list of open Docker issues.

Vagrant (Legacy & Windows)

First you need to have installed Virtualbox and Vagrant.

Next, fork the OpenLibrary repo to your own Github account and clone your forked repo to your local machine:

git clone [email protected]:YOURACCOUNT/openlibrary.git

For Windows Users Only

1. Before proceeding further, kindly make sure to set the line endings to type input by executing the below command:

# Configure Git on Windows to properly handle line endings so Git will convert CRLF to LF on commit
git config --global core.autocrlf input

Enter the project directory and provision + launch the dev virtual machine instance using vagrant:

cd openlibrary
vagrant up

For Windows Users Only

1. If dev virtual machine instance doesn't start by any chance and throws an error No module found then you need to check whether symlinks are enabled or not. The openlibrary makes use of symlinks, which by default git on windows checks out as plain text files. You can check that by executing below command:

git config core.symlinks

2. If symlinks are enabled then go to the next step. If symlinks are not enabled then enable it by executing below command:

git config core.symlinks true

3. Then hard reset the repo so git will create proper symlinks by executing below command:

git reset --hard HEAD

Note:
If you get permission issue while executing any above commands then kindly run the git bash shell as an Administrator.

You can now view your running instance by loading http://localhost:8080 in a web browser.

You can turn off the virtual machine from the host machine using:

vagrant halt

To administrate and ssh into the vagrant dev virtual machine, type:

vagrant ssh

Note:
Remember that, thanks to vagrant and virtual box, your local folder openlibrary (where you ran vagrant up) contains exactly the same files as /openlibrary in the dev virtual machine (the one that you login to via vagrant ssh).

Reload vagrant services:

• From within vagrant restart the Open Library service via: sudo systemctl restart ol-web.
  
• If you are not in the vagrant dev virtual machine you can simply run vagrant reload for the same.

Help!

If running in Vagrant, but services don't seem to have been properly started -- e.g. the site works but you can't login with the default credentials -- try running vagrant up --provision.

Developer's Guide

For instructions on administrating your Open Library instance and build instructions for developers, refer the Developer's Quickstart Guide.

You can also find more information regarding Developer Documentation for Open Library in the Open Library Wiki

Code Organization

• openlibrary/core - core openlibrary functionality, imported and used by www
• openlibrary/plugins - other models, controllers, and view helpers
• openlibrary/views - views for rendering web pages
• openlibrary/templates - all the templates used in the website
• openlibrary/macros - macros are like templates, but can be called from wikitext

Architecture

The Backend

OpenLibrary is developed on top of the Infogami wiki system, which is itself built on top of the web.py Python web framework and the Infobase database framework.

• Overview of Backend Web Technologies

Once you've read the overview of OpenLibrary Backend technologies, it's highly encouraged you read the developer primer which explains how to use Infogami (and its database, Infobase):

• Infogami Developer Tutorial

Running tests

Open Library tests can be run using pytest. Kindly look up on our Testing Document for more details

Inside vagrant, go to the application base directory:

cd /openlibrary
make test

Integration Tests

Integration tests use the Splinter webdriver with Google Chrome. For instructions on installation requirements and running integration tests, see Integration Tests README