https://github.com/smzoha/bookshare
A webapp that helps users to track books, their reading progress, while keeping up with the updates of their connections
https://github.com/smzoha/bookshare
bootstrap java javascript jquery spring spring-boot spring-security thymeleaf
Last synced: 3 months ago
JSON representation
A webapp that helps users to track books, their reading progress, while keeping up with the updates of their connections
- Host: GitHub
- URL: https://github.com/smzoha/bookshare
- Owner: smzoha
- License: gpl-2.0
- Created: 2025-09-06T12:37:17.000Z (10 months ago)
- Default Branch: main
- Last Pushed: 2026-04-06T19:32:48.000Z (3 months ago)
- Last Synced: 2026-04-07T07:45:41.420Z (3 months ago)
- Topics: bootstrap, java, javascript, jquery, spring, spring-boot, spring-security, thymeleaf
- Language: JavaScript
- Homepage:
- Size: 9.67 MB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# 📖 BookShare
BookShare is a **modern web application** to track your books, reading progress, and connect with other readers. Keep your library organized and stay updated with friends' reading activity!
---
## 📌 Table of Contents
- [Features](#features)
- [Technology Stack](#technology-stack)
- [Getting Started](#getting-started)
- [Prerequisites](#prerequisites)
- [Installation](#installation)
- [Running the Application](#running)
- [Running with Docker](#docker)
- [Set up Gmail API & Google OAuth2 Login](#google)
- [Usage](#usage)
- [Contributing](#contributing)
- [License](#license)
- [Contact](#contact)
---
✨ Features
- User registration, login, and authentication
- Add books and track reading progress
- Connect with other users and view their activity
- Responsive interface built with **Thymeleaf** and **Bootstrap**
- Secure backend with **Spring Boot** and **Spring Security**
- Easily extensible for reviews, ratings, and more
---
🛠 Technology Stack
| Layer | Technology |
|------------|--------------------------------------------|
| Backend | Java, Spring Boot, Spring Security |
| Frontend | Thymeleaf, Bootstrap, HTML/CSS, JavaScript |
| Database | PostgreSQL, Flyway |
| Build Tool | Gradle |
| Versioning | Git & GitHub |
---
🚀 Getting Started
Prerequisites
- Java 25+
- Gradle 8+
- PostgreSQL
- Git
- Docker & Docker Compose _(optional, for containerized setup)_
Installation
```bash
# Clone the repository
git clone https://github.com/smzoha/bookshare.git
cd bookshare
# Configure database in src/main/resources/application-dev.properties:
spring.datasource.url=jdbc:postgresql://localhost:5432/bookshare
spring.datasource.username=your_db_user
spring.datasource.password=your_db_password
```
Running the Application
```bash
# Run with Gradle
./gradlew bootRun
```
### Access the app at:
```
http://localhost:6001
```
---
🐳 Running with Docker
Docker will spin up both the application and a PostgreSQL database together, with no local setup required.
**1. Set up your environment file:**
```bash
cp .env.example .env
```
Edit `.env` with your preferred credentials:
```env
DATABASE_NAME=bookshare
DATABASE_USER=your_db_user
DATABASE_PASSWORD=your_db_password
```
**2. Start all services:**
```bash
./deploy.sh start
```
**3. Stop all services:**
```bash
./deploy.sh stop
```
> App logs are persisted to the `./logs/` directory on your host machine.
---
✉️ 🔐 Set up Gmail API & Google OAuth2 Login
Follow these steps to set up Google OAuth2 credentials for two features:
- **Gmail API** — sending emails via Gmail
- **Google OAuth2 Login** — Login with Google authentication
**Create OAuth2 Credentials in Google Cloud:**
- Go to [Google Cloud Console](https://console.cloud.google.com/) and select your project (the name defined for this project is "bookshare").
- **Enable Required APIs**:
- APIs & Services → Library → **Gmail API** → Enable
- **Configure OAuth Consent Screen**:
- App Type: External
- Fill in App Name and Support Email (bookshare and your choice of Gmail address respectively)
- Add the following **OAuth2 scopes**:
- `https://www.googleapis.com/auth/gmail.send` — Send emails via Gmail
- `openid` — Google Login: authenticate user identity
- `https://www.googleapis.com/auth/userinfo.email` — Google Login: access user's email address
- `https://www.googleapis.com/auth/userinfo.profile` — Google Login: access user's basic profile info
- **Create OAuth Client ID**:
- Application Type: Web application
- Add **Authorized redirect URIs**:
- `http://localhost:6001` *(for refresh token generation)*
- `http://localhost:6001/login/oauth2/code/google` *(for Google Login callback — adjust host/port as needed)*
- `http://localhost:6001/oauth2/authorization/google` *(for Google Login callback — adjust host/port as needed)*
- Copy the `client_id` and `client_secret`
**Generate Refresh Token (for Gmail sending):**
- Open the following URL in your browser (replace `YOUR_CLIENT_ID`):
```
https://accounts.google.com/o/oauth2/v2/auth?
client_id=YOUR_CLIENT_ID
&redirect_uri=http://localhost:6001
&response_type=code
&scope=https://www.googleapis.com/auth/gmail.send
&access_type=offline
&prompt=consent
```
- Login with your Gmail account and allow access.
- Copy the `code` from the redirected URL: `http://localhost:6001/?code=AUTH_CODE`
- Exchange `AUTH_CODE` for tokens via POST request:
```http
POST https://oauth2.googleapis.com/token
Content-Type: application/x-www-form-urlencoded
code=AUTH_CODE&
client_id=YOUR_CLIENT_ID&
client_secret=YOUR_CLIENT_SECRET&
redirect_uri=http://localhost:6001&
grant_type=authorization_code
```
- The response will include the refresh token:
```json
{
"access_token": "...",
"expires_in": 3599,
"refresh_token": "YOUR_REFRESH_TOKEN",
"scope": "https://www.googleapis.com/auth/gmail.send",
"token_type": "Bearer"
}
```
> **Note:** The Google Login flow is handled automatically by Spring Security OAuth2 — no manual token exchange is needed for login.
**Add Secret Tokens to env and properties files:**
- Add the following key/value pairs to the `.env` file (for Docker deployment)
- Refer to the `.env.example` for example
```
GOOGLE_CLIENT_ID=your_client_id
GOOGLE_CLIENT_SECRET=your_client_secret
GOOGLE_REFRESH_TOKEN=your_refresh_token
```
- For Spring Boot deployment, add a `secrets-dev.properties` file and include the following properties
- Refer to `secret-dev.properties.example` for example
```
app.gmail.client.id=${GOOGLE_CLIENT_ID:client}
app.gmail.client.secret=${GOOGLE_CLIENT_SECRET:secret}
app.gmail.refresh.token=${GOOGLE_REFRESH_TOKEN:token}
spring.security.oauth2.client.registration.google.client-id=${app.gmail.client.id}
spring.security.oauth2.client.registration.google.client-secret=${app.gmail.client.secret}
```
---
💻 Usage
1. Register a new account or log in with an existing account.
2. Add books to your library.
3. Track reading progress (pages read / percentage).
4. Connect with other users to view their activity.
5. Manage your book collection across shelves.
🤝 Contributing
We welcome contributions! Follow these steps:
1. Fork the repository
2. Create a branch: `git checkout -b feat/my-feature` for features, `git checkout -b bugfix/my-fix` for bugfixes
3. Commit your changes: `git commit -m "Add feature"`
4. Push to the branch: `git push origin feature/my-feature`
5. Open a Pull Request
### Guidelines:
- Follow existing code style
- Include tests for new features when applicable
- Update documentation as needed
---
📄 License
This project is licensed under the **GNU General Public License v2 (GPL-2.0)**.
See the full license text in the [LICENSE](LICENSE) file for details.
You are free to:
- Use, copy, and modify the software
- Distribute copies and derivatives under the same license
> This ensures that BookShare and any derivative works remain free software under GPL v2.
---
📫 Contact
**BookShare** — Powered by ZedApps
GitHub Profile: [smzoha](https://github.com/smzoha)
Email: shamah.zoha@gmail.com