jeremiahyan / book-project

Book platform for book lovers (web app)

Book tracker web app made using Spring Boot and Vaadin 14 (only the free components will be used).

Update: we are currently redesigning the web app from scratch (with React instead of Vaadin). Take a look at the 0.2.0 branch.

See a live demo. Instead of creating an account, you can use the test credentials shown in the Access site section. This is only for demonstration purposes, so please do not rely on any saved data persisting.

Features:

• Add books that you have read to a 'to read', 'currently reading', 'read' or 'did not finish' shelf (or a custom shelf)
• A rating scale from 0-10 that that goes up in steps of 0.5
• Track your progress towards a reading goal: the number of books or pages you hope to read by the end of the year
• Statistics about your reading habits
• Export your saved data to JSON
• User registration and accounts
• Import books from Goodreads
• And much more!

Coming soon:

• Import books from LibraryThing
• Search from a catalogue of books
• 2-factor authentication
• Magic links
• And much more!

The images above may look slightly different to the app. If major changes are made, new images will be uploaded to reflect this.

Getting Started

Prerequisites:

• JDK 11 (the app currently won't work on later versions due to an issue with one of the libraries -- Karibu testing -- not being compatible with later versions)
• If you don't have Node.js installed globally, it is not needed as Vaadin will install it automatically
  • If you do have Node.js installed, please ensure it is at least version 10.0
• MySQL 8.0.* or (better) Docker
  • Windows or macOS: install Docker Desktop
  • Linux: install Docker Engine and Docker Compose

Running the app

1. Clone the repository
2. Import the project as a maven project into your favourite IDE (or run maven on the terminal)
3. Start Docker engine (Linux) or Docker desktop (Windows or macOS)

Then, if you want to use Docker, follow one of the approaches below:

1. Start locally with MySQL and phpMyAdmin running in Docker

4. Build the project at the root using ./mvnw clean install (Unix) or mvnw.cmd clean install (Windows)
5. Start the MySQL database using docker-compose up -d mysql phpmyadmin
   • May need to add sudo to this command
6. Start the application using java -jar target/book-project-0.0.1-SNAPSHOT.jar

2. Start locally with Vaadin live reload (the tests do not run)

We recommended this approach if you need to work on the frontend with Vaadin. This approach allows you to use Vaadin Live reload which prevents you from needing to re-run the server every time or manually refresh your browser (i.e. it's a lot quicker).

4. Start the MySQL database using docker-compose up -d mysql phpmyadmin
   • May need to add sudo to this command
5. Run the project from your IDE or with Maven:
   • ./mvnw spring-boot:run on Unix
   • mvnw.cmd spring-boot:run on Windows

If you're running the app from your IDE, after making a Vaadin-related change, build the app from your IDE after making any changes.

Access site

After following the instructions for running the app above, go to localhost:8080. Then, log in with the details below:

• Username: user
• Password: password

Fixing Lombok errors

You may find lots of errors for things like the log statements, or the entities not having constructors. You can find instructions on how to fix this for IntelliJ and Eclipse in our troubleshooting wiki page. Other common errors and solutions are also in the troubleshooting page.

Access database

To access the MySQL database when docker-compose is running:

1. Go to http://localhost:8081/
2. Log in with the settings below.
   • User Name: root
   • Password: rootpassword
3. Click on connect

Contributing

If you wish to contribute (thanks!), please first see the contributing document.

You can join our Slack workspace to chat with the maintainers and contributors, as well as to help shape the future of the project.

If you're interested and are able to contribute from a UI/UX perspective, we'd love to hear from you! Feel free to get in touch with us over our Slack workspace.

Help

If you need help with anything, feel free to ask by starting a new discussion on our GitHub Q&A.

The GitHub Q&A discussions is a community-driven effort. While the maintainers try their best to help everyone, it is not always possible. If you're able to help someone else, feel free to do so (much appreciated!).

Further information

For more information, such as a roadmap and the underlying principles of the project, see the Book Project wiki.

To see the open source software we use, refer to our Acknowledgements file