Merge pull request #27 from strapi-community/init/docs

.github/workflows/deploy-docs.yml

@@ -0,0 +1,53 @@
+name: Deploy Docs to GitHub Pages
+
+on:
+  push:
+    branches:
+      - main
+
+defaults:
+  run:
+    working-directory: docs
+
+jobs:
+  build:
+    name: Build Docusaurus
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: yarn
+
+      - name: Install dependencies
+        run: yarn install --frozen-lockfile
+      - name: Build website
+        run: yarn build
+
+      - name: Upload Build Artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: build
+
+  deploy:
+    name: Deploy to GitHub Pages
+    needs: build
+
+    # Grant GITHUB_TOKEN the permissions required to make a Pages deployment
+    permissions:
+      pages: write # to deploy to Pages
+      id-token: write # to verify the deployment originates from an appropriate source
+
+    # Deploy to the github-pages environment
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+
+    runs-on: ubuntu-latest
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

.github/workflows/test-deploy-docs.yml

@@ -0,0 +1,28 @@
+name: Test Deploy Docs to GitHub Pages
+
+on:
+  pull_request:
+    branches:
+      - main
+
+defaults:
+  run:
+    working-directory: docs
+
+jobs:
+  test-deploy:
+    name: Test deployment
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: yarn
+
+      - name: Install dependencies
+        run: yarn install --frozen-lockfile
+      - name: Test build website
+        run: yarn build

.markdownlint.json

@@ -0,0 +1,5 @@
+{
+  "default": true,
+  "MD033": false,
+  "MD013": false
+}

docs/.gitignore

@@ -0,0 +1,20 @@
+# Dependencies
+/node_modules
+
+# Production
+/build
+
+# Generated files
+.docusaurus
+.cache-loader
+
+# Misc
+.DS_Store
+.env.local
+.env.development.local
+.env.test.local
+.env.production.local
+
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*

docs/README.md

@@ -0,0 +1,41 @@
+# Website
+
+This website is built using [Docusaurus](https://docusaurus.io/), a modern static website generator.
+
+### Installation
+
+```
+$ yarn
+```
+
+### Local Development
+
+```
+$ yarn start
+```
+
+This command starts a local development server and opens up a browser window. Most changes are reflected live without having to restart the server.
+
+### Build
+
+```
+$ yarn build
+```
+
+This command generates static content into the `build` directory and can be served using any static contents hosting service.
+
+### Deployment
+
+Using SSH:
+
+```
+$ USE_SSH=true yarn deploy
+```
+
+Not using SSH:
+
+```
+$ GIT_USER=<Your GitHub username> yarn deploy
+```
+
+If you are using GitHub pages for hosting, this command is a convenient way to build the website and push to the `gh-pages` branch.

docs/babel.config.js

@@ -0,0 +1,3 @@
+module.exports = {
+  presets: [require.resolve('@docusaurus/core/lib/babel/preset')],
+};

docs/docs/api/client.md

@@ -0,0 +1,11 @@
+---
+sidebar_label: 'Client'
+slug: '/api/client'
+---
+
+# API Client
+
+Accessed with: `strapi.redis.connections.default.client`
+*Note you can swap the default key with any other named database you have configured*
+
+From here you have full access to the [ioredis API](https://github.com/luin/ioredis/blob/master/API.md).

docs/docs/api/config.md

@@ -0,0 +1,10 @@
+---
+sidebar_label: 'Config'
+slug: '/api/config'
+---
+
+# API Config
+
+Access with: `strapi.redis.config`
+
+The config key contains the entire plugin config including all ioredis instances configurations. These should not be modified after bootstrapping your Strapi application (aka while the server is running).

docs/docs/api/connections.md

@@ -0,0 +1,10 @@
+---
+sidebar_label: 'Connections'
+slug: '/api/connections'
+---
+
+# API Connections
+
+Access with: `strapi.redis.connections`
+
+For each connection either a normal Redis client is created, or if the cluster setting is enabled and you have properly passed in an array of nodes (and optionally any cluster options) a Redis Cluster client.

docs/docs/api/intro.md

@@ -0,0 +1,10 @@
+---
+sidebar_label: 'Introduction'
+slug: '/api/intro'
+---
+
+# API Introduction
+
+This plugin provides a Redis client for your Strapi application. It is based on the [ioredis](https://github.com/luin/ioredis/blob/master/API.md) package and provides a simple and easy-to-use interface for connecting to a Redis (or Redis alternative) database.
+
+More detailed examples for using this packages API will be coming shortly.

docs/docs/best-practices.md

@@ -0,0 +1,8 @@
+---
+sidebar_label: 'Best Practices'
+slug: '/best-practices'
+---
+
+# Best Practices
+
+Best practices will be coming soon, please check back later.

docs/docs/faq.md

@@ -0,0 +1,26 @@
+---
+sidebar_label: 'FAQ'
+slug: '/faq'
+---
+
+# Frequently Asked Questions
+
+## Do you plan on implementing a feature for X?
+
+Probably not unless the feature request has been opened on the [GitHub Repo](https://github.com/strapi-community/plugin-redis) and up voted by the community. However we do also accept PRs for new features.
+
+## How do I contribute to the project?
+
+Please open up a PR on the [GitHub Repo](https://github.com/strapi-community/plugin-redis), we will review it and merge it if it meets our standards. If you would like to discuss something before you contribute you are welcome to open an issue on the repo.
+
+## Do you plan on rewriting this in Typescript or providing Typescript support?
+
+No, we do not plan on rewriting this in Typescript or providing Types. Certainly we will accept PRs if you believe you can provide a good implementation that doesn't overly complicate the code-base but in general you should be able to use the existing types provided by the `ioredis` package.
+
+The Lead maintainer of this package has a strong preference for Javascript over Typescript and does not see the value in rewriting the package in Typescript.
+
+## I can't get the package to work, can you help me?
+
+Please open an issue on the [GitHub Repo](https://github.com/strapi-community/plugin-redis) and we will do our best to help you. Please provide as much information as possible including the version of Strapi you are using, the version of the plugin you are using, and any error messages you are seeing.
+
+Most of the time the issue is not with this plugin and is with your Redis configuration or your Strapi configuration. In many cases certain cloud providers have very strict network firewalls or restrictions that can prevent the connection.

docs/docs/installation.md

@@ -0,0 +1,62 @@
+---
+sidebar_label: 'Installation'
+slug: '/installation'
+---
+
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+# Installation
+
+As of plugin version 2.0.0+, the plugin package name has changed to `@strapi-community/plugin-redis`.
+This change was made to align with the naming convention of official Strapi plugins.
+
+As such the following table outlines the plugin versions vs the Strapi versions they are compatible with:
+
+| Strapi Version | Plugin Version |
+|----------------|----------------|
+| 5.x.x          | 2.x.x          |
+| 4.x.x          | 1.x.x          |
+| 3.x.x          | N/A            |
+
+## Installation for Strapi 5.x.x
+
+To install the plugin, run the following command:
+
+<Tabs groupId="install">
+  <TabItem value="yarn" label="Yarn">
+
+```bash
+yarn add @strapi-community/plugin-redis
+```
+
+  </TabItem>
+  <TabItem value="npm" label="NPM">
+
+```bash
+npm install @strapi-community/plugin-redis --save
+```
+
+  </TabItem>
+</Tabs>
+
+## Installation for Strapi 4.x.x
+
+To install the plugin, run the following command:
+
+<Tabs groupId="install">
+  <TabItem value="yarn" label="Yarn">
+
+```bash
+yarn add strapi-plugin-redis
+```
+
+  </TabItem>
+  <TabItem value="npm" label="NPM">
+
+```bash
+npm install strapi-plugin-redis --save
+```
+
+  </TabItem>
+</Tabs>

docs/docs/introduction.md

@@ -0,0 +1,34 @@
+---
+sidebar_label: 'Introduction'
+slug: '/'
+---
+
+# Introduction
+
+The purpose of this package is to have a universal Redis connector for all packages wanting to utilize a Redis database and/or for those wanting to develop custom functions and code within your Strapi project and would prefer a centralized Redis database for various purposes.
+
+This package is a wrapper around the `ioredis` package and provides a simple and easy-to-use interface for connecting to a Redis (or Redis alternative) database.
+
+Likewise, this package also includes the `redlock` package for distributed locks. Currently, if you horizontally scale Strapi and use the cron feature, you will end up with multiple instances of Strapi running the same cron job at the same time, potentially causing race conditions. This can cause issues with your database or other services that you are trying to integrate with. If enabled the Redlock option will automatically force those cron jobs to establish a lock before running the job meaning that only one instance of Strapi will run the job at a time.
+
+## Features
+
+- **Universal Redis Connector**: This package is a universal Redis connector for all packages wanting to utilize a Redis database.
+- **Multiple Redis Connections**: This package supports multiple Redis connections.
+- **Cluster/Sentinel Support**: This package supports Redis Cluster and Redis Sentinel.
+- **Redlock Support**: This package supports Redlock for distributed locks.
+- **Automatic Redlock CronTasks**: This package automatically uses Redlock for Strapi built-in CronTasks.
+
+## Possible Future Features
+
+- **Admin Panel Interface to see all Redis Connections**: This package may include an admin panel interface to see all Redis connections and their status.
+- **Admin Panel Interface to see all Redis Key/Values**: This package may include an admin panel interface to see all Redis keys and their values.
+- **Admin Panel Interface to see all Redis Server Status**: This package may include an admin panel interface to see all Redis server status (memory usage, CPU usage, etc).
+
+## Common Use-cases
+
+- **Caching**: This package can be used for caching data, for example see the LRU based plugin that uses this package called [REST Cache](/plugins/rest-cache).
+- **Apollo Server GraphQL Cache**: This package can be used for caching Apollo Server GraphQL data.
+- **IP based Rate Limiting**: This package can be used for IP based rate limiting using something like [koa2-ratelimit](https://www.npmjs.com/package/koa2-ratelimit).
+- **Server-side User Sessions**: This package can be used for server-side user session storage and management.
+- **So Much More**: The possibilities are endless!

docs/docs/plugins/rest-cache.md

@@ -0,0 +1,8 @@
+---
+sidebar_label: 'REST Cache'
+slug: '/plugins/rest-cache'
+---
+
+# REST Cache Plugin
+
+Details on this plugin are coming soon! Please check back later.

docs/docs/redis/basic.md

@@ -0,0 +1,35 @@
+---
+sidebar_label: 'Basic'
+slug: '/redis/basic'
+---
+
+# Basic Single Node Config
+
+The default configuration for the Redis plugin is a single node configuration. This is the most common configuration for Redis and is the default configuration for the plugin.
+
+```javascript
+// path ./config/plugins.js
+
+module.exports = {
+  redis: {
+    config: {
+      settings:{
+        debug: false,
+        enableRedlock: true,
+      }
+      connections: {
+        default: {
+          connection: {
+            host: '127.0.0.1',
+            port: 6379,
+            db: 0,
+          },
+          settings: {
+            debug: false,
+          },
+        },
+      },
+    },
+  },
+};
+```

docs/docs/redis/cluster.md

@@ -0,0 +1,8 @@
+---
+sidebar_label: 'Cluster'
+slug: '/redis/cluster'
+---
+
+# Cluster Config
+
+Cluster Configuration enable coming soon! Please check back later.