Capistrano documentation, tutorials
31 views
Skip to first unread message
psimoes
Jan 12, 2009, 6:49:51 AM1/12/09
to Capistrano
Hello,
I'd like to use Capistrano to do some system administration tasks but
I think Capistrano lacks documentation. Where can I find information
about the functions to use in the tasks, how to use the Capistrano API
in ruby scripts and something like that?
Thanks.
I'd like to use Capistrano to do some system administration tasks but
I think Capistrano lacks documentation. Where can I find information
about the functions to use in the tasks, how to use the Capistrano API
in ruby scripts and something like that?
Thanks.
jhearn
Jan 12, 2009, 2:47:18 PM1/12/09
to Capistrano
Checking the man page, we find:
> For more information about the cap cap and cap capify commands
> you can use their --h flag. There is also online documentation
> available at "http://manuals.rubyonrails.com/read/chapter/97".
Cleverly, that URL leads to a "Page Not Found" error.
A quick google search produces nothing promising, but we can go to
archive.org to access a copy that is about 18 months out of date:
http://web.archive.org/web/20070612144611/http://manuals.rubyonrails.com/read/chapter/97
If your good at google cache hacking, you might be able to find
something more recent. Hope that is sort of helpful. Best of luck.
> For more information about the cap cap and cap capify commands
> you can use their --h flag. There is also online documentation
> available at "http://manuals.rubyonrails.com/read/chapter/97".
Cleverly, that URL leads to a "Page Not Found" error.
A quick google search produces nothing promising, but we can go to
archive.org to access a copy that is about 18 months out of date:
http://web.archive.org/web/20070612144611/http://manuals.rubyonrails.com/read/chapter/97
If your good at google cache hacking, you might be able to find
something more recent. Hope that is sort of helpful. Best of luck.
Jamis Buck
Jan 12, 2009, 3:03:50 PM1/12/09
to capis...@googlegroups.com
Wow, I didn't even realize there was a man page for Capistrano. That
wasn't written by me. :) I don't even know who to go to, to correct the
bad link (which is hopelessly obsolete, and hasn't been valid for at
least two years).
- Jamis
wasn't written by me. :) I don't even know who to go to, to correct the
bad link (which is hopelessly obsolete, and hasn't been valid for at
least two years).
- Jamis
Karel Minarik
Jan 13, 2009, 4:58:24 AM1/13/09
to Capistrano
Hello Jamis,
would be too complicated to export static HTML files with RDoc to
http://www.capify.org/documentation/rdoc ? Possibly hooked to
publishing the gem? This is something Sinatra devel team does for
http://sinatra.rubyforge.org/api/ (see
http://github.com/rtomayko/sinatra/blob/9ab1b600c9486b5456b16a1acae5ab855036d7a1/Rakefile#L77)
Also, @psimoes, people often complain that "Capistrano lacks
documentation", but don't state *what precisely* they need to be
documented? Is this only about RDoc (API) being available? (In my eyes
at least Cap is far away from "lacking documentation". Yes, a very
short and simple help for beginners would be good, for instance, and
possibly other things. But that's not "lack of documentation" as I see
it.)
Karel
would be too complicated to export static HTML files with RDoc to
http://www.capify.org/documentation/rdoc ? Possibly hooked to
publishing the gem? This is something Sinatra devel team does for
http://sinatra.rubyforge.org/api/ (see
http://github.com/rtomayko/sinatra/blob/9ab1b600c9486b5456b16a1acae5ab855036d7a1/Rakefile#L77)
Also, @psimoes, people often complain that "Capistrano lacks
documentation", but don't state *what precisely* they need to be
documented? Is this only about RDoc (API) being available? (In my eyes
at least Cap is far away from "lacking documentation". Yes, a very
short and simple help for beginners would be good, for instance, and
possibly other things. But that's not "lack of documentation" as I see
it.)
Karel
Lee Hambley
Jan 13, 2009, 5:03:54 AM1/13/09
to capis...@googlegroups.com
Karel,
Good point, we talk to a lot of people on IRC, and there's a growing selection of documentation in our wiki (not really public yet, but it is) - and there are a handful of tutorials out there.... what did you have in mind, Tyler B and I are trying to manage the Documentation project... but with a lack of input, and with both of us being pretty handy with Capistrano, it's difficult to know what beginners struggle with.
Jamis Buck
Jan 13, 2009, 11:01:31 AM1/13/09
to capis...@googlegroups.com
Sadly, the rdoc is not useful at all to people wanting to use cap. It's
useful if you want to _embed_ cap, but not to use it. In my experience,
what people want are detailed descriptions of each task (which are kind
of available, via "cap -e task_name"), and examples of how to use them
in various different deployment configurations. They also want to know
how to use cap to get started--which cap is not very good at,
unfortunately. (Cap works great once you've got it set up and
established, but using it for the first time, and especially on a
never-before-deployed app, is not push-button.)
I've written a basic getting-started guide, but the problem is that it
only covers one deployment scenario. I don't have experience with other
set-ups, which is part of why I've dragged my feet on writing more of these.
- Jamis
useful if you want to _embed_ cap, but not to use it. In my experience,
what people want are detailed descriptions of each task (which are kind
of available, via "cap -e task_name"), and examples of how to use them
in various different deployment configurations. They also want to know
how to use cap to get started--which cap is not very good at,
unfortunately. (Cap works great once you've got it set up and
established, but using it for the first time, and especially on a
never-before-deployed app, is not push-button.)
I've written a basic getting-started guide, but the problem is that it
only covers one deployment scenario. I don't have experience with other
set-ups, which is part of why I've dragged my feet on writing more of these.
- Jamis
Karel Minarik
Jan 16, 2009, 6:06:57 AM1/16/09
to Capistrano
Hi Lee and Jamis,
all fair points. Sorry for delay with reply. If it's worth anything,
I'd like to add some more:
First, the original docs at http://www.capify.org/getting-started
*are* really good. The problem with them is that they have kinda loose
focus, cover lots of functionality and are quite extensive (and even
outdated in some parts).
I think a very concise and tight "Using Cap to deploy Rails app in 10
minutes" would be great to have as an authoritative source *in some
central place*. (Me personally would like that as part of Rails
Guides, but that could bring some strong discussion.) When everything
is set-up on the server, deployment with Cap really should not take
any longer. Such "walktrough" could guide developer through the whole
deployment scenario, from `cap deploy:check` to `cap
deploy:migrations` / `cap rolback`, etc. It could provide basic info
about various parts of Cap, like "What is the `deploy:start` task",
etc. This guide should be tighly focused *on the developer*, and not
cover any sysadmin stuff around Cap.
Because, *setting up the infrastructure* on the server may be another
matter and could be quite complicated. Of course, lots of developers
are "their own sysadmins", so both angles matter for them, but I think
two things are important:
1/ The guides should be split: one for developers and another one for
sysadmins. In my experience, these are quite different angles when
using Capistrano. (First problem: obviously, different deployment
strategies -- proxied Mongrel/mod_rails -- and different OSes would
probably need different guides.)
2/ There should be some "advocacy" or other initiative from Capistrano
core aimed at hosting/VPS/etc providers. *They* should be concerned
about smooth deployment experience for *their* customers, and *they*
have all the means to do so. (And let's not forget that you can deploy
whatever with Cap, not only a Rails app.) For instance, where I live,
major Rails hosting provider www.railshosting.cz provides you with
custom `deploy.rb` when you order new hosting package. So you just
drop this in your `config` directory after capifying the app, and you
are set. For another example, UK provider Brightbox offers a
deployment Rubygem: http://wiki.brightbox.co.uk/docs:gemv2:howto ,
which works similarly. There's probably no reason the experience
should not be as smooth as this everywhere -- it's just a matter of
education and offering support.
That said, I personally would gladly help with the first part -- the
guide, but just cannot promise anything at this point. Not only
because I have promised to participate on two different guides for
other projects...
However, I think it would work best to set up a Github repo a la
"capistrano-book", put some kind of draft in there and then start
bugging people to fork/update/amend. Whenever someone complains,
whenever someone discovers something, he should fork/updated/amend.
This works reasonably well for Sinatra book (http://github.com/sinatra/
sinatra-book/commits/master), for instance. And of course, it works
great for the Rails Guides.
Best,
Karel
all fair points. Sorry for delay with reply. If it's worth anything,
I'd like to add some more:
First, the original docs at http://www.capify.org/getting-started
*are* really good. The problem with them is that they have kinda loose
focus, cover lots of functionality and are quite extensive (and even
outdated in some parts).
I think a very concise and tight "Using Cap to deploy Rails app in 10
minutes" would be great to have as an authoritative source *in some
central place*. (Me personally would like that as part of Rails
Guides, but that could bring some strong discussion.) When everything
is set-up on the server, deployment with Cap really should not take
any longer. Such "walktrough" could guide developer through the whole
deployment scenario, from `cap deploy:check` to `cap
deploy:migrations` / `cap rolback`, etc. It could provide basic info
about various parts of Cap, like "What is the `deploy:start` task",
etc. This guide should be tighly focused *on the developer*, and not
cover any sysadmin stuff around Cap.
Because, *setting up the infrastructure* on the server may be another
matter and could be quite complicated. Of course, lots of developers
are "their own sysadmins", so both angles matter for them, but I think
two things are important:
1/ The guides should be split: one for developers and another one for
sysadmins. In my experience, these are quite different angles when
using Capistrano. (First problem: obviously, different deployment
strategies -- proxied Mongrel/mod_rails -- and different OSes would
probably need different guides.)
2/ There should be some "advocacy" or other initiative from Capistrano
core aimed at hosting/VPS/etc providers. *They* should be concerned
about smooth deployment experience for *their* customers, and *they*
have all the means to do so. (And let's not forget that you can deploy
whatever with Cap, not only a Rails app.) For instance, where I live,
major Rails hosting provider www.railshosting.cz provides you with
custom `deploy.rb` when you order new hosting package. So you just
drop this in your `config` directory after capifying the app, and you
are set. For another example, UK provider Brightbox offers a
deployment Rubygem: http://wiki.brightbox.co.uk/docs:gemv2:howto ,
which works similarly. There's probably no reason the experience
should not be as smooth as this everywhere -- it's just a matter of
education and offering support.
That said, I personally would gladly help with the first part -- the
guide, but just cannot promise anything at this point. Not only
because I have promised to participate on two different guides for
other projects...
However, I think it would work best to set up a Github repo a la
"capistrano-book", put some kind of draft in there and then start
bugging people to fork/update/amend. Whenever someone complains,
whenever someone discovers something, he should fork/updated/amend.
This works reasonably well for Sinatra book (http://github.com/sinatra/
sinatra-book/commits/master), for instance. And of course, it works
great for the Rails Guides.
Best,
Karel
Tilendor
Jan 16, 2009, 2:52:21 PM1/16/09
to Capistrano
I've just started using Capistrano in the past two weeks. We're in a
Ruby on Rails project that is 8 months old. While cap uses ruby, its
got a whole layer of conventions on top of it, and seems similiar a
lot to rake. These conventions are hard to understand and the
configuration options seem to only surface in blog posts
(ie :checkout, :scm_password, :copy_compression) as well as the
callback strucure after and before.
I didn't know how to override a method like symlink (turns out it
needs to be in the same namespace as the original) and whether I would
put these changes in the capfile or deploy.rb. Also with multistage
deployment I didn't know if I could change all, or only some of the
configuration in the deploy/staging.rb file.) Right now I'm
researching the migration side of it, because all my deploys are using
the production environment, so I need to see how to override that
specific behaviour.
Thats the trouble I've run into so far
Thanks
~Tilendor
Ruby on Rails project that is 8 months old. While cap uses ruby, its
got a whole layer of conventions on top of it, and seems similiar a
lot to rake. These conventions are hard to understand and the
configuration options seem to only surface in blog posts
(ie :checkout, :scm_password, :copy_compression) as well as the
callback strucure after and before.
I didn't know how to override a method like symlink (turns out it
needs to be in the same namespace as the original) and whether I would
put these changes in the capfile or deploy.rb. Also with multistage
deployment I didn't know if I could change all, or only some of the
configuration in the deploy/staging.rb file.) Right now I'm
researching the migration side of it, because all my deploys are using
the production environment, so I need to see how to override that
specific behaviour.
Thats the trouble I've run into so far
Thanks
~Tilendor
Bharat
Jan 17, 2009, 8:35:13 AM1/17/09
to Capistrano
You may want to look at the book Deploying Rails Applications.
Chapter 5 is all about Capistrano and is very well written.
Bharat
Chapter 5 is all about Capistrano and is very well written.
Bharat
Simone Carletti
Feb 26, 2009, 6:49:16 AM2/26/09
to Capistrano
My 2 cents about this topic.
I agree that Capistrano needs more documentation.
From one side I agree with Jamis that rdoc is not useful at all for
people who wants to *use* Capistrano, but it might be helpful for
those who wants to *extend* or play with it at development level.
When I first approached Capistrano I've been a little scared about all
those undocumented options.
I have been searching for a long time a page describing at least the
most important configuration options but I never found it.
Most of them are stored directly in deploy recipes and you don't the
existence of them until you open the source code and you scan line by
line.
As an example, have a look at the capistrano/recipes/deploy/scm/
subversion.rb file. Only the authentication method uses 4 scm-specific
configuration wonderful variables not documented at all somewhere.
Trying to fix this lack I worked on a small configuration parser a
couple of months ago. It was supposed to scan all Capistrano files and
extract configuration variables. The final version never saw the light
but I should have the alpha release stored somewhere in my repos.
The provider initiative it's nice but requires more cooperation from
the hosting providers.
The guys at Brighbox are deeply involved in the Ruby/Rails community
(see for example http://isitruby19.com/) and I'm not surprised they
offer such this useful GEM.
I think only those companies focused on providing a Rails service
could be interested in having a Capistrano documentation page.
Yesterday I was thinking about the capify initialization method. Rails
2.3 introduces the template feature and the user can define custom
templates for new rails applications.
A similar feature could be applied to Capistrano and the
"capification" process.
For example, the following command would capify the current Rails
project with a custom template
capify . --template brighbox
Sorry for my long post,
Simone
-
http://www.simonecarletti.com/
On Jan 16, 12:06 pm, Karel Minarik <karel.mina...@gmail.com> wrote:
> Hi Lee and Jamis,
>
> all fair points. Sorry for delay with reply. If it's worth anything,
> I'd like to add some more:
>
> First, the original docs athttp://www.capify.org/getting-started
> major Rails hosting providerwww.railshosting.czprovides you with
I agree that Capistrano needs more documentation.
From one side I agree with Jamis that rdoc is not useful at all for
people who wants to *use* Capistrano, but it might be helpful for
those who wants to *extend* or play with it at development level.
When I first approached Capistrano I've been a little scared about all
those undocumented options.
I have been searching for a long time a page describing at least the
most important configuration options but I never found it.
Most of them are stored directly in deploy recipes and you don't the
existence of them until you open the source code and you scan line by
line.
As an example, have a look at the capistrano/recipes/deploy/scm/
subversion.rb file. Only the authentication method uses 4 scm-specific
configuration wonderful variables not documented at all somewhere.
Trying to fix this lack I worked on a small configuration parser a
couple of months ago. It was supposed to scan all Capistrano files and
extract configuration variables. The final version never saw the light
but I should have the alpha release stored somewhere in my repos.
The provider initiative it's nice but requires more cooperation from
the hosting providers.
The guys at Brighbox are deeply involved in the Ruby/Rails community
(see for example http://isitruby19.com/) and I'm not surprised they
offer such this useful GEM.
I think only those companies focused on providing a Rails service
could be interested in having a Capistrano documentation page.
Yesterday I was thinking about the capify initialization method. Rails
2.3 introduces the template feature and the user can define custom
templates for new rails applications.
A similar feature could be applied to Capistrano and the
"capification" process.
For example, the following command would capify the current Rails
project with a custom template
capify . --template brighbox
Sorry for my long post,
Simone
-
http://www.simonecarletti.com/
On Jan 16, 12:06 pm, Karel Minarik <karel.mina...@gmail.com> wrote:
> Hi Lee and Jamis,
>
> all fair points. Sorry for delay with reply. If it's worth anything,
> I'd like to add some more:
>
Lee Hambley
Feb 26, 2009, 7:03:00 AM2/26/09
to capis...@googlegroups.com
Simone,
Good information in your post, managing the disparate versions of Capistrano over the next few weeks is going to be difficult, as well as managing the documentation project...
Maybe those who're interested should get their heads together in #irc and hash something out about how to continue with documentation.
The r-doc syntax isn't bad, I am mostly looking for a way to version changes, under SCM to files that we can then render as a webpage, or plaintext, or whatever.... (read: Markdown/textile)
Thoughts are welcome, both Tyler and I are way busy, but I at least am still interested, and I'm sure he is too, EY have a lot of use for Capistrano.
I've been prompted to finish hashing out a load of blog articles that have been sitting round my site as drafts since forever... and get them made into real posts - I think I posted two yesterday, and will continue to post anything I think is useful.
Maybe someone should take the initiative and make something on feedburner of bloglines to aggregate posts from various blogs tagged as related to capistrano?
- Lee
2009/2/26 Simone Carletti <wep...@gmail.com>
Simone Carletti
Feb 26, 2009, 7:26:02 AM2/26/09
to Capistrano
> I've been prompted to finish hashing out a load of blog articles that have
> been sitting round my site as drafts since forever... and get them made into
> real posts - I think I posted two yesterday, and will continue to post
> anything I think is useful.
The same here! :D
> been sitting round my site as drafts since forever... and get them made into
> real posts - I think I posted two yesterday, and will continue to post
> anything I think is useful.
> Maybe someone should take the initiative and make something on feedburner of
> bloglines to aggregate posts from various blogs tagged as related to
> capistrano?
The guys at WordPress did an excellent job with WordPress Planet
http://planet.wordpress.org/
It's basically an aggregation of articles focused on WordPress
declined for the most important languages (see http://planet.wordpress-it.it/
for the Italian market).
The feature I most appreciate is that this is not an aggregation of
all articles about WordPress over the world. Talking about the Italian
version, they only aggregates blog that decided to give consent.
To be included in the list the blog should expose either a WordPress
category or tag and it should manually approved.
This is more restrictive but prevents junk posts to be included in the
final feed.
-- Simone
Reply all
Reply to author
Forward
0 new messages