Back to documentation
# PODNAME: Statocles::Help::Deploy
# ABSTRACT: How to deploy a Statocles site


This document describes various ways to deploy a Statocles site.

=head2 C<base_url>

Both the site and every deploy can have a C<base_url>, which should be set
to the full URL the site will be deployed to, like C<> or

Any time a full URL is needed, the C<base_url> will be used to create one. Even better,
if there is a C</path>, all internal links will be rewritten to prepend the C</path>,
making it easy to move a site to a different URL path.

=head1 Github Pages

By far the easiest way is to deploy to a L<Github Pages|>
site (though you can L<make your own Git-based deployment|/"Custom Git Deploy">
as well).


To make a user site, accessed at, you need to create a
repository called "<user>", replacing <user> with your username.

Once you have that, you can start your Statocles site. Your deploy is
configured very simply, with the default branch of "master" being correct:

    # site.yml
        class: Statocles::Deploy::Git

        class: Statocles::Site
            deploy: { $ref: gh_deploy }


If you have an existing project that you want to add a Github Pages site to,
you can do so by creating a branch named "gh-pages". Create the branch as an
orphan branch so that you don't attach yourself to the regular history of the
project. Leaving the branch attached to the main history can make things a bit
more complicated if that history needs to change, but git will also show the
branches as related in a graph (which they are not).

    $ git checkout -b --orphan gh-pages
    $ git reset --hard 'HEAD'
    $ git add .gitignore
    $ git commit -m'starting github pages site'
    $ git checkout master

Now we just have to configure a Git deploy to point to our "gh-pages" branch,
and make sure to rewrite our page URLs to the right directory.

    # site.yml
        class: Statocles::Deploy::Git
            branch: gh-pages

        class: Statocles::Site
            deploy: { $ref: gh_deploy }

=head1 Custom Git Deploy

To create a Github-Pages-like deploy without hosting on Github, you need a few things:

=over 4

=item 1

A bare repository to push to

=item 2

A git hook to check out the site's files


To set up a bare repository to push to, I recommend
L<gitolite|>. Gitolite manages git repositories for you,
making it easy to add/remove them.

If you do not want to use gitolite, you can probably just use SSH:

    $ ssh
    $ mkdir
    $ cd
    $ git init --bare

Before we're done on the server, we need to add our git hook. Since a bare repo
doesn't have a working copy of the files, the hook is going to check out the
site's HTML files into a directory we specify (we'll use
C</var/www/> for this example... dot com)

    $ mkdir /var/www/
    $ echo "GIT_WORK_TREE=/var/www/ git checkout -f" > hooks/post-receive
    $ chmod +x hooks/post-receive
    $ exit

Now that the bare repository is ready, you can deploy your site. First, we add
the remote manually:

    $ git remote add deploy ssh://

Now we can set up our Deploy object:

    # site.yml
        class: Statocles::Deploy::Git
            remote: deploy

And give it to our site:

    # site.yml
        class: Statocles::Site
            deploy: { $ref: git_deploy }

Now when we run C<statocles deploy>, our repository will be updated and so will
our web root C</var/www/>.

=head1 File

If you only need to copy the files to another directory to serve them, if
you're writing the site on the web server, or you've got a Jenkins server that
can build the site, you can use the L<File deploy|Statocles::Deploy::File>.
This deploy simply copies the built website to another directory.

    # site.yml
        class: Statocles::Deploy::File
            path: /var/www/

        class: Statocles::Site
            deploy: { $ref: file_deploy }

This is the default deploy. If you just give a path to the site object, the
site will be copied to that path:

        class: Statocles::Site
            deploy: /var/www/

=begin comment

# XXX: Make Statocles::Deploy::Command for this!

=head1 Deploy Command

Any command can be used to deploy a Statocles site with
L<Statocles::Deploy::Command>. If you use C<rsync> or C<sftp> or C<scp> or C<ftp>, you
can deploy your Statocles site.

To deploy via rsync, set up your command like so:

    # site.yml
        class: Statocles::Deploy::Command
            command: 'rsync -avz'

By default, the build directory will get appended to the command, so the full
command that will be run is:

    $ rsync -avz .statocles-build

If you need to put the build directory somewhere other than the end of the
command, you can use C<{}> to indicate where the build directory should be

    # site.yml
        class: Statocles::Deploy::Command
            command: 'cp -R {}/* /var/www/'

=end comment

=head1 Custom Deploy Module

If none of these work for you, you can build your own deploy module. See
L<Statocles::Deploy> for details.