> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ilyama.golain.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Omega setup for SQLite sync

> Install, configure, and run Omega for Golain SQLite replication.

Omega ships a production reference client **`ilyama-edge`** for Golain SQLite replication. This page covers install paths, environment, and first run.

## Fastest path: golain scaffold

If you have [golain installed](/tools/platform-tui/install) and a registered device:

```bash theme={null}
golain login
golain context set --org=my-org --project=my-project

golain omega scaffold \
  --device=gw-floor-2 \
  --fleet=sensors \
  --sample-db \
  --transport=tls \
  --verify-tables
```

This command:

1. Issues or reuses MQTT mTLS certificates
2. Seeds a sample SQLite DB, or a three-table verification DB when you pass `--verify-tables` (`vrf_*_events`, `vrf_*_state`, `vrf_*_metrics`)
3. Downloads **Omega** and **SQLite deps** from `https://tools.ilyama.golain.io/omega/`
4. Writes `omega-config.yaml`, `omega-env.sh`, and replication triggers

Run:

```bash theme={null}
source ~/.config/golain/omega/gw-floor-2/omega-env.sh
~/.config/golain/omega/gw-floor-2/omega \
  -client ~/.config/golain/omega/gw-floor-2/omega-config.yaml
```

Or use the TUI **Deploy Omega** wizard (`O` on device detail). → [Omega deploy](/tools/platform-tui/omega-deploy)

<Warning>
  Prefer **`--transport=tls`** when QUIC is unavailable. Some brokers reject QUIC; TLS (`ssl://host:8883`) is the reliable default for first connect.
</Warning>

## Manual install (CDN)

When not using scaffold:

```bash theme={null}
curl -fsSL https://tools.ilyama.golain.io/omega/install.sh | sh
curl -fsSL https://tools.ilyama.golain.io/omega/install-sqlite-deps.sh | sh
```

→ [Install Omega](/edge/install)

## Prerequisites

* Device registered in Golain ([fleets and devices](/console/fleets-and-devices))
* mTLS certificate issued for MQTT (scaffold does this automatically; see [provisioning checklist](/edge/data-sync/provisioning-checklist) for manual flow)
* Application SQLite database path on the device
* Network path to MQTT broker (TLS TCP or QUIC)

## Build from source (development)

### Client-specific binary (production)

Embeds connection config and only required modules:

```bash theme={null}
git clone https://github.com/golain-io/omega
cd omega
make build-client CLIENT=ilyama-edge GOOS=linux GOARCH=arm64
# → bin/omega-linux-arm64
```

### Development run from source

```bash theme={null}
make build
go run ./cmd/omega -client clients/ilyama-edge-dev.yaml
```

`ilyama-edge-dev.yaml` adds macOS support and explicit `state_db_path_env`.

## Reference client YAML

Scaffold generates a profile equivalent to `clients/ilyama-edge.yaml`:

```yaml theme={null}
name: ilyama-edge
platform: linux
connection:
  transport: mqtt
  server_url_env: OMEGA_MQTT_BROKER_URL
  device_id_env: OMEGA_DEVICE_ID
  root_topic_env: OMEGA_ROOT_TOPIC
  mqtt:
    keep_alive: 30s
    clean_session: false
    tls:
      ca_cert_path_env: OMEGA_TLS_CA_PATH
      client_cert_path_env: OMEGA_TLS_CERT_PATH
      client_key_path_env: OMEGA_TLS_KEY_PATH

modules:
  required:
    - sqlite-replication
    - heartbeat

security:
  auth_token_env: OMEGA_AUTH_TOKEN
  signed_control:
    enabled: true
  capabilities:
    sqlite-replication: true
    heartbeat: true

sqlite-replication:
  source_db_path_env: OMEGA_SOURCE_DB_PATH
  flush_interval: 5s
```

→ Full field reference: [Configuration](/edge/data-sync/configuration)

## Environment variables

| Variable                | Purpose                                                           |
| ----------------------- | ----------------------------------------------------------------- |
| `OMEGA_MQTT_BROKER_URL` | e.g. `ssl://mqtt.example.com:8883` or `quic://host:port`          |
| `OMEGA_DEVICE_ID`       | Device **name** (must match Golain registration / MQTT client id) |
| `OMEGA_ROOT_TOPIC`      | `{topic_slug}/{device_name}` or `/{device_name}` if no slug       |
| `OMEGA_SOURCE_DB_PATH`  | Path to application SQLite file                                   |
| `OMEGA_STATE_DB_PATH`   | Persistent cursors/pause state (recommended prod)                 |
| `OMEGA_TLS_CA_PATH`     | Broker CA PEM                                                     |
| `OMEGA_TLS_CERT_PATH`   | Device client cert PEM                                            |
| `OMEGA_TLS_KEY_PATH`    | Device client key PEM                                             |
| `OMEGA_AUTH_TOKEN`      | Control message auth (HMAC envelope)                              |

Example block (also generated in `omega-env.sh`):

```bash theme={null}
export OMEGA_MQTT_BROKER_URL=ssl://mqtt.ilyama.golain.io:8883
export OMEGA_DEVICE_ID=gw-floor-2
export OMEGA_ROOT_TOPIC=acme-prod/gw-floor-2
export OMEGA_SOURCE_DB_PATH=/var/lib/myapp/data.db
export OMEGA_STATE_DB_PATH=/var/lib/omega/state.db
export OMEGA_TLS_CA_PATH=/etc/omega/ca.pem
export OMEGA_TLS_CERT_PATH=/etc/omega/device.pem
export OMEGA_TLS_KEY_PATH=/etc/omega/device.key
export OMEGA_AUTH_TOKEN=<from-provisioning>
./omega-linux-arm64
```

## Sample multi-table dev setup

When building Omega from source without scaffold:

```bash theme={null}
bash scripts/seed-sample-replication-db.sh
go run ./cmd/omega -client clients/ilyama-edge-sample.yaml
# second terminal — mutations after omega installed triggers:
bash scripts/sample-replication-mutations.sh
```

Tables: `order_events`, `device_state`, `sensor_timeseries`. Use `rows` for relational/state tables and `telemetry` for time-series tables with a stable timestamp column.

## Multi-table verification with `--verify-tables`

`golain omega scaffold --verify-tables` creates three uniquely named SQLite tables so you can validate a fresh end-to-end sync without colliding with existing lineages in a shared Project:

* `vrf_<suffix>_events` — row-batch verification
* `vrf_<suffix>_state` — relational/state verification
* `vrf_<suffix>_metrics` — telemetry verification

This is the fastest way to confirm the full current Omega + ilyama flow:

1. Scaffold with `--verify-tables`
2. Start Omega
3. Approve the queued review in **Edge Sync**
4. Confirm all three lineages appear for the device
5. Read telemetry from the Project-scoped `edge_ts_*` hypertable for `vrf_<suffix>_metrics`

## Verify cloud ingest

1. Console or `golain devices get` — device **connected**.
2. golain TUI → **Edge Sync → Lineages** — lineages appear per table. With `--verify-tables`, expect **three** lineages for the device.
3. Expect schema review **queued** on first batch — [approve workflow](/edge/data-sync/schema-review-workflow).
4. After approval, expect telemetry for the `vrf_*_metrics` table in the Project's `edge_ts_*` hypertable and relational rows for `vrf_*_state` through `mirror-rows`.

Maintainer e2e script (ilyama):

```bash theme={null}
cd ilyama/tools/platform-tui
./scripts/verify-omega-scaffold.sh
```

## Deploy as service

→ [Deploy Omega](/edge/deploy) (systemd / launchd / Windows)

## Automated deployed e2e (maintainers)

```bash theme={null}
echo '<bearer-token>' > .e2e-deployed/bearer.token
bash scripts/run-deployed-replication-e2e.sh
```

Details: [omega deployed-e2e-provisioning](https://github.com/golain-io/omega/blob/main/docs/deployed-e2e-provisioning.md).

## Related

* [Capture strategies](/edge/data-sync/capture-strategies)
* [Provisioning checklist](/edge/data-sync/provisioning-checklist)
* [Connect to Golain](/edge/connect)
* [golain Omega deploy](/tools/platform-tui/omega-deploy)