Started documentation using vuepress@v2

.github/workflows/docs.yml

@@ -0,0 +1,56 @@
+name: docs
+
+on:
+  # trigger deployment on every push to main branch
+  push:
+    branches: [main]
+  # trigger deployment manually
+  workflow_dispatch:
+
+jobs:
+  docs:
+    runs-on: ubuntu-latest
+
+    defaults:
+      run:
+        shell: bash
+        working-directory: ./docs
+
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          # fetch all commits to get last updated time or other git log info
+          fetch-depth: 0
+
+      - name: Setup pnpm
+        uses: pnpm/action-setup@v2
+        with:
+          # choose pnpm version to use
+          version: 8
+          # install deps with pnpm
+          run_install: true
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          # choose node.js version to use
+          node-version: 18
+          # cache deps for pnpm
+          cache: pnpm
+
+      # run build script
+      - name: Build VuePress site
+        run: pnpm docs:build
+
+      # please check out the docs of the workflow for more details
+      # @see https://github.com/crazy-max/ghaction-github-pages
+      - name: Deploy to GitHub Pages
+        uses: crazy-max/ghaction-github-pages@v4
+        with:
+          # deploy to gh-pages branch
+          target_branch: gh-pages
+          # deploy the default output dir of VuePress
+          build_dir: docs/content/.vuepress/dist
+        env:
+          # @see https://docs.github.com/en/actions/reference/authentication-in-a-workflow#about-the-github_token-secret
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

docs/.gitignore

@@ -0,0 +1,3 @@
+content/.vuepress/.temp
+content/.vuepress/.cache
+content/.vuepress/dist

docs/content/.vuepress/config.ts

@@ -10,14 +10,78 @@ export default defineUserConfig({
     docsBranch: "main",
     docsDir: "docs/content",
     editLinkPattern: ":repo/-/edit/:branch/:path",
+    sidebar: {
+      "/guides/": [
+        {
+          text: "Introduction",
+          link: "/intro.md",
+        },
+        {
+          text: "How Tos",
+          children: [
+            {
+              text: "Getting Started",
+              link: "/guides/getting-started.md",
+            },
+            {
+              text: "User and Role Management",
+              link: "/guides/user-role-management.md",
+            },
+            {
+              text: "CLI Reference",
+              link: "/guides/cli-reference.md",
+            },
+          ],
+        },
+        {
+          text: "Setup",
+          link: "/guides/README.md",
+          children: [
+            {
+              text: "WebAuthN",
+            },
+            {
+              text: "E-Mail",
+            },
+            {
+              text: "SMS (Twilio)",
+            },
+            {
+              text: "WebPush Notifications",
+            },
+            {
+              text: "OpenID Connect (OIDC)",
+            },
+            {
+              text: "Configuration File Reference",
+            },
+          ],
+        },
+        {
+          text: "Developer Docs",
+          children: [
+            {
+              text: "ConnectRPC APIs",
+              children: [
+                {
+                  text: "with Go",
+                },
+                {
+                  text: "with Javascript/Typescript",
+                },
+                {
+                  text: "with CURL",
+                },
+              ],
+            },
+          ],
+        },
+      ],
+    },
     navbar: [
       {
-        text: "Get Started",
-        link: "/guides/getting-started",
-      },
-      {
-        text: "Architecture",
-        link: "architecture",
+        text: "Guides",
+        link: "/guides/",
       },
       {
         text: "Report an issue",

docs/content/guides/README.md

@@ -1 +1,20 @@
 # Guides
+
+Welcome to our collection of `cisidm` guides.
+
+**Check the navigation bar on the left for an overview of available guides and references.**
+
+---
+
+:::warning Work-In-Progress
+The documentation of `cisidm` has just begun. A lot of pages, examples and guides are not yet available but might appear in the navigation bar because we're already planning which content is important for the first release of the docs.
+
+---
+
+If you feel comfortable with using `cisidm`, please consider contributing to either the source code, the documentation or both! :rocket:
+
+:::
+
+---
+
+If you still feel brave enough to test out cisidm or start contributing, checkout out our [**Getting Started Guide**](/guides/getting-started.md) which will walk you through a simple docker-compose based setup to secure your applications and services.

docs/content/guides/getting-started.md

@@ -313,14 +313,54 @@ The above service snippet configures Traefik as our reverse proxy. Let's go thro
   `--certificatesresolvers.resolver.acme.httpchallenge.entrypoint=http`  
   Configure a certificate resolver that uses ACME to request certificates from Let's Encrypt.
 
-## Start the project
+### Identity Management Server
+
+```yaml
+cisidm:
+  image: ghcr.io/tierklinik-dobersberg/cis-idm:latest
+  restart: unless-stopped
+  volumes:
+    - ./config/idm-config.yml:/etc/config.yml:ro
+  labels:
+    - "traefik.enable=true"
+    - "traefik.http.routers.idm.rule=Host(`account.example.com`)"
+    - "traefik.http.routers.idm.entrypoints=web"
+    - "traefik.http.routers.idm.tls=true"
+    - "traefik.http.routers.idm.tls.certresolver=resolver"
+    - "traefik.http.middlewares.auth.forwardauth.address=http://cisidm:8080/validate"
+    - "traefik.http.middlewares.auth.forwardauth.authResponseHeaders=X-Remote-User,X-Remote-User-ID,X-Remote-Mail,X-Remote-Mail-Verified,X-Remote-Avatar-URL,X-Remote-Role,X-Remote-User-Display-Name"
+  environment:
+    CONFIG_FILE: "/etc/config.yml"
+  depends_on:
+    - rqlite
+```
+
+This configures the `cisidm` docker container, mounts the configuration file to `/etc/config.yml` and tells traefik that is should be reachable at `account.example.com`.
+
+It also configures a new HTTP middleware `auth` that uses the forward-auth feature of traefik:
+
+- `traefik.http.middlewares.auth.forwardauth.address=http://cisidm:8080/validate`  
+  This configures the Forward-Auth middleware (named `auth` here) to forward any HTTP request to cisidm to determine if the user is actually allowed to access the requested resource. If cisidm replies with a HTTP success status code (2xx) than traefik will forward the original request to the actual service container. If cisidm replies with an error code, traefik will immediately return the response from `cisidm` to the user. This is used to redirect the user to the login page in case the request is unauthenticated.
+
+- `traefik.http.middlewares.auth.forwardauth.authResponseHeaders=....`  
+  When `cisidm` successfully authenticated a request, it will return a set of headers that contain information about the logged in user. With this setting, we tell traefik to forward those headers to the actual service container. This enables service containers to know which user performs the access without the need to parse and validate the JWT token issued by `cisidm` for every successful authentication.
+
+## First Start
 
 Finally it's time to start our services by calling the following command from the project directory (the one that contains the docker-compose file)
 
 ```
 docker-compose up -d
 ```
 
+:::tip Admin User
+Whenever `cisidm` starts, it checks if a user with super-user privileges (member of the `iam_superuser` role) exists. If not, a new registration token will be created and logged to stdout.
+
+To create your initial admin user, copy that token from the log output (`docker-compose logs cisidm | grep "superuser account"`) and visit `https://account.example.com/registration?token=YOUR_TOKEN` and replace `YOUR_TOKEN` with the token from the log output.
+
+It's also possible to use the cli tool for the registration: `idmctl register-user --registration-token YOUR-TOKEN your-username`.
+:::
+
 <br />
 
 ---
@@ -330,5 +370,5 @@ docker-compose up -d
 :::tip Congratulations
 You just finished setting up cisidm with a HTTPS enabled reverse proxy that will now protect your services using Proxy/Forward Authentication.
 
-Now it's time to check the [User and Role Administration Guide](./user-role-management.md).
+Now it's time to check the [User and Role Administration Guide](./user-role-management.md) or the [Command Line Reference](./cli-reference.md).
 :::

docs/content/guides/to-be-done.md

@@ -0,0 +1,9 @@
+# Sorry, documentation is work-in-progress
+
+:::warning Page Not Found
+The page you're looking for does not yet exist.
+
+---
+
+Please be patient and check again in a few days. If you want, consider contributing to the `cisidm` documentation.
+:::

docs/content/guides/user-role-management.md

@@ -0,0 +1,9 @@
+# User and Role Management
+
+`cisidm` implements the concept of users and roles where each user can be assigned to any number of roles. Note that roles per-se do not permit any special permissions. For simple authentication purposes, an administrator can use role definitions to configure forward-auth permissions. For a micro-service environment, developers may grant permissions based on user roles but `cisidm` itself does not implement RBAC (Role Based Access Control). For the time being, roles are a flat list instead of being hierarchical so it's not possible that a single role assignment automatically includes other roles. However, this might change in a future release.
+
+:::warning Note
+There is one special role in `cisidm` called the `iam_superuser` role. This role actually does imply a set of permissions: Any user with this role can perform any action on any API endpoint of cisidm and is thus considered an administrative account.
+
+It's **strongly advised** to only use a `iam_superuser` account for administrative tasks and multi factor authentication (TOTP or SMS/E-Mail codes) and use a separate user account for daily work/authentication.
+:::

docs/content/index.md

@@ -35,3 +35,18 @@ features:
   - title: Easy Deployment
     details: Easily deploy using docker.
 ---
+
+---
+
+:::warning Documentation is Work-in-Progress
+
+Please note that the documentation for `cisidm` is currently being built and cannot be considered complete!  
+There's a lot of missing information and setup-guides.
+
+<center>
+
+**Stay tuned** :rocket:
+
+</center>
+
+:::

docs/content/intro.md

@@ -0,0 +1,23 @@
+# Welcome to `cisidm`
+
+Welcome to `cisidm`, a simple Identity Management Service with Self-Service capabilities for custom application development or to secure self-hosted applications with support for Single-Sign-On (SSO) using Proxy/Forward Authentication or OpenID Connect (using DexIdP).
+
+## Features
+
+The following is a likely incomplete list of features currently implemented by `cisidm`:
+
+## Motivation
+
+## Use Cases
+
+### SSO Authentication
+
+### Custom Application / Service Development
+
+## Comparisons
+
+### Authelia
+
+### Kanidm
+
+### DexIdP