Update README.md and add demo and dev Docker Compose

alexandrebouthinon · Jan 9, 2021 · d1c3fa3 · d1c3fa3
1 parent c93bc6e
commit d1c3fa3
Show file tree

Hide file tree

Showing 4 changed files with 259 additions and 9 deletions.
diff --git a/.traefik.yml b/.traefik.yml
@@ -1,7 +1,7 @@
 displayName: Basic Auth powered by Kuzzle
 type: middleware
 import: github.com/alexandrebouthinon/traefik-kuzzle-auth
-summary: Traefik Basic Auth Plugin powered by Kuzzle
+summary: Traefik Basic Auth middleware powered by Kuzzle
 testData:
   customRealm: "Use a valid Kuzzle user to authenticate"
   kuzzle:
@@ -11,4 +11,5 @@ testData:
       login: /_login/local
       getCurrentUser: /_me # With Kuzzle v1 you must use '/users/_me'
     allowedUsers:
-      - admin
+      - admin
+      - developer
diff --git a/README.md b/README.md
@@ -17,14 +17,154 @@
     </a>
 </p>
 
-## What?
+<!-- TOC -->
+
+- [What?](#what)
+- [Why?](#why)
+- [How?](#how)
+  - [Prerequisites](#prerequisites)
+  - [Demo](#demo)
+  - [Installation](#installation)
+  - [Configuration](#configuration)
+- [Development](#development)
+- [Roadmap](#roadmap)
+- [What is Kuzzle?](#what-is-kuzzle)
+
+<!-- /TOC -->
+
+# What?
 This is a Traefik Basic Auth Plugin using Kuzzle as authentication provider.
 
-## Why?
+# Why?
+
+*One authentication system to rule them all* :sunglasses:
+
+Kuzzle offer a complex and fine-grained RBAC authentication system, why do not use it everywhere? 
+
+
+# How?
+> :warning: At this time, Traefik Plugin system is still an experimental feature use it with caution. You can freeze your Traefik version to increase stability if you want to use this plugin on a real world use case
+
+## Prerequisites
+
+* A valid [Traefik Pilot](https://pilot.traefik.io) token for your Traefik instance.
+* A running Kuzzle server in which one or more users are configured.
+
+
+## Demo
+You can found a demonstration Docker Compose file (`docker-compose.demo.yml`) in the repository root. 
+
+```shell
+TRAEFIK_PILOT_TOKEN="xxxx" docker-compose -f docker-compose.demo.yml up -d
+```
+This will launch:
+* A complete Kuzzle stack (Kuzzle, Elasticsearch and Redis containers)
+* A Traefik instance with dashboard and latest released plugin version enabled and only available using `admin` Kuzzle user
+* A `whoami` instance available using both `admin` and `developer` Kuzzle users
+
+Once all containers are started and healthy, you can use the [Kuzzle Admin Console](https://next-console.kuzzle.io) to create your users (`admin` and `developer`).
+
+## Installation
+Declare it in the Traefik configuration:
+
+**YAML**
+```yaml
+pilot:
+  token: "xxxx"
+experimental:
+  plugins:
+    traefik-kuzzle-auth:
+        moduleName: github.com/alexandrebouthinon/traefik-kuzzle-auth
+        version: v0.1.0
+```
+
+**TOML**
+```toml
+[pilot]
+  token = "xxxx"
+[experimental.plugins.fail2ban]
+    moduleName = "github.com/alexandrebouthinon/traefik-kuzzle-auth"
+    version = "v0.1.0"
+```
+
+**CLI**
+```shell
+--pilot.token=${TRAEFIK_PILOT_TOKEN}
+--experimental.plugins.traefik-kuzzle-auth.moduleName=github.com/alexandrebouthinon/traefik-kuzzle-auth
+--experimental.plugins.traefik-kuzzle-auth.version=v0.1.0
+```
+
+## Configuration
+
+**YAML**
+```yaml
+middlewares:
+  your-well-named-middleware:
+    plugin:
+      traefik-kuzzle-auth:
+        customRealm: "Use a valid Kuzzle user to authenticate" # optional
+        kuzzle:
+          url: "http://localhost:7512" # required
+          routes: # optional
+            ping: /_publicApi
+            login: /_login/local
+            getCurrentUser: /_me # With Kuzzle v1 you must use '/users/_me'
+          allowedUsers: # optional
+            - admin
+            - developer
+```
+
+**TOML**
+```toml
+[middlewares]
+  [middlewares.your-well-named-middleware]
+    [middlewares.your-well-named-middleware.plugin]
+      [middlewares.your-well-named-middleware.plugin.traefik-kuzzle-auth]
+        customRealm = "Use a valid Kuzzle user to authenticate" # optional
+        [middlewares.your-well-named-middleware.plugin.traefik-kuzzle-auth.kuzzle]
+          url = "http://localhost:7512" # required
+          [middlewares.your-well-named-middleware.plugin.traefik-kuzzle-auth.kuzzle.routes] # optional
+            ping = /_publicApi
+            login = /_login/local
+            getCurrentUser = /_me # With Kuzzle v1 you must use '/users/_me'
+          [middlewares.your-well-named-middleware.plugin.traefik-kuzzle-auth.kuzzle.allowedUsers] # optional
+            - admin
+            - developer
+```
+
+**Docker Compose Labels**
+```yaml
+labels:
+  - "traefik.http.middlewares.your-well-named-middleware.plugin.traefik-kuzzle-auth.customRealm=Use a valid Kuzzle user to authenticate" # optional
+  - "traefik.http.middlewares.your-well-named-middleware.plugin.traefik-kuzzle-auth.kuzzle.url=http://kuzzle:7512" # required
+  - "traefik.http.middlewares.your-well-named-middleware.plugin.traefik-kuzzle-auth.kuzzle.routes.ping=/_publicApi" # optional
+  - "traefik.http.middlewares.your-well-named-middleware.plugin.traefik-kuzzle-auth.kuzzle.routes.login=/_login/local" # optional
+  - "traefik.http.middlewares.your-well-named-middleware.plugin.traefik-kuzzle-auth.kuzzle.routes.getCurrentUser=/_me" # With Kuzzle v1 you must use '/users/_me' (optional)
+  - "traefik.http.middlewares.kuzzle-auth.plugin.traefik-kuzzle-auth.kuzzle.allowedUsers=admin,developer" # optional
+```
+
+# Development
+You can found a development Docker Compose file (`docker-compose.dev.yml`) in the repository root. 
+
+```shell
+TRAEFIK_PILOT_TOKEN="xxxx" docker-compose -f docker-compose.dev.yml up -d
+```
+This will launch:
+* A complete Kuzzle stack (Kuzzle, Elasticsearch and Redis containers)
+* A Traefik instance with dashboard and local plugin enabled and only available using `admin` Kuzzle user
+* A `whoami` instance available using both `admin` and `developer` Kuzzle users
+
+Once all containers are started and healthy, you can use the [Kuzzle Admin Console](https://next-console.kuzzle.io) to create your users (`admin` and `developer`).
+
+# Roadmap
+
+- [x] [Users](https://docs.kuzzle.io/core/2/guides/main-concepts/permissions/#users) greenlisting
+- [ ] [Profiles](https://docs.kuzzle.io/core/2/guides/main-concepts/permissions/#profiles) greenlisting
+- [ ] [Kuzzle API Key](https://docs.kuzzle.io/core/2/guides/advanced/api-keys/) authentication
 
-One authentication system to rule them all. Kuzzle offer a complex and fine-grained RBAC authentication system, why do not use it everywhere? 
+New ideas are welcome, feel free to fill out an issue and let's discuss it :wink:
 
-## What is Kuzzle?
+# What is Kuzzle?
 
 Kuzzle is a [generic backend](https://docs.kuzzle.io/core/2/guides/introduction/general-purpose-backend/) offering **the basic building blocks common to every application**.
 

diff --git a/docker-compose.demo.yml b/docker-compose.demo.yml
@@ -0,0 +1,99 @@
+version: "3.3"
+
+services:
+#------------------------------------------------------------------------------
+# Traefik proxy configured with plugin dev mode and Dashboard
+# NOTE: Only 'admin' user can access Traefik Dashboard
+#------------------------------------------------------------------------------
+  traefik:
+    image: "traefik:v2.3"
+    container_name: "traefik"
+    depends_on:
+      kuzzle:
+        condition: service_healthy
+    command:
+      - "--api.dashboard=true"
+      - "--api.insecure=true"
+      - "--providers.docker=true"
+      - "--providers.docker.exposedbydefault=false"
+      - "--entrypoints.web.address=:80"
+      - "--pilot.token=${TRAEFIK_PILOT_TOKEN}"
+      - "--experimental.plugins.traefik-kuzzle-auth.moduleName=github.com/alexandrebouthinon/traefik-kuzzle-auth"
+      - "--experimental.plugins.traefik-kuzzle-auth.version=v0.1.0"
+    labels:
+      - "traefik.enable=true"
+      - "traefik.http.routers.dashboard.entrypoints=web"
+      - "traefik.http.routers.dashboard.rule=Host(`traefik.localhost`)"
+      - "traefik.http.routers.dashboard.service=api@internal"
+      - "traefik.http.routers.dashboard.middlewares=kuzzle-auth"
+      - "traefik.http.middlewares.kuzzle-auth.plugin.traefik-kuzzle-auth.kuzzle.url=http://kuzzle:7512"
+      - "traefik.http.middlewares.kuzzle-auth.plugin.traefik-kuzzle-auth.kuzzle.allowedUsers=admin"
+    ports:
+      - "80:80"
+    volumes:
+      - "/var/run/docker.sock:/var/run/docker.sock:ro"
+      - "./:/plugins/go/src/github.com/alexandrebouthinon/traefik-kuzzle-auth"
+
+#------------------------------------------------------------------------------
+# Kuzzle server stack
+#------------------------------------------------------------------------------
+
+  kuzzle:
+    image: kuzzleio/kuzzle:2
+    ports:
+      - "7512:7512"
+      - "1883:1883"
+    cap_add:
+      - SYS_PTRACE
+    depends_on:
+      redis:
+        condition: service_healthy
+      elasticsearch:
+        condition: service_healthy
+    healthcheck:
+      test: ["CMD", "curl", "-f", "http://kuzzle:7512/_publicApi"]
+      timeout: 10s
+      interval: 10s
+      retries: 3
+    environment:
+      - kuzzle_services__storageEngine__client__node=http://elasticsearch:9200
+      - kuzzle_services__internalCache__node__host=redis
+      - kuzzle_services__memoryStorage__node__host=redis
+      - kuzzle_server__protocols__mqtt__enabled=true
+      - NODE_ENV=production
+
+  redis:
+    image: redis:5
+    healthcheck:
+      test: ["CMD", "redis-cli", "ping"]
+      interval: 1s
+      timeout: 3s
+      retries: 30
+
+  elasticsearch:
+    image: kuzzleio/elasticsearch:7.4.0
+    healthcheck:
+      test: ["CMD", "curl", "-f", "http://localhost:9200"]
+      interval: 2s
+      timeout: 2s
+      retries: 10
+    ulimits:
+      nofile: 65536
+
+#------------------------------------------------------------------------------
+# Secured application using plugin
+# NOTE: Users 'admin' and 'developer' can access this app
+#------------------------------------------------------------------------------
+
+  whoami:
+    image: "traefik/whoami"
+    container_name: "simple-service"
+    depends_on:
+      - traefik
+    labels:
+      - "traefik.enable=true"
+      - "traefik.http.routers.whoami.rule=Host(`whoami.localhost`)"
+      - "traefik.http.routers.whoami.entrypoints=web"
+      - "traefik.http.routers.whoami.middlewares=kuzzle-auth"
+      - "traefik.http.middlewares.kuzzle-auth.plugin.traefik-kuzzle-auth.kuzzle.url=http://kuzzle:7512"
+      - "traefik.http.middlewares.kuzzle-auth.plugin.traefik-kuzzle-auth.kuzzle.allowedUsers=admin,developer"
diff --git a/docker-compose.yml → docker-compose.dev.yml b/docker-compose.yml → docker-compose.dev.yml
@@ -2,7 +2,8 @@ version: "3.3"
 
 services:
 #------------------------------------------------------------------------------
-# Traefik proxy configured with plugin dev mode
+# Traefik proxy configured with plugin dev mode and Dashboard
+# NOTE: Only 'admin' user can access Traefik Dashboard
 #------------------------------------------------------------------------------
   traefik:
     image: "traefik:v2.3"
@@ -11,16 +12,24 @@ services:
       kuzzle:
         condition: service_healthy
     command:
+      - "--api.dashboard=true"
       - "--api.insecure=true"
       - "--providers.docker=true"
       - "--providers.docker.exposedbydefault=false"
       - "--entrypoints.web.address=:80"
       - "--pilot.token=${TRAEFIK_PILOT_TOKEN}"
       - "--experimental.devPlugin.goPath=/plugins/go"
       - "--experimental.devPlugin.moduleName=github.com/alexandrebouthinon/traefik-kuzzle-auth"
+    labels:
+      - "traefik.enable=true"
+      - "traefik.http.routers.dashboard.entrypoints=web"
+      - "traefik.http.routers.dashboard.rule=Host(`traefik.localhost`)"
+      - "traefik.http.routers.dashboard.service=api@internal"
+      - "traefik.http.routers.dashboard.middlewares=kuzzle-auth"
+      - "traefik.http.middlewares.kuzzle-auth.plugin.dev.kuzzle.url=http://kuzzle:7512"
+      - "traefik.http.middlewares.kuzzle-auth.plugin.dev.kuzzle.allowedUsers=admin"
     ports:
       - "80:80"
-      - "8080:8080"
     volumes:
       - "/var/run/docker.sock:/var/run/docker.sock:ro"
       - "./:/plugins/go/src/github.com/alexandrebouthinon/traefik-kuzzle-auth"
@@ -73,6 +82,7 @@ services:
 
 #------------------------------------------------------------------------------
 # Secured application using plugin
+# NOTE: Users 'admin' and 'developer' can access this app
 #------------------------------------------------------------------------------
 
   whoami:
@@ -86,4 +96,4 @@ services:
       - "traefik.http.routers.whoami.entrypoints=web"
       - "traefik.http.routers.whoami.middlewares=kuzzle-auth"
       - "traefik.http.middlewares.kuzzle-auth.plugin.dev.kuzzle.url=http://kuzzle:7512"
-      - "traefik.http.middlewares.kuzzle-auth.plugin.dev.kuzzle.allowedUsers=admin"
+      - "traefik.http.middlewares.kuzzle-auth.plugin.dev.kuzzle.allowedUsers=admin,developer"