DEPLOY.md

# KaraBot — Deployment Guide Everything below is designed to be copy-pasted in order. Replace placeholders shown in CAPS where indicated. --- ## BEFORE YOU START — Things to collect 1. **Telegram bot token** — Open Telegram, DM @BotFather, send `/newbot`. - Give it a display name (e.g. `KaraBot`) - Give it a username — must end in `bot` (e.g. `mykarabot_bot`) - BotFather sends back a token like `7123456789:AAFxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx` - Copy it. You'll paste it into `.env.bot` in Step 4. 2. **Your Telegram numeric user ID** — DM @userinfobot. It replies with your ID (a number like `412345678`). 3. **Your Karakeep API key** — Open your Karakeep web UI → Settings → API Keys → Create new key. Copy it. 4. **Your server username** — used in all SSH/SCP commands below. Replace `YOUR_USERNAME` with it. 5. **Your deploy path** — where you want the bot to live on the server. Replace `YOUR_DEPLOY_PATH` with it (e.g. `/opt/karabot` or `/home/youruser/karabot`). --- ## Step 1 — Create the bot directory on the server ```bash ssh YOUR_USERNAME@YOUR_SERVER_IP "mkdir -p YOUR_DEPLOY_PATH/data" ``` --- ## Step 2 — Copy the bot files to the server Run this from the folder that contains the `karabot` directory: ```bash scp -r karabot YOUR_USERNAME@YOUR_SERVER_IP:YOUR_DEPLOY_PATH ``` --- ## Step 3 — Verify the Karakeep service name You need to know what Docker calls the Karakeep web service so the bot can reach it internally. ```bash ssh YOUR_USERNAME@YOUR_SERVER_IP "docker ps --format 'table {{.Names}}\t{{.Ports}}'" ``` Look for the container serving port 3001. Its name is what you put in `KARAKEEP_INTERNAL_URL` below. It is usually `karakeep-web-1` or just `web` depending on your setup. The internal URL format is: `http://SERVICE_NAME:3001` Example: `http://karakeep-web-1:3001` --- ## Step 4 — Create the secrets file on the server SSH in and create the `.env.bot` file. You'll fill in the values yourself: ```bash ssh YOUR_USERNAME@YOUR_SERVER_IP ``` Then once you're in: ```bash nano YOUR_DEPLOY_PATH/.env.bot ``` Paste this, filling in all values: ``` TELEGRAM_BOT_TOKEN=PASTE_YOUR_BOT_TOKEN_HERE TELEGRAM_ALLOWED_USER_IDS=PASTE_YOUR_NUMERIC_ID_HERE KARAKEEP_INTERNAL_URL=http://KARAKEEP_SERVICE_NAME:3001 KARAKEEP_EXTERNAL_URL=http://YOUR_SERVER_IP:3001 BOT_DATABASE_PATH=/data/karabot.db METADATA_ENRICHMENT=true ``` Save and exit nano: `Ctrl+O`, Enter, `Ctrl+X`. Then restrict the file so only your user can read it: ```bash chmod 600 YOUR_DEPLOY_PATH/.env.bot ``` To add a second user later, add their Telegram ID comma-separated: ``` TELEGRAM_ALLOWED_USER_IDS=YOUR_ID,SECOND_USER_ID ``` --- ## Step 5 — Add KaraBot to Karakeep's docker-compose Open your Karakeep `docker-compose.yml`: ```bash nano YOUR_KARAKEEP_PATH/docker-compose.yml ``` Scroll to the bottom of the `services:` section and add this block. Make sure the indentation matches the other services (2 spaces): ```yaml karabot: build: context: YOUR_DEPLOY_PATH dockerfile: Dockerfile image: karabot:latest container_name: karabot restart: unless-stopped env_file: - YOUR_DEPLOY_PATH/.env.bot volumes: - YOUR_DEPLOY_PATH/data:/data ``` Save and exit: `Ctrl+O`, Enter, `Ctrl+X`. --- ## Step 6 — Build the bot image ```bash ssh YOUR_USERNAME@YOUR_SERVER_IP "cd YOUR_KARAKEEP_PATH && docker compose build karabot" ``` This will take 1–3 minutes the first time (downloading Python base image, installing packages). --- ## Step 7 — Start the bot ```bash ssh YOUR_USERNAME@YOUR_SERVER_IP "cd YOUR_KARAKEEP_PATH && docker compose up -d karabot" ``` --- ## Step 8 — Check it's running ```bash ssh YOUR_USERNAME@YOUR_SERVER_IP "docker logs karabot -f" ``` You should see: ``` ... [INFO] karabot: KaraBot starting — 1 allowed user(s), enrichment=True ... [INFO] karabot: Database initialised at /data/karabot.db ... [INFO] karabot: Bot commands registered with Telegram ``` Press `Ctrl+C` to stop following the log. The bot keeps running. --- ## Step 9 — Link your Karakeep account in Telegram 1. Open Telegram, find your bot by its username 2. Send `/start` 3. Send your Karakeep API key (just paste it, nothing else) 4. The bot will verify it against Karakeep and confirm --- ## Step 10 — (Optional) Set up Karakeep cookie injection for Reddit This is separate from the bot — it makes Karakeep's OWN crawler (for archiving) work better on Reddit. On your PC, install the Cookie Editor extension: - Chrome/Edge: https://chrome.google.com/webstore/detail/cookie-editor/hlkenndednhfkekhgcdicdfddnkalmdm - Firefox: https://addons.mozilla.org/en-US/firefox/addon/cookie-editor/ 1. Log into Reddit in your browser 2. Click the Cookie Editor extension → Export → Export as JSON 3. Save the JSON file to your server: ```bash scp cookies_reddit.json YOUR_USERNAME@YOUR_SERVER_IP:YOUR_KARAKEEP_PATH/cookies.json ``` 4. Add this to your Karakeep `.env` file: ```bash ssh YOUR_USERNAME@YOUR_SERVER_IP "echo 'BROWSER_COOKIE_PATH=/karakeep_data/cookies.json' >> YOUR_KARAKEEP_PATH/.env" ``` (Adjust the path to match where your Karakeep data volume maps cookies.json inside the container.) 5. Restart Karakeep: ```bash ssh YOUR_USERNAME@YOUR_SERVER_IP "cd YOUR_KARAKEEP_PATH && docker compose restart web" ``` --- ## Day-to-day commands **View bot logs:** ```bash ssh YOUR_USERNAME@YOUR_SERVER_IP "docker logs karabot --tail 50" ``` **Restart the bot (e.g. after updating files):** ```bash ssh YOUR_USERNAME@YOUR_SERVER_IP "cd YOUR_KARAKEEP_PATH && docker compose restart karabot" ``` **Rebuild and restart after code changes:** ```bash scp -r karabot YOUR_USERNAME@YOUR_SERVER_IP:YOUR_DEPLOY_PATH ssh YOUR_USERNAME@YOUR_SERVER_IP "cd YOUR_KARAKEEP_PATH && docker compose build karabot && docker compose up -d karabot" ``` **Stop the bot only (Karakeep keeps running):** ```bash ssh YOUR_USERNAME@YOUR_SERVER_IP "docker stop karabot" ``` **Check all running containers:** ```bash ssh YOUR_USERNAME@YOUR_SERVER_IP "docker ps" ``` --- ## If something goes wrong **Bot not responding in Telegram:** ```bash ssh YOUR_USERNAME@YOUR_SERVER_IP "docker logs karabot --tail 100" ``` Look for ERROR lines. Most common causes: - Bad bot token (check .env.bot) - Can't reach Karakeep (check KARAKEEP_INTERNAL_URL matches the actual service name from Step 3) **"Failed to save" errors:** - Usually the Karakeep API key is wrong or expired - Re-generate in Karakeep → Settings → API Keys and update .env.bot - Then: `docker compose restart karabot` **Bot image failed to build:** - Usually a network issue pulling packages. Try again: ```bash ssh YOUR_USERNAME@YOUR_SERVER_IP "cd YOUR_KARAKEEP_PATH && docker compose build --no-cache karabot" ```