Updates the Install Minder Server documentation (#3880)

* Updates the Install Minder Server documentation

Updated the docs for installation

Fixes #3835

* Resolves issue with invalid values in server-config

* Update docs/docs/run_minder_server/config_oauth.md

Co-authored-by: Evan Anderson <evan@stacklok.com>

* Update docs/docs/run_minder_server/config_provider.md

Co-authored-by: Evan Anderson <evan@stacklok.com>

* Update docs/docs/run_minder_server/config_provider.md

Co-authored-by: Evan Anderson <evan@stacklok.com>

* Update docs/docs/run_minder_server/config_webhook.md

Co-authored-by: Evan Anderson <evan@stacklok.com>

* Update docs/docs/run_minder_server/run_the_server.md

Co-authored-by: Evan Anderson <evan@stacklok.com>

* Update docs/docs/run_minder_server/run_the_server.md

Co-authored-by: Evan Anderson <evan@stacklok.com>

* Update docs/docs/run_minder_server/run_the_server.md

Co-authored-by: Evan Anderson <evan@stacklok.com>

* Update docs/docs/run_minder_server/run_the_server.md

Co-authored-by: Evan Anderson <evan@stacklok.com>

* Update docs/docs/run_minder_server/run_the_server.md

Co-authored-by: Evan Anderson <evan@stacklok.com>

---------

Co-authored-by: Evan Anderson <evan@stacklok.com>
Co-authored-by: Don Browne <dmjb@users.noreply.github.com>

config/server-config.yaml.example

@@ -68,16 +68,19 @@ webhook-config:
   webhook_secret: "your-password"
 # previous_webhook_secret_file: ./previous_secrets
 
-# OAuth2 Configuration (used during enrollment)
-# These values are to be set within the GitHub OAuth2 App page
-github:
-    client_id: "abcde....."
-    client_secret: "abcde....."
-    payload_secret: "your-password"
-    redirect_uri: "http://localhost:8080/api/v1/auth/callback/github"
-    # [*] for all events. It can also be a list such as [push,branch_protection_rule].
-    # Please check complete list on https://docs.github.com/en/webhooks-and-events/webhooks/webhook-events-and-payloads
-    events: ["*"]
+
+# See https://minder-docs.stacklok.dev/run_minder_server/config_oauth for more information on setting these values
+github-app:
+  client_id: "client-id"
+  client_secret: "client-secret"
+  redirect_uri: "http://localhost:8080/api/v1/auth/callback/github-app/app" # This needs to match the registered callback URL in the GitHub App
+
+provider:
+  github-app:
+    app_name: "app-name"
+    app_id: 1234
+    user_id: 1234
+    private_key: ".secrets/github-app.pem"
 
 events:
   driver: go-channel

docker-compose.yaml

@@ -13,7 +13,6 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-version: '3.2'
 services:
   minder:
     container_name: minder_server
@@ -65,6 +64,7 @@ services:
       - MINDER_PROVIDER_GITHUB_APP_PRIVATE_KEY=/app/.secrets/github-app.pem
       - MINDER_FLAGS_GO_FEATURE_FILE_PATH=/app/flags-config.yaml
       - MINDER_LOG_GITHUB_REQUESTS=1
+    working_dir: /app
     networks:
       - app_net
     depends_on:

docs/docs/developer_guide/get-hacking.md

@@ -5,93 +5,12 @@ sidebar_position: 1
 
 # Get Hacking
 
-## Prerequisites
-
-- [Go](https://golang.org/doc/install)
-- [Docker](https://docs.docker.com/get-docker/)
-- [Docker Compose](https://docs.docker.com/compose/install/)
-
-## Clone the repository
-
-```bash
-git clone git@github.com:stacklok/minder.git
-```
-
-## Build the application
-
-```bash
-make build
-```
-
-## Install tools
-
-You may bootstrap the whole development environment, which includes initializing the `config.yaml` and `server-config.yaml`
-files with:
-
-```bash
-make bootstrap
-```
-This also installs the required tools for running different make targets.
-
-Note that if you intend to run minder outside `docker compose`, you should
-change the Keycloak and OpenFGA URLs in `server-config.yaml` to refer to
-localhost instead of the `docker-compose.yaml` names. There are comments inside the
-config file which explain what needs to be changed.
-
-## Start dependencies
-
-Note that the application requires a database to be running. This can be achieved
-using docker compose:
-
-```bash
-services="postgres keycloak migrate openfga" make run-docker
-```
-
-## Set up a Keycloak user
-
-You have two options here: setting up a GitHub app (possibly the same one you
-use for Minder enrollment), or using username / password.
-
-### Username / password Keycloak user
-
-Assuming that you've run `make run-docker`, you can run:
-
-```bash
-make password-login
-```
-
-to create a `testuser` Keycloak user with the password `tester`.  (You can create more users either through the KeyCloak UI or by modifying the command in [./mk/identity.mk](https://github.com/stacklok/minder/blob/main/.mk/identity.mk).)  This is purely intended as a convenience method, and is fairly fragile.
-
-### GitHub App
-
-[Create an OAuth2 application for GitHub](../run_minder_server/config_oauth.md).
-Select `New OAuth App` and fill in the details.
-
-Create a new client secret for your OAuth2 client.
-
-Using the client ID and client secret you created above, enable GitHub login on Keycloak by running the following command:
-```bash
-make KC_GITHUB_CLIENT_ID=<client_id> KC_GITHUB_CLIENT_SECRET=<client_secret> github-login
-```
-
-## Run the application
-
-Then run the application
-
-```bash
-bin/minder-server serve
-```
-
-Or direct from source
-
-```bash
-go run cmd/server/main.go serve
-```
+## Run Minder
+Follow the steps in the [Installing a Development version](./../run_minder_server/run_the_server.md) guide.
 
 The application will be available on `https://localhost:8080` and gRPC on `https://localhost:8090`.
 
 ## Run the tests
-
 ```bash
 make test
 ```

docs/docs/run_minder_server/config_oauth.md

@@ -1,99 +1,17 @@
 ---
-title: Configure GitHub Provider
-sidebar_position: 20
+title: Create a GitHub OAuth Application 
+sidebar_position: 120
 ---
 
-# Getting Started (Configuring a GitHub Provider)
-
-Minder currently only supports GitHub as a provider. Later versions will support other providers.
-
-Minder can either use GitHub OAuth2 application or GitHub App for authentication. This means that you will need to 
-configure a GitHub OAuth 2.0 application or a GitHub App, to allow enrollment of users into Minder.
 
 ## Prerequisites
 
 - [GitHub](https://github.com) account
 
-## Create a GitHub App (option 1)
-
-This approach allows users fine-grained control over the permissions that Minder has in their repositories. It also 
-allows users to limit the repositories that Minder can access.
-
-### Configure the GitHub App
-
-1. Navigate to [GitHub Developer Settings](https://github.com/settings/profile)
-1. Select "Developer Settings" from the left hand menu
-1. Select "GitHub Apps" from the left hand menu
-1. Select "New GitHub App"
-1. Enter the following details:
-   - GitHub App Name: `My Minder App` (or any other name you like)
-   - Homepage URL: `http://localhost:8080`
-   - Callback URL: `http://localhost:8080/api/v1/auth/callback/github-app/app`
-   - Select the checkbox for "Request user authorization (OAuth) during installation"
-1. Select the following permissions:
-   - Repository Permissions:
-     - Administration (read and write)
-     - Contents (read and write)
-     - Metadata (read only)
-     - Packages (read and write)
-     - Pull requests (read and write)
-     - Repository security advisories (read and write)
-     - Webhooks (read and write), Workflows (read and write)
-   -  Organization Permissions:
-     - Members (read only)
-1. (optional) For the option "Where can this GitHub App be installed?", select "Any account" if you want to allow any GitHub user to install the app. Otherwise, select "Only on this account" to restrict the app to only your account.
-1. Select "Create GitHub App"
-1. Generate a client secret
-1. Generate a private key 
-
-### Set up `server-config.yaml`
-
-The next step sets up Minder with the GitHub App you just created.
-
-In your `server-config.yaml` file add the following section:
-```yaml
-github-app:
-  client_id: <client-id>
-  client_secret: <client-secret>
-  redirect_uri: "http://localhost:8080/api/v1/auth/callback/github-app/app" # This needs to match the registered callback URL in the GitHub App
-```
-Replace `<client-id>` and `<client-secret>` with the client ID and secret of your GitHub App.
-
-Then, add the following section to your `server-config.yaml` file:
-
-```yaml
-provider:
-  github-app:
-    app_name: <app-name>
-    app_id: <app-id>
-    user_id: <user-id>
-    private_key: ".secrets/github-app.pem"
-```
-
-Replace `<app-name>` with the name of your app, which you can get by looking at the GitHub URL when editing your GitHub App. For example, if the URL is `https://github.com/settings/apps/my-test-app`, then your app name is `my-test-app`.
-Replace `<app-id>` with the app ID of your GitHub App, which is found in the General -> About section of your GitHub App on GitHub.
-Replace `<user-id>` with the result of running this command `curl https://api.github.com/users/<app-name>%5Bbot%5D | jq ".id"`, where `<app-name>` is the App name you used above.
-
-Finally, ensure the private key is stored in the `.secrets` directory in the root of the Minder repository.
-
-### Set up a fallback token for listing artifacts
-When using a GitHub App installation token, GitHub does not allow listing artifacts. To work around this, you can create a personal access token, with the scopes `public_repo` and `read:packages` and add it to the `server-config.yaml` file:
-
-```yaml
-provider:
-  github-app:
-    fallback_token: <personal-access-token>
-```
-This token will be used to list artifacts in repositories.
-
-### (optional) Configure the webhook
-If you'd like Minder to automatically remove a provider when the GitHub App is uninstalled, you can configure a webhook in the GitHub App settings. The webhook can be configured to send events to `<your-domain>/api/v1/ghapp/`, where `<your-domain>` is the domain where Minder is running.
-
-Note that if you're running Minder locally, you can use a service like [ngrok](https://ngrok.com/) to expose your local server to the internet.
+## Steps
 
-## Create a GitHub OAuth Application (option 2)
 
-Alternatively, you can use a GitHub OAuth application to allow users to enroll into Minder. There is no need to creat both a GitHub App and a GitHub OAuth application.
+A legacy method for allowing users to enroll into Minder is using a GitHub OAuth application.
 
 1. Navigate to [GitHub Developer Settings](https://github.com/settings/profile)
 2. Select "Developer Settings" from the left hand menu

docs/docs/run_minder_server/config_provider.md

@@ -0,0 +1,139 @@
+---
+title: Configure a Provider
+sidebar_position: 20
+---
+
+# Configuring a Provider
+A provider connects Minder to your software supply chain — giving Minder information about your source code repositories, and their pull requests, dependencies, and artifacts.
+
+The currently supported providers are:
+- GitHub   
+
+For GitHub, you configure a Provider by creating a GitHub App. 
+
+## Prerequisites
+
+- [GitHub](https://github.com) account
+
+## Create a GitHub App
+This approach allows fine-grained control over the permissions that Minder has in users' repositories.  It also 
+allows users to limit the repositories that Minder can access.
+
+1. Navigate to [GitHub Developer Settings](https://github.com/settings/profile)
+1. Select "Developer Settings" from the left hand menu
+1. Select "GitHub Apps" from the left hand menu
+1. Select "New GitHub App"
+
+![Adding a new GitHub App](./images/new-github-app.png)
+
+### Basic Information
+Complete the following fields:
+   - GitHub App Name: `My Minder App` (or any other name you like)
+   - Homepage URL: `http://localhost:8080`
+
+![Basic fields](./images/provider-basic.png)
+
+### Identifying and authorizing users
+Complete the following fields:
+   - Callback URL: `http://localhost:8080/api/v1/auth/callback/github-app/app`
+   - Add an additional Callback URL for Keycloak: `http://localhost:8081/realms/stacklok/broker/github/endpoint`
+   - Select the checkbox for "Request user authorization (OAuth) during installation"
+![Configuring the GitHub Provider](./images/provider-ident-and-auth.png)
+
+### Webhook
+- Under Webhook, uncheck Active
+
+### Permissions
+Select the following permissions:
+   - Repository Permissions:
+     - Administration (read and write)
+     - Contents (read and write)
+     - Metadata (read only)
+     - Packages (read and write)
+     - Pull requests (read and write)
+     - Repository security advisories (read and write)
+     - Webhooks (read and write)
+     - Workflows (read and write)
+   -  Organization Permissions:
+      - Members (read only)
+   - Account permissions:
+      - Email Addresses (read only)
+
+Once completed, double check your selected numbers match the ones in the screenshot.
+![Permissions](./images/provider-permissions.png)
+
+### Installation and Scope
+For the option "Where can this GitHub App be installed?":
+- Select "Any account" if you want to allow any GitHub user to install the app
+- Or, select "Only on this account" to restrict the app to only your account.
+
+Then select "Create GitHub App" to create the App.
+
+![Permissions](./images/provider-create.png)
+
+### Generate a client secret
+You should now have a GitHub App created. You now need to create a `Client secret` for authentication.
+Click the `Generate a new client secret button`.
+
+![Client secret](./images/provider-client-secret-created.png)
+
+Save the Client secret value for use in the Configure Minder step. 
+
+### Generate a private key 
+Scroll down to the bottom of the page and generate a private key.
+![Generate a private key](./images/provider-generate-private.png)
+
+This will generate and download your private key.
+Now we need to move and rename the private key.
+Run the following commands from the Minder root directory, replacing `<downloaded-file>` with the path to the downloaded private key.
+```bash
+mkdir .secrets
+cp <downloaded-file> .secrets/github-app.pem
+```
+
+## Configure the Minder server
+Now that we've created our GitHub App, we need to configure the Minder server to use it.
+
+
+### Add GitHub App configuration
+
+In your `server-config.yaml` file, located in the root Minder directory, find the following section:
+```yaml
+github-app:
+  client_id: "client-id"
+  client_secret: "client-secret"
+  redirect_uri: "http://localhost:8080/api/v1/auth/callback/github-app/app" # This needs to match the registered callback URL in the GitHub App
+```
+Update the `client_id` and `client_secret` values with the following:
+- Client ID : Found in the General -> About section of your GitHub App on GitHub.
+![Client ID](./images/provider-client-id.png)
+- Client Secret : The value you saved previously. 
+
+### Add Provider configuration
+Then, find the following section in the same `server-config.yaml` file:
+
+```yaml
+provider:
+  github-app:
+    app_name: "app-name"
+    app_id: 1234
+    user_id: 1234
+    private_key: ".secrets/github-app.pem"
+```
+Update the `app_name` with the name of your app, which you can get by looking at the GitHub URL when editing your GitHub App. For example, if the URL is https://github.com/settings/apps/my-test-app, then your app name is my-test-app.
+![App name](./images/provider-app-name.png)
+
+Update `app_id` with the app ID of your GitHub App, which is found in the General -> About section of your GitHub App on GitHub.
+![App ID](./images/provider-app-id.png)
+
+Finally, you need the `user_id` value. To get the value, run the following command, where `<app-name>` is the App name you used above:
+
+```bash
+curl https://api.github.com/users/<app-name>%5Bbot%5D
+```
+Update the `user_id` value with the `id` value returned from that command. 
+![User ID](./images/provider-user-id.png)
+
+Now save the file. Your Provider is now created and the Minder server is configured to use it.
+
+