Update docs

CONTRIBUTING.md

@@ -18,7 +18,7 @@ You can also run individual tests using Go's test runner. For example:
 
 You can run the application using `go run`:
 
- go run cmd/thruster/main.go
+ go run ./cmd/thrust
 
 You can also build for the current environment using the Makefile:
 
@@ -39,6 +39,8 @@ In order to ship the platform-specific binary inside a gem, we actually build
 multiple gems, one for each platform. The `rake release` task will build all the
 necessary gems.
 
+The comlete steps for releasing a new version are:
+
 - Update the version & changelog:
  - [ ] update `lib/thruster/version.rb`
  - [ ] update `CHANGELOG.md`

README.md

@@ -2,24 +2,42 @@
 
 Thruster is an HTTP/2 proxy for simple production-ready deployments of Rails
 applications. It runs alongside the Puma webserver to provide a few additional
-features to help your app run efficiently and safely on the open Internet:
+features that help your app run efficiently and safely on the open Internet:
 
-- Automatic SSL certificate management with Let's Encrypt
 - HTTP/2 support
-- Basic HTTP caching
-- X-Sendfile support for efficient file serving
-- Automatic GZIP compression
+- Automatic SSL certificate management with Let's Encrypt
+- Basic HTTP caching of public assets
+- X-Sendfile support and compression, to efficiently serve static files
+
+Thruster aims to be as zero-config as possible. It has no configuration file,
+and most features are automatically enabled with sensible defaults. The goal is
+that simply running your Puma server with Thruster should be enough to get a
+production-ready setup.
+
+The only exception to this is SSL provisioning: in order for Thruster to
+provision SSL certificates, it needs to know which domain those certificates
+should be for. So to use SSL, you need to set the `SSL_DOMAIN` environment
+variable. If you don't set this variable, Thruster will run in HTTP-only mode.
 
-Thruster tries to be as zero-config as possible, so most features are
-automatically enabled with sensible defaults.
+Thruster also wraps the Puma process so that you can use it without managing
+multiple processes yourself. This is particularly useful when running in a
+containerized environment, where you typically won't have a process manager
+available to coordinate the processes. Instead you can use Thruster as your
+`CMD`, and it will manage Puma for you.
+
+Thruster was originally created for the [ONCE](https://once.com) project, where
+we wanted a no-fuss way to serve a Rails application from a single container,
+directly on the open Internet. We've since found it useful for simple
+deployments of other Rails applications.
 
-One exception to that is the `SSL_DOMAIN` environment variable, which is
-required to enable SSL provisioning. If `SSL_DOMAIN` is not set, Thruster will
-operate in HTTP-only mode.
 
 ## Installation
 
-Add this line to your application's Gemfile:
+Thruster is distributed as a Ruby gem. Because Thruster is written in Go, we
+provide several pre-built platform-specific binaries. Installing the gem will
+automatically fetch the approach binary for your platform.
+
+To install it, add it to your application's Gemfile:
 
 ```ruby
 gem 'thruster'
@@ -31,6 +49,7 @@ Or install it globally:
 $ gem install thruster
 ```
 
+
 ## Usage
 
 To run your Puma application inside Thruster, prefix your usual command string
@@ -46,27 +65,23 @@ Or with automatic SSL:
 $ SSL_DOMAIN=myapp.example.com thrust bin/rails server
 ```
 
-## Custom configuration
 
-Thruster provides a number of environment variables that can be used to
-customize its behavior.
+## Custom configuration
 
-To prevent naming clashes with your application's own environment variables,
-Thruster's environment variables can optionally be prefixed with `THRUSTER_`.
-For example, `SSL_DOMAIN` can also be set as `THRUSTER_SSL_DOMAIN`. Whenever a
-prefixed variable is set, Thruster will use it in preference to the unprefixed
-version.
+In most cases, Thruster should work out of the box with no additional
+configuration. But if you need to customize its behavior, there are a few
+environment variables that you can set.
 
 | Variable Name | Description | Default Value |
 |-----------------------|---------------------------------------------------------------------------------|---------------|
 | `SSL_DOMAIN` | The domain name to use for SSL provisioning. If not set, SSL will be disabled. | None |
-| `TARGET_PORT` | The port that your Puma server should run on. Thruster will set `PORT` to this when starting your server. | 3000 |
+| `TARGET_PORT` | The port that your Puma server should run on. Thruster will set `PORT` to this value when starting your server. | 3000 |
 | `CACHE_SIZE` | The size of the HTTP cache in bytes. | 64MB |
 | `MAX_CACHE_ITEM_SIZE` | The maximum size of a single item in the HTTP cache in bytes. | 1MB |
 | `X_SENDFILE_ENABLED` | Whether to enable X-Sendfile support. Set to `0` or `false` to disable. | Enabled |
-| `MAX_REQUEST_BODY` | The maximum size of a request body in bytes. Requests larger than this size will be refused; `0` means no maximum size. | `0` |
-| `STORAGE_PATH` | The path to store Thruster's internal state.   | `./storage/thruster` |
-| `BAD_GATEWAY_PAGE` | Path to an HTML file to serve when the backend server returns a 502 Bad Gateway error. If there is no file at the specific path, Thruster will serve an empty 502 response instead. | `./public/502.html` |
+| `MAX_REQUEST_BODY` | The maximum size of a request body in bytes. Requests larger than this size will be refused; `0` means no maximum size is enforced. | `0` |
+| `STORAGE_PATH` | The path to store Thruster's internal state. Provisioned SSL certificates will be stored here, so that they will not need to be requested every time your application is started. | `./storage/thruster` |
+| `BAD_GATEWAY_PAGE` | Path to an HTML file to serve when the backend server returns a 502 Bad Gateway error. If there is no file at the specific path, Thruster will serve an empty 502 response instead. Because Thruster boots very quickly, a custom page can be a useful way to show that your application is starting up. | `./public/502.html` |
 | `HTTP_PORT` | The port to listen on for HTTP traffic. | 80 |
 | `HTTPS_PORT` | The port to listen on for HTTPS traffic. | 443 |
 | `HTTP_IDLE_TIMEOUT` | The maximum time in seconds that a client can be idle before the connection is closed. | 60 |
@@ -76,3 +91,8 @@ version.
 | `EAB_KID` | The EAB key identifier to use when provisioning SSL certificates, if required. | None |
 | `EAB_HMAC_KEY` | The Base64-encoded EAB HMAC key to use when provisioning SSL certificates, if required. | None |
 | `DEBUG` | Set to `1` or `true` to enable debug logging. | Disabled |
+
+To prevent naming clashes with your application's own environment variables,
+Thruster's environment variables can optionally be prefixed with `THRUSTER_`.
+For example, `SSL_DOMAIN` can also be written as `THRUSTER_SSL_DOMAIN`. Whenever
+a prefixed variable is set, it will take precedence over the unprefixed version.