From 6e4bed555b0a24a2169d326038ff94496ddc1947 Mon Sep 17 00:00:00 2001 From: Kevin McConnell Date: Tue, 5 Mar 2024 14:01:33 +0000 Subject: [PATCH] Update docs --- CONTRIBUTING.md | 4 ++- README.md | 66 ++++++++++++++++++++++++++++++++----------------- 2 files changed, 46 insertions(+), 24 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index a0d4a45..f37b535 100644 --- a/CONTRIBUTING.md +++ b/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` diff --git a/README.md b/README.md index 44f3fec..d6a5945 100644 --- a/README.md +++ b/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.