1  # 🌊 Wave Service Setup
  2  
  3  The **Wave** service is a component of the Drips stack that handles GitHub integrations. To run it locally, you need to configure a GitHub App and provide its credentials to the service via environment variables.
  4  
  5  ## 📋 Prerequisites
  6  
  7  - Ensure you have followed the [Quick Start guide in DEVELOPMENT.md](./DEVELOPMENT.md) to set up the general development environment.
  8  - You will need a GitHub account to create a GitHub App.
  9  
 10  ## 🛠️ GitHub App Configuration
 11  
 12  To fully utilize the Wave service locally, you must create a GitHub App.
 13  
 14  1.  **Create a New GitHub App**:
 15      - Go to [GitHub Developer Settings > GitHub Apps](https://github.com/settings/apps).
 16      - Click **New GitHub App**.
 17  
 18  2.  **Basic Information**:
 19      - **GitHub App Name**: Choose a unique name (e.g., `drips-wave-local-<yourname>`).
 20      - **Homepage URL**: `http://localhost:5173` (or your local frontend URL).
 21      - **Callback URL**:
 22          - **Option A (Localhost)**: `http://localhost:8000/api/auth/oauth/github/callback`
 23          - **Option B (Static Tunnel)**: `https://<your-domain>/api/auth/oauth/github/callback`
 24          - *Note: This must match the `GITHUB_OAUTH_CALLBACK_URL` configured in `docker-compose.yml` (via `WAVE_PUBLIC_URL`).*
 25      - **Webhook URL**:
 26          - **Option A (Quick Tunnel - Random URL)**:
 27              - Leave `WAVE_PUBLIC_URL` empty in your `.env`.
 28              - The Wave service will automatically detect the random URL on startup.
 29              - Check logs for the URL: `docker compose logs wave | grep "Found Tunnel URL"`
 30              - Example: `https://<random>.trycloudflare.com/api/webhooks/github`
 31          - **Option B (Static URL)**:
 32              - Set `WAVE_PUBLIC_URL` in your `.env` (e.g. `https://my-tunnel.example.com`).
 33              - Use your configured domain: `https://<your-domain>/api/webhooks/github`
 34  
 35          - *Active*: Check this box.
 36  
 37  3.  **Permissions and Events**:
 38      - Configure the following permissions (adjust based on specific development needs, but these are standard for Drips integrations):
 39          - **Repository permissions**:
 40              - `Contents`: Read-only (to read `FUNDING.json` etc.)
 41              - `Metadata`: Read-only
 42              - `Pull requests`: Read & Write (if the bot needs to comment or merge)
 43              - `Issues`: Read & Write
 44          - **Organization permissions**:
 45              - `Members`: Read-only
 46          - **Account permissions**:
 47              - `Email addresses`: Read-only
 48      - Configure the following events:
 49          - `Installation target`
 50          - `Issues`
 51          - `Organization`
 52          - `Membership`
 53          - `Repository`
 54  
 55  4.  **Generate Client Secret**:
 56      - Scroll to the "Client secrets" section.
 57      - Click **Generate a new client secret**.
 58      - Copy this secret immediately (you won't see it again).
 59  
 60  5.  **Generate Private Key**:
 61      - (After saving the app, you will be prompted to generate a private key.)
 62      - Scroll down to "Private keys" and click **Generate a private key**.
 63      - This will download a `.pem` file. You will need the contents of this file.
 64  
 65  6.  **Install the App**:
 66      - Go to **Install App** in the sidebar.
 67      - Install the app on your personal account or a test organization.
 68  
 69  ## ⚙️ Environment Variables
 70  
 71  Once your GitHub App is created, you need to update your `.env` file (or set these variables in your shell) to match the `docker-compose.yml` requirements.
 72  
 73  Open your `.env` file (create one from `.env.template` if you haven't already) and add/update the following:
 74  
 75  ```bash
 76  # GitHub OAuth Configuration
 77  GITHUB_OAUTH_CLIENT_ID=your_client_id_here
 78  GITHUB_OAUTH_CLIENT_SECRET=your_client_secret_here
 79  
 80  # GitHub App Configuration
 81  GITHUB_APP_ID=your_app_id_here
 82  GITHUB_APP_PRIVATE_KEY="-----BEGIN RSA PRIVATE KEY-----\n...\n-----END RSA PRIVATE KEY-----"
 83  GITHUB_APP_BOT_USER_ID=your_bot_user_id_here
 84  GITHUB_WEBHOOK_SECRET=your_webhook_secret_here
 85  ```
 86  
 87  ### Where to find these values:
 88  
 89  -   **`GITHUB_OAUTH_CLIENT_ID`**: Found on your GitHub App's "General" settings page (Client ID).
 90  -   **`GITHUB_OAUTH_CLIENT_SECRET`**: Generate a new Client Secret on the "General" settings page.
 91  -   **`GITHUB_APP_ID`**: Found on the "General" settings page (App ID).
 92  -   **`GITHUB_APP_PRIVATE_KEY`**: The content of the `.pem` file you downloaded. **Important**: Ensure you preserve newlines or use `\n` if setting it as a single line string in some environments, though `.env` files usually handle multi-line strings if quoted properly.
 93  -   **`GITHUB_APP_BOT_USER_ID`**: The unique numeric ID for your GitHub App's bot user.
 94      1.  **Find your App Slug**: On your App's public page (e.g. `https://github.com/apps/my-app`), the slug is the last part of the URL (`my-app`).
 95      2.  **Query the API**: Run `curl https://api.github.com/users/<slug>[bot]`.
 96          - Note: If using `curl` in Z sh/Bash, you may need to escape brackets or use URL encoding: `https://api.github.com/users/<slug>%5Bbot%5D`
 97      3.  **Get the ID**: Use the integer `id` field from the JSON response.
 98  -   **`GITHUB_WEBHOOK_SECRET`**: The secret you set in the "Webhook URL" section (if you enabled webhooks). If you didn't set one, you can define any string here, but it must match what you configured in GitHub if webhooks are active.
 99  -   **`WAVE_PUBLIC_URL`**: (Optional) The public URL where your Wave service is accessible.
100      -   **If set** (e.g. `http://localhost:8000` or `https://my-dev.com`): The Cloudflare tunnel service will be **skipped** (it will log a message and wait in idle state), and the Wave service will use this URL as its base.
101      -   **If empty**: The Cloudflare tunnel service will start a **Quick Tunnel** (random URL). The `wave` service will automatically detect the generated URL by monitoring a shared volume where `cloudflared` writes its output.
102  
103  ### Postgres Wave
104  A dedicated database service `postgres-wave` will be automatically started alongside the `wave` service. It runs on port 54324 by default and uses the `wave_db` database. No manual configuration is required.
105  
106  ## 🚀 Running the Service
107  
108  The Wave service is now an **optional** component of the Docker Compose stack, managed via the `wave` profile.
109  
110  ### Option A: Auto-Detection (Default)
111  
112  When running `npm run dev:docker`, the script automatically detects if you have access to the `wave` Docker image.
113  - **Access confirmed**: The `wave` profile is enabled (added to your `COMPOSE_PROFILES`).
114  - **No access**: The `wave` profile is skipped.
115  
116  #### Not starting Wave server
117  
118  If you want to explicitly NOT start the Wave service (for example because you already have it running for development), you can explicitly set `PUBLIC_WAVE_API_URL` and `PUBLIC_INTERNAL_WAVE_API_URL` in your `.env` file. For example:
119  
120  ```
121  PUBLIC_WAVE_API_URL=http://localhost:8000
122  PUBLIC_INTERNAL_WAVE_API_URL=http://172.17.0.1:8000
123  ```
124  
125  Note that `PUBLIC_WAVE_API_URL` should be on `localhost` to ensure cookie scoping works, but at the same time `PUBLIC_INTERNAL_WAVE_API_URL` must be reachable from within the Docker network (hence using the host's Docker bridge IP `172.17.0.1` in this particular case, which may differ depending on your Docker setup).
126  
127  ### Option B: Manual Control
128  
129  You can manually control the profile if you are not using the startup script or wish to override behavior.
130  
131  **Enable via CLI:**
132  ```bash
133  docker compose --profile wave up
134  ```
135  
136  **Enable via Environment:**
137  Add `COMPOSE_PROFILES=wave` to your `.env` file. This is useful if you run `docker compose` commands directly.
138  
139  ### Checking Status
140  
141  You can check the logs to verify it started:
142  
143  ```bash
144  docker compose logs -f wave
145  ```
146  
147  ## 🌐 Webhook Integration (Cloudflared)
148  
149  ### Option 1: Localhost (No Tunnel)
150  If you don't need external webhooks (e.g. you're just clicking around the UI), you can skip the tunnel.
151  
152  1.  Set `WAVE_PUBLIC_URL=http://localhost:8000` in your `.env`.
153  2.  Start the stack: `npm run dev:docker`.
154  3.  The `cloudflared` service will log "Skipping Cloudflare Tunnel startup" and wait (it will not exit, but stays idle).
155  4.  The `wave` service will start immediately with `BASE_URL=http://localhost:8000`.
156  
157  ### Option 2: Quick Tunnel (Random URL)
158  The default setup uses a Cloudflare Quick Tunnel, which generates a random URL each time.
159  
160  1.  Leave `WAVE_PUBLIC_URL` empty in `.env`.
161  2.  Start the stack: `npm run dev:docker`.
162  3.  The `cloudflared` service will start and generate a random URL.
163  4.  The `wave` service will detect this URL immediately via `inotify` (watching the shared volume) and configure itself.
164  5.  Find your URL in the logs:
165      ```bash
166      docker compose logs cloudflared | grep "URL captured"
167      ```
168  6.  On GitHub, update the GitHub App Webhook URL with this new URL.
169  
170  ### Option 3: Static URL (Custom Tunnel / Deployment)
171  For a persistent URL (e.g., `https://my-drips-dev.example.com`), you can use your own tunneling solution (like ngrok, a manually managed Cloudflare Tunnel, or a VPS).
172  
173  1.  **Configure Environment**:
174      - Set `WAVE_PUBLIC_URL=<your-public-url>` in your `.env` file.
175  2.  **Restart**:
176      - `npm run dev:docker`.
177  3.  **Result**:
178      - The built-in Cloudflare service will be skipped.
179      - The Wave service will start with your specified URL.
180      - You must ensure traffic to that URL is routed to `localhost:8000`.