puma-daemon 0.2.2 → 0.2.3
Sign up to get free protection for your applications and to get access to all the features.
- checksums.yaml +4 -4
- data/.github/workflows/main.yml +20 -2
- data/.gitignore +1 -1
- data/Dockerfile.download +1 -1
- data/Makefile +3 -0
- data/README.adoc +92 -44
- data/README.pdf +9557 -1
- data/codecov.yml +4 -0
- data/example/config.ru +3 -1
- data/example/puma.rb +4 -2
- data/exe/pumad +1 -0
- data/lib/puma/daemon/runner_adapter.rb +38 -26
- data/lib/puma/daemon/version.rb +1 -1
- data/puma-daemon.gemspec +2 -1
- metadata +20 -4
checksums.yaml
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
---
|
|
2
2
|
SHA256:
|
|
3
|
-
metadata.gz:
|
|
4
|
-
data.tar.gz:
|
|
3
|
+
metadata.gz: e7b8150de79698d1088f01144bb81576619499a8fe9aef1100ff1af34ba494e6
|
|
4
|
+
data.tar.gz: d5d18c2979ed94fffb92a54dcd84c4376bd4fb38496fb0355a4777f7735fc820
|
|
5
5
|
SHA512:
|
|
6
|
-
metadata.gz:
|
|
7
|
-
data.tar.gz:
|
|
6
|
+
metadata.gz: a4795d230cc70bfe87b7477f0fbbf07e323daf828d0e592bfe7c39f163920102e9fd058e9033aef7861d04b756541816b632f467dcff52e68c847e639f4e2f52
|
|
7
|
+
data.tar.gz: 60ff6ab16ece8f09c415e5be2a967df283159d6415d36ab5047c537b23f402fd3c55066e12c488e1f5f812c92dc478f15a305f8081ceb815e655113bfd84242f
|
data/.github/workflows/main.yml
CHANGED
|
@@ -9,14 +9,32 @@ jobs:
|
|
|
9
9
|
matrix:
|
|
10
10
|
ruby-version: [3.2.0, 3.1.3, 3.0.5, 2.7.2, 2.6.6, 2.5.7]
|
|
11
11
|
|
|
12
|
+
env:
|
|
13
|
+
RUBY_VERSION: ${{ matrix.ruby-version }}
|
|
14
|
+
CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}
|
|
15
|
+
|
|
12
16
|
steps:
|
|
13
17
|
- uses: actions/checkout@v2
|
|
18
|
+
|
|
14
19
|
- name: Set up Ruby ${{ matrix.ruby-version }}
|
|
15
20
|
uses: ruby/setup-ruby@v1
|
|
16
21
|
with:
|
|
17
22
|
ruby-version: ${{ matrix.ruby-version }}
|
|
23
|
+
|
|
18
24
|
- name: Run Specs
|
|
19
25
|
run: make test-all
|
|
20
|
-
|
|
21
|
-
|
|
26
|
+
|
|
27
|
+
- name: Rubocop
|
|
28
|
+
run: bundle exec rubocop
|
|
29
|
+
|
|
30
|
+
- uses: codecov/codecov-action@v3
|
|
31
|
+
with:
|
|
32
|
+
token: ${{ secrets.CODECOV_TOKEN }} # not required for public repos
|
|
33
|
+
directory: coverage
|
|
34
|
+
env_vars: RUBY_VERSION
|
|
35
|
+
files: codecov-result.json
|
|
36
|
+
flags: unittests # optional
|
|
37
|
+
name: codecov-umbrella # optional
|
|
38
|
+
fail_ci_if_error: true # optional (default = false)
|
|
39
|
+
verbose: true # optional (default = false)
|
|
22
40
|
|
data/.gitignore
CHANGED
data/Dockerfile.download
CHANGED
data/Makefile
CHANGED
|
@@ -45,6 +45,9 @@ docker-build-run: docker-build-ruby ## Drops you into a BASH session on ubuntu
|
|
|
45
45
|
docker-download-run: docker-download-ruby ## Drops you into a BASH session on ubuntu with ruby 3.0.0
|
|
46
46
|
@docker run -it puma-daemon:latest
|
|
47
47
|
|
|
48
|
+
generate-pdf: ## Regenerates README,pdf from README.adoc
|
|
49
|
+
@bash -c "[[ -d ~/.bashmatic ]] || git clone https://github.com/kigster/bashmatic ~/.bashmatic"
|
|
50
|
+
@bash -c "source ~/.bashmatic/init.sh && ~/.bashmatic/bin/adoc2pdf README.adoc"
|
|
48
51
|
|
|
49
52
|
clean: ## Clean-up
|
|
50
53
|
@rm -rf Gemfile Gemfile.lock coverage
|
data/README.adoc
CHANGED
|
@@ -4,24 +4,69 @@
|
|
|
4
4
|
:sectnums:
|
|
5
5
|
:icons: font
|
|
6
6
|
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
image:https://app.fossa.com/api/projects/git%2Bgithub.com%2Fkigster%2Fpuma-daemon.svg?type=shield[link=https://app.fossa.com/projects/git%2Bgithub.com%2Fkigster%2Fpuma-daemon?ref=badge_shield]
|
|
10
|
-
image:https://badge.fury.io/rb/puma-daemon.svg["Gem Version", link="https://badge.fury.io/rb/puma-daemon"]
|
|
7
|
+
[cols="2,7",width="100%",align="center",options="header"]
|
|
8
|
+
|===
|
|
11
9
|
|
|
12
|
-
|
|
10
|
+
|Badge
|
|
11
|
+
|Type
|
|
13
12
|
|
|
14
|
-
|
|
13
|
+
|Test Suite
|
|
14
|
+
|image:https://github.com/kigster/puma-daemon/workflows/Ruby/badge.svg[link=https://github.com/kigster/puma-daemon/actions?query=workflow%3ARuby,width="150"]
|
|
15
15
|
|
|
16
|
-
In version 5.0 of the popular Ruby HTTP server https://github.com/puma/puma[Puma] the developers chose to https://github.com/puma/puma/pull/2170/files[drop the daemonization] support from Puma. They did that because the code wasn't actively maintained. Other and perhaps better options now exist (such as `systemd`, etc), not to mention that many people have switched to Kubernetes and Docker, where you generally want to start all servers in the foreground.
|
|
17
16
|
|
|
18
|
-
|
|
17
|
+
|Licensing
|
|
18
|
+
|image:https://app.fossa.com/api/projects/git%2Bgithub.com%2Fkigster%2Fpuma-daemon.svg?type=shield[link=https://app.fossa.com/projects/git%2Bgithub.com%2Fkigster%2Fpuma-daemon?ref=badge_shield,width="190"]
|
|
19
19
|
|
|
20
|
-
|
|
20
|
+
|Gem Version
|
|
21
|
+
|image:https://badge.fury.io/rb/puma-daemon.svg["Gem Version",link="https://badge.fury.io/rb/puma-daemon",width="220s"]
|
|
21
22
|
|
|
22
|
-
|
|
23
|
+
|Test Coverage
|
|
24
|
+
|image:https://codecov.io/gh/kigster/puma-daemon/branch/master/graph/badge.svg?token=asxarMSGbz[link=https://codecov.io/gh/kigster/puma-daemon,width="220"]
|
|
23
25
|
|
|
24
|
-
|
|
26
|
+
|Coverage Areas
|
|
27
|
+
|image:https://codecov.io/gh/kigster/puma-daemon/branch/master/graphs/sunburst.svg?token=asxarMSGbz[sunbirst,width="30%",link=https://codecov.io/gh/kigster/puma-daemon,float=left] image:https://codecov.io/gh/kigster/puma-daemon/branch/master/graphs/icicle.svg?token=asxarMSGbz[coverage-graph,width="60%",link=https://codecov.io/gh/kigster/puma-daemon,float=right]
|
|
28
|
+
|
|
29
|
+
|===
|
|
30
|
+
|
|
31
|
+
NOTE: You can read this in a nicely formatted https://github.com/kigster/puma-daemon/blob/master/README.pdf[README.pdf] document.
|
|
32
|
+
|
|
33
|
+
== Usage for the Impatient
|
|
34
|
+
|
|
35
|
+
1. Add `gem 'puma-daemon'` to your Gemfile. If you prefer, you can add `require: false` (your Rails instances such as Sidekiq will have no use for this gem).
|
|
36
|
+
|
|
37
|
+
2. You have two options to daemonize Puma using this gem:
|
|
38
|
+
|
|
39
|
+
a. In your `config/puma.rb` file, add the following line: `require 'puma/daemon'` at the top, and at the bottom call `daemonize`.
|
|
40
|
+
b. Wherever you use `puma` to start it (except using puma-ctl) replace `puma` with `pumad` and daemonization will be enabled automatically.
|
|
41
|
+
|
|
42
|
+
|
|
43
|
+
== Introduction
|
|
44
|
+
|
|
45
|
+
Let's start with the facts: https://github.com/puma/puma[Puma] is the most popular server to run Ruby and Rails applications. It's both multi-threaded and multi-process, making it one of the only servers that can truly saturate your web hardware. While 100% saturation is probably not what you want, the alternative is paying a fortune for under-utilized hardware. A good rule of thumb is to keep your web servers busy around 70-80% most of the time. Puma let's you do that by configuring the number of workers and threads within each worker.
|
|
46
|
+
|
|
47
|
+
=== What is Daemonization?
|
|
48
|
+
|
|
49
|
+
Unix processes have the ability to daemonize and go into the background.
|
|
50
|
+
|
|
51
|
+
This is not a trivial task: to properly daemonize a process must detach the from controlling terminal and run in the background as a system daemon.
|
|
52
|
+
|
|
53
|
+
In Ruby this is accomplished with the https://ruby-doc.org/core-3.0.1/Process.html#method-c-daemon[Process.daemon] method, which receives two boolean arguments:
|
|
54
|
+
|
|
55
|
+
* Unless the first argument `nochdir` is `true`, it will change the current working directory to the root (“/”).
|
|
56
|
+
* Unless the second argument `noclose` is true, `daemon()` will also redirect standard input, standard output and standard error to `/dev/null`.
|
|
57
|
+
* Finally, it will return zero on success, or raise one of ` Errno::*` and pass the control to the subsequent Ruby code, which will now continue executing within a daemon.
|
|
58
|
+
|
|
59
|
+
=== Why was it removed from Puma v5?
|
|
60
|
+
|
|
61
|
+
For production deployments, tools like `systemd` offer much better alternative, including ability to cap overall memory and CPU consumed by the Puma and all of its workers using Linux cgroups.
|
|
62
|
+
|
|
63
|
+
The proliferation of Docker deployments meant that Puma is run on the foreground within a Docker container.
|
|
64
|
+
|
|
65
|
+
Finally, the code which previously daemonized Puma in version 4 was not really maintained, and for this reason was removed from Puma version 5.
|
|
66
|
+
|
|
67
|
+
=== What does `puma-daemon` do?
|
|
68
|
+
|
|
69
|
+
We thought that while the core Puma removing daemonization was the right move, it felt useful in some occastions and so we created this gem to restore the daemonization functionality to Puma v5+.
|
|
25
70
|
|
|
26
71
|
== Compatibility
|
|
27
72
|
|
|
@@ -37,17 +82,19 @@ Currently Puma versions 5 and 6 are supported.
|
|
|
37
82
|
|
|
38
83
|
=== Known Issues
|
|
39
84
|
|
|
40
|
-
Please see the list of open issues on the https://github.com/kigster/puma-daemon/issues[Issues Page].
|
|
85
|
+
Please see the list of open issues on the https://github.com/kigster/puma-daemon/issues[Issues Page].
|
|
86
|
+
Any help is always welcomed.
|
|
41
87
|
|
|
42
|
-
|
|
88
|
+
=== How it works?
|
|
43
89
|
|
|
44
90
|
This gem's goal was to surgically augment Puma's source code to restore daemonization by merely requiring `puma/daemon`.
|
|
45
91
|
|
|
46
|
-
We accomplished this goal by adding the daemonization call to the routine `output_header()` which is invoked by both `Puma::Single` runner and the `Puma::Cluster` runner at the very beginning of the launch process.
|
|
92
|
+
We accomplished this goal by adding the daemonization call to the routine `output_header()` which is invoked by both `Puma::Single` runner and the `Puma::Cluster` runner at the very beginning of the launch process.
|
|
93
|
+
While relatively brittle, particularly if the future versions of Puma change this, this approach seems to work with the currently released version of Puma (5 and 6).
|
|
47
94
|
|
|
48
95
|
If you run into problems, please https://github.com/kigster/puma-daemon/issues/new[submit an issue].
|
|
49
96
|
|
|
50
|
-
==
|
|
97
|
+
== Examples
|
|
51
98
|
|
|
52
99
|
Add this line to your application's Gemfile:
|
|
53
100
|
|
|
@@ -70,29 +117,19 @@ daemonize
|
|
|
70
117
|
|
|
71
118
|
And then execute:
|
|
72
119
|
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
== Usage
|
|
79
|
-
|
|
80
|
-
There were two ways you could daemonize Puma in the past:
|
|
81
|
-
|
|
82
|
-
1. By specifying `daemonize` or `daemonize(true)` in your config file.
|
|
83
|
-
2. By specifying `-d` or `--daemonize` on the command line.
|
|
84
|
-
|
|
85
|
-
Both of these ways are supported, as long as you do `require 'puma/daemon'` in your puma config file, and — in the case of `-d` flag, you pass it to `pumad` executable, not `puma`.
|
|
86
|
-
|
|
87
|
-
The recommended way to daemonize is via the provided `pumad` executable, or via the require in `puma.rb` and a subsequent call to `daemonize()` method.
|
|
120
|
+
[source,bash]
|
|
121
|
+
----
|
|
122
|
+
bundle install -j 12
|
|
123
|
+
bundle exec puma -C config/puma.rb [rackup.ru]
|
|
124
|
+
----
|
|
88
125
|
|
|
89
|
-
|
|
126
|
+
Make sure you have `config.ru` Rackup file in the current folder.
|
|
127
|
+
Checkout the shell script inside the `example` folder for more info.
|
|
90
128
|
|
|
91
|
-
=== Examples
|
|
92
129
|
|
|
93
|
-
Please see the https://github.com/kigster/puma-daemon/tree/master/example[`example`] directory in the source of the gem. It contains `single.sh` and `cluster.sh` scripts that boot Puma via `pumad` binary.
|
|
130
|
+
NOTE: Please see the https://github.com/kigster/puma-daemon/tree/master/example[`example`] directory in the source of the gem. It contains `single.sh` and `cluster.sh` scripts that boot Puma via `pumad` binary.
|
|
94
131
|
|
|
95
|
-
===
|
|
132
|
+
=== Using Config File
|
|
96
133
|
|
|
97
134
|
If you want to specify `daemonize` in your config file, simply include `require 'puma/daemon'` at the top of your config file:
|
|
98
135
|
|
|
@@ -123,7 +160,7 @@ Here is an example of daemonizing via the config file shown above, and using the
|
|
|
123
160
|
[62235] * Environment: development
|
|
124
161
|
[62235] * Master PID: 62235
|
|
125
162
|
[62235] * Puma Daemon: Daemonizing...
|
|
126
|
-
[62235] * Gem: puma-daemon v0.2.
|
|
163
|
+
[62235] * Gem: puma-daemon v0.2.2
|
|
127
164
|
[62235] * Gem: puma v6.1.1
|
|
128
165
|
[62258] * Workers: 4
|
|
129
166
|
[62258] * Restarts: (✔) hot (✔) phased
|
|
@@ -133,13 +170,15 @@ Here is an example of daemonizing via the config file shown above, and using the
|
|
|
133
170
|
|
|
134
171
|
Note that using this method you can decide whether to daemonize or not by passing true or false to the `daemonize` method.
|
|
135
172
|
|
|
136
|
-
===
|
|
173
|
+
=== Using Command Line
|
|
137
174
|
|
|
138
175
|
If you prefer to make a decision whether to daemonize or not on the command line, you only have to make one chance: replace `puma` with `pumad`.
|
|
139
176
|
|
|
140
|
-
NOTE: We did not want to conflict with the `puma` gem by introducing another executable under the same name.
|
|
177
|
+
NOTE: We did not want to conflict with the `puma` gem by introducing another executable under the same name.
|
|
178
|
+
The executable this gem provides is called `pumad` (where 'd' stands for daemon, and follows standard UNIX convention, as in eg `sshd`, `ftpd`, etc).
|
|
141
179
|
|
|
142
|
-
If you replace `puma` with `pumad`, you no longer need to pass any additional command line flag (`-d` and `--daemonize`) to daemonize.
|
|
180
|
+
If you replace `puma` with `pumad`, you no longer need to pass any additional command line flag (`-d` and `--daemonize`) to daemonize.
|
|
181
|
+
You can continue passing them or you can remove them (these flags are stripped out before ARGV is passed onto Puma's CLI parser.)
|
|
143
182
|
|
|
144
183
|
[source,bash]
|
|
145
184
|
----
|
|
@@ -153,7 +192,7 @@ Puma starting in single mode...
|
|
|
153
192
|
* Environment: development
|
|
154
193
|
* PID: 63179
|
|
155
194
|
* Puma Daemon: Daemonizing...
|
|
156
|
-
* Gem: puma-daemon v0.2.
|
|
195
|
+
* Gem: puma-daemon v0.2.2
|
|
157
196
|
* Gem: puma v6.1.1
|
|
158
197
|
* Listening on unix:///tmp/puma.sock
|
|
159
198
|
* Listening on http://0.0.0.0:9292
|
|
@@ -161,15 +200,24 @@ Puma starting in single mode...
|
|
|
161
200
|
|
|
162
201
|
As you can see, at the end it says "Daemonizing".
|
|
163
202
|
|
|
164
|
-
If you start puma this way, you can still specify `daemonize(false)` in the configuration file to turn it off, but the default is to daemonize.
|
|
203
|
+
If you start puma this way, you can still specify `daemonize(false)` in the configuration file to turn it off, but the default is to daemonize.
|
|
204
|
+
Also, if you start with `pumad` you do not need to include `require 'puma/daemon'` in your configuration file, as the `pumad` binary loads all dependencies prior to parsing the config.
|
|
165
205
|
|
|
166
|
-
==
|
|
206
|
+
== Contributing
|
|
167
207
|
|
|
168
|
-
|
|
208
|
+
NOTE: You do need a working `make` utility to use the below commands.
|
|
169
209
|
|
|
170
|
-
|
|
210
|
+
* After checking out the repo, run `make puma-v5` or `make puma-v6` to configure your dependent vesion of Puma.
|
|
171
211
|
|
|
172
|
-
|
|
212
|
+
* After that, run `bin/setup` to install dependencies.
|
|
213
|
+
|
|
214
|
+
* Then, run `rake spec` to run the tests.
|
|
215
|
+
|
|
216
|
+
* You can also run `bin/console` for an interactive prompt that will allow you to experiment.
|
|
217
|
+
|
|
218
|
+
* To install this gem onto your local machine, run `bundle exec rake install`.
|
|
219
|
+
|
|
220
|
+
* To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to https://rubygems.org[rubygems.org].
|
|
173
221
|
|
|
174
222
|
Bug reports and pull requests are welcome on GitHub at https://github.com/kigster/puma-daemon.
|
|
175
223
|
|