{"id":30268024,"url":"https://github.com/heapy/kotbusta","last_synced_at":"2025-08-16T00:13:04.736Z","repository":{"id":307079012,"uuid":"1028247893","full_name":"Heapy/kotbusta","owner":"Heapy","description":null,"archived":false,"fork":false,"pushed_at":"2025-08-11T07:17:52.000Z","size":1856,"stargazers_count":0,"open_issues_count":3,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-08-12T13:06:27.742Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Kotlin","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"agpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Heapy.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-07-29T08:45:14.000Z","updated_at":"2025-08-05T16:58:36.000Z","dependencies_parsed_at":"2025-07-29T10:50:45.758Z","dependency_job_id":"69d8b8f6-05ed-4058-910b-c30e26681739","html_url":"https://github.com/Heapy/kotbusta","commit_stats":null,"previous_names":["heapy/kotbusta"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/Heapy/kotbusta","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Heapy%2Fkotbusta","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Heapy%2Fkotbusta/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Heapy%2Fkotbusta/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Heapy%2Fkotbusta/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Heapy","download_url":"https://codeload.github.com/Heapy/kotbusta/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Heapy%2Fkotbusta/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":270649295,"owners_count":24622060,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-15T02:00:12.559Z","response_time":110,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-08-16T00:13:03.003Z","updated_at":"2025-08-16T00:13:04.721Z","avatar_url":"https://github.com/Heapy.png","language":"Kotlin","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Kotbusta - Digital Library for Flibusta Books\n\nA modern web application for browsing, searching, and downloading books from Flibusta torrent archives. Built with Kotlin/Ktor backend and Preact frontend.\n\n## Features\n\n- 📚 **Browse Books**: View books with covers, metadata, and descriptions\n- 🔍 **Advanced Search**: Search by title, author, genre, and language\n- ⭐ **Favorites**: Star books and create personal collections\n- 📝 **Notes \u0026 Comments**: Add private notes and public comments\n- 📥 **Format Conversion**: Download books in FB2, EPUB, or MOBI formats\n- 🔐 **Google OAuth**: Secure authentication with Google accounts\n- 📱 **Responsive Design**: Works on desktop and mobile devices\n\n## Technology Stack\n\n**Backend:**\n- Kotlin + Ktor\n- Postgres database with jOOQ\n- Google OAuth authentication\n- RESTful API design\n\n**Frontend:**\n- Preact (no bundler)\n- Modern CSS with CSS Grid/Flexbox\n- Native ES modules\n- Progressive Web App features\n\n**Infrastructure:**\n- Docker \u0026 Docker Compose\n- Pandoc-based conversion service\n- Read-Only Volume mounts for book data\n\n## Quick Start\n\n### Prerequisites\n\n- Docker and Docker Compose\n- Flibusta torrent data (FB2 files and INPX metadata)\n- Google OAuth credentials\n\n### Deployment\n\n1. **Clone the repository**\n   ```bash\n   git clone https://github.com/Heapy/kotbusta.git\n   cd kotbusta\n   ```\n\n2. **Set up environment variables**\n   ```bash\n   cp .env.example .env\n   ```\n\n   Edit `.env` and configure the following required variables:\n   - `KOTBUSTA_GOOGLE_CLIENT_ID` - Your Google OAuth client ID\n   - `KOTBUSTA_GOOGLE_CLIENT_SECRET` - Your Google OAuth client secret\n   - `KOTBUSTA_GOOGLE_REDIRECT_URI` - OAuth redirect URI (e.g., `https://yourdomain.com/callback`)\n   - `KOTBUSTA_SESSION_SIGN_KEY` - Session signing key (will be auto-generated if not provided)\n   - `KOTBUSTA_SESSION_ENCRYPT_KEY` - Session encryption key (will be auto-generated if not provided)\n   - `KOTBUSTA_ADMIN_EMAIL` - Your admin email address\n   - `KOTBUSTA_POSTGRES_HOST` - PostgreSQL host\n   - `KOTBUSTA_POSTGRES_PORT` - PostgreSQL port\n   - `KOTBUSTA_POSTGRES_USER` - PostgreSQL username\n   - `KOTBUSTA_POSTGRES_PASSWORD` - PostgreSQL password\n   - `KOTBUSTA_POSTGRES_DATABASE` - PostgreSQL database name\n   - `KOTBUSTA_DB_DATA_PATH_LOCAL` - Local path for PostgreSQL data storage\n   - `KOTBUSTA_BOOKS_DATA_PATH_LOCAL` - Local path to your Flibusta book archives\n\n3. **Prepare your Flibusta data**\n   ```bash\n   # Create directory for book data if it doesn't exist\n   mkdir -p /path/to/flibusta/books\n\n   # Your directory should contain:\n   # - fb2-*.zip archives with books\n   # - flibusta_fb2_local.inpx metadata file\n   ```\n\n4. **Run the application**\n   ```bash\n   docker compose -f deploy/prod/docker-compose.yml up -d\n   ```\n\n5. **Monitor the startup**\n   ```bash\n   # Check logs to ensure services started correctly\n   docker compose -f deploy/prod/docker-compose.yml logs -f\n\n   # Verify containers are running\n   docker compose -f deploy/prod/docker-compose.yml ps\n   ```\n\n6. **Initial setup**\n   - Navigate to your configured URL (e.g., `https://yourdomain.com`)\n   - Login with Google using your admin email\n   - Go to the Admin panel\n   - Run the import process to index your book collection\n   - The import may take some time depending on your collection size\n\n7. **Verify installation**\n   - Check that books appear in the catalog\n   - Test search functionality\n   - Try downloading a book in different formats\n\n### Development Setup\n\n1. **Clone the repository**\n   ```bash\n   git clone git@github.com:Heapy/kotbusta.git\n   cd kotbusta\n   ```\n\n2. **Set up environment**\n   ```bash\n   cp .env.example .env\n   # Edit .env\n   ```\n\n3. **Configure Google OAuth**\n   - Go to [Google Console](https://console.developers.google.com/)\n   - Create a new project or select existing\n   - Create OAuth 2.0 credentials\n   - Add authorized redirect URI: `http://localhost:8080/callback`\n   - Copy Client ID and Secret to `.env`\n   - Add your email address as ad\n\n4. **Prepare book data**\n   ```bash\n   # Create directory for your Flibusta data\n   mkdir books-data\n   # Copy your FB2 archives and INPX files here\n   # Structure should match: books-data/fb2-*.zip, books-data/flibusta_fb2_local.inpx\n   ```\n\n5. **Start postgres container**\n   ```bash\n   docker-compose up -d\n   ```\n6. **Start the application in IDEA***\n   - Run Kotbusta run-configuration\n\n7. **Access the application**\n   - Open http://localhost:8080\n   - Click \"Login with Google\" to authenticate\n   - Go to \"Admin\" and run import\n   - Start browsing your digital library!\n\n## API Endpoints\n\n### Public Endpoints\n- `GET /api/books` - List books with pagination\n- `GET /api/books/search` - Search books\n- `GET /api/books/{id}` - Get book details\n- `GET /api/books/{id}/cover` - Get book cover image\n- `GET /api/books/{id}/comments` - Get book comments\n- `GET /api/activity` - Get recent activity\n\n### Authenticated Endpoints\n- `POST/DELETE /api/books/{id}/star` - Star/unstar books\n- `GET /api/books/starred` - Get starred books\n- `POST /api/books/{id}/comments` - Add comment\n- `POST /api/books/{id}/notes` - Add/update note\n- `GET /api/books/{id}/download/{format}` - Download book\n\n## Development\n\n### Running Locally\n\n1. **Backend development**\n   ```bash\n   Start `Kotbusta` run-configuration in IDEA\n   # Navigate to http://localhost:8080`\n   ```\n\n2. **Frontend development**\n   - Edit files in `src/main/resources/static/`\n   - No build process needed, Kotbusta uses native ES modules\n   - Reload browser to see changes\n\n### Database Schema\n\nThe application uses SQLite with the following main tables:\n- `books` - Book metadata and file paths\n- `authors` - Author information\n- `series` - Book series\n- `users` - User accounts (from Google OAuth)\n- `user_stars` - User's starred books\n- `user_comments` - Public comments\n- `user_notes` - Private notes\n- `downloads` - Download history\n\n### File Structure\n\n```\nkotbusta/\n├── src/main/kotlin/io/heapy/kotbusta/\n│   ├── Application.kt         # Main application\n│   ├── ApplicationFactory.kt  # All services, daos and configurations are created here\n│   ├── ktor/                  # Ktor routes and modules\n│   ├── database/              # Database setup\n│   ├── jooq/                  # jOOQ code generation\n│   ├── model/                 # Data models\n│   ├── parser/                # FB2/INPX parsers\n│   └── service/               # Business logic\n├── src/main/resources/\n│   ├── static/                # Frontend files\n│   └── application.conf       # Ktor Configuration\n└── .env                       # Application Configuration\n```\n\n## Documentation\n\n- [INP File Format](docs/INP.md) - Detailed documentation about the INP/INPX file format used by Flibusta for metadata cataloging\n\n## Configuration\n\n### Environment Variables\n\nEdit the `.env` file to configure all aspects of the application.\n\n### Ktor Configuration\n\nEdit `src/main/resources/application.conf` to add additional ktor modules and adjust ktor configuration.\n\n### Logs\n\n```bash\n# Follow logs in real-time\ndocker-compose logs -f\n```\n\n## Contributing\n\n1. Fork the repository\n2. Create a feature branch\n3. Make your changes\n4. Add tests if applicable\n5. Submit a pull request\n\n## License\n\nThis project is licensed under the AGPL-3.0 - see the [LICENSE](LICENSE) file for details.\n\n## Acknowledgments\n\n- Flibusta library for book archives\n- Pandoc for format conversion\n- Preact team for the lightweight framework\n- Ktor team for the excellent Kotlin framework\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fheapy%2Fkotbusta","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fheapy%2Fkotbusta","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fheapy%2Fkotbusta/lists"}