echo6-docs/archive/matrix/hookshot_deployment_discovery.md

Hookshot Deployment Discovery

Generated: 2026-04-09 (Phase 6.0, Question 2)

Contabo Resource Availability

Memory

• Total: 47 GB
• Used: 11 GB
• Available: 35 GB
• Headroom: PLENTY for hookshot (~100 MB requirement)

Disk

• Total: 968 GB
• Used: 77 GB (8%)
• Available: 892 GB
• Headroom: PLENTY

CPU

Current idle is ~65%. TAK Server is the biggest consumer at 22%. Hookshot is single-threaded Node.js, minimal CPU.

Verdict: Hookshot can run on Contabo alongside existing services with no resource concerns.

Hookshot Version

• Latest stable: 7.3.2 (released 2026-01-30)
• Image: halfshot/matrix-hookshot:7.3.2 (Docker Hub, multi-arch)
• Pin to exact tag, not :latest

Port Requirements

Purpose	Default Port	Status on Contabo
Appservice (HS→hookshot)	9993	AVAILABLE
Webhooks (inbound/outbound)	9000	CONFLICT — Authentik (127.0.0.1:9000) and TAK (100.64.0.1:9000)
Metrics (Prometheus)	9001	CONFLICT — TAK (100.64.0.1:9001)
Widgets	9002	AVAILABLE

Conflicts on default ports. Resolution options:

• Use non-default ports: e.g., 9800 for webhooks, 9801 for metrics
• Since hookshot outbound webhooks talk to a LOCAL receiver, any port works
• Appservice port 9993 is fine (container-internal via matrix-net)

Appservice Registration Flow

Same pattern as mautrix-signal. Registration file (registration.yml) goes into Synapse's app_service_config_files list.

Registration file format:

id: matrix-hookshot
as_token: <random>
hs_token: <random>
namespaces:
  rooms: []
  users:
    - regex: "@_webhooks_.*:echo6\\.co"
      exclusive: true
  aliases: []
sender_localpart: hookshot
url: "http://matrix-hookshot:9993"
rate_limited: false

MAS bypass: CONFIRMED from Phase 3. Appservice tokens (as_token/hs_token) are handled natively by Synapse, bypassing MAS entirely. Same mechanism as mautrix-signal.

Docker Compose Snippet (NOT APPLIED)

  matrix-hookshot:
    image: halfshot/matrix-hookshot:7.3.2
    container_name: matrix-hookshot
    restart: unless-stopped
    depends_on:
      postgres:
        condition: service_healthy
    volumes:
      - ./hookshot:/data
    networks:
      - matrix-net
    # No ports: section — internal to matrix-net only
    # Appservice reachable at http://matrix-hookshot:9993 from synapse
    # Webhook listener on 9800 (non-default) for internal receiver

No host port mapping needed. hookshot communicates with:

• Synapse via matrix-net (appservice transactions)
• A local receiver (if built) via matrix-net or localhost

Dependencies

If encryption is enabled (relevant to Question 3):

• Redis is REQUIRED
• Could use Mailcow's existing Redis, or add a dedicated instance
• Crypto store needs persistent volume

If encryption is NOT enabled:

• No Redis needed
• Minimal config

Resource Requirements

Per hookshot docs:

• RAM: ~100 MB baseline
• CPU: Minimal (single-threaded Node.js)
• Disk: Negligible (crypto store if E2EE, otherwise just config)