Statocles::Help::Deploy - How to deploy a Statocles site
version 0.091
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.
http://example.com/
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.
/path
By far the easiest way is to deploy to a Github Pages site (though you can make your own Git-based deployment as well).
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 }
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 }
To create a Github-Pages-like deploy without hosting on Github, you need a few things:
A bare repository to push to
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)
/var/www/www.example.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.
statocles deploy
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
If none of these work for you, you can build your own deploy module. See Statocles::Deploy for details.
Doug Bell <preaction@cpan.org>
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.
To install Statocles, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Statocles
CPAN shell
perl -MCPAN -e shell install Statocles
For more information on module installation, please visit the detailed CPAN module installation guide.