mina 0.3.0 → 0.3.1

Sign up to get free protection for your applications and to get access to all the features.
Files changed (49) hide show
  1. data/.gitignore +2 -0
  2. data/.travis.yml +14 -5
  3. data/HISTORY.md +45 -1
  4. data/LICENSE +1 -1
  5. data/Makefile +29 -0
  6. data/Notes.md +70 -0
  7. data/Readme.md +1009 -0
  8. data/bin/mina +1 -1
  9. data/data/deploy.rb +13 -7
  10. data/lib/mina/bundler.rb +6 -1
  11. data/lib/mina/chruby.rb +49 -0
  12. data/lib/mina/default.rb +1 -0
  13. data/lib/mina/deploy.rb +17 -1
  14. data/lib/mina/deploy_helpers.rb +4 -4
  15. data/lib/mina/exec_helpers.rb +26 -19
  16. data/lib/mina/foreman.rb +5 -1
  17. data/lib/mina/git.rb +1 -1
  18. data/lib/mina/helpers.rb +22 -13
  19. data/lib/mina/rails.rb +6 -6
  20. data/lib/mina/rbenv.rb +1 -0
  21. data/lib/mina/rvm.rb +2 -4
  22. data/lib/mina/ssh_helpers.rb +2 -1
  23. data/lib/mina/version.rb +1 -1
  24. data/lib/mina/whenever.rb +6 -6
  25. data/mina.gemspec +2 -2
  26. data/spec/command_helper.rb +1 -1
  27. data/spec/commands/cleanup_spec.rb +16 -0
  28. data/spec/commands/command_spec.rb +18 -18
  29. data/spec/commands/custom_config_spec.rb +2 -2
  30. data/spec/commands/deploy_spec.rb +7 -7
  31. data/spec/commands/outside_project_spec.rb +7 -7
  32. data/spec/commands/real_deploy_spec.rb +21 -21
  33. data/spec/commands/verbose_spec.rb +2 -2
  34. data/spec/dsl/invoke_spec.rb +17 -2
  35. data/spec/dsl/queue_spec.rb +4 -4
  36. data/spec/dsl/settings_in_rake_spec.rb +6 -6
  37. data/spec/dsl/settings_spec.rb +16 -10
  38. data/spec/dsl/to_spec.rb +2 -2
  39. data/spec/helpers/exec_helper_spec.rb +19 -0
  40. data/spec/spec_helper.rb +6 -0
  41. data/support/Readme-footer.md +32 -0
  42. data/support/Readme-header.md +16 -0
  43. data/support/guide.md +297 -0
  44. data/support/index.html +53 -0
  45. data/support/to_md.rb +11 -0
  46. data/test_env/config/deploy.rb +2 -0
  47. metadata +96 -61
  48. checksums.yaml +0 -7
  49. data/README.md +0 -114
data/Readme.md ADDED
@@ -0,0 +1,1009 @@
1
+ # Mina
2
+
3
+ Really fast deployer and server automation tool.
4
+
5
+ Mina works really fast because it's a deploy Bash script generator. It
6
+ generates an entire procedure as a Bash script and runs it remotely in the
7
+ server.
8
+
9
+ Compare this to the likes of Vlad or Capistrano, where each command
10
+ is run separately on their own SSH sessions. Mina only creates *one* SSH
11
+ session per deploy, minimizing the SSH connection overhead.
12
+
13
+ $ gem install mina
14
+ $ mina
15
+
16
+ [![Build Status](https://travis-ci.org/mina-deploy/mina.svg?branch=master)](https://travis-ci.org/mina-deploy/mina) [![Gem Version](https://badge.fury.io/rb/mina.svg)](http://badge.fury.io/rb/mina)
17
+
18
+ User guide
19
+ ==========
20
+
21
+ Setting up a project
22
+ --------------------
23
+
24
+ Let's deploy a project using Mina.
25
+
26
+ ### Step 1: Create a config/deploy.rb
27
+
28
+ In your project, type `mina init` to create a sample of this file.
29
+
30
+ $ mina init
31
+ Created config/deploy.rb.
32
+
33
+ This is just a Rake file with tasks! See [About deploy.rb](#about-deployrb) for
34
+ more info on what *deploy.rb* is. You will want to at least configure your
35
+ server:
36
+
37
+ ~~~ ruby
38
+ # config/deploy.rb
39
+ set :user, 'username'
40
+ set :domain, 'your.server.com'
41
+ set :deploy_to, '/var/www/flipstack.com'
42
+ ...
43
+ ~~~
44
+
45
+ ### Step 2: Set up your server
46
+
47
+ Make a directory in your server called `/var/www/flipstack.com` (in *deploy_to*)
48
+ change it's ownership to the correct user.
49
+
50
+ $ ssh username@your.server.com
51
+
52
+ # Once in your server, create the deploy folder:
53
+ ~@your.server.com$ mkdir /var/www/flipstack.com
54
+ ~@your.server.com$ chown -R username /var/www/flipstack.com
55
+
56
+ ### Step 3: Run 'mina setup'
57
+
58
+ Back at your computer, do `mina setup` to set up the [folder
59
+ structure](#directory_structure) in this path. This will connect to your server
60
+ via SSH and create the right directories.
61
+
62
+ $ mina setup
63
+ -----> Creating folders... done.
64
+
65
+ See [directory structure](#directory-structure) for more info.
66
+
67
+ ### Step 4: Deploy!
68
+
69
+ Use `mina deploy` to run the `deploy` task defined in *config/deploy.rb*.
70
+
71
+ $ mina deploy
72
+ -----> Deploying to 2012-06-12-040248
73
+ ...
74
+ Lots of things happening...
75
+ ...
76
+ -----> Done.
77
+
78
+ About deploy.rb
79
+ ---------------
80
+
81
+ The file `deploy.rb` is simply a Rakefile invoked by Rake. In fact, `mina` is
82
+ mostly an alias that invokes Rake to load `deploy.rb`.
83
+
84
+ ~~~ ruby
85
+ # Sample config/deploy.rb
86
+ set :domain, 'your.server.com'
87
+
88
+ task :restart do
89
+ queue 'sudo service restart apache'
90
+ end
91
+ ~~~
92
+
93
+ As it's all Rake, you can define tasks that you can invoke using `mina`. In this
94
+ example, it provides the `mina restart` command.
95
+
96
+ The magic of Mina is in the new commands it gives you.
97
+
98
+ The `queue` command queues up Bash commands to be run on the remote server.
99
+ If you invoke `mina restart`, it will invoke the task above and run the queued
100
+ commands on the remote server `your.server.com` via SSH.
101
+
102
+ See [the command queue](#the-command-queue) for more information on the *queue*
103
+ command.
104
+
105
+ The command queue
106
+ -----------------
107
+
108
+ At the heart of it, Mina is merely sugar on top of Rake to queue commands
109
+ and execute them remotely at the end. Take a look at this minimal *deploy.rb*
110
+ configuration:
111
+
112
+ ~~~ ruby
113
+ # config/deploy.rb
114
+ set :user, 'john'
115
+ set :domain, 'flipstack.com'
116
+
117
+ task :logs do
118
+ queue 'echo "Contents of the log file are as follows:"'
119
+ queue "tail -f /var/log/apache.log"
120
+ end
121
+ ~~~
122
+
123
+ Once you type `mina logs` in your terminal, it invokes the *queue*d commands
124
+ remotely on the server using the command `ssh john@flipstack.com`.
125
+
126
+ ~~~ sh
127
+ $ mina logs --simulate
128
+ # Execute the following commands via
129
+ # ssh john@flipstack.com:
130
+ #
131
+ echo "Contents of the log file are as follows:"
132
+ tail -f /var/log/apache.log
133
+ ~~~
134
+
135
+ Subtasks
136
+ --------
137
+
138
+ Mina provides the helper `invoke` to invoke other tasks from a
139
+ task.
140
+
141
+ ~~~ ruby
142
+ # config/deploy.rb
143
+ task :down do
144
+ invoke :maintenance_on
145
+ invoke :restart
146
+ end
147
+
148
+ task :maintenance_on
149
+ queue 'touch maintenance.txt'
150
+ end
151
+
152
+ task :restart
153
+ queue 'sudo service restart apache'
154
+ end
155
+ ~~~
156
+
157
+ In this example above, if you type `mina down`, it simply invokes the other
158
+ subtasks which queues up their commands. The commands will be run after
159
+ everything.
160
+
161
+ Directory structure
162
+ -------------------
163
+
164
+ The deploy procedures make the assumption that you have a folder like so:
165
+
166
+ /var/www/flipstack.com/ # The deploy_to path
167
+ |- releases/ # Holds releases, one subdir per release
168
+ | |- 1/
169
+ | |- 2/
170
+ | |- 3/
171
+ | '- ...
172
+ |- shared/ # Holds files shared between releases
173
+ | |- logs/ # Log files are usually stored here
174
+ | `- ...
175
+ '- current/ # A symlink to the current release in releases/
176
+
177
+ It also assumes that the `deploy_to` path is fully writeable/readable for the
178
+ user we're going to SSH with.
179
+
180
+ Deploying
181
+ ---------
182
+
183
+ Mina provides the `deploy` command which *queue*s up a deploy script for
184
+ you.
185
+
186
+ ~~~ ruby
187
+ # config/deploy.rb
188
+ set :domain, 'flipstack.com'
189
+ set :user, 'flipstack'
190
+ set :deploy_to, '/var/www/flipstack.com'
191
+ set :repository, 'http://github.com/flipstack/flipstack.git'
192
+
193
+ task :deploy do
194
+ deploy do
195
+ # Put things that prepare the empty release folder here.
196
+ # Commands queued here will be run on a new release directory.
197
+ invoke :'git:clone'
198
+ invoke :'bundle:install'
199
+
200
+ # These are instructions to start the app after it's been prepared.
201
+ to :launch do
202
+ queue "mkdir -p #{deploy_to}/#{current_path}/tmp/"
203
+ queue "touch #{deploy_to}/#{current_path}/tmp/restart.txt"
204
+ end
205
+
206
+ # This optional block defines how a broken release should be cleaned up.
207
+ to :clean do
208
+ queue 'log "failed deployment"'
209
+ end
210
+ end
211
+ end
212
+ ~~~
213
+
214
+ It works by capturing the *queue*d commands inside the block, wrapping them
215
+ in a deploy script, then *queue*ing them back in.
216
+
217
+ ### How deploying works
218
+
219
+ Here is an example of a deploy! (Note that some commands have been simplified
220
+ to illustrate the point better.)
221
+
222
+ ### Step 1: Build it
223
+
224
+ The deploy process builds a new temp folder with instructions you provide.
225
+ In this example, it will do `git:clone` and `bundle:install`.
226
+
227
+ $ mina deploy --verbose
228
+ -----> Creating the build path
229
+ $ mkdir tmp/build-128293482394
230
+ -----> Cloning the Git repository
231
+ $ git clone https://github.com/flipstack/flipstack.git . -n --recursive
232
+ Cloning... done.
233
+ -----> Installing gem dependencies using Bundler
234
+ $ bundle install --without development:test
235
+ Using i18n (0.6.0)
236
+ Using multi_json (1.0.4)
237
+ ...
238
+ Your bundle is complete! It was installed to ./vendor/bundle
239
+
240
+ ### Step 2: Move it to releases
241
+
242
+ Once the project has been built, it will be moved to `releases/`. A symlink
243
+ called `current/` will be created to point to the active release.
244
+
245
+ $
246
+ -----> Moving to releases/4
247
+ $ mv "./tmp/build-128293482394" "releases/4"
248
+ -----> Symlinking to current
249
+ $ ln -nfs releases/4 current
250
+
251
+ ### Step 3: Launch it
252
+
253
+ Invoke the commands queued up in the `to :launch` block. These often
254
+ commands to restart the webserver process. Once this in complete, you're done!
255
+
256
+ $
257
+ -----> Launching
258
+ $ cd releases/4
259
+ $ sudo service nginx restart
260
+ -----> Done. Deployed v4
261
+
262
+ ### What about failure?
263
+
264
+ If it fails at any point, the release path will be deleted. If any commands are
265
+ queued using the `to :clean` block, they will be run. It will be as if nothing
266
+ happened. Lets see what happens if a build fails:
267
+
268
+ $
269
+ -----> Launching
270
+ $ cd releases/4
271
+ $ sudo service nginx restart
272
+ Starting nginx... error: can't start service
273
+ -----> ERROR: Deploy failed.
274
+ -----> Cleaning up build
275
+ $ rm -rf tmp/build-128293482394
276
+ -----> Unlinking current
277
+ $ ln -nfs releases/3 current
278
+ OK
279
+
280
+ Command line options
281
+ --------------------
282
+
283
+ Basic usage:
284
+
285
+ $ mina [OPTIONS] [TASKS] [VAR1=val VAR2=val ...]
286
+
287
+ ### Options
288
+
289
+ * `-v` / `--verbose` - This will show commands being done on the server. Off by
290
+ default.
291
+
292
+ * `-S` / `--simulate` - This will not invoke any SSH connections; instead, it
293
+ will simply output the script it builds.
294
+
295
+ * `-t` / `--trace` - Show backtraces when errors occur.
296
+
297
+ * `-f FILE` - Use a custom deploy.rb configuration.
298
+
299
+ * `-V` / `--version` - Shows the current version.
300
+
301
+ ### Tasks
302
+
303
+ There are many tasks available. See the [tasks reference](http://mina-deploy.github.io/mina/tasks/index.html), or
304
+ type `mina tasks`.
305
+
306
+ ### Variables
307
+
308
+ You may specify additional variables in the `KEY=value` style, just like Rake.
309
+ You can add as many variables as needed.
310
+
311
+ $ mina restart on=staging
312
+
313
+ # This sets the ENV['on'] variable to 'staging'.
314
+
315
+
316
+ # Helpers
317
+
318
+ ### invoke
319
+ Invokes another Rake task. By default if the task has already been invoked it will not been executed again (see the `:reenable` option).
320
+
321
+ Invokes the task given in `task`. Returns nothing.
322
+
323
+ ~~~ ruby
324
+ invoke :'git:clone'
325
+ invoke :restart
326
+ ~~~
327
+
328
+ __Options:__
329
+ `:reenable` (bool) - Execute the task even next time. Defaults to `false`
330
+
331
+ ### erb
332
+ Evaluates an ERB block in the current scope and returns a string.
333
+
334
+ ~~~ ruby
335
+ a = 1
336
+ b = 2
337
+ # Assuming foo.erb is <%= a %> and <%= b %>
338
+ puts erb('foo.erb')
339
+ #=> "1 and 2"
340
+ ~~~
341
+
342
+ Returns the output string of the ERB template.
343
+
344
+ ### run!
345
+ SSHs into the host and runs the code that has been queued.
346
+
347
+ This is already automatically invoked before Rake exits to run all
348
+ commands that have been queued up.
349
+
350
+ ~~~ ruby
351
+ queue "sudo restart"
352
+ run!
353
+ ~~~
354
+
355
+ Returns nothing.
356
+
357
+ ### report_time
358
+ Report time elapsed in the block.
359
+ Returns the output of the block.
360
+
361
+ ~~~ ruby
362
+ report_time do
363
+ sleep 2
364
+ # do other things
365
+ end
366
+ # Output:
367
+ # Elapsed time: 2.00 seconds
368
+ ~~~
369
+
370
+ ### measure
371
+ Measures the time (in seconds) a block takes.
372
+ Returns a [time, output] tuple.
373
+
374
+ ### mina_cleanup
375
+ __Internal:__ Invoked when Rake exits.
376
+
377
+ Returns nothing.
378
+
379
+ ## Errors
380
+
381
+ ### die
382
+ Exits with a nice looking message.
383
+ Returns nothing.
384
+
385
+ ~~~ ruby
386
+ die 2
387
+ die 2, "Tests failed"
388
+ ~~~
389
+
390
+ ### error
391
+ __Internal:__ Prints to stdout.
392
+ Consider using `print_error` instead.
393
+
394
+ ## Queueing
395
+
396
+ ### queue
397
+ Queues code to be run.
398
+
399
+ This queues code to be run to the current code bucket (defaults to `:default`).
400
+ To get the things that have been queued, use commands[:default]
401
+
402
+ Returns nothing.
403
+
404
+ ~~~ ruby
405
+ queue "sudo restart"
406
+ queue "true"
407
+ commands == ['sudo restart', 'true']
408
+ ~~~
409
+
410
+ ### queue!
411
+ Shortcut for `queue`ing a command that shows up in verbose mode.
412
+
413
+ ### echo_cmd
414
+ Converts a bash command to a command that echoes before execution.
415
+ Used to show commands in verbose mode. This does nothing unless verbose mode is on.
416
+
417
+ Returns a string of the compound bash command, typically in the format of
418
+ `echo xx && xx`. However, if `verbose_mode?` is false, it returns the
419
+ input string unharmed.
420
+
421
+ ~~~ ruby
422
+ echo_cmd("ln -nfs releases/2 current")
423
+ #=> echo "$ ln -nfs releases/2 current" && ln -nfs releases/2 current
424
+ ~~~
425
+
426
+ ## Commands
427
+
428
+ ### commands
429
+ Returns an array of queued code strings.
430
+
431
+ You may give an optional `aspect`.
432
+
433
+ Returns an array of strings.
434
+
435
+ ~~~ ruby
436
+ queue "sudo restart"
437
+ queue "true"
438
+ to :clean do
439
+ queue "rm"
440
+ end
441
+ commands == ["sudo restart", "true"]
442
+ commands(:clean) == ["rm"]
443
+ ~~~
444
+
445
+ ### isolate
446
+ Starts a new block where new `commands` are collected.
447
+
448
+ Returns nothing.
449
+
450
+ ~~~ ruby
451
+ queue "sudo restart"
452
+ queue "true"
453
+ commands.should == ['sudo restart', 'true']
454
+ isolate do
455
+ queue "reload"
456
+ commands.should == ['reload']
457
+ end
458
+ commands.should == ['sudo restart', 'true']
459
+ ~~~
460
+
461
+ ### in_directory
462
+ Starts a new block where #commands are collected, to be executed inside `path`.
463
+
464
+ Returns nothing.
465
+
466
+ ~~~ ruby
467
+ in_directory './webapp' do
468
+ queue "./reload"
469
+ end
470
+ commands.should == ['cd ./webapp && (./reload && true)']
471
+ ~~~
472
+
473
+ ### to
474
+ Defines instructions on how to do a certain thing.
475
+ This makes the commands that are `queue`d go into a different bucket in commands.
476
+
477
+ Returns nothing.
478
+
479
+ ~~~ ruby
480
+ to :prepare do
481
+ run "bundle install"
482
+ end
483
+ to :launch do
484
+ run "nginx -s restart"
485
+ end
486
+ commands(:prepare) == ["bundle install"]
487
+ commands(:restart) == ["nginx -s restart"]
488
+ ~~~
489
+
490
+ ## Settings helpers
491
+
492
+ ### set
493
+ Sets settings.
494
+ Sets given symbol `key` to value in `value`.
495
+
496
+ Returns the value.
497
+
498
+ ~~~ ruby
499
+ set :domain, 'kickflip.me'
500
+ ~~~
501
+
502
+ ### set_default
503
+ Sets default settings.
504
+ Sets given symbol `key` to value in `value` only if the key isn't set yet.
505
+
506
+ Returns the value.
507
+
508
+ ~~~ ruby
509
+ set_default :term_mode, :pretty
510
+ set :term_mode, :system
511
+ settings.term_mode.should == :system
512
+ set :term_mode, :system
513
+ set_default :term_mode, :pretty
514
+ settings.term_mode.should == :system
515
+ ~~~
516
+
517
+ ### settings
518
+ Accesses the settings hash.
519
+
520
+ ~~~ ruby
521
+ set :domain, 'kickflip.me'
522
+ settings.domain #=> 'kickflip.me'
523
+ domain #=> 'kickflip.me'
524
+ ~~~
525
+
526
+ ### method_missing
527
+ Hook to get settings.
528
+ See #settings for an explanation.
529
+
530
+ Returns things.
531
+
532
+ ## Command line mode helpers
533
+
534
+ ### verbose_mode?
535
+ Checks if Rake was invoked with --verbose.
536
+
537
+ Returns true or false.
538
+
539
+ ~~~ ruby
540
+ if verbose_mode?
541
+ queue %[echo "-----> Starting a new process"]
542
+ end
543
+ ~~~
544
+
545
+ ### simulate_mode?
546
+ Checks if Rake was invoked with --simulate.
547
+
548
+ Returns true or false.
549
+
550
+ ## Internal helpers
551
+
552
+ ### indent
553
+ Indents a given code block with `count` spaces before it.
554
+
555
+ ### unindent
556
+ __Internal:__ Normalizes indentation on a given string.
557
+
558
+ Returns the normalized string without extraneous indentation.
559
+
560
+ ~~~ ruby
561
+ puts unindent %{
562
+ Hello
563
+ There
564
+ }
565
+ # Output:
566
+ # Hello
567
+ # There
568
+ ~~~
569
+
570
+ ### reindent
571
+ Resets the indentation on a given code block.
572
+
573
+ ### capture
574
+ Returns the output of command via SSH.
575
+
576
+ # Helpers: Deploy helpers
577
+ Helpers for deployment.
578
+
579
+ ### deploy
580
+ Wraps the things inside it in a deploy script and queues it.
581
+ This generates a script using deploy_script and queues it.
582
+
583
+ Returns nothing.
584
+
585
+ ### deploy_script
586
+ Wraps the things inside it in a deploy script.
587
+
588
+ ~~~ ruby
589
+ script = deploy_script do
590
+ invoke :'git:checkout'
591
+ end
592
+ queue script
593
+ ~~~
594
+
595
+ Returns the deploy script as a string, ready for `queue`ing.
596
+
597
+ # Modules: Bundler
598
+ Adds settings and tasks for managing Ruby Bundler.
599
+
600
+ ~~~ ruby
601
+ require 'mina/bundler'
602
+ ~~~
603
+
604
+ ## Settings
605
+ Any and all of these settings can be overriden in your `deploy.rb`.
606
+
607
+ ### bundle_bin
608
+ Sets the bundle path.
609
+
610
+ ### bundle_path
611
+ Sets the path to where the gems are expected to be.
612
+
613
+ This path will be symlinked to `./shared/bundle` so that the gems cache will
614
+ be shared between all releases.
615
+
616
+ ### bundle_options
617
+ Sets the options for installing gems via Bundler.
618
+
619
+ ## Deploy tasks
620
+ These tasks are meant to be invoked inside deploy scripts, not invoked on
621
+ their own.
622
+
623
+ ### bundle:install
624
+ Installs gems.
625
+
626
+ # Modules: Default
627
+ This module is loaded when invoking `mina` with or without a project.
628
+
629
+ ## Settings
630
+ Here are some of the common settings. All settings are optional unless
631
+ otherwise noted.
632
+
633
+ ### deploy_to
634
+ (Required) Path to deploy to.
635
+
636
+ ### domain
637
+ (Required) Host name to deploy to.
638
+
639
+ ### port
640
+ SSH port number.
641
+
642
+ ### forward_agent
643
+ If set to `true`, enables SSH agent forwarding.
644
+
645
+ ### identity_file
646
+ The local path to the SSH private key file.
647
+
648
+ ### ssh_options
649
+ Switches to be passed to the `ssh` command.
650
+
651
+ ## Tasks
652
+ Any and all of these settings can be overriden in your `deploy.rb`.
653
+
654
+ ### environment
655
+ Make the `:environment` task exist by default. This is meant to be overridden
656
+ by users.
657
+
658
+ ### init
659
+ Initializes a new Mina project.
660
+
661
+ ~~~ ruby
662
+ $ mina init
663
+ ~~~
664
+
665
+ ### help
666
+ Shows the help screen.
667
+
668
+ ### tasks
669
+ Display all tasks in a nice table.
670
+
671
+ ~~~ ruby
672
+ $ mina tasks
673
+ ~~~
674
+
675
+ # Modules: Deployment
676
+ This module is automatically loaded for all Mina projects.
677
+
678
+ ## Settings
679
+ Any and all of these settings can be overriden in your `deploy.rb`.
680
+
681
+ ### releases_path
682
+ (default: 'releases')
683
+
684
+ ### shared_path
685
+ (default: 'shared')
686
+
687
+ ### current_path
688
+ (default: 'current_path')
689
+
690
+ ### lock_file
691
+ Name of the file to generate while a deploy is currently ongoing.
692
+ (default: 'deploy.lock')
693
+
694
+ ### keep_releases
695
+ Number of releases to keep when doing the `deploy:cleanup` task.
696
+ (default: 5)
697
+
698
+ ## Tasks
699
+
700
+ ### deploy:force_unlock
701
+ Forces a deploy unlock by deleting the lock file.
702
+
703
+ ~~~ ruby
704
+ $ mina deploy:force_unlock
705
+ ~~~
706
+
707
+ You can also combine that task with `deploy`:
708
+
709
+ ~~~ ruby
710
+ $ mina deploy:force_unlock deploy
711
+ ~~~
712
+
713
+ ### deploy:link_shared_paths
714
+ Links the shared paths in the `shared_paths` setting.
715
+
716
+ ### deploy:cleanup
717
+ Cleans up old releases.
718
+
719
+ By default, the last 5 releases are kept on each server (though you can
720
+ change this with the keep_releases setting). All other deployed revisions
721
+ are removed from the servers."
722
+
723
+ ### setup
724
+ Sets up a site's directory structure.
725
+
726
+ ### run[]
727
+ Runs a command on a server.
728
+
729
+ ~~~ ruby
730
+ $ mina run[tail -f logs.txt]
731
+ ~~~
732
+
733
+ # Modules: Foreman
734
+ Adds settings and tasks for managing projects with [foreman].
735
+
736
+ NOTE: Requires sudo privileges
737
+
738
+ [foreman]: http://rubygems.org/ddolar/foreman
739
+
740
+ require 'mina/foreman'
741
+
742
+ ## Common usage
743
+
744
+ set :application, "app-name"
745
+
746
+ task :deploy => :environment do
747
+ ~~~ ruby
748
+ deploy do
749
+ # ...
750
+ invoke 'foreman:export'
751
+ # ...
752
+ end
753
+ to :launch do
754
+ invoke 'foreman:restart'
755
+ end
756
+ ~~~
757
+
758
+ end
759
+
760
+ ## Settings
761
+ Any and all of these settings can be overriden in your `deploy.rb`.
762
+
763
+ ### foreman_app
764
+ Sets the service name that foreman will export to upstart. Uses *application*
765
+ variable as a default. It should be set, otherwise export command will fail.
766
+
767
+ ### foreman_user
768
+ Sets the user under which foreman will execute the service. Defaults to *user*
769
+
770
+ ### foreman_log
771
+ Sets the foreman log path. Defaults to *shared/log*
772
+
773
+ encoding: utf-8
774
+
775
+ # Modules: Git
776
+ Adds settings and tasks related to managing Git.
777
+
778
+ ~~~ ruby
779
+ require 'mina/git'
780
+ ~~~
781
+
782
+ ## Settings
783
+ Any and all of these settings can be overriden in your `deploy.rb`.
784
+
785
+ ### branch
786
+ Sets the branch to be deployed.
787
+
788
+ ## Deploy tasks
789
+ These tasks are meant to be invoked inside deploy scripts, not invoked on
790
+ their own.
791
+
792
+ ### git:clone
793
+ Clones the Git repository. Meant to be used inside a deploy script.
794
+
795
+ # Modules: Rails
796
+ Adds settings and tasks for managing Rails projects.
797
+
798
+ ~~~ ruby
799
+ require 'mina/rails'
800
+ ~~~
801
+
802
+ ## Settings
803
+ Any and all of these settings can be overriden in your `deploy.rb`.
804
+
805
+ ### rails_env
806
+ Sets the Rails environment for `rake` and `rails` commands.
807
+
808
+ Note that changing this will NOT change the environment that your application
809
+ is run in.
810
+
811
+ ### bundle_prefix
812
+ Prefix for Bundler commands. Often to something like `RAILS_ENV=production
813
+ bundle exec`.
814
+
815
+ ~~~ ruby
816
+ queue! "#{bundle_prefix} annotate -r"
817
+ ~~~
818
+
819
+ ### rake
820
+ The prefix for `rake` commands. Use like so:
821
+
822
+ ~~~ ruby
823
+ queue! "#{rake} db:migrate"
824
+ ~~~
825
+
826
+ ### rails
827
+ The prefix for `rails` commands. Use like so:
828
+
829
+ ~~~ ruby
830
+ queue! "#{rails} console"
831
+ ~~~
832
+
833
+ ### asset_paths
834
+ The paths to be checked.
835
+
836
+ Whenever assets are compiled, the asset files are checked if they have
837
+ changed from the previous release.
838
+
839
+ If they're unchanged, compiled assets will simply be copied over to the new
840
+ release.
841
+
842
+ Override this if you have custom asset paths declared in your Rails's
843
+ `config.assets.paths` setting.
844
+
845
+ ### rake_assets_precompile
846
+ The command to invoke when precompiling assets.
847
+ Override me if you like.
848
+
849
+ ----
850
+
851
+ Macro used later by :rails, :rake, etc
852
+
853
+ ## Command-line tasks
854
+ These tasks can be invoked in the command line.
855
+
856
+ ### rails[]
857
+ Invokes a rails command.
858
+
859
+ ~~~ ruby
860
+ $ mina rails[console]
861
+ ~~~
862
+
863
+ ### rake[]
864
+ Invokes a rake command.
865
+
866
+ ~~~ ruby
867
+ $ mina rake db:cleanup
868
+ ~~~
869
+
870
+ ### console
871
+ Opens the Ruby console for the currently-deployed version.
872
+
873
+ ~~~ ruby
874
+ $ mina console
875
+ ~~~
876
+
877
+ ## Deploy tasks
878
+ These tasks are meant to be invoked inside deploy scripts, not invoked on
879
+ their own.
880
+
881
+ ### rails:db_migrate
882
+
883
+ ### rails:db_migrate:force
884
+
885
+ ### rails:assets_precompile:force
886
+
887
+ ### rails:assets_precompile
888
+
889
+ # Modules: rbenv
890
+ Adds settings and tasks for managing [rbenv] installations.
891
+
892
+ [rbenv]: https://github.com/sstephenson/rbenv
893
+
894
+ ~~~ ruby
895
+ require 'mina/rbenv'
896
+ ~~~
897
+
898
+ ## Common usage
899
+
900
+ ~~~ ruby
901
+ task :environment do
902
+ invoke :'rbenv:load'
903
+ end
904
+ task :deploy => :environment do
905
+ ...
906
+ end
907
+ ~~~
908
+
909
+ ## Settings
910
+ Any and all of these settings can be overriden in your `deploy.rb`.
911
+
912
+ ### rbenv_path
913
+ Sets the path where *rbenv* is installed.
914
+
915
+ You may override this if rbenv is placed elsewhere in your setup.
916
+
917
+ ## Tasks
918
+
919
+ ### rbenv:load
920
+ Loads the *rbenv* runtime.
921
+
922
+ # Modules: RVM
923
+ Adds settings and tasks for managing [RVM] installations.
924
+
925
+ [rvm]: http://rvm.io
926
+
927
+ ~~~ ruby
928
+ require 'mina/rvm'
929
+ ~~~
930
+
931
+ ## Common usage
932
+
933
+ ~~~ ruby
934
+ task :environment do
935
+ invoke :'rvm:use[ruby-1.9.3-p125@gemset_name]'
936
+ end
937
+ task :deploy => :environment do
938
+ ...
939
+ end
940
+ ~~~
941
+
942
+ ## Settings
943
+ Any and all of these settings can be overriden in your `deploy.rb`.
944
+
945
+ ### rvm_path
946
+ Sets the path to RVM.
947
+
948
+ You can override this in your projects if RVM is installed in a different
949
+ path, say, if you have a system-wide RVM install.
950
+
951
+ ## Tasks
952
+
953
+ ### rvm:use[]
954
+ Uses a given RVM environment provided as an argument.
955
+
956
+ This is usually placed in the `:environment` task.
957
+
958
+ ~~~ ruby
959
+ task :environment do
960
+ invoke :'rvm:use[ruby-1.9.3-p125@gemset_name]'
961
+ end
962
+ ~~~
963
+
964
+ ### rvm:wrapper[]
965
+ Creates a rvm wrapper for a given executable.
966
+
967
+ This is usually placed in the `:setup` task.
968
+
969
+ ~~~ ruby
970
+ task ::setup => :environment do
971
+ ...
972
+ invoke :'rvm:wrapper[ruby-1.9.3-p125@gemset_name,wrapper_name,binary_name]'
973
+ end
974
+ ~~~
975
+
976
+ Adds settings and tasks for managing projects with [whenever].
977
+ [whenever]: http://rubygems.org/gems/whenever
978
+
979
+ Acknowledgements
980
+ ----------------
981
+
982
+ © 2012-2014, Nadarei. Released under the [MIT
983
+ License](http://www.opensource.org/licenses/mit-license.php).
984
+
985
+ Mina is authored and maintained by [Rico Sta. Cruz][rsc] and [Michael
986
+ Galero][mg] with help from its [contributors][c]. It is sponsored by our
987
+ startup, [Nadarei][nd].
988
+
989
+ * [Nadarei](http://nadarei.co) (nadarei.co)
990
+ * [Github](http://github.com/nadarei) (@nadarei)
991
+
992
+ Rico:
993
+
994
+ * [My website](http://ricostacruz.com) (ricostacruz.com)
995
+ * [Github](http://github.com/rstacruz) (@rstacruz)
996
+ * [Twitter](http://twitter.com/rstacruz) (@rstacruz)
997
+
998
+ Michael:
999
+
1000
+ * [My website][mg] (michaelgalero.com)
1001
+ * [Github](http://github.com/mikong) (@mikong)
1002
+
1003
+ [rsc]: http://ricostacruz.com
1004
+ [mg]: http://devblog.michaelgalero.com/
1005
+ [c]: https://github.com/mina-deploy/mina/graphs/contributors
1006
+ [nd]: http://nadarei.co
1007
+ [issues]: https://github.com/mina-deploy/mina/issues
1008
+ [trello]: https://trello.com/board/mina/4fc8b3023d9c9a4d72e573e6
1009
+