Fork me on GitHub
{:awestruct}

Build Status

GitHub Actions

Site deployment

Awestruct provides several automated options to deploy your site, which makes publishing online easy!

Using Awestruct, you can deploy your site to any of these destinations:

  1. GitHub Pages

  2. an arbitrary server using rsync and ssh

  3. Amazon S3

You use site profiles, to configure your deployment. Once you’re configured, deploying is just a single command.

$ awestruct -P production --deploy

Configuration

In your _config/site.yml, you should define a profiles block, and a profile for each deployment environment. The names are arbitrary.

profiles:
  development:
  staging:
  production:

Awestruct can gzip the contents of your html, css and javascript files, before deploying. This can be usefull to avoid extra CPU usage on your server.

profiles:
  development:
  staging:
  production:
    deploy:
      gzip: true

By default, Awestruct will use the highest compression level. You can change the compression level by adding the gzip_level. The value must be between 1 (low compression) and 9 (high compression).

profiles:
  development:
  staging:
  production:
    deploy:
      gzip: true
      gzip_level: 5
Warning
 Help! Awestruct keeps complaining that I have uncommitted changes when deploying

Awestruct deployments will fail if you have uncommitted changes in your git local history. While this is fine for most, there are occasions when you may wish to deploy to a stagging site to inspect your changes without adding a commit. Simply add uncommitted: true to your deploy config.

profiles:
  development:
  staging:
    deploy:
      uncommitted: true
  production:

GitHub Pages

To deploy your site to GitHub pages, you will need to be using GitHub as a source repository for the site you want to publish.

Note
 To enable GitHub Pages deployment, set host to github_pages and set the base_url to the github pages URL.

The base_url can be your own domain if you set it up correctly in GitHub. In this example, it’s just the default domain that GitHub provides.

profiles:
  production:
    base_url: http://awestruct.github.com/github_pages
    deploy:
      host: github_pages

This will publish your site to the default gh-pages branch, used by GitHub for site publication. To publish to the master branch, add branch: master to your deployment configuration.

profiles:
  production:
    base_url: http://awestruct.github.com/github_pages
    deploy:
      host: github_pages
      branch: master

Amazon S3

If you host your site on Amazon S3, you can also deploy to different buckets for each of your profiles.

Note
 To enable Amazon S3 deployment, set type to s3 and set bucket to the S3 bucket URL (that starts with s3://). 
profiles:
  development:
  staging:
    deploy:
      type: s3
      bucket: s3://staging.example.com
    production:
      deploy:
      type: s3
      bucket: s3://example.com
Note
 Wait, what command are you actually using?

The deployment to Amazon S3 is using the ruby-s3cmd gem and the executed command looks like

$ s3cmd sync _site/ $S3_BUCKET

Rsync and SSH

Rsync and SSH require a little more configuration than GitHub pages, but in general, this is the more flexible option. Before deploying, make sure you have your public and private SSH keys setup on your server and local system before deploying.

Note
 To enable rsync deployment, set host and path to specify where the resulting site should be copied to. Also make sure that base_url is set correctly for each profile. 
profiles:
  development:
  staging:
    base_url: https://staging.example.com
    deploy:
      host: example.com
      path: /var/www/domains/staging.example.com/staging/htdocs/
    production:
      base_url: https://example.com
      deploy:
        host: example.com
        path: /var/www/domains/example.com/www/htdocs/
Note
 Wait, what command are you actually using?

The rsync command executed looks like

$ rsync -rv --delete _site/ $HOST:$PATH