🚀 Noona-Portal

Welcome to Noona-Portal, a multi-purpose, self-hosted Discord bot designed to integrate with Kavita, giving you seamless access to your comics and manga libraries directly from Discord.

🔹 Open-source | 🔹 Containerized with Docker | 🔹 Powered by Node.js

---

📚 Overview

Noona-Portal simplifies library management, enhances user interactions, and provides automated notifications for your Kavita instance. With Discord's rich APIs and Kavita's powerful library system, this bot allows you to:

✅ Search & Retrieve manga, comics, or series from your Kavita libraries.
✅ Receive Real-time Updates about new additions to your collection.
✅ Administer User Roles & Permissions with ease.
✅ Trigger Server Maintenance Tasks directly from Discord.
✅ Engage Users via interactive buttons & commands.

🔗 GitHub Repository: The-Noona-Project/Noona-Portal
📝 License: GNU GPL v2

---

🎯 Project Goals

1. 🔗 Seamless Integration – Bridge Discord & Kavita for library management.
2. 💬 Enhanced User Interaction – Intuitive commands & workflows.
3. 🤖 Automation – Notifications & maintenance features.
4. 🛠 Customizability – Role-based access & permissions.
5. 🧩 Extendable – Open-source & ready for community contributions.

---

✨ Features

📖 Library Interaction

🔍 /search – Look up series by title with Discord embeds.
📢 Notification System – Auto-post updates about new library additions.

⚙️ Admin & Maintenance

🛠 /admin commands – Manage users, roles, and perform server maintenance.
📊 Server Stats – Monitor Kavita server health & status.

🎛️ User Engagement

📌 Interactive Scanning – Use /scan to pick & scan libraries via Discord buttons.
🔑 Role-based Permissions – Secure bot usage with customizable role restrictions.
📜 Slash Commands – Organized and efficient Discord bot command system.

---

📦 Installation & Setup

This bot is fully containerized with Docker for easy deployment.

🔧 Prerequisites

Before installing, make sure you have:

• Docker installed.
• A running Kavita instance.
• A Discord Bot Token from the Discord Developer Portal.

🏗️ Docker Installation

1️⃣ Pull the Docker image:

docker pull captainpax/noona-portal

2️⃣ Run the container:

docker network create noona-network

docker run -d \
  --name='noona-portal' \
  --net='noona-network' \
  -e TZ="America/Los_Angeles" \
  -e HOST_CONTAINERNAME="noona-portal" \
  -e 'DISCORD_TOKEN'='<your_discord_token>' \
  -e 'DISCORD_CLIENT_ID'='<your_discord_client_id>' \
  -e 'REQUIRED_GUILD_ID'='<your_guild_id>' \
  -e 'REQUIRED_ROLE_ADMIN'='<your_admin_role_id>' \
  -e 'REQUIRED_ROLE_MOD'='<your_mod_role_id>' \
  -e 'REQUIRED_ROLE_USER'='<your_user_role_id>' \
  -e 'NOTIFICATION_CHANNEL_ID'='<your_notification_channel_id>' \
  -e 'KAVITA_URL'='<your_kavita_url>' \
  -e 'KAVITA_API_KEY'='<your_kavita_api_key>' \
  -e 'KAVITA_LIBRARY_IDS'='<library_ids>' \
  -e 'KAVITA_LOOKBACK_HOURS'='<lookback_hours>' \
  -e 'VAULT_URL'='http://noona-vault:3120' \
  -e 'VAULT_JWT'='super-secret-key' \
  captainpax/noona-portal

3️⃣ Replace placeholders (<your_discord_token>, etc.) with actual values.

---

⚙️ Configuration

🌍 Environment Variables

Variable	Description
DISCORD_TOKEN	Required. Your Discord bot token.
DISCORD_CLIENT_ID	Required. Your Discord application ID.
REQUIRED_GUILD_ID	Required. ID of your Discord server.
REQUIRED_ROLE_ADMIN	Required. Role ID for Admin commands.
REQUIRED_ROLE_MOD	Optional. Role ID for Moderator access.
REQUIRED_ROLE_USER	Optional. Role ID for General users.
NOTIFICATION_CHANNEL_ID	Required. Channel ID for library updates.
KAVITA_URL	Required. URL to your Kavita instance.
KAVITA_API_KEY	Required. API key for Kavita authentication.
KAVITA_LIBRARY_IDS	Required. Library IDs to give to new users.
KAVITA_LOOKBACK_HOURS	Required. Hours to look back for new items. Default: 168 (7 days).
VAULT_URL	Required. REST endpoint for Noona-Vault service.
VAULT_JWT	Required. JWT for authenticating with Vault.

📌 See .env.example for a full template.

---

💻 Development Setup

For local development:

npm install  # Install dependencies
node initmain.mjs  # Run bot locally

Test commands in your Discord server after setup.

---

⚡ Command Reference

🏠 General Commands

Command	Description
/search	Search for a series by title.
/scan	Display libraries and initiate a scan.
/join	Create a Kavita account and provide an invite link.
/ding	Test if the bot is responsive.

🛠 Admin Commands

Command	Description
/admin role	Assign or manage roles for a Kavita user.
/admin server-status	Display Kavita server statistics.
/admin server-maintenance	Trigger maintenance tasks for Kavita.

---

🤝 Contributing

We welcome contributions! 🚀

🛠 How to Contribute:

1️⃣ Fork the repository.
2️⃣ Create a new branch for your feature.
3️⃣ Submit a pull request for review.

🔗 Issues & Feature Requests: GitHub Issues

---

📜 License

Noona-Portal is open-source under the GNU General Public License v2.

---

🎉 Acknowledgments

💙 Thanks to:

• Kavita – Robust library management platform.
• Discord.js – Powerful Discord API library.
• The Noona Project Community – For ideas, testing, and contributions.

---

🚀 Get Started Now!

🔗 GitHub Repo
🛠 Docker Hub
💬 Discord Community (coming soon!)

Happy reading & managing with Noona-Portal! 📚✨