litestream_rails 0.1.0 → 0.3.0

Sign up to get free protection for your applications and to get access to all the features.
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA256:
3
- metadata.gz: 16364fd870caac32d1ebd6384fdf8efa2df6ffe03d869fc2b81690e17dee918f
4
- data.tar.gz: ee3fd64699cb1e653af24b8fb18cfdb90e2dba88f97eed0233cc077e9880cb98
3
+ metadata.gz: 2e9c8bcec979cf18668f44388864b49c3111ed8be9025cc16e8dde054ef2281a
4
+ data.tar.gz: b747117ff97159c50a17b87b1ad7bfdcbb2f1c0503195ff63e7c1c85ea66f9f0
5
5
  SHA512:
6
- metadata.gz: bf308da1364cd89cae383a9a611f44f6d9f8ad887e1a98b5129197a712776fb731ae48ee2586371a9e78981771bbc856d067a4c2fbfff530a5046c0a197feb3a
7
- data.tar.gz: 031747b8616a4f7fe095a1e54bbeed0ce62183bd7a29df3d33a44c6dcc425446c8228eabd1bd4750a7da8895bd52be2eb26aa485fb4b721b51b9f79d9dd4e93f
6
+ metadata.gz: ded52a5d85703cb8a3f573ccfdb98a267e2db042f82a66db25afcfe703d7dca08e1feb161bb6e1a08fbab2de6134a08f44964ff69f01e400f289a31c87714230
7
+ data.tar.gz: 3a6e1933b8ce9cf878dc73564c923fe36ec5bb69ee17685f13700b7561532134efce2809b604027f22c3f945f611aea1cabbfb5e0c07b07104fe3ec68dcb12d1
data/README.md CHANGED
@@ -1,24 +1,183 @@
1
- # LitestreamRails
2
-
3
- TODO: Delete this and the text below, and describe your gem
4
-
5
- Welcome to your new gem! In this directory, you'll find the files you need to be able to package up your Ruby library into a gem. Put your Ruby code in the file `lib/litestream_rails`. To experiment with that code, run `bin/console` for an interactive prompt.
1
+ # Litestream Rails
2
+
3
+ <p>
4
+ <a href="https://rubygems.org/gems/litestream_rails">
5
+ <img alt="GEM Version" src="https://img.shields.io/gem/v/litestream_rails?color=168AFE&include_prereleases&logo=ruby&logoColor=FE1616">
6
+ </a>
7
+ <a href="https://rubygems.org/gems/litestream_rails">
8
+ <img alt="GEM Downloads" src="https://img.shields.io/gem/dt/litestream_rails?color=168AFE&logo=ruby&logoColor=FE1616">
9
+ </a>
10
+ <a href="https://github.com/testdouble/standard">
11
+ <img alt="Ruby Style" src="https://img.shields.io/badge/style-standard-168AFE?logo=ruby&logoColor=FE1616" />
12
+ </a>
13
+ <a href="https://github.com/fractaledmind/litestream_rails/actions/workflows/main.yml">
14
+ <img alt="Tests" src="https://github.com/fractaledmind/litestream_rails/actions/workflows/main.yml/badge.svg" />
15
+ </a>
16
+ <a href="https://github.com/sponsors/fractaledmind">
17
+ <img alt="Sponsors" src="https://img.shields.io/github/sponsors/fractaledmind?color=eb4aaa&logo=GitHub%20Sponsors" />
18
+ </a>
19
+ <a href="https://ruby.social/@fractaledmind">
20
+ <img alt="Ruby.Social Follow" src="https://img.shields.io/mastodon/follow/109291299520066427?domain=https%3A%2F%2Fruby.social&label=%40fractaledmind&style=social">
21
+ </a>
22
+ <a href="https://twitter.com/fractaledmind">
23
+ <img alt="Twitter Follow" src="https://img.shields.io/twitter/url?label=%40fractaledmind&style=social&url=https%3A%2F%2Ftwitter.com%2Ffractaledmind">
24
+ </a>
25
+ </p>
26
+
27
+ Litestream Rails provides seamless integration of the [Litestream](https://litestream.io/) SQLite backup tool with your Rails applications. Built on top of the [Litestream Ruby](https://github.com/fractaledmind/litestream-ruby) gem, Litestream Rails allows you to configure, run, and monitor Litestream backups directly from your Rails application.
6
28
 
7
29
  ## Installation
8
30
 
9
- TODO: Replace `UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG` with your gem name right after releasing it to RubyGems.org. Please do not do it earlier due to security reasons. Alternatively, replace this section with instructions to install your gem from git if you don't plan to release to RubyGems.org.
10
-
11
31
  Install the gem and add to the application's Gemfile by executing:
12
-
13
- $ bundle add UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG
32
+ ```bash
33
+ $ bundle add litestream_rails
34
+ ```
14
35
 
15
36
  If bundler is not being used to manage dependencies, install the gem by executing:
37
+ ```bash
38
+ $ gem install litestream_rails
39
+ ```
40
+
41
+ After installing the gem, run the installer:
42
+ ```bash
43
+ $ rails generate litestream:install
44
+ ```
16
45
 
17
- $ gem install UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG
46
+ The installer will create a configuration file at `config/litestream.yml`, an initializer file for configuring the gem at `config/initializers/litestream.rb`, as well as a `Procfile` so that you can run the Litestream replication process alongside your Rails application in production.
47
+
48
+ Then mount the engine in your `config/routes.rb` file:
49
+ ```ruby
50
+ authenticate :user, -> (user) { user.admin? } do
51
+ mount LitestreamRails::Engine, at: "/litestream_rails"
52
+ end
53
+ ```
54
+
55
+ > [!NOTE]
56
+ > Be sure to [secure the dashboard](#authentication) in production.
18
57
 
19
58
  ## Usage
20
59
 
21
- TODO: Write usage instructions here
60
+ The [`litestream-ruby` gem](https://github.com/fractaledmind/litestream-ruby) wraps the standalone executable version of the [Litestream](https://litestream.io/install/source/) utility. These executables are platform specific, so there are actually separate underlying gems per platform, but the correct gem will automatically be picked for your platform. Litestream itself doesn't support Windows, so this gem doesn't either.
61
+
62
+ Supported platforms are:
63
+
64
+ * arm64-darwin (macos-arm64)
65
+ * x86_64-darwin (macos-x64)
66
+ * arm64-linux (linux-arm64)
67
+ * x86_64-linux (linux-x64)
68
+
69
+ This Rails engine intentionally provides only a few features. Since the Litestream utility only does one thing, and does it well, all this gem can do beyond the lower-level [`litestream-ruby` gem](https://github.com/fractaledmind/litestream-ruby) is to provide a web interface for introspecting Litestream's state and logs. The only action you can take from the dashboard is to restore a particular database from its Litestream backup.
70
+
71
+ There are, however, a few features I would like to add in the future:
72
+
73
+ - [ ] an ActiveJob for regularly verifying backups
74
+ - [ ] logs of the verification job runs in the web dashboard
75
+ - [ ] provide more information about the running Litestream replication process, like memory usage, CPU usage, etc.
76
+
77
+ ### Configuration
78
+
79
+ You can configure Litestream Rails via the Rails configuration object, under the `litestream_rails` key. Currently, only 2 configuration options are available:
80
+
81
+ * `username` - The username to use for HTTP authentication. See [Authentication](#authentication) for more information.
82
+ * `password` - The password to use for HTTP authentication. See [Authentication](#authentication) for more information.
83
+
84
+ #### Authentication
85
+
86
+ Litestream Rails does not restrict access out of the box. You must secure the dashboard yourself. However, it does provide basic HTTP authentication that can be used with basic authentication or Devise. All you need to do is setup a username and password.
87
+
88
+ There are two ways to setup a username and password. First, you can use the `LITESTREAMRAILS_USERNAME` and `LITESTREAMRAILS_PASSWORD` environment variables:
89
+
90
+ ```ruby
91
+ ENV["LITESTREAMRAILS_USERNAME"] = "frodo"
92
+ ENV["LITESTREAMRAILS_PASSWORD"] = "ikeptmysecrets"
93
+ ```
94
+
95
+ Second, you can set the `LitestreamRails.username` and `LitestreamRails.password` variables in an initializer:
96
+
97
+ ```ruby
98
+ # Set authentication credentials for Litestream Rails
99
+ config.litestream_rails.username = Rails.application.credentials.litestream_rails.username
100
+ config.litestream_rails.password = Rails.application.credentials.litestream_rails.password
101
+ ```
102
+
103
+ Either way, if you have set a username and password, Litestream Rails will use basic HTTP authentication. If you have not set a username and password, Litestream Rails will not require any authentication to view the dashboard.
104
+
105
+ If you use Devise for authentication in your app, you can also restrict access to the dashboard by using their `authenticate` constraint in your routes file:
106
+
107
+ ```ruby
108
+ authenticate :user, -> (user) { user.admin? } do
109
+ mount LitestreamRails::Engine, at: "/litestream_rails"
110
+ end
111
+ ```
112
+
113
+ ### Examples
114
+
115
+ There is only one screen in the dashboard.
116
+
117
+ * the show view of the Litestream replication process:
118
+
119
+ ![image description](images/show-screenshot.png)
120
+
121
+ ### Usage with API-only Applications
122
+
123
+ If your Rails application is an API-only application (generated with the `rails new --api` command), you will need to add the following middleware to your `config/application.rb` file in order to use the dashboard UI provided by Litestream Rails:
124
+
125
+ ```ruby
126
+ # /config/application.rb
127
+ config.middleware.use ActionDispatch::Cookies
128
+ config.middleware.use ActionDispatch::Session::CookieStore
129
+ config.middleware.use ActionDispatch::Flash
130
+ ```
131
+
132
+ ### Overwriting the views
133
+
134
+ You can find the views in [`app/views`](https://github.com/fractaledmind/litestream_rails/tree/main/app/views).
135
+
136
+ ```bash
137
+ app/views/
138
+ ├── layouts
139
+ │   └── litestream_rails
140
+ │   ├── _style.html
141
+ │   └── application.html.erb
142
+ └── litestream_rails
143
+ └── processes
144
+    └── show.html.erb
145
+
146
+ ```
147
+
148
+ You can always take control of the views by creating your own views and/or partials at these paths in your application. For example, if you wanted to overwrite the application layout, you could create a file at `app/views/layouts/litestream_rails/application.html.erb`. If you wanted to remove the footer and the automatically disappearing flash messages, as one concrete example, you could define that file as:
149
+
150
+ ```erb
151
+ <!DOCTYPE html>
152
+ <html>
153
+ <head>
154
+ <title>Litestream Rails</title>
155
+ <%= csrf_meta_tags %>
156
+ <%= csp_meta_tag %>
157
+
158
+ <%= render "layouts/litestream_rails/style" %>
159
+ </head>
160
+ <body class="h-full flex flex-col">
161
+ <main class="container mx-auto max-w-4xl mt-4 px-2 grow">
162
+ <%= content_for?(:content) ? yield(:content) : yield %>
163
+ </main>
164
+
165
+ <div class="fixed top-0 left-0 right-0 text-center py-2">
166
+ <% if notice.present? %>
167
+ <p class="py-2 px-3 bg-green-50 text-green-500 font-medium rounded-lg inline-block">
168
+ <%= notice %>
169
+ </p>
170
+ <% end %>
171
+
172
+ <% if alert.present? %>
173
+ <p class="py-2 px-3 bg-red-50 text-red-500 font-medium rounded-lg inline-block">
174
+ <%= alert %>
175
+ </p>
176
+ <% end %>
177
+ </div>
178
+ </body>
179
+ </html>
180
+ ```
22
181
 
23
182
  ## Development
24
183
 
@@ -28,7 +187,7 @@ To install this gem onto your local machine, run `bundle exec rake install`. To
28
187
 
29
188
  ## Contributing
30
189
 
31
- Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/litestream_rails. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/[USERNAME]/litestream_rails/blob/main/CODE_OF_CONDUCT.md).
190
+ Bug reports and pull requests are welcome on GitHub at https://github.com/fractaledmind/litestream_rails. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/fractaledmind/litestream_rails/blob/main/CODE_OF_CONDUCT.md).
32
191
 
33
192
  ## License
34
193
 
@@ -36,4 +195,4 @@ The gem is available as open source under the terms of the [MIT License](https:/
36
195
 
37
196
  ## Code of Conduct
38
197
 
39
- Everyone interacting in the LitestreamRails project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/[USERNAME]/litestream_rails/blob/main/CODE_OF_CONDUCT.md).
198
+ Everyone interacting in the LitestreamRails project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/fractaledmind/litestream_rails/blob/main/CODE_OF_CONDUCT.md).
@@ -1,7 +1,14 @@
1
1
  module LitestreamRails
2
2
  class ApplicationController < ActionController::Base
3
3
  protect_from_forgery with: :exception
4
+ around_action :force_english_locale!
4
5
 
5
6
  http_basic_authenticate_with name: LitestreamRails.username, password: LitestreamRails.password if LitestreamRails.password
7
+
8
+ private
9
+
10
+ def force_english_locale!(&action)
11
+ I18n.with_locale(:en, &action)
12
+ end
6
13
  end
7
14
  end
@@ -0,0 +1,9 @@
1
+ module LitestreamRails
2
+ class ProcessesController < ApplicationController
3
+ # GET /process
4
+ def show
5
+ @process = LitestreamRails.replicate_process
6
+ @databases = LitestreamRails.databases
7
+ end
8
+ end
9
+ end