docs: update NC Talk doc with real container name, commands, and logs section

- Use dgr_zone_nextcloud-app-1 throughout (actual container name)
- talk:bot:uninstall (not remove — wrong command in previous version)
- Added Logs section: occ log:tail + journalctl
- Bruteforce reset command now includes full docker exec form

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
Scott Idem
2026-03-29 13:47:43 -04:00
parent ddf5dd6338
commit 6b725afc3e

View File

@@ -38,29 +38,31 @@ Create `home/{username}/channels.json` on the Cortex server:
### 2. Register the bot in Nextcloud ### 2. Register the bot in Nextcloud
Run on the Nextcloud server (inside the Docker container): The Nextcloud container for DgrZone is `dgr_zone_nextcloud-app-1`. Substitute your own container name if different.
First, list existing bots to check if one is already registered (note the bot ID):
```bash ```bash
docker exec -it --user www-data <nc-app-container> php /var/www/html/occ talk:bot:install \ docker exec -it --user www-data dgr_zone_nextcloud-app-1 php /var/www/html/occ talk:bot:list
"{persona_name}" \ ```
If re-registering (new URL or new secret), uninstall the old bot first:
```bash
docker exec -it --user www-data dgr_zone_nextcloud-app-1 php /var/www/html/occ talk:bot:uninstall <bot-id>
```
Install the bot:
```bash
docker exec -it --user www-data dgr_zone_nextcloud-app-1 php /var/www/html/occ talk:bot:install \
"Inara" \
"<bot_secret from channels.json>" \ "<bot_secret from channels.json>" \
"https://cortex.dgrzone.com/webhook/nextcloud/{username}" \ "https://cortex.dgrzone.com/webhook/nextcloud/{username}" \
--feature webhook --feature response --feature reaction --feature webhook --feature response --feature reaction
``` ```
After installing, enable the bot in each Talk conversation via the conversation settings UI (three-dot menu → Bots). After installing, enable the bot in each Talk conversation: open the conversation three-dot menu → **Bots** → enable the bot by name.
To list installed bots and verify registration:
```bash
docker exec -it --user www-data <nc-app-container> php /var/www/html/occ talk:bot:list
```
To remove a bot (e.g. to re-register with a new secret or URL):
```bash
docker exec -it --user www-data <nc-app-container> php /var/www/html/occ talk:bot:remove <bot-id>
```
--- ---
@@ -131,6 +133,20 @@ location ^~ /webhook/ {
--- ---
## Logs
Two log streams are useful when debugging:
```bash
# Nextcloud server logs (bot registration errors, webhook rejections)
docker exec -it --user www-data dgr_zone_nextcloud-app-1 php /var/www/html/occ log:tail
# Cortex service logs (LLM errors, signature failures, timeouts)
journalctl --user -u cortex -f
```
---
## Troubleshooting ## Troubleshooting
| Symptom | Cause | Fix | | Symptom | Cause | Fix |
@@ -139,7 +155,7 @@ location ^~ /webhook/ {
| Webhook not received | Bot not enabled for conversation | Enable in Talk conversation settings (Bots) | | Webhook not received | Bot not enabled for conversation | Enable in Talk conversation settings (Bots) |
| Incoming 401 | `bot_secret` in `channels.json` doesn't match `occ install` secret | Re-register with matching secret | | Incoming 401 | `bot_secret` in `channels.json` doesn't match `occ install` secret | Re-register with matching secret |
| Reply POST returns 401 (first try) | HMAC computed over wrong data | Sign `random + message_text` only (not raw JSON body) | | Reply POST returns 401 (first try) | HMAC computed over wrong data | Sign `random + message_text` only (not raw JSON body) |
| Reply POST returns 401 (persistent) | Brute force protection triggered | `occ security:bruteforce:reset <cortex-IP>` | | Reply POST returns 401 (persistent) | Brute force protection triggered | `docker exec -it --user www-data dgr_zone_nextcloud-app-1 php /var/www/html/occ security:bruteforce:reset <cortex-IP>` |
| Bot auto-disabled by Nextcloud | Webhook held open too long | Verify `BackgroundTasks` is used — Cortex returns 200 immediately | | Bot auto-disabled by Nextcloud | Webhook held open too long | Verify `BackgroundTasks` is used — Cortex returns 200 immediately |
| Claude falls back to Gemini | Stale/expired auth token | Run `claude auth login`; token is auto-refreshed from `~/.claude/.credentials.json` | | Claude falls back to Gemini | Stale/expired auth token | Run `claude auth login`; token is auto-refreshed from `~/.claude/.credentials.json` |
| No response at all | Nginx blocking the path | Add a `location ^~ /webhook/` block before any auth block | | No response at all | Nginx blocking the path | Add a `location ^~ /webhook/` block before any auth block |