Permalink
Browse files

doc: emphasize the importance of stderr_path

While second nature to myself, stderr_path may be an
overlooked configuration parameter for some users.  Also,
add a minimal sample configuration file that is shorter
and hopefully less intimidating to new users.
  • Loading branch information...
1 parent 59a625b commit 2d5a4b075801493a85c6e8d2dbdf0c95002e046d Eric Wong committed Jun 4, 2010
Showing with 40 additions and 7 deletions.
  1. +13 −0 examples/unicorn.conf.minimal.rb
  2. +9 −3 examples/unicorn.conf.rb
  3. +18 −4 lib/unicorn/configurator.rb
@@ -0,0 +1,13 @@
+# Minimal sample configuration file for Unicorn (not Rack) when used
+# with daemonization (unicorn -D) started in your working directory.
+#
+# See http://unicorn.bogomips.org/Unicorn/Configurator.html for complete
+# documentation.
+# See also http://unicorn.bogomips.org/examples/unicorn.conf.rb for
+# a more verbose configuration using more features.
+
+listen 2007 # by default Unicorn listens on port 8080
+worker_processes 2 # this should be >= nr_cpus
+pid "/path/to/app/shared/pids/unicorn.pid"
+stderr_path "/path/to/app/shared/log/unicorn.log"
+stdout_path "/path/to/app/shared/log/unicorn.log"
View
@@ -1,4 +1,9 @@
-# Sample configuration file for Unicorn (not Rack)
+# Sample verbose configuration file for Unicorn (not Rack)
+#
+# This configuration file documents many features of Unicorn
+# that may not be needed for some applications. See
+# http://unicorn.bogomips.org/examples/unicorn.conf.minimal.rb
+# for a much simpler configuration file.
#
# See http://unicorn.bogomips.org/Unicorn/Configurator.html for complete
# documentation.
@@ -22,8 +27,9 @@
# feel free to point this anywhere accessible on the filesystem
pid "/path/to/app/shared/pids/unicorn.pid"
-# some applications/frameworks log to stderr or stdout, so prevent
-# them from going to /dev/null when daemonized here:
+# By default, the Unicorn logger will write to stderr.
+# Additionally, ome applications/frameworks log to stderr or stdout,
+# so prevent them from going to /dev/null when daemonized here:
stderr_path "/path/to/app/shared/log/unicorn.stderr.log"
stdout_path "/path/to/app/shared/log/unicorn.stdout.log"
@@ -7,9 +7,11 @@ module Unicorn
# Implements a simple DSL for configuring a Unicorn server.
#
- # See http://unicorn.bogomips.org/examples/unicorn.conf.rb for an
- # example config file. An example config file for use with nginx is
- # also available at http://unicorn.bogomips.org/examples/nginx.conf
+ # See http://unicorn.bogomips.org/examples/unicorn.conf.rb and
+ # http://unicorn.bogomips.org/examples/unicorn.conf.minimal.rb
+ # example configuration files. An example config file for use with
+ # nginx is also available at
+ # http://unicorn.bogomips.org/examples/nginx.conf
class Configurator < Struct.new(:set, :config_file, :after_reload)
# Default settings for Unicorn
@@ -78,6 +80,10 @@ def [](key) # :nodoc:
# sets object to the +new+ Logger-like object. The new logger-like
# object must respond to the following methods:
# +debug+, +info+, +warn+, +error+, +fatal+, +close+
+ # The default Logger will log its output to the path specified
+ # by +stderr_path+. If you're running Unicorn daemonized, then
+ # you must specify a path to prevent error messages from going
+ # to /dev/null.
def logger(new)
%w(debug info warn error fatal close).each do |m|
new.respond_to?(m) and next
@@ -310,11 +316,19 @@ def preload_app(bool)
# file will be opened with the File::APPEND flag and writes
# synchronized to the kernel (but not necessarily to _disk_) so
# multiple processes can safely append to it.
+ #
+ # If you are daemonizing and using the default +logger+, it is important
+ # to specify this as errors will otherwise be lost to /dev/null.
+ # Some applications/libraries may also triggering warnings that go to
+ # stderr, and they will end up here.
def stderr_path(path)
set_path(:stderr_path, path)
end
- # Same as stderr_path, except for $stdout
+ # Same as stderr_path, except for $stdout. Not many Rack applications
+ # write to $stdout, but any that do will have their output written here.
+ # It is safe to point this to the same location a stderr_path.
+ # Like stderr_path, this defaults to /dev/null when daemonized.
def stdout_path(path)
set_path(:stdout_path, path)
end

0 comments on commit 2d5a4b0

Please sign in to comment.