{"id":18648262,"url":"https://github.com/capistrano/maintenance","last_synced_at":"2025-04-13T07:50:13.883Z","repository":{"id":8244943,"uuid":"9689852","full_name":"capistrano/maintenance","owner":"capistrano","description":"Maintenance Page Support For Capistrano","archived":false,"fork":false,"pushed_at":"2022-10-19T08:35:09.000Z","size":37,"stargazers_count":154,"open_issues_count":3,"forks_count":32,"subscribers_count":9,"default_branch":"master","last_synced_at":"2024-04-26T01:20:46.324Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"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/capistrano.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2013-04-26T07:40:02.000Z","updated_at":"2023-07-21T23:24:26.000Z","dependencies_parsed_at":"2022-09-10T13:22:06.803Z","dependency_job_id":null,"html_url":"https://github.com/capistrano/maintenance","commit_stats":null,"previous_names":[],"tags_count":4,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/capistrano%2Fmaintenance","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/capistrano%2Fmaintenance/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/capistrano%2Fmaintenance/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/capistrano%2Fmaintenance/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/capistrano","download_url":"https://codeload.github.com/capistrano/maintenance/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248681494,"owners_count":21144700,"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-11-07T06:29:54.437Z","updated_at":"2025-04-13T07:50:13.861Z","avatar_url":"https://github.com/capistrano.png","language":"Ruby","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Capistrano::Maintenance\n\n## Installation\n\nAdd this line to your application's Gemfile:\n\n``` ruby\ngem 'capistrano', '~\u003e 3.11'\ngem 'capistrano-maintenance', '~\u003e 1.2', require: false\n```\n\nAnd then execute:\n\n``` bash\n$ bundle\n```\n\nOr install it yourself:\n\n``` bash\n$ gem install capistrano-maintenance\n```\n\n## Usage\n\nBefore using the maintenance tasks, you need to configure your webserver. How you do this depends on how your server is configured, but the following examples should help you on your way.\n\nApplication servers such as [Passenger](https://www.phusionpassenger.com) and [unicorn](http://unicorn.bogomips.org) requires you to set your public web directory to `current/public`. Both examples below are compatible with this setup.\n\nHere is an example config for **nginx**. Note that this is just a part of the complete config, and will probably require modifications.\n\n``` nginx\nerror_page 503 @503;\n\n# Return a 503 error if the maintenance page exists.\nif (-f /var/www/domain.com/shared/public/system/maintenance.html) {\n  return 503;\n}\n\nlocation @503 {\n  # Serve static assets if found.\n  if (-f $request_filename) {\n    break;\n  }\n\n  # Set root to the shared directory.\n  root /var/www/domain.com/shared/public;\n  rewrite ^(.*)$ /system/maintenance.html break;\n}\n```\n\nAnd here is an example config for **Apache**. This will also need to be modified.\n\n``` apache\n# Create an alias to the maintenance page used as error document.\nAlias \"/error\" \"/var/www/domain.com/shared/public/system/\"\nErrorDocument 503 /error/maintenance.html\n\n# Return 503 error if the maintenance page exists.\nRewriteCond /var/www/domain.com/shared/public/system/maintenance.html -f\nRewriteRule !^/error/maintenance.html - [L,R=503]\n\n# Redirect all non-static requests to unicorn (or similar).\n# Will not redirect any requests if the maintenance page exists.\nRewriteCond /var/www/domain.com/shared/public/system/maintenance.html !-f\nRewriteCond %{DOCUMENT_ROOT}/%{REQUEST_FILENAME} !-f\nRewriteRule ^/(.*)$ balancer://unicornserver%{REQUEST_URI} [P,QSA,L]\n```\n\nYou can now require the gem in your `Capfile`:\n\n```\nrequire 'capistrano/maintenance'\n```\n\n### Enable task\n\nPresent a maintenance page to visitors. Disables your application's web interface\nby writing a `\"#{maintenance_basename}.html\"` file to each web server. The\nservers must be configured to detect the presence of this file, and if\nit is present, always display it instead of performing the request.\n\nBy default, the maintenance page will just say the site is down for\n\"maintenance\", and will be back \"shortly\", but you can customize the\npage by specifying the REASON and UNTIL environment variables:\n\n```\ncap maintenance:enable REASON=\"hardware upgrade\" UNTIL=\"12pm Central Time\"\n```\n\nYou can use a different template for the maintenance page by setting the\n`:maintenance_template_path` variable in your deploy.rb file with an absolute path.\n\n```\nset :maintenance_template_path, File.expand_path(\"../../app/path/to/maintenance.html.erb\", __FILE__)\n```\n\nThe template file should either be a plaintext or an erb file. For example:\n\n``` html\n\u003c!DOCTYPE html\u003e\n\u003chtml\u003e\n\u003chead\u003e\n    \u003ctitle\u003eMaintenance\u003c/title\u003e\n    \u003cstyle type=\"text/css\"\u003e\n    body {\n        width: 400px;\n        margin: 100px auto;\n        font: 300 120% \"OpenSans\", \"Helvetica Neue\", \"Helvetica\", Arial, Verdana, sans-serif;\n    }\n\n    h1 {\n        font-weight: 300;\n    }\n    \u003c/style\u003e\n\u003c/head\u003e\n\u003cbody\u003e\n    \u003ch1\u003eMaintenance\u003c/h1\u003e\n\n    \u003cp\u003eThe system is down for \u003c%= reason ? reason : \"maintenance\" %\u003e\u003cbr\u003e\n           as of \u003c%= Time.now.strftime(\"%F %H:%M %Z\") %\u003e.\u003c/p\u003e\n\n    \u003cp\u003eIt'll be back \u003c%= deadline ? deadline : \"shortly\" %\u003e.\u003c/p\u003e\n\u003c/body\u003e\n\u003c/html\u003e\n```\n\nYou can customize which folder the maintenance page template is rendered to by\nsetting the `:maintenance_dirname` variable. By default it renders to\n`\"#{shared_path}/public/system\"`.\n\n```\nset :maintenance_dirname, -\u003e { \"#{current_path}/dist\" }\n```\n\nBy default, the maintenance page will be uploaded to all servers with the `web` role,\nbut if your application has different needs, you can customize this using the\n`maintenance_roles` variable:\n\n```\nset :maintenance_roles, -\u003e { roles([:web, :other_role]) }\n```\n\nFurther customization will require that you write your own task.\n\n### Disable task\n\n``` bash\ncap maintenance:disable\n```\n\nMakes the application web-accessible again. Removes the\n`\"#{maintenance_basename}.html\"` page generated by maintenance:enable, which (if your\nweb servers are configured correctly) will make your application web-accessible again.\n\n## Contributing\n\n1. Fork it\n2. Create your feature branch (`git checkout -b my-new-feature`)\n3. Commit your changes (`git commit -am 'Add some feature'`)\n4. Push to the branch (`git push origin my-new-feature`)\n5. Create new Pull Request\n\n## Authors\n\nThe original `capistrano-maintenance` gem was created by [Thomas von Deyen](https://github.com/tvdeyen) and the implementation for Capistrano 3 in this repo was written by [Kir Shatrov](https://github.com/kirs).\n\nAs a Capistrano team, we thank Thomas for collaboration and providing the push access to the `capistrano-maintenance` gem.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcapistrano%2Fmaintenance","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcapistrano%2Fmaintenance","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcapistrano%2Fmaintenance/lists"}