/ 
Statocles-0.098
River stage one • 4 direct dependents • 4 total dependents
/ Statocles::Help::Deploy

NAME

Statocles::Help::Deploy - How to deploy a Statocles site

VERSION

version 0.098

DESCRIPTION

This document describes various ways to deploy a Statocles site.

base_url

Both the site and every deploy can have a base_url, which should be set to the full URL the site will be deployed to, like http://example.com/ or http://example.com/path.

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

Github Pages

By far the easiest way is to deploy to a Github Pages site (though you can make your own Git-based deployment as well).

user.github.io

To make a user site, accessed at http://user.github.io, you need to create a repository called "<user>.github.io", 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
gh_deploy:
    class: Statocles::Deploy::Git

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

user.github.io/project

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
gh_deploy:
    class: Statocles::Deploy::Git
    args:
        branch: gh-pages
        base_url: http://user.github.io/project

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

Custom Git Deploy

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

  1. A bare repository to push to

  2. A git hook to check out the site's files

To set up a bare repository to push to, I recommend 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 example.com
$ mkdir www.example.com
$ cd www.example.com
$ 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 /var/www/www.example.com for this example... dot com)

$ mkdir /var/www/www.example.com
$ echo "GIT_WORK_TREE=/var/www/www.example.com 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://example.com/www.example.com.git

Now we can set up our Deploy object:

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

And give it to our site:

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

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

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 File deploy. This deploy simply copies the built website to another directory.

# site.yml
file_deploy:
    class: Statocles::Deploy::File
    args:
        path: /var/www/www.example.com

site:
    class: Statocles::Site
    args:
        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:

site:
    class: Statocles::Site
    args:
        deploy: /var/www/www.example.com

Custom Deploy Module

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

AUTHOR

Doug Bell <preaction@cpan.org>

COPYRIGHT AND LICENSE

This software is copyright (c) 2016 by Doug Bell.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.