jcrosswh/book-project

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

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.

Setup

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

Clone the repository
Import the project as a maven project into your favourite IDE (or run maven on the terminal)
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 only MySQL running in docker

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

2. Start using docker-compose in production mode

At the root of the project, build the project in production mode using one of the following commands. In production mode all UI components are packaged in a jar file.
- ./mvnw clean package -Pproduction (Unix), or
- mvnw.cmd clean package -Pproduction (Windows)
Start the MySQL Database and book project app using docker-compose up --build
- May need to add sudo to this command on Unix

3. 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).

Start the MySQL database using docker-compose up -d mysql phpmyadmin
- May need to add sudo to this command on Unix
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:

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

Contributing

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

Help

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

Both the Slack #help channel and GitHub Q&A discussions are community-driven efforts. 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

jcrosswh / book-project