Karakeepbot

Karakeepbot is a simple Telegram Bot written in Go that enables users to effortlessly save bookmarks to Karakeep (previously Hoarder), a self-hostable bookmark-everything app, directly through Telegram.

Features • Requirements • Installation • Configuration • Contributing • License

Features

• 📄 Add text, URL and image bookmarks into your Karakeep instance (tested on v0.27.1).
• 🤖 Obtain AI-generated tags in hashtag format for easy searching on Telegram.
• 🔒 Mandatory chat ID allowlist to prevent abuse (thread ID allowlist is also supported).
• 🐳 Production-ready Docker image for easy deployment.

Requirements

• A Telegram bot token (you can get one by talking to @BotFather on Telegram)
• Your Telegram Chat ID (see How to Find Your Chat ID).
• A valid API key from Karakeep.

Installation

Docker

Using docker run

Use the docker run command to start Karakeepbot. Make sure to set the required environment variables:

docker run --name karakeepbot \
  -e KARAKEEPBOT_TELEGRAM_TOKEN=your-telegram-bot-token \
  -e KARAKEEPBOT_TELEGRAM_ALLOWLIST=your-telegram-chat-id \
  -e KARAKEEPBOT_KARAKEEP_TOKEN=your-karakeep-api-key \
  -e KARAKEEPBOT_KARAKEEP_URL=https://your-karakeep-instance.tld \
  ghcr.io/madh93/karakeepbot:latest

Using docker compose

Create a docker-compose.yml file with the following content:

services:
  karakeepbot:
    image: ghcr.io/madh93/karakeepbot:latest
    restart: unless-stopped
    # volumes:
    #   - ./custom.config.toml:/var/run/ko/config.default.toml # Optional: specify a custom configuration file instead of the default one
    environment:
      - KARAKEEPBOT_TELEGRAM_TOKEN=your-telegram-bot-token
      - KARAKEEPBOT_TELEGRAM_ALLOWLIST=your-telegram-chat-id
      - KARAKEEPBOT_KARAKEEP_TOKEN=your-karakeep-api-key
      - KARAKEEPBOT_KARAKEEP_URL=https://your-karakeep-instance.tld

Use the docker compose up command to start Karakeepbot:

docker compose up

From releases

Download the latest binary from the releases page:

curl -L https://github.com/Madh93/karakeepbot/releases/latest/download/karakeepbot_$(uname -s)_$(uname -m).tar.gz | tar -xz -O karakeepbot > /usr/local/bin/karakeepbot
chmod +x /usr/local/bin/karakeepbot

From source

If you have Go installed:

go install github.com/Madh93/karakeepbot@latest

Configuration

Karakeepbot comes with a default configuration file that you can modify to suit your needs.

Loading a custom configuration file

You can load a different configuration file by using the -config path/to/config/file flag when starting the application:

karakeepbot -config custom.config.toml

Overriding with environment variables

Additionally, you can override the configuration values using environment variables that begin with the prefix KARAKEEPBOT_. This allows you to customize your setup without needing to modify any configuration file:

KARAKEEPBOT_LOGGING_LEVEL=debug KARAKEEPBOT_TELEGRAM_ALLOWLIST=chat_id_1,chat_id_2 karakeepbot

Security Concerns

To protect your bot from abuse and spam from unauthorized users, Karakeepbot implements a mandatory Chat ID allowlist.

By default, the bot is configured with a placeholder value and it will not start until you explicitly configure the telegram.allowlist parameter. You have two options:

1. Recommended: Provide a list of one or more specific Chat IDs. This ensures only you and other authorized users can interact with the bot.
2. Not Recommended: Provide an empty list ([] or KARAKEEPBOT_TELEGRAM_ALLOWLIST="" environment variable). This will allow any Telegram user to interact with your bot, exposing it to potential abuse.

How to Find Your Chat ID

1. Open your Telegram client.
2. Search for the bot @userinfobot and start a chat with it.
3. The bot will immediately reply with your user information, including your Id. This is your Chat ID.

Contributing

Contributions are welcome! Please open an issue or submit a pull request for any bug fixes or enhancements.

1. Fork the repository.
2. Create a new branch (git checkout -b feature-branch).
3. Commit your changes (git commit -am 'Add new feature').
4. Push to the branch (git push origin feature-branch).
5. Open a Pull Request.

License

This project is licensed under the MIT license.