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 +4 -4
- data/README.md +172 -13
- data/app/controllers/litestream_rails/application_controller.rb +7 -0
- data/app/controllers/litestream_rails/processes_controller.rb +9 -0
- data/app/views/layouts/litestream_rails/_style.html +269 -612
- data/app/views/layouts/litestream_rails/application.html.erb +3 -3
- data/app/views/litestream_rails/processes/show.html.erb +121 -0
- data/config/routes.rb +2 -2
- data/lib/litestream_rails/version.rb +1 -1
- data/lib/litestream_rails.rb +58 -13
- metadata +8 -8
- data/app/controllers/litestream_rails/databases_controller.rb +0 -32
- data/app/views/litestream_rails/databases/index.html.erb +0 -85
checksums.yaml
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
---
|
|
2
2
|
SHA256:
|
|
3
|
-
metadata.gz:
|
|
4
|
-
data.tar.gz:
|
|
3
|
+
metadata.gz: 2e9c8bcec979cf18668f44388864b49c3111ed8be9025cc16e8dde054ef2281a
|
|
4
|
+
data.tar.gz: b747117ff97159c50a17b87b1ad7bfdcbb2f1c0503195ff63e7c1c85ea66f9f0
|
|
5
5
|
SHA512:
|
|
6
|
-
metadata.gz:
|
|
7
|
-
data.tar.gz:
|
|
6
|
+
metadata.gz: ded52a5d85703cb8a3f573ccfdb98a267e2db042f82a66db25afcfe703d7dca08e1feb161bb6e1a08fbab2de6134a08f44964ff69f01e400f289a31c87714230
|
|
7
|
+
data.tar.gz: 3a6e1933b8ce9cf878dc73564c923fe36ec5bb69ee17685f13700b7561532134efce2809b604027f22c3f945f611aea1cabbfb5e0c07b07104fe3ec68dcb12d1
|
data/README.md
CHANGED
|
@@ -1,24 +1,183 @@
|
|
|
1
|
-
#
|
|
2
|
-
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
+
|
|
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/
|
|
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/
|
|
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
|