Add some deployment docs

This commit is contained in:
Vincent Prouillet 2018-02-20 09:47:14 +01:00
parent fa8a2bfb2a
commit ec35d72b6f
4 changed files with 113 additions and 0 deletions

View file

@ -0,0 +1,8 @@
+++
title = "Deployment"
weight = 5
sort_by = "weight"
insert_anchor_links = "left"
redirect_to = "documentation/deployment/overview"
+++

View file

@ -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.

View file

@ -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"
```

View file

@ -0,0 +1,9 @@
+++
title = "Overview"
weight = 10
+++
Gutenberg outputs plain files, no databases needed. This makes hosting and deployment
trivial on many providers.