From ec35d72b6fbecc80fad804329fae0340a91144fe Mon Sep 17 00:00:00 2001 From: Vincent Prouillet Date: Tue, 20 Feb 2018 09:47:14 +0100 Subject: [PATCH] Add some deployment docs --- .../documentation/deployment/_index.md | 8 +++ .../documentation/deployment/github-pages.md | 52 +++++++++++++++++++ .../documentation/deployment/netlify.md | 44 ++++++++++++++++ .../documentation/deployment/overview.md | 9 ++++ 4 files changed, 113 insertions(+) create mode 100644 docs/content/documentation/deployment/_index.md create mode 100644 docs/content/documentation/deployment/github-pages.md create mode 100644 docs/content/documentation/deployment/netlify.md create mode 100644 docs/content/documentation/deployment/overview.md diff --git a/docs/content/documentation/deployment/_index.md b/docs/content/documentation/deployment/_index.md new file mode 100644 index 00000000..c331806b --- /dev/null +++ b/docs/content/documentation/deployment/_index.md @@ -0,0 +1,8 @@ ++++ +title = "Deployment" +weight = 5 +sort_by = "weight" +insert_anchor_links = "left" +redirect_to = "documentation/deployment/overview" ++++ + diff --git a/docs/content/documentation/deployment/github-pages.md b/docs/content/documentation/deployment/github-pages.md new file mode 100644 index 00000000..f45f9994 --- /dev/null +++ b/docs/content/documentation/deployment/github-pages.md @@ -0,0 +1,52 @@ ++++ +title = "GitHub Pages" +weight = 30 ++++ + +By default, GitHub Pages uses Jekyll (A ruby based static site generator), +but you can use whatever you want provided you have an `index.html` file in the root of a branch called `gh-pages`. +That branch name can also be manually changed in the settings of a repository. + +We are going to use [TravisCI](https://travis-ci.org) to automatically publish the site. If you are not using Travis already, +you will need to login with the GitHub OAuth and activate Travis for the repository. +Don't forget to also check if your repository allows GitHub Pages in its settings. + +## Allowing Travis to push to GitHub + +Before pushing anything, Travis needs a Github private access key in order to make changes to your repository. +If you're already logged in to your account, just click [here](https://github.com/settings/tokens) to go to your tokens page. +Otherwise, navigate to `Settings > Developer Settings > Personal Access Tokens`. +Generate a new token, and give it any description you'd like. +Under the "Select Scopes" section, give it repo permissions. Click "Generate token" to finish up. + +Your token will now be visible! +Copy it into your clipboard and head back to Travis. +Once on Travis, click on your project, and navigate to "Settings". Scroll down to "Environment Variables" and input a name of `GH_TOKEN` with a value of your access token. +Make sure "Display value in build log" is off, and then click add. Now Travis has access to your repository. + +## Setting up Travis + +We're almost done. We just need some scripts in a .travis.yml file to tell Travis what to do. + +```yaml +before_script: + # Download and unzip the gutenberg executable + # Replace the version numbers in the URL by the version you want to use + - curl -s -L https://github.com/Keats/gutenberg/releases/download/v0.3.1/gutenberg-v0.3.1-x86_64-unknown-linux-gnu.tar.gz | sudo tar xvzf - -C /usr/local/bin + +script: + - gutenberg build + +# If you are using a different folder than `public` for the output directory, you will +# need to change the `gutenberg` command and the `ghp-import` path +after_success: | + [ $TRAVIS_BRANCH = master ] && + [ $TRAVIS_PULL_REQUEST = false ] && + gutenberg build && + sudo pip install ghp-import && + ghp-import -n public && + git push -fq https://${GH_TOKEN}@github.com/${TRAVIS_REPO_SLUG}.git gh-pages +``` + +If your site is using a custom domain, you will need to mention it in the `ghp-import` command: `ghp-import -c vaporsoft.net -n public` +for example. diff --git a/docs/content/documentation/deployment/netlify.md b/docs/content/documentation/deployment/netlify.md new file mode 100644 index 00000000..e5fedc86 --- /dev/null +++ b/docs/content/documentation/deployment/netlify.md @@ -0,0 +1,44 @@ ++++ +title = "Netlify" +weight = 20 ++++ + +Netlify provides best practices like SSL, CDN distribution, caching and continuous deployment +with no effort. This very site is hosted by Netlify and automatically deployed on commits. + +If you don't have an account with Netlify, you can [sign up](https://app.netlify.com) for one. + +Once you are in the admin interface, you can add a site from a Git provider (GitHub, GitLab or Bitbucket). At the end + of this process, you can select the deploy settings for the project: + + - build command: `GUTENBERG_VERSION=0.3.1 gutenberg build` (replace the version number in the variable by the version you want to use) + - publish directory: the path to where the `public` directory is + +With this setup, your site should be automatically deployed on every commit on master. + +However, if you want to use everything that Netlify gives you, you should also publish temporary sites for pull requests. + +This is done by adding the following `netlify.toml` file in your repository and removing the build command/publish directory in +the admin interface. + +```toml +[build] +# assuming the gutenberg site is in a docs folder, if it isn't you don't need +# to have a `base` variable but you do need the `publish` and `command` +base = "docs" +publish = "docs/public" +command = "gutenberg build" + +[build.environment] +# Set the version name that you want to use and Netlify will automatically use it +GUTENBERG_VERSION = "0.3.1" + +# The magic for deploying previews of branches +# We need to override the base url with what the url of the preview is ($DEPLOY_PRIME_URL) +# otherwise links would not work properly +[context.deploy-preview] +command = "gutenberg build --base-url $DEPLOY_PRIME_URL" + +``` + + diff --git a/docs/content/documentation/deployment/overview.md b/docs/content/documentation/deployment/overview.md new file mode 100644 index 00000000..c776b263 --- /dev/null +++ b/docs/content/documentation/deployment/overview.md @@ -0,0 +1,9 @@ ++++ +title = "Overview" +weight = 10 ++++ + +Gutenberg outputs plain files, no databases needed. This makes hosting and deployment +trivial on many providers. + +