From e3bb6b61d363f383f977f99172139b3d8c7c1b62 Mon Sep 17 00:00:00 2001
From: Lev Kokotov <lev.kokotov@gmail.com>
Date: Thu, 7 Nov 2024 10:50:23 -0800
Subject: [PATCH] docs

---
 docs/docs/migrating-from-rails.md | 69 +++++++++++++++++++++++++++++++
 examples/rails/.cargo/config.toml |  1 +
 examples/rails/src/main.rs        |  2 +-
 rwf/src/controller/mod.rs         |  7 +++-
 4 files changed, 76 insertions(+), 3 deletions(-)
 create mode 100644 docs/docs/migrating-from-rails.md
 create mode 120000 examples/rails/.cargo/config.toml

diff --git a/docs/docs/migrating-from-rails.md b/docs/docs/migrating-from-rails.md
new file mode 100644
index 00000000..a9271e04
--- /dev/null
+++ b/docs/docs/migrating-from-rails.md
@@ -0,0 +1,69 @@
+# Migrating from Rails
+
+Rwf comes with its own [Rack](https://github.com/rack/rack) server which you can run side by side with your [controllers](controllers/index.md). This allows you to run your Rails app inside Rwf, while moving traffic from Rails controllers to Rwf controllers without downtime.
+
+## Running Rails
+
+!!! note
+    Our Rack server is currently highly experimental. Ruby doesn't have ergonomic bindings to Rust (unlike [Python](migrating-from-python.md)), so
+    a lot of this had to be written specifically for this project.
+
+### Ruby
+
+Depending on your operating system, Ruby installation may differ.
+
+#### Linux
+
+On Linux, you can install Ruby using your package manager. Since Rails uses Bundler to manage dependencies, make sure you set the `GEM_HOME` environment variable to a folder writable by your UNIX user, e.g. `~/.gems`:
+
+```bash
+mkdir -p ~/.gems
+export GEM_HOME=~/.gems
+```
+
+Since we'll be compiling our Ruby bindings from source, make sure to install the Ruby headers as well. On most systems, that'll come from the `ruby-dev` package.
+
+#### Mac OS
+
+Mac OS comes with its own Ruby version, however it's very much out of date and won't work with modern Rails apps. You'll need to install Ruby from [homebrew](https://brew.sh/):
+
+```bash
+brew install ruby
+```
+
+When building a Rwf app with Ruby bindings, you'll need to make sure the linker can find the right Ruby library. Since you'll have two versions of Ruby installed at this point, the linker will get confused and use the system one, which won't work. To get around this, create a `.cargo/config` file in your project, and add the right library path to the linker arguments:
+
+```toml
+[build]
+rustflags = ["-C", "link-args=-L/opt/homebrew/Cellar/ruby/3.3.4/lib"]
+```
+
+The path here will depend on the version of Ruby you have installed with homebrew.
+
+### Running the app
+
+Running a Rails app with Rwf requires only adding the built-in Rack controller to your server:
+
+```rust
+use rwf::prelude::*;
+use rwf::http::{Server, self};
+use rwf::controllers::RackController;
+
+#[tokio::main]
+async fn main() -> Result<(), http::Error> {
+    Server::new(vec![
+        RackController::new("path/to/your/rails/app")
+            .wildcard("/")
+    ])
+    .launch("0.0.0.0:8000")
+    .await
+}
+```
+
+The `RackController` takes the path (relative or absolute) to your Rails application as an argument.
+
+
+
+## Learn more
+
+- [examples/rails](https://github.com/levkk/rwf/tree/main/examples/rails)
diff --git a/examples/rails/.cargo/config.toml b/examples/rails/.cargo/config.toml
new file mode 120000
index 00000000..30fa1cea
--- /dev/null
+++ b/examples/rails/.cargo/config.toml
@@ -0,0 +1 @@
+config
\ No newline at end of file
diff --git a/examples/rails/src/main.rs b/examples/rails/src/main.rs
index d9b4aea5..473b081d 100644
--- a/examples/rails/src/main.rs
+++ b/examples/rails/src/main.rs
@@ -1,4 +1,4 @@
-use rwf::controller::rack::RackController;
+use rwf::controller::RackController;
 use rwf::http::{self, Server};
 use rwf::prelude::*;
 
diff --git a/rwf/src/controller/mod.rs b/rwf/src/controller/mod.rs
index 07f583a1..653fddb5 100644
--- a/rwf/src/controller/mod.rs
+++ b/rwf/src/controller/mod.rs
@@ -4,8 +4,6 @@ pub mod auth;
 pub mod engine;
 pub mod error;
 pub mod middleware;
-#[cfg(feature = "rack")]
-pub mod rack;
 pub mod ser;
 pub mod static_files;
 pub mod turbo_stream;
@@ -16,6 +14,11 @@ pub mod wsgi;
 #[cfg(feature = "wsgi")]
 pub use wsgi::WsgiController;
 
+#[cfg(feature = "rack")]
+pub mod rack;
+#[cfg(feature = "rack")]
+pub use rack::RackController;
+
 pub use auth::{AllowAll, AuthHandler, Authentication, BasicAuth, DenyAll, Session, SessionId};
 pub use engine::Engine;
 pub use error::Error;