middleman-deploy/README.md

181 lines
4.9 KiB
Markdown
Raw Normal View History

# middleman-deploy [![Gem Version](https://badge.fury.io/rb/middleman-deploy.png)](http://badge.fury.io/rb/middleman-deploy)
2012-08-21 01:42:11 +02:00
2014-05-24 21:19:25 +02:00
## Help! middleman-deploy needs a new maintainer. Please [create a GitHub issue](https://github.com/tvaughan/middleman-deploy/issues) if you're interested. Thanks!
Deploys a [middleman](http://middlemanapp.com/) built site via **rsync**,
**ftp**, **sftp**, or **git** (e.g. gh-pages on github).
2012-08-22 19:06:47 +02:00
## Installation
2012-08-21 01:42:11 +02:00
Add this to the Gemfile of the repository of your middleman site:
2012-08-21 01:42:11 +02:00
```ruby
gem "middleman-deploy"
```
and run `bundle install`.
2012-08-21 01:42:11 +02:00
## Usage
2012-08-21 01:42:11 +02:00
```
$ middleman build [--clean]
$ middleman deploy [--build-before]
```
2012-08-21 01:42:11 +02:00
To automatically run `middleman build` during `middleman deploy`, turn on the
`build_before` option while activating the deploy extension:
2012-08-21 01:42:11 +02:00
```ruby
activate :deploy do |deploy|
# ...
deploy.build_before = true # default: false
end
```
2012-08-21 01:42:11 +02:00
## Possible Configurations
2012-08-21 01:42:11 +02:00
Middleman-deploy can deploy a site via rsync, ftp, sftp, or git.
2012-08-21 01:42:11 +02:00
2013-11-18 14:37:42 +01:00
Checkout [the wiki](https://github.com/tvaughan/middleman-deploy/wiki/_pages) for advanced set-up options.
### rsync
2012-10-04 20:22:16 +02:00
Make sure that `rsync` is installed, and activate the extension by adding the
following to `config.rb`:
2012-08-21 01:42:11 +02:00
```ruby
activate :deploy do |deploy|
deploy.method = :rsync
deploy.host = "www.example.com"
deploy.path = "/srv/www/site"
# Optional Settings
# deploy.user = "tvaughan" # no default
# deploy.port = 5309 # ssh port, default: 22
# deploy.clean = true # remove orphaned files on remote host, default: false
# deploy.flags = "-rltgoDvzO --no-p --del" # add custom flags, default: -avz
end
```
2012-08-21 01:42:11 +02:00
### Git (e.g. GitHub Pages)
2012-08-21 01:42:11 +02:00
Make sure that `git` is installed, and activate the extension by adding the
following to `config.rb`:
2012-08-21 01:42:11 +02:00
```ruby
activate :deploy do |deploy|
deploy.method = :git
# Optional Settings
# deploy.remote = "custom-remote" # remote name or git url, default: origin
# deploy.branch = "custom-branch" # default: gh-pages
# deploy.strategy = :submodule # commit strategy: can be :force_push or :submodule, default: :force_push
# deploy.commit_message = "custom-message" # commit message (can be empty), default: Automated commit at `timestamp` by middleman-deploy `version`
end
```
2012-08-21 01:42:11 +02:00
If you use a remote name, you must first add it using `git remote add`. Run
`git remote -v` to see a list of possible remote names. If you use a git url,
it must end with '.git'.
2012-08-21 01:42:11 +02:00
Afterwards, the `build` directory will become a git repo.
If you use the force push strategy, this branch will be created on the remote if
it doesn't already exist.
But if you use the submodule strategy, you must first initialize build folder as
a submodule. See `git submodule add` documentation.
2012-08-21 01:42:11 +02:00
### FTP
2012-08-21 01:47:42 +02:00
Activate the extension by adding the following to `config.rb`:
2012-08-21 01:42:11 +02:00
```ruby
activate :deploy do |deploy|
deploy.method = :ftp
deploy.host = "ftp.example.com"
deploy.path = "/srv/www/site"
deploy.user = "tvaughan"
deploy.password = "secret"
end
```
2012-08-21 01:42:11 +02:00
### SFTP
2012-08-21 01:47:42 +02:00
Activate the extension by adding the following to `config.rb`:
```ruby
activate :deploy do |deploy|
deploy.method = :sftp
deploy.host = "sftp.example.com"
2014-01-18 14:55:50 +01:00
deploy.port = 22
deploy.path = "/srv/www/site"
# Optional Settings
# deploy.user = "tvaughan" # no default
# deploy.password = "secret" # no default
end
```
2014-02-23 05:09:29 +01:00
### Multiple Environments
Deploy your site to more than one configuration using environment variables.
```ruby
# config.rb
case ENV['TARGET'].to_s.downcase
when 'production'
activate :deploy do |deploy|
deploy.method = :rsync
deploy.host = "www.example.com"
deploy.path = "/srv/www/production-site"
end
else
activate :deploy do |deploy|
deploy.method = :rsync
deploy.host = "staging.example.com"
deploy.path = "/srv/www/staging-site"
end
end
```
```ruby
# Rakefile
namespace :deploy do
def deploy(env)
puts "Deploying to #{env}"
system "TARGET=#{env} bundle exec middleman deploy"
2014-02-23 05:09:29 +01:00
end
task :staging do
deploy :staging
end
task :production do
deploy :production
end
end
```
$ rake deploy:staging
$ rake deploy:production
## Breaking Changes
2012-10-04 20:22:16 +02:00
* `v0.1.0`
- Removed the `--clean` command-line option. This option only applied to
the rsync deploy method. The idea going forward is that command-line
options must apply to all deploy methods. Options that are specific to a
deploy method will only be available in `config.rb`.
- Removed `deploy` from the `after_build` hook. This caused a `deploy` to
be run each time `build` was called. This workflow never made
sense. `deploy` was added to the `after_build` hook simply because it
was available.
## Thanks!
A **BIG** thanks to
[everyone who has contributed](https://github.com/tvaughan/middleman-deploy/graphs/contributors)!
Almost all pull requests are accepted.
## Other
2012-08-21 01:56:13 +02:00
Inspired by the rsync task in
[Octopress](https://github.com/imathis/octopress).