# 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.