From e9d3484de6e79cda4c3e54531085a684c7c0eae7 Mon Sep 17 00:00:00 2001
From: Andy Pfister <andy.pfister@hey.com>
Date: Fri, 24 May 2024 18:19:40 +0200
Subject: [PATCH] Add page which describes the "redisless" setup (#703)

This PR adds a new page which describes how to setup StimulusReflex
without Redis. I extracted it into a separate page because I felt it was
too much to rewrite all the existing documentation, which relies on
Redis. I assume most people will use Redis, and the "redisless"
configuration likely is a niche thing.

Fixes #684
---
 docs/.vitepress/config.js   |  1 +
 docs/appendices/no-redis.md | 58 +++++++++++++++++++++++++++++++++++++
 docs/hello-world/setup.md   |  4 +--
 3 files changed, 61 insertions(+), 2 deletions(-)
 create mode 100644 docs/appendices/no-redis.md

diff --git a/docs/.vitepress/config.js b/docs/.vitepress/config.js
index e09ee71d..3ca2f3c6 100644
--- a/docs/.vitepress/config.js
+++ b/docs/.vitepress/config.js
@@ -74,6 +74,7 @@ export default {
         items: [
           { text: "Working with Events", link: "/appendices/events" },
           { text: "Testing (WIP)", link: "/appendices/testing" },
+          { text: "StimulusReflex without Redis", link: "/appendices/no-redis" },
           { text: "Deployment", link: "/appendices/deployment" },
           { text: "Troubleshooting", link: "/appendices/troubleshooting" },
           { text: "Release History", link: "/appendices/release-history" },
diff --git a/docs/appendices/no-redis.md b/docs/appendices/no-redis.md
new file mode 100644
index 00000000..8d9c7010
--- /dev/null
+++ b/docs/appendices/no-redis.md
@@ -0,0 +1,58 @@
+# StimulusReflex without Redis
+
+The default setup uses Redis for the Rails cache store, the Rails session store, and the ActionCable adapter. This setup variant is battle-tested, and we can promise it will work. However, if you cannot use Redis (or do not want to use Redis), there is a way to run StimulusReflex without Redis, which is purely backed by the PostgreSQL database.
+
+Start with the manual setup, which is described [here](/hello-world/setup#manual-configuration). Complete the manual setup until we explain how to set up the initializer. This is the part where we want to change things.
+
+First, let's add two new gems to our Gemfile.
+
+```ruby [Gemfile]
+gem "active-record-session_store"
+gem "solid_cache"
+```
+
+Generate the required database configurations.
+
+```shell
+bin/rails solid_cache:install:migrations
+bin/rails generate active_record:session_migration
+```
+
+Then, run migrations.
+
+```shell
+bin/rails db:migrate
+```
+
+Afterward, configure your Rails environments to use these gems.
+
+```ruby
+Rails.application.configure do
+  # CHANGE the following line; it's :memory_store by default
+  config.cache_store = :solid_cache_store
+    
+  # ADD the following line; it probably doesn't exist
+  config.session_store :active_record_store, key: "_session_development"
+end
+```
+
+You can add this configuration per environment or add it to an initializer.
+
+Adjust the ActionCable configuration to use the PostgreSQL adapter.
+
+```yaml
+development:
+  adapter: postgresql
+
+test:
+  adapter: postgresql
+
+production:
+  adapter: postgresql
+```
+
+Now Rails will happily boot your application, and StimulusReflex will work as well.
+
+```shell
+rails s
+```
diff --git a/docs/hello-world/setup.md b/docs/hello-world/setup.md
index 7a7be5c3..090c2f53 100644
--- a/docs/hello-world/setup.md
+++ b/docs/hello-world/setup.md
@@ -13,7 +13,7 @@ description: How to prepare your app to use StimulusReflex
 StimulusReflex relies on [Stimulus](https://stimulus.hotwired.dev), an excellent library from the creators of Rails. You can easily install StimulusReflex to new and existing Rails 6+ projects. For Rails 5.2, see [here](/hello-world/setup#rails-5-2-support).
 
 ::: warning
-StimulusReflex requires Redis to be [installed and running](https://redis.io/topics/quickstart).
+StimulusReflex recommends to use [Redis](https://redis.io/topics/quickstart). Details on how to setup StimulusReflex without Redis are provided [here](/appendices/no-redis).
 :::
 
 The terminal commands below will ensure that both Stimulus and StimulusReflex are installed. It creates common files and an example to get you started. It also handles some of the configuration outlined below, **including enabling caching in your development environment**. (You can read more about why we enable caching [here](/appendices/deployment#session-storage).)
@@ -105,7 +105,7 @@ And that's it! You can start using StimulusReflex in your application with the `
 Some developers will need more control than a one-size-fits-all install task, so we're going to step through what's actually required to get up and running with StimulusReflex in your Rails 6+ project in the _development_ environment. You'll need to keep reading to set up [test](/appendices/testing#test-environment-setup) and [production](/appendices/deployment). For Rails 5.2, see [here](/hello-world/setup#rails-5-2-support).
 
 ::: warning
-StimulusReflex requires Redis to be [installed and running](https://redis.io/topics/quickstart).
+StimulusReflex recommends to use [Redis](https://redis.io/topics/quickstart). Details on how to setup StimulusReflex without Redis are provided [here](/appendices/no-redis).
 
 You can learn more about optimizing your Redis configuration, why we enable caching in development and why we don't currently support cookie sessions on the [Deployment](/appendices/deployment#session-storage) page.
 :::