GIA/INSTALL.md

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

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/

10) 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"

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.