docs: T-HUB README and validation guide
README: architecture diagrams (single account, shared accounts, components), status per platform, outreach, hardware and bandwidth requirements, ports, security practices and what to monitor. docs/T-HUB-VALIDACION.txt: per-commit test plan for reviewers.
This commit is contained in:
parent
f6840ff69b
commit
c7d133c395
2 changed files with 417 additions and 6 deletions
267
README.md
267
README.md
|
|
@ -1,4 +1,259 @@
|
|||
# Tactical Media Broadcast Hub
|
||||
# T-HUB
|
||||
|
||||
<p align="center"><img src="docs/brand/t-hub.svg" width="160" alt="T-HUB"></p>
|
||||
|
||||
Copia de trabajo del [Tactical Media Broadcast Hub](https://gitlab.moxexley.com/mediatools/tacticalmediahub)
|
||||
para la red de acampadas: [acampada26s.net](https://acampada26s.net),
|
||||
[tomalacalle.net](https://tomalacalle.net) y [takethestreet.net](https://takethestreet.net).
|
||||
El despliegue en uso es [app.occupymedia.cc](https://app.occupymedia.cc).
|
||||
|
||||
Seguimos la rama `main` de upstream y mandamos allí los cambios que les sirvan.
|
||||
Lo propio de T-HUB va en este repo. Para revisar y validar los cambios, ver
|
||||
[docs/T-HUB-VALIDACION.txt](docs/T-HUB-VALIDACION.txt).
|
||||
|
||||
Cambios respecto a upstream:
|
||||
|
||||
- Instagram registrado en conexión y publicación; claves de la app de Meta solo en el entorno del servidor.
|
||||
- Panel **Outreach** para escribir por privado a mano, contacto a contacto, con seguimiento.
|
||||
- RLS forzado en `media_assets` (migración 042).
|
||||
- Estilo de acampada26s.net en la web: negro, blanco, neón `#00e5ff` y títulos en Anton.
|
||||
|
||||
| Remoto | URL |
|
||||
|---|---|
|
||||
| `origin` | `https://gitea.laenre.net/hacklab/T-HUB.git` |
|
||||
| `upstream` | `https://gitlab.moxexley.com/mediatools/tacticalmediahub.git` |
|
||||
|
||||
```bash
|
||||
git fetch upstream && git merge upstream/main
|
||||
```
|
||||
|
||||
## Arquitectura
|
||||
|
||||
### 1. Una cuenta
|
||||
|
||||
Una persona conecta una cuenta del colectivo una sola vez. A partir de ahí
|
||||
redacta, alguien aprueba y el Hub publica. La contraseña de la red social no
|
||||
pasa nunca por el Hub: la red devuelve un token y el Hub lo guarda cifrado.
|
||||
|
||||
```mermaid
|
||||
flowchart LR
|
||||
P([Persona]) -->|1. Conectar| H[T-HUB]
|
||||
H -->|2. Pantalla de permiso| R[(Red social)]
|
||||
R -->|3. Token| H
|
||||
P -->|4. Redacta| H
|
||||
H -->|5. Aprobación| A([Otra persona del colectivo])
|
||||
A -->|6. Visto bueno| H
|
||||
H -->|7. Publica a su hora| R
|
||||
```
|
||||
|
||||
### 2. Varias cuentas compartidas
|
||||
|
||||
Cada colectivo tiene sus cuentas y sus reglas de aprobación. Un borrador puede
|
||||
ir a varias cuentas a la vez: el Hub crea una copia por destino y cada una pasa
|
||||
la regla de su cuenta (automática, una persona, mayoría o consenso). Lo que deba
|
||||
salir en toda la red sube a la cola del colectivo padre.
|
||||
|
||||
```mermaid
|
||||
flowchart TB
|
||||
subgraph TTS[TAKE THE STREET]
|
||||
Q[Cola común] --> IG1[Instagram internacional]
|
||||
Q --> M1[Mastodon @takethestreet]
|
||||
end
|
||||
subgraph S26[ACAMPADA 26S]
|
||||
D[Borrador] --> IG2[Instagram @acampada26s]
|
||||
D --> M2[Mastodon @26s]
|
||||
D --> T2[Telegram acampada26s]
|
||||
end
|
||||
subgraph SUB[Acampadas locales]
|
||||
B[Barcelona] --> IG3[Instagram propio]
|
||||
S[Sevilla] --> IG4[Instagram propio]
|
||||
end
|
||||
S26 -->|Sube para toda la red| Q
|
||||
SUB -->|Sube a 26S| D
|
||||
IG2 -.->|Regla: 2 aprobaciones| G{{Aprobación}}
|
||||
M2 -.->|Regla: automática| G
|
||||
```
|
||||
|
||||
### 3. Parte técnica
|
||||
|
||||
La web solo habla con la API. La API guarda el estado en Postgres con
|
||||
aislamiento por colectivo (RLS), los tokens van en un vault cifrado y el
|
||||
envío programado lo hace el scheduler con Temporal. Cada red es un conector;
|
||||
fuera de los conectores no hay código que distinga redes.
|
||||
|
||||
```mermaid
|
||||
flowchart LR
|
||||
subgraph Cliente
|
||||
W[apps/web<br/>Next.js]
|
||||
end
|
||||
subgraph Control
|
||||
API[apps/api<br/>NestJS]
|
||||
SCH[apps/scheduler<br/>Temporal worker]
|
||||
REG[ConnectorRegistry<br/>packages/connector-*]
|
||||
end
|
||||
subgraph Datos
|
||||
PG[(PostgreSQL<br/>RLS por colectivo)]
|
||||
RD[(Redis<br/>estado OAuth 10 min)]
|
||||
V[Vault<br/>AES-256-GCM + KEK]
|
||||
S3[(S3 / R2<br/>medios cifrados)]
|
||||
end
|
||||
subgraph Medios
|
||||
MW[apps/media-worker<br/>FFmpeg]
|
||||
PT[PeerTube<br/>tube.occupymedia.cc]
|
||||
end
|
||||
subgraph Redes
|
||||
MA[Mastodon API]
|
||||
IG[Graph API<br/>Instagram]
|
||||
TG[Telegram Bot API]
|
||||
end
|
||||
|
||||
W -->|HTTPS + sesión| API
|
||||
API --> PG
|
||||
API --> RD
|
||||
API --> V
|
||||
V --> PG
|
||||
API -->|connect / identity| REG
|
||||
SCH -->|publish| REG
|
||||
SCH --> PG
|
||||
REG -->|providerFetch<br/>control de salida| MA
|
||||
REG --> IG
|
||||
REG --> TG
|
||||
MW --> S3
|
||||
MW -->|RTMP| PT
|
||||
```
|
||||
|
||||
Conectar una cuenta (OAuth con `state` de un solo uso y PKCE donde la red lo admite):
|
||||
|
||||
1. `POST /connections/authorize`: la API guarda en Redis, cifrado, el estado de la petición y devuelve la URL de la red.
|
||||
2. La persona acepta en la red y la red vuelve a `GET /connections/callback`.
|
||||
3. La API comprueba `state`, cookie y permisos, canjea el código y guarda el token en el vault.
|
||||
|
||||
## Estado por red
|
||||
|
||||
| Red | Conectar | Publicar | Notas |
|
||||
|---|---|---|---|
|
||||
| Mastodon | Sí | Texto | Sin claves de servidor; cada cuenta registra la app en su instancia. |
|
||||
| Telegram | Sí | Texto | Token del bot de BotFather. |
|
||||
| Instagram | Sí, con `INSTAGRAM_CLIENT_ID/SECRET` | No todavía | Meta descarga la imagen de una URL pública y los medios están cifrados: falta un endpoint temporal. Ver [docs/oauth-connect.md](docs/oauth-connect.md). |
|
||||
| PeerTube | No | Directo sí | Falta el puente OAuth en tube.occupymedia.cc. |
|
||||
| X | No | No | Sin conector. API de pago por uso. |
|
||||
| TikTok | No | No | Fuera de alcance: la API exige auditoría y sin ella solo publica en privado. |
|
||||
|
||||
## Panel Outreach (mensajes privados)
|
||||
|
||||
Lista de cuentas públicas (artistas, colectivos, medios) a las que escribir por
|
||||
privado para pedir difusión. Cada contacto tiene su mensaje, se puede rellenar
|
||||
con una plantilla (`{name}`, `{handle}`) y se marca enviado, respondido o
|
||||
rechazado. Se importa en CSV:
|
||||
|
||||
```
|
||||
name,platform,handle,profileUrl,category,language
|
||||
Climáximo,bluesky,climaximopt.bsky.social,https://bsky.app/profile/climaximopt.bsky.social,clima,pt
|
||||
```
|
||||
|
||||
El Hub **no envía** los mensajes. "Copy & open profile" copia el texto y abre el
|
||||
perfil; la persona lo pega y lo envía desde la propia red. Motivos:
|
||||
|
||||
| Red | Abrir un privado por API | Problema |
|
||||
|---|---|---|
|
||||
| Instagram | No | La API solo deja responder a quien te escribió en las últimas 24 h. |
|
||||
| X | Sí, de pago | Mensajes en masa a desconocidos van contra sus normas de automatización: suspensión. |
|
||||
| Mastodon | Sí (mención privada) | Las instancias silencian o bloquean cuentas que lo hacen en masa; puede caer la instancia entera. |
|
||||
| Bluesky | Sí | Mismo criterio de spam; los chats de desconocidos suelen estar cerrados. |
|
||||
|
||||
El contador de la pantalla avisa a partir de 20 primeros mensajes al día por
|
||||
colectivo. Repartidlos entre varias personas y días, y personalizad cada uno.
|
||||
|
||||
## Requisitos
|
||||
|
||||
Medido en el despliegue actual (ver
|
||||
[docs/ops/2026-10-12-cloud-hosting-requirements.md](docs/ops/2026-10-12-cloud-hosting-requirements.md)).
|
||||
Los medios van a R2, así que el disco no crece con los vídeos.
|
||||
|
||||
| Nivel | CPU | RAM | Disco | Para qué |
|
||||
|---|---|---|---|---|
|
||||
| Mínimo | 4 vCPU | 8 GB | 160 GB SSD | Todo el stack, transcodificación fuera de la máquina |
|
||||
| Recomendado | 8 vCPU | 16 GB | 240 GB SSD | Directos, transcodificación en la máquina, Collabora |
|
||||
| Nodo de render (opcional) | 4+ núcleos o GPU con NVENC | 8 GB | 50 GB | Se une por Tailscale; nunca guarda claves |
|
||||
|
||||
Uso real hoy: unos 2,6 GB de RAM entre todos los servicios.
|
||||
|
||||
Ancho de banda:
|
||||
|
||||
| Uso | Necesario |
|
||||
|---|---|
|
||||
| Panel, publicación, APIs de redes | < 1 Mbps sostenido |
|
||||
| Un directo saliente (1080p30 hacia PeerTube) | 6 Mbps de subida por directo; 3 Mbps a 720p |
|
||||
| Espectadores | Los sirve Cloudflare desde la caché de HLS; el origen no escala con la audiencia |
|
||||
| Subidas de vídeo | Picos de lo que dé la línea; límite de 2 GiB por archivo |
|
||||
|
||||
Coste orientativo: VPS de 30 €/mes + R2 de 1 a 5 $/mes. Cloudflare en plan gratuito.
|
||||
|
||||
## Red y puertos
|
||||
|
||||
Entrada desde internet: **ninguna** directa. Todo entra por el túnel de
|
||||
Cloudflare; el nginx de borde solo acepta rangos de Cloudflare en 80/443.
|
||||
|
||||
| Puerto | Servicio | Exponer a |
|
||||
|---|---|---|
|
||||
| 443/tcp | nginx de borde | Solo rangos de Cloudflare |
|
||||
| 80/tcp | nginx de borde (redirección) | Solo rangos de Cloudflare |
|
||||
| 3000/tcp | API | Solo 127.0.0.1 |
|
||||
| 3001/tcp | Web | Solo 127.0.0.1 |
|
||||
| 9000/tcp | PeerTube | Solo 127.0.0.1 o Tailscale |
|
||||
| 1935/tcp | RTMP de PeerTube | Solo Tailscale (worker de medios) |
|
||||
| 6167/tcp | Matrix (conduwuit) | Solo 127.0.0.1 |
|
||||
| 9200, 9980/tcp | oCIS, Collabora | Solo 127.0.0.1 |
|
||||
| 5432, 6379, 7233 | Postgres, Redis, Temporal | Nunca fuera de la red de Docker |
|
||||
|
||||
Salida que hace falta: 443/tcp a las APIs de las redes y a R2, 7844/tcp+udp
|
||||
para `cloudflared`, 41641/udp para Tailscale.
|
||||
|
||||
Docker publica puertos saltándose ufw. Para cerrarlos: publicar en `127.0.0.1:PUERTO`
|
||||
o en la IP de Tailscale, o añadir reglas en la cadena `DOCKER-USER`.
|
||||
|
||||
## Seguridad y monitorización
|
||||
|
||||
Prácticas para cualquier despliegue. Los fallos de seguridad se comunican en
|
||||
privado a quien mantiene el código, no en issues públicas.
|
||||
|
||||
- **Registro solo por invitación.** Un registro abierto da a cualquiera un colectivo propio y permisos de Owner sobre él.
|
||||
- **Un secreto por servicio.** La web y los workers no necesitan `SUPERPOSTER_KEK`, `S3_KEK` ni `SESSION_SECRET`. Claves distintas para el vault y para los medios.
|
||||
- **FFmpeg siempre en sandbox** (`NODE_ENV=production`, `MEDIA_SANDBOX=on`), sin red y sin variables de entorno heredadas.
|
||||
- **Cabeceras**: CSP estricta, HSTS, `X-Content-Type-Options`, `Referrer-Policy` en web y API.
|
||||
- **Límites de peticiones** en `/auth/*`, invitaciones, OIDC y subidas públicas, por `CF-Connecting-IP`.
|
||||
- **Metadatos fuera**: quitar EXIF/GPS de fotos y vídeos antes de guardarlos o publicarlos.
|
||||
- **Copias cifradas** (`age` o GPG) y fuera de la máquina; probar la restauración.
|
||||
- **Auditoría inalterable**: quitar `UPDATE`/`DELETE` sobre `audit_log` al rol `sp_app` y anclar fuera la cabeza de la cadena.
|
||||
|
||||
Qué vigilar (Prometheus + Grafana ya están en `infra/`; Grafana nunca con acceso anónimo):
|
||||
|
||||
| Señal | Alerta si |
|
||||
|---|---|
|
||||
| `401`/`403` en `/auth/login` por IP | > 20 en 5 min |
|
||||
| Registros nuevos / invitaciones canjeadas | Cualquiera fuera de lo previsto |
|
||||
| Eventos `audit_log`: `member.*`, `connection.removed`, `group.deleted`, `outreach.removed` | Picos o actores raros |
|
||||
| `connections` en estado `needs_credentials` | Cualquiera: token revocado o caducado |
|
||||
| Errores 5xx de la API | > 1 % durante 5 min |
|
||||
| Memoria de API y workers | > 80 % |
|
||||
| Cola de publicación `failed`/`unknown` | Cualquiera |
|
||||
| Logins al panel de Cloudflare y cambios de DNS | Siempre |
|
||||
|
||||
## Desarrollo
|
||||
|
||||
```bash
|
||||
corepack enable
|
||||
pnpm install
|
||||
pnpm exec turbo run build typecheck --filter=@tactical-media-broadcast-hub/api...
|
||||
pnpm --filter @tactical-media-broadcast-hub/connector-instagram test
|
||||
```
|
||||
|
||||
Los tests de integración de `apps/api` que usan Postgres se saltan si no hay
|
||||
base de datos configurada.
|
||||
|
||||
---
|
||||
|
||||
## Upstream: Tactical Media Broadcast Hub
|
||||
|
||||
Self-hosted multi-tenant social / video / livestream management platform with a
|
||||
generic connector system and a Virtual Channel / Auto Director subsystem.
|
||||
|
|
@ -8,7 +263,7 @@ concentrating access in one person's hands. Every credential lives in an
|
|||
encrypted vault. Every editorial decision lands in a tamper-evident audit log.
|
||||
Every feature is multi-tenant with row-level security.
|
||||
|
||||
## Features
|
||||
### Features
|
||||
|
||||
- **Publishing pipeline** — drafts → group approval → schedule → fenced dispatch → receipts. Per-connection publish governance: `auto`, one-admin, majority or consensus sign-off per account — boosts included. Multi-platform fan-out (Mastodon, Telegram, Bluesky, PeerTube, Facebook, Instagram, Threads, LinkedIn, Reddit, Twitch, Discord, Slack). DST-proof scheduling.
|
||||
- **Files SSO** — the Hub is the OIDC issuer for oCIS Drive: one sign-in, auto-provisioned personal drives, rotating refresh tokens that die with your Hub session (logout propagates).
|
||||
|
|
@ -20,7 +275,7 @@ Every feature is multi-tenant with row-level security.
|
|||
- **Archive** — content-addressed encrypted S3, dedup, full-text search, CSV/JSON export. Deleted platform content stays citable.
|
||||
- **Analytics** — month-partitioned snapshots, current + previous month with deltas, per-provider breakdown.
|
||||
|
||||
## Quickstart
|
||||
### Quickstart
|
||||
|
||||
```bash
|
||||
pnpm install
|
||||
|
|
@ -38,7 +293,7 @@ curl localhost:3000/healthz
|
|||
curl localhost:3000/readyz
|
||||
```
|
||||
|
||||
## Documentation
|
||||
### Documentation
|
||||
|
||||
| Section | Path |
|
||||
|---|---|
|
||||
|
|
@ -49,13 +304,13 @@ curl localhost:3000/readyz
|
|||
| Streaming architecture | [`docs/design/streaming-architecture.md`](docs/design/streaming-architecture.md) |
|
||||
| Deployment (occupymedia.cc) | [`infra/occupymedia/DEPLOY.md`](infra/occupymedia/DEPLOY.md) |
|
||||
|
||||
## Deterministic live-source testing
|
||||
### Deterministic live-source testing
|
||||
|
||||
```bash
|
||||
pnpm --filter @tactical-media-broadcast-hub/media-worker soak -- --hours 8 --out
|
||||
```
|
||||
|
||||
## Security & trust model
|
||||
### Security & trust model
|
||||
|
||||
Self-hosted, end to end — no corporate cloud, no accounts needed to run the
|
||||
system itself. Multi-tenant with row-level security; platform credentials in an
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue