add contribution guide to documentation (#2318)

* add contribution guide to doucmentation

* fix EOF

contrib/local-environment/dex.yaml

@@ -1,7 +1,7 @@
 # This configuration is intended to be used with the docker-compose testing
 # environment.
 # This should configure Dex to run on port 4190 and provides a static login
-issuer: http://dex.localhost:4190/dex
+issuer: http://dex.localtest.me:4190/dex
 storage:
   type: etcd
   config:
@@ -19,7 +19,7 @@ staticClients:
 - id: oauth2-proxy
   redirectURIs:
   # These redirect URIs point to the `--redirect-url` for OAuth2 proxy.
-  - 'http://localhost:4180/oauth2/callback' # For basic proxy example.
+  - 'http://oauth2-proxy.localtest.me:4180/oauth2/callback' # For basic proxy example.
   - 'http://oauth2-proxy.oauth2-proxy.localhost/oauth2/callback' # For nginx and traefik example.
   name: 'OAuth2 Proxy'
   secret: b2F1dGgyLXByb3h5LWNsaWVudC1zZWNyZXQK

contrib/local-environment/docker-compose-keycloak.yaml

@@ -12,7 +12,6 @@
 # Access http://keycloak.localtest.me:9080 with the same credentials to check out the settings
 version: '3.0'
 services:
-
   oauth2-proxy:
     container_name: oauth2-proxy
     image: quay.io/oauth2-proxy/oauth2-proxy:v7.5.1
@@ -21,6 +20,8 @@ services:
     volumes:
       - "./oauth2-proxy-keycloak.cfg:/oauth2-proxy.cfg"
     restart: unless-stopped
+    ports:
+      - 4180:4180/tcp
     networks:
       keycloak: {}
       httpbin: {}
@@ -28,15 +29,17 @@ services:
     depends_on:
       - httpbin
       - keycloak
-    ports:
-      - 4180:4180/tcp
 
   httpbin:
     container_name: httpbin
     image: kennethreitz/httpbin:latest
     hostname: httpbin
+    ports:
+      - 8080:80/tcp
     networks:
-      httpbin: {}
+      httpbin:
+        aliases:
+          - httpbin.localtest.me
 
   keycloak:
     container_name: keycloak
@@ -50,19 +53,19 @@ services:
         '-Dkeycloak.migration.action=import',
         '-Dkeycloak.migration.provider=dir',
         '-Dkeycloak.migration.dir=/realm-config',
-        '-Dkeycloak.migration.strategy=IGNORE_EXISTING',
+        '-Dkeycloak.migration.strategy=IGNORE_EXISTING'
       ]
     volumes:
       - ./keycloak:/realm-config
     environment:
       KEYCLOAK_USER: admin@example.com
       KEYCLOAK_PASSWORD: password
+    ports:
+      - 9080:9080/tcp
     networks:
       keycloak:
         aliases:
           - keycloak.localtest.me
-    ports:
-      - 9080:9080/tcp
 
 networks:
   httpbin: {}

contrib/local-environment/docker-compose.yaml

@@ -8,19 +8,19 @@
 # Or:
 #    make <command> (eg. make up, make down)
 #
-# Access http://localhost:4180 to initiate a login cycle
+# Access http://oauth2-proxy.localtest.me:4180 to initiate a login cycle
 version: '3.0'
 services:
   oauth2-proxy:
     container_name: oauth2-proxy
     image: quay.io/oauth2-proxy/oauth2-proxy:v7.5.1
     command: --config /oauth2-proxy.cfg
-    ports:
-      - 4180:4180/tcp
     hostname: oauth2-proxy
     volumes:
       - "./oauth2-proxy.cfg:/oauth2-proxy.cfg"
     restart: unless-stopped
+    ports:
+      - 4180:4180/tcp
     networks:
       dex: {}
       httpbin: {}
@@ -31,16 +31,16 @@ services:
     container_name: dex
     image: ghcr.io/dexidp/dex:v2.30.3
     command: dex serve /dex.yaml
-    ports:
-      - 4190:4190/tcp
     hostname: dex
     volumes:
       - "./dex.yaml:/dex.yaml"
     restart: unless-stopped
+    ports:
+      - 4190:4190/tcp
     networks:
       dex:
         aliases:
-        - dex.localhost
+          - dex.localtest.me
       etcd: {}
     depends_on:
       - etcd
@@ -50,7 +50,9 @@ services:
     ports:
       - 8080:80/tcp
     networks:
-      httpbin: {}
+      httpbin:
+        aliases:
+          - httpbin.localtest.me
   etcd:
     container_name: etcd
     image: gcr.io/etcd-development/etcd:v3.4.7

contrib/local-environment/oauth2-proxy-keycloak.cfg

@@ -1,8 +1,8 @@
 http_address="0.0.0.0:4180"
 cookie_secret="OQINaROshtE9TcZkNAm-5Zs2Pv3xaWytBmc5W7sPX7w="
-email_domains=["example.com"]
+email_domains="example.com"
 cookie_secure="false"
-upstreams="http://httpbin"
+upstreams="http://httpbin.localtest.me:8080"
 cookie_domains=[".localtest.me"] # Required so cookie can be read on all subdomains.
 whitelist_domains=[".localtest.me"] # Required to allow redirection back to original requested target.
 
@@ -16,5 +16,3 @@ redirect_url="http://oauth2-proxy.localtest.me:4180/oauth2/callback"
 oidc_issuer_url="http://keycloak.localtest.me:9080/auth/realms/master"
 provider="oidc"
 provider_display_name="Keycloak"
-
-

contrib/local-environment/oauth2-proxy.cfg

@@ -1,11 +1,16 @@
 http_address="0.0.0.0:4180"
 cookie_secret="OQINaROshtE9TcZkNAm-5Zs2Pv3xaWytBmc5W7sPX7w="
-provider="oidc"
 email_domains="example.com"
-oidc_issuer_url="http://dex.localhost:4190/dex"
+cookie_secure="false"
+upstreams="http://httpbin.localtest.me:8080"
+cookie_domains=[".localtest.me"] # Required so cookie can be read on all subdomains.
+whitelist_domains=[".localtest.me"] # Required to allow redirection back to original requested target.
+
+# dex provider
 client_secret="b2F1dGgyLXByb3h5LWNsaWVudC1zZWNyZXQK"
 client_id="oauth2-proxy"
-cookie_secure="false"
+redirect_url="http://oauth2-proxy.localtest.me:4180/oauth2/callback"
 
-redirect_url="http://localhost:4180/oauth2/callback"
-upstreams="http://httpbin"
+oidc_issuer_url="http://dex.localtest.me:4190/dex"
+provider="oidc"
+provider_display_name="Dex"

docs/docs/community/contribution.md

@@ -0,0 +1,78 @@
+---
+id: contribution
+title: Contribution Guide
+---
+
+We track bugs and issues using Github.
+
+If you find a bug, please open an Issue. When opening an Issue or Pull Request please follow the preconfigured template and take special note of the checkboxes.
+
+If you want to fix a bug, add a new feature or extend existing functionality, please create a fork, create a feature branch and open a PR back to this repo.
+Please mention open bug issue number(s) within your PR if applicable.
+
+We suggest using [Visual Studio Code](https://code.visualstudio.com/docs/languages/go) with the official [Go for Visual Studio Code](https://marketplace.visualstudio.com/items?itemName=golang.go) extension.
+
+
+# Go version
+
+This project is currently still using go 1.19. You can follow the installation guide for go [here.](https://go.dev/doc/install) And you can find go version 1.19 in the archived section [here.](https://go.dev/dl/)
+
+# Preparing your fork
+Clone your fork, create a feature branch and update the depedencies to get started.
+```bash
+git clone git@github.com:<YOUR_FORK>/oauth2-proxy
+cd oauth2-proxy
+git branch feature/<BRANCH_NAME>
+git push --set-upstream origin feature/<BRANCH_NAME>
+go mod download
+```
+
+
+# Testing / Debugging
+For starting oauth2-proxy locally open the debugging tab and create the `launch.json` and select `Go: Launch Package`.
+
+![Debugging Tab](/img/debug-tab.png)
+```json
+{
+    "version": "0.2.0",
+    "configurations": [
+        {
+            "name": "Launch OAuth2-Proxy with Dex",
+            "type": "go",
+            "request": "launch",
+            "mode": "auto",
+            "program": "${workspaceFolder}",
+            "args": [
+                "--config",
+                // The following configuration contains settings for a locally deployed 
+                // upstream and dex as an idetity provider
+                "contrib/local-environment/oauth2-proxy.cfg"
+            ]
+        },
+        {
+            "name": "Launch OAuth2-Proxy with Keycloak",
+            "type": "go",
+            "request": "launch",
+            "mode": "auto",
+            "program": "${workspaceFolder}",
+            "args": [
+                "--config",
+                // The following configuration contains settings for a locally deployed 
+                // upstream and keycloak as an idetity provider
+                "contrib/local-environment/oauth2-proxy-keycloak.cfg"
+            ]
+        }
+    ]
+}
+```
+
+Before you can start your local version of oauth2-proxy, you will have to use the provided docker compose files to start a local upstream service and identity provider. We suggest using [httpbin](https://hub.docker.com/r/kennethreitz/httpbin) as your upstream for testing as it allows for request and response introspection of all things HTTP.
+
+Open a terminal and switch to the `contrib/local-environment` directory.
+
+- Dex as your IdP: `docker compose -f docker-compose.yaml up dex etcd httpbin`
+- Keycloak as your IdP: `docker compose -f docker-compose-keycloak.yaml up keycloak httpbin`
+
+The username for both is `admin@example.com` and password is `password`.
+
+Start oauth2-proxy from the debug tab and open http://oauth2-proxy.localtest.me:4180/ for testing.

docs/sidebars.js

@@ -67,7 +67,7 @@ module.exports = {
         id: 'community/security',
       },
       collapsed: false,
-      items: ['community/security'],
+      items: ['community/contribution', 'community/security'],
     },
   ],
 };

docs/src/pages/index.md

@@ -14,8 +14,8 @@ Versions v3.0.0 and up are from this fork and will have diverged from any change
 A list of changes can be seen in the [CHANGELOG](https://github.com/oauth2-proxy/oauth2-proxy/blob/master/CHANGELOG.md).
 :::
 
-![Sign In Page](../../static/img/sign-in-page.png)
+![Sign In Page](/img/sign-in-page.png)
 
 ## Architecture
 
-![OAuth2 Proxy Architecture](../../static/img/architecture.png)
+![OAuth2 Proxy Architecture](/img/architecture.png)

docs/versioned_docs/version-7.5.x/community/contribution.md

@@ -0,0 +1,78 @@
+---
+id: contribution
+title: Contribution Guide
+---
+
+We track bugs and issues using Github.
+
+If you find a bug, please open an Issue. When opening an Issue or Pull Request please follow the preconfigured template and take special note of the checkboxes.
+
+If you want to fix a bug, add a new feature or extend existing functionality, please create a fork, create a feature branch and open a PR back to this repo.
+Please mention open bug issue number(s) within your PR if applicable.
+
+We suggest using [Visual Studio Code](https://code.visualstudio.com/docs/languages/go) with the official [Go for Visual Studio Code](https://marketplace.visualstudio.com/items?itemName=golang.go) extension.
+
+
+# Go version
+
+This project is currently still using go 1.19. You can follow the installation guide for go [here.](https://go.dev/doc/install) And you can find go version 1.19 in the archived section [here.](https://go.dev/dl/)
+
+# Preparing your fork
+Clone your fork, create a feature branch and update the depedencies to get started.
+```bash
+git clone git@github.com:<YOUR_FORK>/oauth2-proxy
+cd oauth2-proxy
+git branch feature/<BRANCH_NAME>
+git push --set-upstream origin feature/<BRANCH_NAME>
+go mod download
+```
+
+
+# Testing / Debugging
+For starting oauth2-proxy locally open the debugging tab and create the `launch.json` and select `Go: Launch Package`.
+
+![Debugging Tab](/img/debug-tab.png)
+```json
+{
+    "version": "0.2.0",
+    "configurations": [
+        {
+            "name": "Launch OAuth2-Proxy with Dex",
+            "type": "go",
+            "request": "launch",
+            "mode": "auto",
+            "program": "${workspaceFolder}",
+            "args": [
+                "--config",
+                // The following configuration contains settings for a locally deployed 
+                // upstream and dex as an idetity provider
+                "contrib/local-environment/oauth2-proxy.cfg"
+            ]
+        },
+        {
+            "name": "Launch OAuth2-Proxy with Keycloak",
+            "type": "go",
+            "request": "launch",
+            "mode": "auto",
+            "program": "${workspaceFolder}",
+            "args": [
+                "--config",
+                // The following configuration contains settings for a locally deployed 
+                // upstream and keycloak as an idetity provider
+                "contrib/local-environment/oauth2-proxy-keycloak.cfg"
+            ]
+        }
+    ]
+}
+```
+
+Before you can start your local version of oauth2-proxy, you will have to use the provided docker compose files to start a local upstream service and identity provider. We suggest using [httpbin](https://hub.docker.com/r/kennethreitz/httpbin) as your upstream for testing as it allows for request and response introspection of all things HTTP.
+
+Open a terminal and switch to the `contrib/local-environment` directory.
+
+- Dex as your IdP: `docker compose -f docker-compose.yaml up dex etcd httpbin`
+- Keycloak as your IdP: `docker compose -f docker-compose-keycloak.yaml up keycloak httpbin`
+
+The username for both is `admin@example.com` and password is `password`.
+
+Start oauth2-proxy from the debug tab and open http://oauth2-proxy.localtest.me:4180/ for testing.

docs/versioned_sidebars/version-7.5.x-sidebars.json

@@ -33,6 +33,7 @@
       "label": "Community",
       "collapsed": false,
       "items": [
+        "community/contribution",
         "community/security"
       ]
     }