diff --git a/.env.docker.example b/.env.docker.example index 89f2043..324371e 100644 --- a/.env.docker.example +++ b/.env.docker.example @@ -5,7 +5,7 @@ COMPOSE_PROFILES=nango,signoz,otel-collector,jaeger # Once set, it cannot be changed without losing existing encrypted data NANGO_ENCRYPTION_KEY= -# Optional: Pre-set the Nango API secret key (generate with: openssl rand -hex 16) +# Optional: Pre-set the Nango API secret key (must be a valid UUID v4) # When set, this overrides the auto-generated key in the Nango database. # The automated setup script (pnpm setup-dev:optional) sets this automatically. # NANGO_SECRET_KEY_DEV= diff --git a/README.md b/README.md index 917b75e..5fefebf 100644 --- a/README.md +++ b/README.md @@ -12,12 +12,12 @@ If you're working with the [Inkeep Agents](https://github.com/inkeep/agents) mon pnpm setup-dev:optional ``` -This clones this repo, starts all services, generates credentials, and wires env vars to your `.env` automatically. The monorepo ships a thin bootstrap shim that delegates to [`scripts/setup.sh`](scripts/setup.sh) in this repo. See the [main repo docs](https://github.com/inkeep/agents) for details. +This clones this repo into `.optional-services/` in your project, starts all services, generates credentials, and writes env vars to your `.env`. See the [main repo docs](https://github.com/inkeep/agents) for details. Lifecycle commands: - `pnpm optional:stop` — stop optional services - `pnpm optional:status` — show service status -- `pnpm optional:reset` — nuke data and re-setup from scratch +- `pnpm optional:reset` — remove all data and re-run setup If you used the automated setup, you can skip the manual steps below. @@ -31,7 +31,7 @@ CALLER_ENV_FILE=/path/to/your/project/.env ./scripts/setup.sh ./scripts/setup.sh --status ``` -`CALLER_ENV_FILE` tells the script where to write service URLs and API keys. It is required for `setup` and `--reset`, but optional for `--stop` and `--status`. +`CALLER_ENV_FILE` tells the script where to write service URLs and API keys. Required for `setup` and `--reset`; optional for `--stop` and `--status`. --- @@ -69,6 +69,8 @@ Use these steps if you're running this repo standalone (without `pnpm setup-dev: ### 1. Clone this repository +Clone as `.optional-services/` (matching the automated setup default) or any directory you prefer. + ### 2. Configure environment variables ```bash @@ -81,12 +83,14 @@ cp .env.docker.example .env && \ -e "s||$nango_dashboard_password|" \ .env > "$tmp_file" && \ mv "$tmp_file" .env && \ - echo "Docker environment file created with auto-generated NANGO_ENCRYPTION_KEY and NANGO_DASHBOARD_PASSWORD" + echo ".env created with auto-generated NANGO_ENCRYPTION_KEY and NANGO_DASHBOARD_PASSWORD" ``` -Optionally, generate a Nango API secret key (so you don't need to retrieve it from the dashboard later): +Optionally, pre-generate a Nango secret key (avoids retrieving it from the dashboard later): + ```bash -nango_key=$(openssl rand -hex 16) && \ +_hex=$(openssl rand -hex 16) && \ + nango_key=$(echo "$_hex" | sed 's/^\(.\{8\}\)\(.\{4\}\).\(.\{3\}\).\(.\{3\}\)\(.\{12\}\)$/\1-\2-4\3-a\4-\5/') && \ echo "NANGO_SECRET_KEY_DEV=$nango_key" >> .env && \ echo "Nango secret key: $nango_key (add this as NANGO_SECRET_KEY in your agents .env)" ``` diff --git a/nango-instructions.md b/nango-instructions.md index 82275dc..f3df49c 100644 --- a/nango-instructions.md +++ b/nango-instructions.md @@ -1,8 +1,8 @@ ## Nango: Setup and Configuration -> **Note:** If you used the automated setup (`pnpm setup-dev:optional` from the [agents](https://github.com/inkeep/agents) monorepo), Nango is already configured and the API key is written to your `.env`. The steps below are for manual setup or troubleshooting. +> **Note:** If you used `pnpm setup-dev:optional`, Nango is already configured. The steps below are for manual setup or troubleshooting. -This guide covers how to configure the Inkeep Agents Framework to work with the self-hosted Nango instance. +This guide covers configuring the Inkeep Agents Framework to use the self-hosted Nango instance. ### 1) Start Nango @@ -27,18 +27,19 @@ docker compose up -d ### 2) Configure the framework to use Nango -Once Nango is running, configure the framework to connect to your local instance. +Once Nango is running, configure the framework to connect to it. -**Important:** Use real credentials from your Nango dashboard (no placeholders). The framework rejects `your_nango_secret_key`. +**Important:** Use real credentials from your Nango dashboard. The framework rejects placeholder values like `your_nango_secret_key`. #### Get your Nango API Key **Option A — Pre-set via environment variable (recommended):** -Generate a key and add it to your `.env` before starting Docker: +Generate a key and add it to `.env` before starting Docker: ```bash -nango_key=$(openssl rand -hex 16) && \ +_hex=$(openssl rand -hex 16) && \ + nango_key=$(echo "$_hex" | sed 's/^\(.\{8\}\)\(.\{4\}\).\(.\{3\}\).\(.\{3\}\)\(.\{12\}\)$/\1-\2-4\3-a\4-\5/') && \ echo "NANGO_SECRET_KEY_DEV=$nango_key" >> .env && \ echo "Nango secret key: $nango_key" ``` @@ -100,11 +101,8 @@ docker compose up -d nango-server **Reset Nango data:** ```bash -# Stop services -docker compose down - -# Remove Nango data (caution: this deletes all configurations and connections) -docker volume rm agents-optional-local-dev_nango-db +# Stop services and remove all data volumes (caution: deletes all configurations and connections) +docker compose down -v # Restart docker compose up -d diff --git a/scripts/setup.sh b/scripts/setup.sh index cf64fcc..9b24f46 100755 --- a/scripts/setup.sh +++ b/scripts/setup.sh @@ -189,7 +189,9 @@ cmd_setup() { set_env_var "$COMPANION_ENV" "NANGO_SECRET_KEY_DEV" "$EXISTING_NANGO_KEY" echo -e " ${GREEN}✓${NC} Re-using existing NANGO_SECRET_KEY" else - NANGO_KEY="$(openssl rand -hex 16)" + # Nango validates keys as UUID v4. Generate one portably (openssl + sed). + _hex="$(openssl rand -hex 16)" + NANGO_KEY="$(echo "$_hex" | sed 's/^\(.\{8\}\)\(.\{4\}\).\(.\{3\}\).\(.\{3\}\)\(.\{12\}\)$/\1-\2-4\3-a\4-\5/')" set_env_var "$COMPANION_ENV" "NANGO_SECRET_KEY_DEV" "$NANGO_KEY" set_env_var "$ENV_FILE" "NANGO_SECRET_KEY" "$NANGO_KEY" echo -e " ${GREEN}✓${NC} Generated NANGO_SECRET_KEY"