Implement reactions and image sync

INSTALL.md

@@ -0,0 +1,151 @@
+# 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
+
+```bash
+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
+
+```bash
+make build
+make run
+```
+
+## 5) Bootstrap database and admin
+
+```bash
+make migrate
+make auth
+```
+
+Optional static token helper:
+
+```bash
+make token
+```
+
+## 6) Logs and health checks
+
+Tail logs:
+
+```bash
+make log
+```
+
+Basic stack status:
+
+```bash
+docker-compose --env-file=stack.env ps
+```
+
+## 7) Restart conventions
+
+### Full environment recycle (preferred when dependency state is broken)
+
+```bash
+make stop && make run
+```
+
+Use the explicit `make stop && make run` command sequence when a full recycle is needed.
+
+### Single service restart
+
+```bash
+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:
+
+```bash
+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:
+
+```bash
+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.