diff options
| -rw-r--r-- | share/man/DEVELOPMENT.md | 50 |
1 files changed, 37 insertions, 13 deletions
diff --git a/share/man/DEVELOPMENT.md b/share/man/DEVELOPMENT.md index 3e21bf7..f8a00bb 100644 --- a/share/man/DEVELOPMENT.md +++ b/share/man/DEVELOPMENT.md @@ -1,13 +1,18 @@ # Development -Sparkle uses [Envoy proxy](https://www.envoyproxy.io/) to redirect -unauthenticated requests to the GitLab Identity Provider and then retrieves an -`id_token`, `access_token` and `refresh_token` using an OpenID Connect workflow -to inject these tokens as cookies before forwarding the request to Sparkle. +Sparkle uses [Envoy Proxy](https://www.envoyproxy.io/) to manage authentication +via GitLab's Identity Provider (IdP). When a user makes a request without valid +authentication cookies, Envoy redirects the request to the IdP. It then completes +an OpenID Connect (OIDC) flow to obtain an `id_token`, `access_token`, and +`refresh_token`, sets them as cookies, and forwards the request to Sparkle. -This flow allows Sparkle to focus on application logic without needing to -directly manage session cookies, exchange a refresh token for a new access token -and directly access the `client_id` and `client_secret`. +This architecture enables Sparkle to focus solely on application logic, without needing to: + +* Handle session cookies manually, +* Exchange refresh tokens for new access tokens, or +* Access client credentials like `client_id` or `client_secret` directly. + +## Request Flow Overview ```plaintext +-------------+ +---------------+ +-----------------+ +-------+ @@ -37,14 +42,34 @@ and directly access the `client_id` and `client_secret`. |<--- Final Response --------| | | ``` -Configuration is injected into envoy and sparkle via environment variables. -Please see the [Envoy installation documentation](https://www.envoyproxy.io/docs/envoy/latest/start/install) -to install the appropriate version of Envoy on your operating system. The version -of envoy that you need to install can be found in the `Dockerfile` in the root -of this repository. +## Configuration + +Both Envoy and Sparkle are configured via environment variables. You can copy the +`.env` file to `.env.local` and fill in the required values: + +```bash +cp .env .env.local +``` + +The following environment variables must be defined: + +| Variable Name | Description | +| ---------------------- | ------------------------------------------------ | +| `APP_ENV` | Sparkle environment (default: `development`) | +| `BIND_ADDR` | Address Sparkle listens on (default: `:8080`) | +| `OAUTH_CLIENT_ID` | The client ID registered with GitLab IdP | +| `OAUTH_CLIENT_SECRET` | The corresponding client secret | +| `OAUTH_REDIRECT_URL` | Redirect URI configured in your GitLab OAuth app | +| `OIDC_ISSUER` | The issuer URL (e.g., `http://gdk.test:3000`) | + +You can refer to the `Dockerfile` in the root of this repository to determine the +exact version of Envoy required. To install Envoy locally, follow the [official +installation guide](https://www.envoyproxy.io/docs/envoy/latest/start/install). ## Usage +You can run Sparkle and Envoy either natively or in Docker: + * **Run Sparkle + Envoy on the host machine:** ```bash @@ -56,4 +81,3 @@ of this repository. ```bash $ make run-image ``` - |