Getting Started

Getting Started

This gets JobRadar running on Linux, macOS or Windows (WSL) and filling Notion from your Telegram channels. Plan on 20–30 minutes, most of it creating the accounts and keys.

Docker files are in the repo, but the Docker setup hasn't been tested end to end yet. Use the uv steps below for now.

1. What you need

• Python 3.11+, git, and uv (curl -LsSf https://astral.sh/uv/install.sh | sh)
• A Telegram account that has joined the job channels you want to watch
• A Notion account
• A Gemini API key (free at aistudio.google.com), optional but needed for job details

2. Install

git clone https://github.com/ThePlator/JobRadar.git
cd JobRadar
uv sync
cp .env.example .env

3. Get your keys (fill them into .env)

.env variable	Where to get it
TG_API_ID, TG_API_HASH	my.telegram.org → API development tools → create an app (Platform: Desktop). See below
NOTION_TOKEN	notion.so/profile/integrations → New integration → Internal → copy the secret. See Notion Setup
NOTION_DATABASE_ID	The 32 characters before ?v= in your Jobs database link. See Notion Setup
GEMINI_API_KEY	aistudio.google.com → Get API key

Rules for .env: one KEY=value per line, no spaces around =, no quotes, and save the file.

Telegram app form (my.telegram.org): App title JobRadar, short name jobradar (letters/numbers only), URL your fork or the repo, platform Desktop. If the page shows a bare "ERROR", turn off VPN or ad-blockers and try another short name.

4. First-time setup

uv run jobradar init

This creates config/config.yaml and config/profile.yaml from the examples. It then logs in to Telegram: enter your phone number and the code Telegram sends to your Telegram app, plus your 2-step password if you use one. Finally it checks that the Notion database matches the template.

Your login is saved in data/tg.session with owner-only permissions. Treat it like a password; it gives full access to your Telegram account.

5. Choose your channels

uv run jobradar chats

Copy the ids of the job channels (numbers like -1001234567890) into config/config.yaml:

sources:
  telegram:
    chats: [-1001234567890, -1009876543210]

6. Run it

uv run jobradar run

On first start JobRadar reads the last 3 days of each channel, then listens live. Rows appear in Notion within seconds, and the details fill in shortly after. Press Ctrl+C to stop. Next time it catches up from where it stopped.

To keep it running after you close the terminal:

tmux new -s jobradar 'uv run jobradar run 2>&1 | tee -a data/run.log'

Detach with Ctrl+B then D; come back with tmux attach -t jobradar.

7. Check it's healthy

uv run jobradar stats --days 3

You should see posts per channel, jobs created, reposts merged, hidden ads, and Queue: 0 waiting, 0 failed.

Jobs that were already in Notion before you added a Gemini key can be read afterwards with:

uv run jobradar extract --missing

Something wrong? See Troubleshooting.