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 either Podman + podman-compose wrapper or Docker Compose compatibility.
• 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

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:

docker-compose --env-file=stack.env ps

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

docker-compose --env-file=stack.env restart <service>

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:

docker-compose --env-file=stack.env restart ur

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.

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.