{"id":13463284,"url":"https://github.com/biola/turnout","last_synced_at":"2025-03-25T06:31:45.049Z","repository":{"id":41870930,"uuid":"2055082","full_name":"biola/turnout","owner":"biola","description":"Turnout makes it easy to put Rack apps into maintenance mode","archived":false,"fork":false,"pushed_at":"2024-06-17T14:17:12.000Z","size":126,"stargazers_count":579,"open_issues_count":7,"forks_count":93,"subscribers_count":18,"default_branch":"master","last_synced_at":"2024-10-29T13:50:44.269Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/biola.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"MIT-LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2011-07-15T19:04:08.000Z","updated_at":"2024-10-26T11:42:59.000Z","dependencies_parsed_at":"2022-08-11T19:50:28.940Z","dependency_job_id":null,"html_url":"https://github.com/biola/turnout","commit_stats":null,"previous_names":[],"tags_count":13,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/biola%2Fturnout","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/biola%2Fturnout/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/biola%2Fturnout/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/biola%2Fturnout/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/biola","download_url":"https://codeload.github.com/biola/turnout/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245414082,"owners_count":20611357,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-07-31T13:00:49.788Z","updated_at":"2025-03-25T06:31:44.653Z","avatar_url":"https://github.com/biola.png","language":"Ruby","readme":"Turnout [![Build Status](https://travis-ci.org/biola/turnout.svg?branch=master)](https://travis-ci.org/biola/turnout) [![Code Climate](https://codeclimate.com/github/biola/turnout.svg)](https://codeclimate.com/github/biola/turnout) [![Gem Version](https://badge.fury.io/rb/turnout.svg)](https://badge.fury.io/rb/turnout)\n=======\nTurnout is [Rack](http://rack.rubyforge.org/) middleware with a [Ruby on Rails](http://rubyonrails.org) engine that allows you to easily put your app in maintenance mode.\n\nFeatures\n========\n* Easy installation\n* Rake commands to turn maintenance mode on and off\n* Easily provide a reason for each downtime without editing the maintenance.html file\n* Allow certain IPs or IP ranges to bypass the maintenance page\n* Allow certain paths to be accessible during maintenance\n* Easily override the default maintenance.html file with your own\n* Simple [YAML](http://yaml.org) based config file for easy activation, deactivation and configuration without the rake commands\n* Support for multiple maintenance page formats. Current [HTML](http://en.wikipedia.org/wiki/HTML) and [JSON](http://en.wikipedia.org/wiki/JSON)\n* Supports Rails, [Sinatra](http://sinatrarb.com) and any other Rack application\n* Supports multiple maintenance file paths so that groups of applications can be put into maintenance mode at once.\n\nInstallation\n============\nRails 3+\n--------\nIn your `Gemfile` add:\n\n    gem 'turnout'\n\nthen run\n\n    bundle install\n    \n_Note that you'll need to restart your Rails server before it will work_\n\nSinatra\n-------\n\nIn your Sinatra app file\n\n```ruby\nrequire 'rack/turnout'\n\nclass App \u003c Sinatra::Base\n  configure do\n    use Rack::Turnout\n```\n\nIn your Rakefile\n\n```ruby\nrequire 'turnout/rake_tasks'\n```\n\nActivation\n==========\n\n    rake maintenance:start\n\nor\n\n    rake maintenance:start reason=\"Somebody googled Google!\"\n\nor\n\n    rake maintenance:start allowed_paths=\"/login,^/faqs/[0-9]*\"\n\nor\n\n    rake maintenance:start allowed_ips=\"4.8.15.16\"\n\nor\n\n    rake maintenance:start reason=\"Someone told me I should type \u003ccode\u003esudo rm -rf /\u003c/code\u003e\" allowed_paths=\"^/help,^/contact_us\" allowed_ips=\"127.0.0.1,192.168.0.0/24\"\n\nor if you've configured `named_maintenance_file_paths` with a path named `server`\n\n    rake maintenance:server:start\n\nNotes\n-----\n* The `reason` parameter can contain HTML\n* Multiple `allowed_paths` and `allowed_ips` can be given. Just comma separate them.\n* All `allowed_paths` are treated as regular expressions.\n* If you need to use a comma in an `allowed_paths` regular expression just escape it with a backslash: `\\,`.\n* IP ranges can be given to `allowed_ips` using [CIDR notation](http://en.wikipedia.org/wiki/CIDR_notation).\n\nDeactivation\n============\n\n    rake maintenance:end\n\nor if you activated with a named path like `server`\n\n    rake maintenance:server:end\n\nConfiguration\n=============\n\nTurnout can be configured in two different ways:\n\n1. __Pass a config hash to the middleware__\n\n    ```ruby\n    use Rack::Turnout,\n      app_root: '/some/path',\n      named_maintenance_file_paths: {app: 'tmp/app.yml', server: '/tmp/server.yml'},\n      maintenance_pages_path: 'app/views/maintenance',\n      default_maintenance_page: Turnout::MaintenancePage::JSON,\n      default_reason: 'Somebody googled Google!',\n      default_allowed_paths: ['^/admin/'],\n      default_response_code: 418,\n      default_retry_after: 3600\n    ```\n\n2. __Using a config block__\n\n    ```ruby\n    Turnout.configure do |config|\n      config.skip_middleware = true\n      config.app_root = '/some/path'\n      config.named_maintenance_file_paths = {app: 'tmp/app.yml', server: '/tmp/server.yml'}\n      config.maintenance_pages_path = 'app/views/maintenance'\n      config.default_maintenance_page = Turnout::MaintenancePage::JSON\n      config.default_reason = 'Somebody googled Google!'\n      config.default_allowed_paths = ['^/admin/']\n      config.default_response_code = 418\n      config.default_retry_after = 3600\n    end\n    ```\n\n__NOTICE:__ Any custom configuration should be loaded not only in the app but in the rake task. This should happen automatically in Rails as the `environment` task is run if it exists. But you may want to create your own `environment` task in non-Rails apps.\n\nDefault Configuration\n---------------------\n\n```ruby\nTurnout.configure do |config|\n  config.app_root = '.'\n  config.named_maintenance_file_paths = {default: config.app_root.join('tmp', 'maintenance.yml').to_s}\n  config.maintenance_pages_path = config.app_root.join('public').to_s\n  config.default_maintenance_page = Turnout::MaintenancePage::HTML\n  config.default_reason = \"The site is temporarily down for maintenance.\\nPlease check back soon.\"\n  config.default_allowed_paths = []\n  config.default_response_code = 503\n  config.default_retry_after = 7200\nend\n```\n\nCustomization\n=============\n\n[Default maintenance pages](https://github.com/biola/turnout/blob/master/public/) are provided, but you can create your own `public/maintenance.[html|json|html.erb]` files instead. If you provide a `reason` to the rake task, Turnout will parse the maintenance page file and attempt to replace a [Liquid](http://liquidmarkup.org/)-style `{{ reason }}` tag with the provided reason. So be sure to include a `{{ reason }}` tag in your `maintenance.html` file. In the case of a `.html.erb` file, `reason` will be a local variable.\n\n__WARNING:__\nThe source code of any custom maintenance files you created in the `/public` directory will be able to be viewed by visiting that URL directly (i.e. `http://example.com/maintenance.html.erb`). This shouldn't be an issue with HTML and JSON files but with ERB files, it could be. If you're going to use a custom `.erb.html` file, we recommend you change the `maintenance_pages_path` setting to something other than the `/public` directory.\n\nTips\n====\n\nDenied Paths\n--------------\nThere is no `denied_paths` feature because turnout denies everything by default.\nHowever you can achieve the same sort of functionality by using\n[negative lookaheads](http://www.regular-expressions.info/lookaround.html) with the `allowed_paths` setting, like so:\n\n    rake maintenance:start allowed_paths=\"^(?!/your/under/maintenance/path)\"\n\nMulti-App Maintenance\n------------------------\nA central `named_maintenance_file_path` can be configured in all your apps such as `/tmp/turnout.yml` so that all apps on a server can be put into mainteance mode at once. You could even configure service based paths such as `/tmp/mongodb_maintenance.yml` so that all apps using MongoDB could be put into maintenance mode.\n\nDetecting Maintenance Mode\n-------------------------------\n\nIf you'd like to detect if maintenance mode is on in your app (for those users or pages that aren't blocked) just call `!Turnout::MaintenanceFile.find.nil?`.\n\nBehind the Scenes\n=================\nOn every request the Rack app will check to see if `tmp/maintenance.yml` exists. If the file exists the maintenance page will be shown (unless allowed IPs are given and the requester is in the allowed range).\n\nSo if you want to get the maintenance page up or down in a hurry `touch tmp/maintenance.yml` and `rm tmp/maintenance.yml` will work.\n\nTurnout will attempt to parse the `maintenance.yml` file looking for `reason`, `allowed_ip` and other settings. The file is checked on every request so you can change these values manually or just rerun the `rake maintenance:start` command.\n\nExample maintenance.yml File\n----------------------------\n\n```yaml\n---\nreason: Someone told me I should type \u003ccode\u003esudo rm -rf /\u003c/code\u003e\nallowed_paths:\n- ^/help\n- ^/contact_us\nallowed_ips:\n- 127.0.0.1\n- 192.168.0.0/24\nresponse_code: 503\nretry_after: 3600\n```\n","funding_links":[],"categories":["Maintenance \u0026 Monitoring"],"sub_categories":["Maintenance Mode"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbiola%2Fturnout","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbiola%2Fturnout","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbiola%2Fturnout/lists"}