Skip to content

Installation & Setup

Jump to bottom
Luna edited this page Apr 21, 2021 · 5 revisions

NOTE: These docs need to be updated for the new repo.

Note: if you are confused by some of the terminology below, feel free to check the Glossary.

Dependencies

In order to run the website locally, you'll need to have the following installed:

  • Git
  • Ruby 2.6.3
  • Bundler 2.0
  • Jekyll 3.8.5

Installation Instructions (in order):

Proceed to the Setup section.

Setup

NOTE: This section is out of date, and will eventually be updated to reflect the new repo.

Clone the repo & cd (change directory) into the repo's root (aka top) directory:

git clone https://github.com/pgpconference/pgpconference.git
cd pgpconference

If you want to give the folder a different local name, you can type:

# replace staging-pgp with any desired name - mine is currently pgpconference.
git clone https://github.com/pgpconference/pgpconference.git staging-pgp
cd staging-pgp

Automated Setup

Run setup.sh after cloning the repo, by typing source setup.sh. Assuming this worked fine, proceed to the Run the Server

Manual Setup

Quick Setup

If you want to do this quickly, you can literally copy & paste line by line from the setup.sh file (found in the project's top directory), and everything should work fine.

Thorough Setup

Update Git's Index

  1. Tell git to ignore changes to the CNAME and _config_local.yml files:

git update-index --skip-worktree CNAME

git update-index --skip-worktree _config_local.yml

The CNAME file contains the site's domain info. Note: not running git update-index --skip-worktree CNAME will cause havoc between the staging and production sites when you make your edits. You must make sure to run this command

_config_local.yml allows us to make changes to our secondary config file locally without worrying about git accidentally pushing them to the main repo. Running git update-index --skip-worktree _config_local.yml allows us to make those changes, without worry about git accidentally uploading them to the remote repo.

About Secondary Config Files:

Sometimes when developing locally you'll want to use a second config file to specify things like the url, baseurl, plugins, port number, etc. If so, type bundle exec jekyll serve --config _config.yml,_config_local.yml when you run the server. Note: that there's no space after the comma between _config.yml,_config_local.yml

This is especially useful if you want to disable plugins to speed up your build time. Anything you put in your second config file will override the settings in the first.

You can find a full list of configuration settings in the Configuring Jekyll doc.

Sync the Docs and Repos

  1. Optional: Get the latest version of the docs by typing git submodule update --init. Alternately, you can always find them here https://github.com/pgpconference/pgpconference/wiki/

  2. Add the remote staging repo and make sure everything's in sync:

git remote add staging https://github.com/pgpconference/staging.git
git fetch --all

Setup Branch Tracking & Push Settings

  1. Create and checkout our local staging branch (where we'll do most of the editing):

git checkout -b staging

The -b flag tells git to create the new branch. In the future you will only need to type git checkout staging, since the branch will already exist.

  1. Tell staging to track the remote staging:gh-pages branch:

git branch -u staging/gh-pages

Note: It's essential to make sure you're on the staging branch when you do this. If you're unsure what branch you're on, type git branch and make sure you see an asterisk next to staging:

$ git branch
  gh-pages
* staging
  1. Set push.default to upstream so that our branches always push (upload) our changes to the right repo. (staging -> staging:gh-pages and gh-pages to origin:gh-pages).
git config push.default upstream

Now we can simply type git push everytime we want to update the remote server.

Note: If you don't do this, then you'll have to manually specify every time you want to push changes:

<a id="to-push-local-staging-to-remote-staginggh-pages"></a>
# To push (local) staging to (remote) staging/gh-pages
git push staging HEAD:gh-pages

<a id="to-push-local-gh-pages-to-remote-origingh-pages"></a>
# To push (local) gh-pages to (remote) origin/gh-pages
git push origin HEAD:gh-pages

That's it - our setup's all done!

Run the Server

Now that we're all set-up, let's make sure that Jekyll's working.

In the root directory of the repo, run bundle exec jekyll serve. If that's working alright, then you'll see something like this:

Configuration file: _config.yml
Configuration file: _config_plugins_local.yml
            Source: C:/Users/lunac/sites/pgpconference
       Destination: C:/Users/lunac/sites/pgpconference/_site
 Incremental build: disabled. Enable with --incremental
      Generating...
       Jekyll Feed: Generating feed for posts
                    done in 25.261 seconds.
 Auto-regeneration: enabled for 'C:/Users/lunac/sites/pgpconference'
  JekyllAdmin mode: production
    Server address: http://127.0.0.1:4000
  Server running... press ctrl-c to stop.

Assuming that went fine, go visit the site in your browser. By default, the address will be localhost:4000 - so type that into your browser's address bar.

Note: sometimes on the first run, your browser will return a "This site can't be reached" error. If that happens, just kill the server from your terminal, with Ctrl-C, and then run bundle exec jekyll serve again.

Assuming everything ran fine, and that the site worked and you've killed it with Ctrl-C, then go check out the Basic Editing doc!

Troubleshooting

If you ran into errors with any of the above, head over to the Troubleshooting doc or contact Luna (preferably with a copy/pasted error message, or ascreenshot) to help get it sorted out.

Clone this wiki locally