README.md in paratrooper-3.0.0.beta1 vs README.md in paratrooper-3.0.0.beta2
- old
+ new
@@ -9,45 +9,39 @@
## Installation
Add this line to your application's Gemfile:
```shell
- gem 'paratrooper'
+gem 'paratrooper'
```
and then execute
```shell
- bundle
+bundle
```
or
install it yourself with
```shell
- gem install paratrooper
+gem install paratrooper
```
## Usage
Instantiate Paratrooper with the name of your heroku application.
```ruby
-Paratrooper::Deploy.new('amazing-app')
+Paratrooper.deploy('amazing-app')
```
You can also provide a tag:
```ruby
-Paratrooper::Deploy.new('amazing-app', tag: 'staging')
-```
-
-or alternatively:
-
-```ruby
-Paratrooper::Deploy.new('amazing-app') do |deploy|
+Paratrooper.deploy('amazing-app') do |deploy|
deploy.tag = 'staging'
end
```
## Authentication
@@ -55,111 +49,74 @@
You can authenticate your Heroku account in a few ways:
* Provide an API Key
```ruby
-Paratrooper::Deploy.new('app', api_key: 'API_KEY')
+Paratrooper.deploy('app') do |deploy|
+ deploy.api_key = 'API_KEY'
+end
```
* Set an environment variable
```ruby
ENV['HEROKU_API_KEY'] = 'API_KEY'
-Paratrooper::Deploy.new('app')
+Paratrooper.deploy('app')
```
* Local Netrc file
```ruby
-Paratrooper::Deploy.new('app')
+Paratrooper.deploy('app')
```
This method works via a local Netrc file handled via the [Heroku Toolbelt][] and is the default and preferred method for providing authentication keys.
## Git SSH key configuration
If you use multiple SSH keys for managing multiple accounts, for example in your `.ssh/config`, you can set the `deployment_host` option:
```ruby
-Paratrooper::Deploy.new('app', deployment_host: 'HOST')
-```
-
-or alternatively:
-
-```ruby
-Paratrooper::Deploy.new('amazing-app') do |deploy|
+Paratrooper.deploy('amazing-app') do |deploy|
deploy.deployment_host = 'HOST'
end
```
This also works if you're using the [heroku-accounts](https://github.com/ddollar/heroku-accounts) plugin:
```ruby
-Paratrooper::Deploy.new('app', deployment_host: 'heroku.ACCOUNT_NAME')
+Paratrooper.deploy('app') do |deploy|
+ deploy.deployment_host: 'heroku.ACCOUNT_NAME'
+end
```
## Tag Management
-By providing tag options for Paratrooper, your code can be tagged and deployed from various reference points.
+Please note: Tag management has been removed from Paratrooper 3. It added unneccesary complexity around an individual's deployment process.
-### Staging example
-```ruby
- Paratrooper::Deploy.new("staging-app", tag: 'staging')
-```
-This will create/update a `staging` git tag at `HEAD`.
-
-### Production example
-```ruby
- Paratrooper::Deploy.new("amazing-production-app",
- tag: 'production',
- match_tag: 'staging'
- )
-```
-
-or alternatively:
-
-```ruby
-Paratrooper::Deploy.new('amazing-production-app') do |deploy|
- deploy.tag = 'production'
- deploy.match_tag = 'staging'
-end
-```
-This will create/update a `production` git tag at `staging` and deploy the `production` tag.
-
## Sensible Default Deployment
-You can use the object's methods any way you'd like, but we've provided a sensible default at `Paratrooper#deploy`.
+You can use the object's methods any way you'd like, but we've provided a sensible default at `Paratrooper.deploy`.
This will perform the following tasks:
-* Create or update a git tag (if provided)
* Push changes to Heroku
* Run database migrations if any have been added to db/migrate
-* Restart the application
-* Warm application instance
+* Restart the application if migrations needed to be run
### Example Usage
```ruby
-require 'paratrooper'
-
namespace :deploy do
desc 'Deploy app in staging environment'
task :staging do
- deployment = Paratrooper::Deploy.new("amazing-staging-app", tag: 'staging')
-
- deployment.deploy
+ Paratrooper.deploy("amazing-staging-app")
end
desc 'Deploy app in production environment'
task :production do
- deployment = Paratrooper::Deploy.new("amazing-production-app") do |deploy|
- deploy.tag = 'production'
- deploy.match_tag = 'staging'
- end
-
- deployment.deploy
+ Paratrooper.deploy("amazing-production-app")
end
end
```
## Bucking the Norm
@@ -172,11 +129,10 @@
There are 'before' and 'after' hooks for each of the following:
* setup
* activate_maintenance_mode
-* update_repo_tag
* push_repo
* run_migrations
* app_restart
* deactivate_maintenance_mode
* warm_instance
@@ -191,24 +147,21 @@
# lib/tasks/deploy.rake
namespace :deploy do
desc 'Deploy app in production environment'
task :production do
- deployment = Paratrooper::Deploy.new("amazing-production-app") do |deploy|
- deploy.tag = 'production'
- deploy.match_tag = 'staging'
+ Paratrooper.deploy("amazing-production-app") do |deploy|
deploy.add_callback(:before_setup) do |output|
output.display("Totally going to turn off newrelic")
system %Q[curl https://rpm.newrelic.com/accounts/ACCOUNT_ID/applications/APPLICATION_ID/ping_targets/disable -X POST -H "X-Api-Key: API_KEY"]
end
+
deploy.add_callback(:after_teardown) do |output|
system %Q[curl https://rpm.newrelic.com/accounts/ACCOUNT_ID/applications/APPLICATION_ID/ping_targets/enable -X POST -H "X-Api-Key: API_KEY"]
output.display("Aaaannnd we're back")
end
end
-
- deployment.deploy
end
end
```
Or maybe you just want to run a rake task on your application. Since this task may take a moment to complete it's probably a good idea to throw up a maintenance page.
@@ -217,18 +170,16 @@
# lib/tasks/deploy.rake
namespace :deploy do
desc 'Deploy app in production environment'
task :production do
- deployment = Paratrooper::Deploy.new("amazing-production-app") do |deploy|
+ Paratrooper.deploy("amazing-production-app") do |deploy|
deploy.maintenance = true
deploy.add_callback(:after_teardown) do |output|
output.display("Running some task that needs to run")
deploy.add_remote_task("rake some:task:to:run")
end
end
-
- deployment.deploy
end
end
```
## Contributing