Project-Books / book-project

Book tracker web app for book lovers

Book tracker web app made with Spring Boot and React (Typescript).

The image above is from our mockup designs, so this may look slightly different to the app. If major changes are made, we will upload a new image.

Getting started locally

Prerequisites:

• Docker with Buildkit enabled
  • Windows or macOS: install Docker Desktop
  • Linux: install Docker Engine and Docker Compose. Follow the post installation guide to add your user to the docker group

1. Clone the repository (if you're contributing, you'll need to first fork the repository and then clone your fork)
2. Start Docker engine (Linux) or Docker desktop (macOS or Windows).
   • If you're using an Apple silicon chip (e.g. M1), you'll need to uncomment this line.
3. In the root of the project, run docker-compose build to build the database, backend and frontend services
4. Run docker-compose --env-file .env up to start the containers
5. Once the development server has started (you'll get notified in the output of docker-compose up), go to localhost:3000 in your web browser to access the frontend
6. When finished, run docker-compose down to stop and remove the containers

You may want to also want to run our Books API to avoid seeing an error on the search page on the frontend.

Note for backend contributors: Please ensure you run the unit tests manually (we supply the -DskipTests flag with Docker by default for convenience).

Log in with our test user

When running the frontend and backend, or only the backend, you can use the following test user:

• Email address: [e-mail]
• Password: password

Note: If you're running the backend, you will need a JWT token for subsequent requests after logging in or creating an account; see our connecting to the backend wiki page.

Access database (optional)

Using your favourite SQL client, use the following settings:

• Host: localhost
• Port: 5433
• User: dbuser
• Password: dbpassword
• Database name: book_project_db

For example, in DataGrip or IntelliJ Ultimate:

Contributing

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

We work hard to make our project approachable to everyone -- from those new to open-source looking to make their first contribution to seasoned developers.

Backend: 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 fixing this for IntelliJ and Eclipse in our troubleshooting page. Other common errors and solutions are also on the troubleshooting page.

Docker running slowly: Windows users

If you are notice that the Vmmem process is consuming too much of your CPU and RAM, you can adjust the maximum limit that Docker can use.

If using the WSL 2 backend (see the image above: go to Docker Desktop > Settings > Resources), create a .wslconfig file at the root of your user folder: C:\Users\<your-username>:

[wsl2]
memory=4GB   # Limits VM memory in WSL 2 up to 4GB
processors=2# Makes the WSL 2 VM use two virtual processors

Update the values as appropriate for your system. See the documentation for more information

Help

If you need help with anything, we'll be happy to help you over a GitHub Q&A discussion. Alternatively, feel free to chat with us on the #book-project channel on our Slack workspace.

When asking for help on Slack, we always recommend asking on our #book-project channel, rather than contacting a maintainer directly. This is so that others can offer help and the answer may help someone else.

Further information

For more information, such as a roadmap and the project's underlying principles, see our documentation site.

To see a list of the open-source software we use, refer to our Acknowledgements file

Donations

If you are able and willing to support us financially, it will go a long way to help us achieve our goals and become more sustainable. We hate to ask for money, but running cloud server costs are not free.

We currently only accept donations through Open Collective.