# Discord and Telegram bot

Posts every run of the [live proxy list](https://proxy-scraper.de/) into a Discord server and answers slash commands. It sets up its own channels, so after inviting it there is nothing to click.

| Channel | What's in it |
|---|---|
| `#about` | what the server is, pinned |
| `#live-feed` | a summary every 6 hours with the 10 fastest proxies and `all.txt` attached |
| `#http` `#socks4` `#socks5` | the current list per protocol, replaced after every run |
| `#commands` | the only channel where members can write |

| Command | |
|---|---|
| `/proxies` | filter by type, country, HTTPS, elite, datacenter; up to 25 shown, the rest as a file |
| `/proxy` | one fast proxy to try, with a ready `curl` command |
| `/stats` | numbers of the last run |
| `/about` | what the bot does |

Answers to commands are only visible to whoever asked, so `#commands` doesn't fill up.

## Setup

1. **Create the application** at <https://discord.com/developers/applications> → *New Application* → *Bot* → *Reset Token*. No privileged intents are needed.
2. **Invite it** with this link (replace `APPLICATION_ID` with the ID from *General Information*):

   ```
   https://discord.com/oauth2/authorize?client_id=APPLICATION_ID&scope=bot+applications.commands&permissions=2251800082246704
   ```

   The permissions are: view channels, send messages, embed links, attach files, read message history, manage messages (to replace its old lists), pin messages (for `#about`), manage channels and roles (to create its channels read-only) and manage server (to set the server icon once, if there is none).

   Invited the bot before pinning became a permission of its own? It still works; only `#about` stays unpinned
   until you give its role *Pin Messages* in the server settings or invite it again with the link above.

3. **Add the secrets** to the repository (*Settings → Secrets and variables → Actions*):

   | Secret | |
   |---|---|
   | `DISCORD_TOKEN` | the bot token |
   | `DEPLOY_HOST` | IP or host name of the server |
   | `DEPLOY_SSH_KEY` | private key that may log in as `root`, or as the user named below |
   | `DEPLOY_KNOWN_HOSTS` | output of `ssh-keyscan -t ed25519 <host>`, so the workflow never talks to a server it doesn't know |

   If the server does not allow `root` to log in, add the secret `DEPLOY_USER`: a user that may run `sudo` without
   a password. The workflow then logs in as that user and runs the same steps through `sudo`.

4. **Deploy**: every push to `main` that changes `bot/` runs [`.github/workflows/bot.yml`](../.github/workflows/bot.yml): tests, then the code goes to a new directory `/opt/proxybot/releases/<time>-<commit>`, the token to `/etc/proxybot.env` (mode 600) and [`deploy/install.sh`](deploy/install.sh) sets up a system user, the release's own venv and a hardened systemd service. *Run workflow* on the Actions page redeploys by hand.

The venv is installed with `pip install --require-hashes -r requirements.lock`: the exact versions the bot's tests ran with ([`.github/requirements/bot.txt`](../.github/requirements/bot.txt) is the same lock plus pytest). `requirements.txt` only says which versions are acceptable; after changing it run `sh .github/requirements/compile.sh` (needs [uv](https://docs.astral.sh/uv/)) to update both locks.

### Releases and rolling back

```
/opt/proxybot/releases/<id>/   code + venv of one deploy (the newest three are kept)
/opt/proxybot/current          -> the release that runs (the systemd unit starts current/venv/bin/python)
/opt/proxybot/previous         -> the one before
```

`install.sh` switches `current` only after the new venv imports the bot. After the restart it waits for the bot to be *ready*, not just running: once every configured bot has logged in (Discord `on_ready`, Telegram `getMe`), the bot writes its PID to `/run/proxybot/ready` (`PROXYBOT_READY_FILE`). The release is kept only when that file holds the PID systemd started within 90 seconds and the same process still runs 15 seconds later. Otherwise `install.sh` points `current` back at the previous release, restarts that and fails the workflow – the bot log lines are in the workflow log; older releases are only pruned after a release that came up.

A token Discord or Telegram refuses (wrong or revoked) is not retried: the bot logs it and exits with code 2, so the service shows as failed (systemd tries again every 10 seconds) instead of looking healthy. Other errors – Discord or Telegram down at boot – still restart only the bot affected, a minute later.

To go back by hand, e.g. after a release that starts but misbehaves:

```bash
sudo sh /opt/proxybot/current/deploy/install.sh --rollback   # current <-> previous, then restart
```

The first deploy with this layout leaves an older `/opt/proxybot/app` and `/opt/proxybot/venv` untouched (it goes back to them if the new release doesn't start); delete them once the bot runs from `/opt/proxybot/current`.

On the server:

```bash
systemctl status proxybot
journalctl -u proxybot -f
readlink /opt/proxybot/current /opt/proxybot/previous
```

## Running it locally

```bash
cd bot
python3 -m venv .venv && .venv/bin/pip install --require-hashes -r requirements.lock
DISCORD_TOKEN=... .venv/bin/python -m proxybot
```

| Variable | Default | |
|---|---|---|
| `DISCORD_TOKEN` | – | required |
| `PROXYBOT_FEED_URL` | the GitHub Pages site | where `stats.json`, `proxies.json` and `history.json` come from |
| `PROXYBOT_POLL_SECONDS` | `300` | how often to look for a new run (at least 60) |
| `PROXYBOT_STATE` | `state.json` | remembers which run was posted where, so restarts don't post twice |
| `PROXYBOT_READY_FILE` | – | where to write the PID once every bot is logged in (the service sets `/run/proxybot/ready`) |

Tests: `cd bot && python -m pytest tests`

## Telegram

The same process can answer on Telegram too – it runs whichever bots have a token.

| Command | |
|---|---|
| `/proxy de socks5` | one fast proxy, with a `curl` line to try it |
| `/proxies 10 us https` | a short list, fastest first (up to 20) |
| `/stats` | numbers of the last run |

Filters come in any order: a country code, a type (`http`, `socks4`, `socks5`), `https` and a number.

1. Talk to [@BotFather](https://t.me/BotFather), send `/newbot` and copy the token.
2. Add it as the repository secret `TELEGRAM_TOKEN`. The deploy writes it next to `DISCORD_TOKEN`; either one alone is enough.
3. Run the *discord bot* workflow by hand (or push to `bot/`) – it restarts the service with both.

It uses long polling, so the server needs no open port and no webhook.
