updating setup and deployment docs

This commit is contained in:
Brandon Mathis 2011-09-19 12:19:20 -05:00
parent 9a24bcb857
commit 42ce9b2176
8 changed files with 245 additions and 130 deletions

View File

@ -0,0 +1,41 @@
If you're deploying to a subdirectory on your site, or if you're using Github's project pages, make sure you set up your urls correctly in your configs.
You can do this *almost* automatically:
``` sh
rake set_root_dir[your/path]
# To go back to publishing to the document root
rake set_root_dir[/]
```
Then update your `_config.yml` and `Rakefile` as follows:
``` sh
# _config.yml
url: http://yoursite.com/your/path
# Rakefile (if deploying with rsync)
document_root = "~/yoursite.com/your/path"
```
To manually configure deployment to a subdirectory, you'll change `_config.yml`, `config.rb` and `Rakefile`.
Here's an example for deploying the Octopress website to Github Project Pages:
``` sh
# _config.yml
destination: public/octopress
url: http://imathis.github.com/octopress
subscribe_rss: /octopress/atom.xml
root: /octopress
# config.rb - for Compass & Sass
http_path = "/octopress"
http_images_path = "/octopress/images"
http_fonts_path = "/octopress/fonts"
css_dir = "public/octopress/stylesheets"
# Rakefile
public_dir = "public/octopress"
# If deploying with rsync, update your Rakefile path
document_root = "~/yoursite.com/your/path"
```

View File

@ -0,0 +1,54 @@
---
layout: page
title: "Deploying to Github Pages"
date: 2011-09-10 17:52
sidebar: false
footer: false
---
To setup deployment, you'll want to clone your target repository into the `_deploy` directory in your Octopress project.
If you're using Github user or organization pages, clone the repository `git@github.com:username/username.github.com.git`.
### With Github User/Organization pages
``` sh
git clone git@github.com:username/username.github.com _deploy
rake config_deploy[master]
```
### With Github Project pages (gh-pages)
``` sh
git clone git@github.com:username/project.git _deploy
rake config_deploy[gh-pages]
```
The `config_deploy` rake task takes a branch name as an argument and creates a [new empty branch](http://book.git-scm.com/5_creating_new_empty_branches.html), and adds an initial commit.
This also sets `deploy_default = "push"` in your `_config.yml` and prepares your branch for easy deployment. The `rake deploy` task copies the generated blog from the `public` directory to the `_deploy` directory, adds new files, removes old files, sets a commit message, and pushes to Github.
Github will queue your site for publishing (which usually occurs instantly or within minutes if it's your first commit).
Now you should be set up to deploy, just run
``` sh
rake generate # If you haven't generated your blog yet
rake deploy # Pushes your generated blog to Github
```
<h2 id="deploy_subdir">Deploying to a Subdirectory (Github Project Pages does this)</h2>
{% render_partial docs/deploying/_subdir.markdown %}
<h2 id="custom_domains">Custom Domains</h2>
First you'll need to create a file named `CNAME` in the source containing your domain name.
``` sh
echo 'your-domain.com' >> source/CNAME
```
From [Github's Pages guide](http://pages.github.com):<br>
Next, youll need to visit your domain registrar or DNS host and add a record for your domain name.
For a sub-domain like `www.example.com` you would simply create a CNAME record pointing at `charlie.github.com`.
If you are using a top-level domain like `example.com`, you must use an A record pointing to `207.97.227.245`.
*Do not use a CNAME record with a top-level domain* it can have adverse side effects on other services like email.
Many DNS services will let you set a CNAME on a TLD, even though you shouldnt. Remember that it may take up to a full day for DNS changes to propagate, so be patient.

View File

@ -0,0 +1,23 @@
---
layout: page
title: "Using Octopress with Heroku"
date: 2011-09-10 17:58
sidebar: false
footer: false
---
If you don't already have a Heroku account, [create one](https://api.heroku.com/signup), it's free. Then install the Heroku gem.
## Basic Octopress setup
{% render_partial docs/setup/_basic.markdown %}
Next create a heroku app for deployment. If this is your first time using Heroku, this command will ask for your account credentials,
and automatically upload your public SSH key. If you don't already have a public key follow [Github's guide and create one](http://help.github.com/set-up-git-redirect/).
```sh
heroku create
```
This will create a new Heroku app for you to deploy to and add a git remote named 'heroku'.
git config branch.master.remote origin

View File

@ -1,100 +1,48 @@
---
layout: page
title: Deploying Octopress
title: Deploying
date: July 18 2011
sidebar: false
footer: false
---
<h2 id="rsync">Deploying with Rsync via SSH</h2>
Here are some nice and easy ways to deploy your Octopress blog.
Add your server configurations to the `Rakefile` under Rsync deploy config. To deploy with Rsync, be sure your public key is listed in your server's `~/.ssh/authorized_keys` file.
## Github Pages
Hosting your blog with Github's [Pages service](pages.github.com) is free and allows custom domains. To deploy you simply push your repository to Gihub.
This is a great way to host a personal blog, or even a multi-author blog, where contributions can be handled with pull requests and commit access.
``` ruby
ssh_user = "user@domain.com"
document_root = "~/website.com/"
deploy_default = "rsync"
```
[Deploying to Github Pages &raquo;](/docs/deploying/github)
Now if you run
## Heroku
Like Github Pages, Heroku is also free, allows custom domains, and uses a git based deployment workflow. Heroku is a bit simpler to use and your blog repository remains private.
[Deploying to Heroku &raquo;](/docs/deploying/heroku)
## Rsync
If you have web hosting service you can probably deploy with [Rsync](http://en.wikipedia.org/wiki/Rsync) which is brilliantly fast, syncing new and changed files through SSH.
If your host doesn't offer SSH access, and you're looking for one that does, check out [Dreamhost](http://www.dreamhost.com/r.cgi?109007) (I've been a happy customer since 2005).
[Deploying with Rsync &raquo;](/docs/deploying/rsync)
## Host your own remote repository
If you want to set up a private git repository on your own server, here's how you'd do it. You'll need SSH access to follow along.
```sh
rake generate # If you haven't generated your blog yet
rake deploy # Syncs your blog via ssh
ssh user@host.com
mkdir -p git/octopress.git
cd git/octopress.git
git init --bare
pwd # print the working directory, you'll need it below.
logout
```
in your terminal, your `public` directory will be synced to your server's document root.
<h2 id="github_pages">Deploying to Github Pages</h2>
To setup deployment, you'll want to clone your target repository into the `_deploy` directory in your Octopress project.
If you're using Github user or organization pages, clone the repository `git@github.com:username/username.github.com.git`.
### With Github User/Organization pages
The origin remote currently points to the Octopress project on Github but you'll want to point it to your remote repository.
```sh
git clone git@github.com:username/username.github.com _deploy
rake config_deploy[master]
git remote rename origin octopress
git remote add origin ssh://user@host.com/(output of pwd above)
git config branch.master.remote origin
```
### With Github Project pages (gh-pages)
``` sh
git clone git@github.com:username/project.git _deploy
rake config_deploy[gh-pages]
```
The `config_deploy` rake task takes a branch name as an argument and creates a [new empty branch](http://book.git-scm.com/5_creating_new_empty_branches.html), and adds an initial commit.
This also sets `deploy_default = "push"` in your `_config.yml` and prepares your branch for easy deployment. The `rake deploy` task copies the generated blog from the `public` directory to the `_deploy` directory, adds new files, removes old files, sets a commit message, and pushes to Github.
Github will queue your site for publishing (which usually occurs instantly or within minutes if it's your first commit).
Now you should be set up to deploy, just run
``` sh
rake generate # If you haven't generated your blog yet
rake deploy # Pushes your generated blog to Github
```
<h2 id="deploy_subdir">Deploying to a Subdirectory (Github Project Pages does this)</h2>
If you're deploying to a subdirectory on your site, or if you're using Github's project pages, make sure you set up your urls correctly in your configs.
You can do this *almost* automatically:
``` sh
rake set_root_dir[your/path]
# To go back to publishing to the document root
rake set_root_dir[/]
```
Then update your `_config.yml` and `Rakefile` as follows:
``` sh
# _config.yml
url: http://yoursite.com/your/path
# Rakefile (if deploying with rsync)
document_root = "~/yoursite.com/your/path"
```
To manually configure deployment to a subdirectory, you'll change `_config.yml`, `config.rb` and `Rakefile`.
Here's an example for deploying the Octopress website to Github Project Pages:
``` sh
# _config.yml
destination: public/octopress
url: http://imathis.github.com/octopress
subscribe_rss: /octopress/atom.xml
root: /octopress
# config.rb - for Compass & Sass
http_path = "/octopress"
http_images_path = "/octopress/images"
http_fonts_path = "/octopress/fonts"
css_dir = "public/octopress/stylesheets"
# Rakefile
public_dir = "public/octopress"
# If deploying with rsync, update your Rakefile path
document_root = "~/yoursite.com/your/path"
```

View File

@ -0,0 +1,27 @@
---
layout: page
title: "Deploying with Rsync"
date: 2011-09-10 17:53
sidebar: false
footer: false
---
<h2 id="rsync">Deploying with Rsync via SSH</h2>
Add your server configurations to the `Rakefile` under Rsync deploy config. To deploy with Rsync, be sure your public key is listed in your server's `~/.ssh/authorized_keys` file.
``` ruby
ssh_user = "user@domain.com"
document_root = "~/website.com/"
deploy_default = "rsync"
```
Now if you run
``` sh
rake generate # If you haven't generated your blog yet
rake deploy # Syncs your blog via ssh
```
in your terminal, your `public` directory will be synced to your server's document root.

View File

@ -8,13 +8,12 @@ footer: false
---
Octopress is a framework designed for Jekyll, the static blogging engine powering Github Pages. Have a look through
the documentation and if you have trouble, [I'll be happy to help](http://convore.com/octopress/support). If you find errors
the documentation and if you have trouble, [I'll be happy to help](/help). If you find errors in the documentation
[post an issue](https://github.com/imathis/octopress/issues) or fork and send a pull request on the [site branch](https://github.com/imathis/octopress/tree/site).
**Note:** If you already have a blog, check out [Jekyll's Migration page](https://github.com/mojombo/jekyll/wiki/blog-migrations) to help you get your current blog set up for Octopress blogging.
## Getting Started
This section will help you get set up, and explain how to configure Octopress for your site.
**Note:** If you already have a blog, check out [Jekyll's Migration page](https://github.com/mojombo/jekyll/wiki/blog-migrations) to help you get your current blog set up for Octopress blogging.
- [Initial setup](/docs/setup) - *get source and install dependencies*
- [Basic Configuration](/docs/configuring) - *enable third party services and personalize your blog*

View File

@ -6,59 +6,48 @@ sidebar: false
footer: false
---
[Create a new repository](https://github.com/repositories/new) for your website then
open up a terminal and follow along. If you plan to host your site on [Github Pages](http://pages.github.com) for a user or organization, make sure the
repository is named `your_username.github.com` or `your_organization.github.com`.
First, I want to stress that **Octopress is a blogging framework for hackers**.
You should be comfortable running shell commands and familiar with the basics of Git.
If that sounds daunting, Octopress probably isn't for you.
## Before You Begin
You'll need to have Git and RVM installed before you move forward.
1. [Download Git](http://git-scm.com/)
2. [Setup RVM](/docs/setup/rvm)
Octopress requires Ruby 1.9.2 so once you have RVM set up, go ahead and install it.
```sh
mkdir my_octopress_site
cd my_octopress_site
git init
git remote add octopress git://github.com/imathis/octopress.git
git pull octopress master
git remote add origin your/repository/url
git push origin master
rvm install 1.9.2
```
Next, **if you're using [Github Pages](http://pages.github.com) to host a site for your user or organization**, create a source branch and push to origin source.
If you're using Github project pages, or hosting the site in a different way, skip this step.
## Setup Octopress
```sh
git checkout -b source
git push origin source
git clone git://github.com/imathis/octopress.git octopress
cd octopress # You'll be asked if you trust the .rvmrc file (say yes).
which ruby # Should report Ruby 1.9.2
```
The `source` branch is created to have somewhere to store the source
for your site. GitHub user/organization pages expects the generated site to be pushed to the
`master` branch of your GitHub repository so that branch needs to stay
clean. In [Deploying Octopress](/docs/deploying/) we'll setup the `master` branch for deployment.
If `which ruby` doesn't say you're using Ruby 1.9.2, you may want to [revisit your RVM installation](/docs/setup/rvm).
Next, setup an [RVM](http://beginrescueend.com/) and install dependencies.
Next, install dependencies.
```sh
rvm rvmrc trust
rvm reload
gem install bundler
gem install rake
bundle install
```
Install the default Octopress theme,
Install the default Octopress theme.
``` sh
rake install
```
### What to Commit?
## Next Steps
With `rake install` you've setup the default Octopress theme in the `source` and `sass` directories. Add them to your git repository, commit and push. *Remember if you're hosting with Github user/organization pages, you'll want to commit these to the `source` branch.*
``` sh
git add .
git commit -m 'Installed Octopress theme'
git push
```
Whenever you write a new post, or make changes to your blog, be sure to commit and push those changes.
See also [Configuring Octopress](/docs/configuring), [Blogging with Octopress](/docs/blogging/) and [Deploying Octopress](/docs/deploying/)
- [Set up deployment](/docs/deploying)
- [Configure your blog](/docs/configuring)
- [Start blogging with Octopress](/docs/blogging)

View File

@ -0,0 +1,34 @@
---
layout: page
title: "Installing RVM"
date: September 19 2011
sidebar: false
footer: false
---
RVM (Ruby Version Manager) handles the installation and management of multiple Ruby environments, and Octopress was designed to work in an RVM-controlled environment.
Installation should be pretty smooth, but if you have trouble [get help here](https://rvm.beginrescueend.com/support/).
Run this command to install RVM for your user account.
```sh
bash < <(curl -s https://rvm.beginrescueend.com/install/rvm)
```
Next add RVM to your shell as a function.
```sh
echo '[[ -s "$HOME/.rvm/scripts/rvm" ]] && . "$HOME/.rvm/scripts/rvm" # Load RVM function' >> ~/.bash_profile
source ~/.bash_profile
# If using Zsh do this instead
echo '[[ -s $HOME/.rvm/scripts/rvm ]] && source $HOME/.rvm/scripts/rvm' >> ~/.zshrc
source ~/.zshrc
```
Install Ruby 1.9.2 and ensure RVM has the latest RubyGems.
```sh
rvm install 1.9.2
rvm rubygems latest
```