XF/GIA
1
0
Fork 0
Code Issues 2 Pull Requests Actions Packages Projects Releases Wiki Activity
Files
da044be68c4299103993461a7613889726fc6448
GIA/INSTALL.md
Mark Veidemanis acedc01e83 Fix all integrations
2026-03-08 22:08:55 +00:00

7.6 KiB
Raw Blame History

INSTALL

This guide covers installation, environment configuration, and operational startup for GIA.

Use this first. Then read README.md for feature and operation-mode details.

1) Prerequisites

  • Linux host with Podman.
  • Git.
  • Network access for service images and Python dependencies.

2) Clone and initialize

git clone <repo-url> GIA
cd GIA
cp stack.env.example stack.env

3) Configure environment (stack.env)

At minimum, set:

  • SECRET_KEY
  • DOMAIN
  • URL
  • ALLOWED_HOSTS
  • CSRF_TRUSTED_ORIGINS
  • APP_DATABASE_FILE
  • APP_LOCAL_SETTINGS
  • STATIC_ROOT

Enable transport services as needed:

  • SIGNAL_NUMBER
  • SIGNAL_HTTP_URL
  • WHATSAPP_ENABLED
  • WHATSAPP_DB_DIR
  • INSTAGRAM_ENABLED
  • COMPOSE_WS_ENABLED

XMPP bridge settings:

  • XMPP_ADDRESS
  • XMPP_JID
  • XMPP_PORT
  • XMPP_SECRET

Prosody container helpers:

  • QUADLET_PROSODY_CONFIG_FILE
  • QUADLET_PROSODY_CERTS_DIR
  • QUADLET_PROSODY_DATA_DIR
  • QUADLET_PROSODY_LOGS_DIR

Memory/wiki search helpers:

  • MEMORY_SEARCH_BACKEND (django or manticore)
  • MANTICORE_HTTP_URL
  • MANTICORE_MEMORY_TABLE
  • MANTICORE_HTTP_TIMEOUT

For XMPP media upload, configure one of:

  • XMPP_UPLOAD_SERVICE
  • XMPP_UPLOAD_JID

If omitted, runtime attempts XEP-0363 discovery.

4) Build and start

make build
make run

5) Bootstrap database and admin

make migrate
make auth

Optional static token helper:

make token TOKEN_USER=<your_username>

Local code-quality checks:

make pre-commit
make pre-commit-glibc

make pre-commit-glibc selects env on musl systems and genv on glibc systems.

6) Logs and health checks

Tail logs:

make log

Basic stack status:

make status

7) Restart conventions

Full environment recycle (preferred when dependency state is broken)

make stop && make run

Use the explicit make stop && make run command sequence when a full recycle is needed.

Single service restart

podman restart <container-name>

If single-service restart fails due to dependency/pod state, use full recycle above.

8) Runtime code change policy

After changing UR/runtime code (core/clients/*, transport, relay paths), restart runtime services before validating behavior.

Minimum target:

podman restart ur_gia

If blocked, use full recycle.

9) Service endpoints

  • Home: /
  • Signal service page: /services/signal/
  • WhatsApp service page: /services/whatsapp/
  • Instagram service page: /services/instagram/
  • Manual compose: /compose/page/
  • AI workspace: /ai/workspace/
  • OSINT search: /search/page/
  • Security encryption settings: /settings/security/encryption/
  • Security permissions settings: /settings/security/permissions/
  • Command routing settings: /settings/command-routing/
  • Task automation settings: /settings/tasks/
  • Task inbox / manual task creation: /tasks/

10) Security and capability controls

  • Require OMEMO encryption rejects plaintext XMPP messages before command routing.
  • Encrypt gateway component chat replies with OMEMO only affects gateway/component conversations.
  • Encrypt contact relay messages to your XMPP client with OMEMO only affects relayed contact chats.
  • Fine-grained capability policy is configured in /settings/security/permissions/ and applies by scope, service, and optional channel pattern.
  • Trusted OMEMO key enforcement depends on trusted key records, not only the most recently observed client key.

11) Common troubleshooting

A) Compose restart errors / dependency improper state

Use:

make stop && make run

B) XMPP attachment upload issues

  • Confirm upload host TLS and cert chain are valid.
  • Confirm XMPP_UPLOAD_SERVICE/XMPP_UPLOAD_JID is set, or discovery works.
  • Check runtime logs for slot request and upload errors.

D) Prosody container (lightweight, no systemd)

Use:

./utilities/prosody/manage_prosody_container.sh up
./utilities/prosody/manage_prosody_container.sh status
./utilities/prosody/manage_prosody_container.sh logs

Auth script path for Prosody config:

external_auth_command = "/code/utilities/prosody/auth_django.sh"

Certificate renewal helper (run as root on host):

./utilities/prosody/renew_prosody_cert.sh

E) Manticore container for memory/wiki retrieval

./utilities/memory/manage_manticore_container.sh up
./utilities/memory/manage_manticore_container.sh status
./utilities/memory/manage_manticore_container.sh logs

Reindex memory into configured backend:

podman exec ur_gia /venv/bin/python manage.py memory_search_reindex --user-id 1 --statuses active

Query memory backend:

podman exec ur_gia /venv/bin/python manage.py memory_search_query --user-id 1 --query "reply style"

Generate proposed memories from recent inbound messages:

podman exec ur_gia /venv/bin/python manage.py memory_suggest_from_messages --user-id 1 --limit-messages 300 --max-items 30

Run memory hygiene (expiry decay + contradiction queueing):

podman exec ur_gia /venv/bin/python manage.py memory_hygiene --user-id 1

Performance defaults now applied in GIA:

  • Batched Manticore reindex writes (REPLACE ... VALUES (...) in chunks) for lower ingest latency.
  • Cached table-ensure checks to avoid CREATE TABLE IF NOT EXISTS overhead on every query.
  • Runtime table maintenance available through MCP (FLUSH RAMCHUNK, OPTIMIZE TABLE) for steady query responsiveness.

F) MCP server for task + memory tooling (VS Code)

The workspace includes an MCP config at /code/xf/.vscode/mcp.json for server manticore.

It launches inside the running ur_gia container and forces:

  • MEMORY_SEARCH_BACKEND=manticore

MANTICORE_HTTP_URL is read from the container environment (stack.env / app settings).

Start requirements first:

make run
./utilities/memory/manage_manticore_container.sh up

Then approve/enable the manticore MCP server in VS Code when prompted.

The MCP task surface now supports canonical task creation/completion in GIA:

  • tasks.create
  • tasks.complete
  • tasks.create_note
  • tasks.link_artifact

Optional ultra-light Rust MCP worker:

cd /code/xf/GIA
make mcp-rust-build

Then enable manticore-rust-worker in /code/xf/.vscode/mcp.json. It is intentionally disabled: true by default so the existing Python MCP server remains the baseline.

H) Optional browser MCP for visual validation

To validate compose/tasks/settings flows visually, add a browser-capable MCP server in your editor workspace alongside manticore. A Playwright-style browser MCP is the intended integration point for GIA UI checks.

Recommended usage:

  • keep browser MCP outside host-network mode
  • point it at the local GIA app URL/port from the running stack
  • use it for page-load, form-flow, and visual regression checks on compose/tasks/settings pages

I) Task command shortcuts

Gateway / XMPP / chat task commands now include:

  • .l -> list open tasks
  • .tasks add <project> :: <title> -> create a canonical task in a named project
  • .task add <title> -> create a task inside the current mapped chat scope

C) Signal or WhatsApp send failures

  • Verify account/link status in service pages.
  • Verify ur service is running.
  • Inspect ur logs for transport-specific errors.

G) XMPP reconnect loop in logs

  • Confirm XMPP_ADDRESS, XMPP_JID, XMPP_PORT, and XMPP_SECRET are populated in stack.env.
  • XMPP_PORT is parsed as an integer in settings; invalid values can cause repeated reconnect failures.
  • The runtime now uses a single reconnect loop with exponential backoff to avoid overlapping reconnect churn.