Merge pull request #4 from shield-auth/develop

installation updated

content/architectural-resource/create-api-user.mdx

@@ -6,11 +6,11 @@ description: This is the create API user flow chart
 import { LightImage, DarkImage } from "@/components/image-switcher";
 
 <LightImage
-  src="/img/flow-charts/3-create-admin-user-transparent-light.png"
+  src="/img/flow-charts/4-create-admin-user-transparent-light.png"
   alt="Create API User Flow Chart"
 />
 
 <DarkImage
-  src="/img/flow-charts/3-create-admin-user-transparent.png"
+  src="/img/flow-charts/4-create-admin-user-transparent.png"
   alt="Create API User Flow Chart"
 />

content/architectural-resource/index.mdx

@@ -15,10 +15,6 @@ import { Step, Steps } from "fumadocs-ui/components/steps";
     On startup of the Shield server, the resource initialization process is
     triggered.
   </Card>
-  <Card title="Admin Login" href="/architectural-resource/admin-login">
-    Once the will reach healthy state then Admin Login api can be used for
-    creation of the API Key.
-  </Card>
   <Card title="Create API User" href="/architectural-resource/create-api-user">
     For any client related operations Like login, logout, password reset, etc.
     the API user is required. There can be more than one API user for a client
@@ -27,8 +23,9 @@ import { Step, Steps } from "fumadocs-ui/components/steps";
   <Card title="Signup user" href="/architectural-resource/signup-user">
     An API user can create or register a new user to its own client.
   </Card>
-  <Card title="Non Admin Login" href="/architectural-resource/non-admin-login">
-    Regular (Non Admin) user can login to the client at this API endpoint.
+  <Card title="Login" href="/architectural-resource/admin-login">
+    Once the will reach healthy state then Admin Login api can be used for
+    creation of the API Key.
   </Card>
   <Card title="Refresh Token" href="/architectural-resource/refresh-token">
     Refresh token is used to refresh the session and generate a new set of token

content/architectural-resource/login.mdx

@@ -0,0 +1,28 @@
+---
+title: Admin Login
+description: This is the admin login flow chart
+---
+
+import { LightImage, DarkImage } from "@/components/image-switcher";
+
+<LightImage
+  src="/img/flow-charts/2-login-transparent-light.png"
+  alt="Admin Login Flow Chart"
+/>
+
+<DarkImage
+  src="/img/flow-charts/2-login-transparent.png"
+  alt="Admin Login Flow Chart"
+/>
+
+## Session Creation Flow
+
+<LightImage
+  src="/img/flow-charts/3-session-creation-transparent-light.png"
+  alt="Admin Login Flow Chart"
+/>
+
+<DarkImage
+  src="/img/flow-charts/3-session-creation-transparent.png"
+  alt="Admin Login Flow Chart"
+/>

content/architectural-resource/meta.json

@@ -4,10 +4,9 @@
   "icon": "Construction",
   "pages": [
     "resource-initialization",
-    "admin-login",
     "create-api-user",
     "signup-user",
-    "non-admin-login",
+    "login",
     "refresh-token",
     "introspection"
   ]

content/architectural-resource/signup-user.mdx

@@ -6,11 +6,11 @@ description: This is the signup user flow chart
 import { LightImage, DarkImage } from "@/components/image-switcher";
 
 <LightImage
-  src="/img/flow-charts/4-signup-user-transparent-light.png"
+  src="/img/flow-charts/5-signup-user-transparent-light.png"
   alt="Signup User Flow Chart"
 />
 
 <DarkImage
-  src="/img/flow-charts/4-signup-user-transparent.png"
+  src="/img/flow-charts/5-signup-user-transparent.png"
   alt="Signup User Flow Chart"
 />

content/getting-started/installation.mdx

@@ -3,6 +3,8 @@ title: Installation
 description: We have a docker images for amd64 and arm64.
 ---
 
+import { Accordion, Accordions } from "fumadocs-ui/components/accordion";
+
 <Callout>
 
 You can find the docker image on [docker hub](https://hub.docker.com/r/shieldauth/shield)
@@ -16,35 +18,250 @@ Before you begin, ensure you have the following installed:
 - [Docker](https://docs.docker.com/get-docker/)
 - [Docker Compose](https://docs.docker.com/compose/install/)
 
-### 1. Clone the repository
+Here are three different ways to deploy Shield Auth, ranging from development to
+production setups:
 
-#### Using HTTPS
+## 1. Run from Source Code 👨‍💻
 
-```bash
+Best for development and customization. Build Shield from source code with full
+control over the build process.
+
+<Accordions>
+<Accordion title="Detailed building steps" id="build-from-source">
+
+### I. Clone the repository
+
+```bash title="terminal"
 git clone https://github.com/shield-auth/shield.git
 cd shield
 ```
 
-### 2. Set Up Environment Variables
+### II. Set Up Environment Variables
 
-```bash
+```bash title="terminal"
 cp .env.example .env
 ```
 
-### 3. Build and Start the Containers
+### III. Build and Start the Containers
 
-```bash
+```bash title="terminal"
 docker compose up -d --build --wait
 ```
 
-### 4. Retrieve Default credentials
+### IV. Retrieve Default credentials
+
+The default credentials are saved in `/usr/local/bin/logs/default_cred.json`.
+To view them:
+
+```bash title="terminal"
+docker exec shield cat /usr/local/bin/logs/default_cred.json
+```
+
+_Note: If the above command doesn't work, use `docker ps` to find the correct
+container ID for the shield container._
+
+</Accordion>
+</Accordions>
+
+## 2. Run with Containerized Database 🐳
+
+Best for single-server deployments and testing. Complete self-contained setup
+with both Shield and PostgreSQL.
+
+<Accordions>
+<Accordion title="Detailed running steps" id="run-from-docker-image">
+
+### I. Setup the environment Variables
+
+```bash title=".env"
+# Shield Service Settings
+SHIELD_VERSION=latest
+EXTERNAL_PORT=5555      # Shield external port
+PORT=5555               # Shield internal port
+RUN_MODE=production     # development or production
+
+# Database Settings
+POSTGRES_VERSION=17
+POSTGRES_USER=postgres
+POSTGRES_PASSWORD=1234
+POSTGRES_PORT=5432
+DB_EXTERNAL_PORT=5435   # External database port
+DATABASE_NAME=shield
+
+# The DATABASE_URL will be constructed from the above settings
+# Format: postgres://${POSTGRES_USER}:${POSTGRES_PASSWORD}@db:${POSTGRES_PORT}
+```
+
+### II. Pull the image and start the services
+
+```yaml title="docker-compose.yml"
+version: "3.8"
+
+services:
+  shield:
+    image: shieldauth/shield:${SHIELD_VERSION:-latest}
+    container_name: shield
+    restart: unless-stopped
+    ports:
+      - "${EXTERNAL_PORT:-5555}:${PORT:-5555}" # External:Internal port mapping
+    depends_on:
+      db:
+        condition: service_healthy
+    environment:
+      - DATABASE_URL=postgres://${POSTGRES_USER:-postgres}:${POSTGRES_PASSWORD:-1234}@db:${POSTGRES_PORT:-5432}
+      - DATABASE_NAME=${DATABASE_NAME:-shield}
+      - RUN_MODE=${RUN_MODE:-production}
+      - PORT=${PORT:-5555}
+    healthcheck:
+      test:
+        ["CMD-SHELL", "curl -f http://localhost:${PORT:-5555}/health || exit 1"]
+      interval: 30s
+      timeout: 10s
+      retries: 3
+      start_period: 40s
+    networks:
+      - shield-network
+    logging:
+      driver: "json-file"
+      options:
+        max-size: "10m"
+        max-file: "3"
+
+  db:
+    image: postgres:${POSTGRES_VERSION:-17}
+    container_name: shield-db
+    restart: unless-stopped
+    volumes:
+      - postgres_data:/var/lib/postgresql/data
+    environment:
+      - POSTGRES_USER=${POSTGRES_USER:-postgres}
+      - POSTGRES_PASSWORD=${POSTGRES_PASSWORD:-1234}
+      - POSTGRES_DB=${DATABASE_NAME:-shield}
+    ports:
+      - "${DB_EXTERNAL_PORT:-5435}:${POSTGRES_PORT:-5432}"
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U ${POSTGRES_USER:-postgres}"]
+      interval: 5s
+      timeout: 5s
+      retries: 5
+    networks:
+      - shield-network
+    logging:
+      driver: "json-file"
+      options:
+        max-size: "10m"
+        max-file: "3"
+
+networks:
+  shield-network:
+    name: shield-${RUN_MODE:-production}
+
+volumes:
+  postgres_data:
+    name: shield-postgres-${RUN_MODE:-production}
+```
+
+```bash
+docker compose up -d
+```
+
+### III. Retrieve Default credentials
+
+The default credentials are saved in `/usr/local/bin/logs/default_cred.json`.
+To view them:
+
+```bash
+docker exec shield cat /usr/local/bin/logs/default_cred.json
+```
+
+_Note: If the above command doesn't work, use `docker ps` to find the correct
+container ID for the shield container._
+
+</Accordion>
+</Accordions>
+
+## 3. Run with External Database 📡
+
+Best for production deployments. Use this when connecting to an existing
+database or managed database service.
+
+<Accordions>
+<Accordion title="Detailed running steps" id="run-with-external-database">
+
+### I. Setup the environment Variables
+
+```bash title=".env"
+# Required Settings
+DATABASE_URL=postgres://user:password@host:5432
+DATABASE_NAME=shield
+
+# Optional Settings with defaults
+SHIELD_VERSION=latest
+EXTERNAL_PORT=8080     # Port exposed to the outside world
+PORT=5555              # Port used inside the container
+RUN_MODE=production    # development or production
+```
+
+### II. Pull the image and start the services
+
+```yaml title="docker-compose.yml"
+version: "3.8"
+
+services:
+  shield:
+    image: shieldauth/shield:${SHIELD_VERSION:-latest}
+    container_name: shield
+    restart: unless-stopped
+    ports:
+      - "${EXTERNAL_PORT:-5555}:${PORT:-5555}" # External:Internal port mapping
+    environment:
+      - DATABASE_URL=${DATABASE_URL:?DATABASE_URL is required}
+      - DATABASE_NAME=${DATABASE_NAME:?DATABASE_NAME is required}
+      - RUN_MODE=${RUN_MODE:-production}
+      - PORT=${PORT:-5555} # Use PORT for application configuration
+    healthcheck:
+      test:
+        ["CMD-SHELL", "curl -f http://localhost:${PORT:-5555}/health || exit 1"]
+      interval: 30s
+      timeout: 10s
+      retries: 3
+      start_period: 40s
+    networks:
+      - shield-network
+    logging:
+      driver: "json-file"
+      options:
+        max-size: "10m"
+        max-file: "3"
 
-The default credentials are saved in `/usr/local/bin/logs/default_cred.json.
+networks:
+  shield-network:
+    name: shield-${RUN_MODE:-production}
+```
+
+### III. Retrieve Default credentials
+
+The default credentials are saved in `/usr/local/bin/logs/default_cred.json`.
 To view them:
 
 ```bash
-docker exec shield-shield-1 cat /usr/local/bin/logs/default_cred.json
+docker exec shield cat /usr/local/bin/logs/default_cred.json
 ```
 
 _Note: If the above command doesn't work, use `docker ps` to find the correct
 container ID for the shield container._
+
+</Accordion>
+</Accordions>
+
+🔄 Deployment Strategy
+Choose your deployment option based on your needs:
+
+Development: Use **"Run from Source Code"** for full development capabilities <br />
+Testing/Staging: Use **"Run with Containerized Database"** for a complete isolated
+environment <br />
+Production: Use **"Run with External Database"** for better scalability and management
+
+Each option includes proper logging, health checks, and container management
+configurations. Refer to the full documentation for detailed configuration
+options and best practices.