Website Maintenance Tips

Website Git Structure

  • Source Files Including Markdown Files for Pages: source Branch
  • Static Pages Built by Jekyll: master Branch
  • The website needs to be loaded from the branch with static pages since there are some unsupported plugins used on the website which will not buildable online by GitHub Jekyll. We have to build the website locally and then upload the static pages to the GitHub.

Page Layouts

Page layout for pages without the sidebar is ‘splash’. Default page layout can be changed in ‘_config.yml’.

Add Wiki as Submodule

In the main repo:

git submodule add https://github.com/ipop-project/ipop-project.github.io.wiki.git wiki
git commit -m "Wiki Added as a Submodule"

Remove Wiki Submodule

Delete the relevant section from the .gitmodules file.

Stage the .gitmodules changes git add .gitmodules.

Delete the relevant section from .git/config.

Run git rm -rf --cached wiki/.

Run rm -rf .git/modules/wiki.

Commit git commit -m "Wiki Submodule Removed".

Delete the now untracked submodule files rm -rf wiki.

Reference

Update Wiki Submodule

In the main repo, source branch:

git rm -rf --cached wiki/
rm -rf .git/modules/wiki
rm -rf wiki
git submodule add https://github.com/ipop-project/ipop-project.github.io.wiki.git wiki

Build Jekyll Website Locally

sudo gem install bundler
sudo apt install ruby-dev

In the main repo, source branch:

bundle install

Add YAML Front Matter to Wiki MarkDown Source Files

Use Jekyll Optional Front Matter plugin.

Importing Wiki into Jekyll Website

In order to make relative links in wiki pages work correctly inside Jekyll website, remove the / from the end of the following line in _config.yml:

permalink: /:categories/:title/

Redirect Wiki Home

Utilizing a Redirected Layout

This technique would allow you to set up redirects for your pages without resorting to any plugin. All you need to do is create a layout named redirected.html in your _layouts folder. The content of this layout would be as shown below:

<!DOCTYPE html>
<html>
<head>
<link rel="canonical" href=""/>
<meta http-equiv="content-type" content="text/html; charset=utf-8" />
<meta http-equiv="refresh" content="0;url=" />
</head>
<body>
      <a href="">Redirecting ...</a>
      <script>location=''</script>
</body>
</html>

Once you have this layout ready, then to set up redirect from any page, all you need to do is specify redirected as your layout in its YAML front matter and specify the destination in redirect_to as shown below. in wiki.md:

---
layout: redirected
sitemap: false
permalink: /wiki/
redirect_to:  Home
---

Note that, I have also included sitemap: false in the front matter as I don’t want the redirected pages to be included in the sitemap.

Reference

Add Table of Contents to the Wiki Pages

jekyll-toc

Note: This plugin doesn’t work on GitHub. So we have to build it locally and then upload the _site directory to gh-pages branch and change the GitHub settings so that it loads the website from gh-pages branch instead of master branch.

To make it appear in all the wiki pages automatically, add toc: true to the wiki layout settings defaults in _config.yml:

  # wiki
  - values:
      toc: true

Integrate Wiki Sidebar into the Website

Remove default layout and sidebar from _Sidebar.html. Exclude everything except `

Use IPOP on Windows, Manually

Warning: This document may be out of date.

  Description
Tested on Microsoft Windows 10 x64
Time ~ 10 Minutes
Question(s) - How to install IPOP?
- How to run IPOP?
- How to remove IPOP?
Objective(s) - Install IPOP
- Run IPOP
- Stop IPOP
- Remove IPOP

Installing IPOP-VPN on Windows

Quick start Installation

The most convenient way to get IPOP installed on Windows 10 is run the ipop-set.ps1 powershell script included in the IPOP ZIP file. Note that you need to have Administrator privileges to install IPOP-VPN.

  1. Download IPOP-VPN for Windows.

  2. Extract the contents of the archive to a directory, e.g., ipop-vpn

  3. Start an Admin Windows Powershell and change to the ipop-vpn directory previously created

  4. Enter the following commands:
     PowerShell -ExecutionPolicy Unrestricted
     .\ipop-setup
    
  5. Follow the prompts to install and setup IPOP

  6. While installing Social VPN, copy the “ip4” entry from “AddressMapper” to “CFx”, e.g.,
     ip4": "172.31.0.100" 
    
  7. Finally, double click ipop-start to run IPOP. Closing this console window will terminate IPOP.

Note: A Windows Firewall exception is created for IPOP-VPN, but you have to create your own for exceptions for other services such as ICMP Echo (ping).

TLDR

If you are using an earlier version of Windows such as 7, 8, Server 2008, or 2012, you will need to manually setup IPOP. Below are the necessary steps to accomplish this.

Manual Setup

  1. Install MS Visual C++ x86 Redistributable Packages for Visual Studio 2010.

  2. Install Python 3.5 for Windows.

  3. Install tap-installer from OpenVPN.

  4. Download IPOP-VPN for Windows.

  5. Extract the contents of the archive to a directory, e.g., ipop-vpn

  6. Decide if you want to run GroupVPN or Social VPN and copy the appropriate sample config to the ipop-vpn directory. Use one of the following for group or social VPN respectively:
     cp .\controller\modules\sample-gvpn-config.json .\config.json
    
     cp .\controller\modules\sample-svpn-config.json .\config.json
    
  7. Update your config file with your XMPP credentials and other details. For SocialVPN you only need to add the XMPP server IP, your XMPP client user id and password. For GroupVPN you will need to add your static virtual IP.

  8. Install Sleek XMPP. Python will have to be in your PATH environment or you will need to provide the path to the pip executable. pip install sleekxmpp

  9. Rename the TAP-Windows Adapter to ipop. From the Control Panel choose View network status and tasks under Network and Internet. On the right side-bar click change adapter settings. Select the TAP Windows Adapter V9 and rename it to “ipop”.

  10. Configure the IPOP Adapter IPv4 interface with a static IP address and subnet mask that will be use for the virtual network. Alternatively you can download download set_interface and [win32_netsh_setup] (https://github.com/ipop-project/Release-Management/blob/master/Deployment/win/win32_netsh_setup.py) to your IPOP directory and run the _setup_interface.bat _ batch file as Admin.

  11. Finally, double click ipop-start to run IPOP

Key Points Summary

Enter the following commands:

PowerShell -ExecutionPolicy Unrestricted
.\ipop-setup

. Check the default.html` content.

use jekyll-include-absolute-plugin to add support for including files outside the _includes directory.

Note: This plugin doesn’t work on GitHub. So we have to build it locally and then upload the _site directory to gh-pages branch and change the GitHub settings so that it loads the website from gh-pages branch instead of master branch.

Include _Sidebar.md to the Jekyll include list in _config.yml:

include:
  - _Sidebar

Insert the sidebar in the wiki template wiki.html. Check the file content.

Add proper styles to main.scss:

.layout--wiki .sidebar .nav__list strong {
  display: block;
  margin: 0.5rem 0;
  padding: 0.5rem 0;
  font-family: -apple-system,".SFNSText-Regular","San Francisco","Roboto","Segoe UI","Helvetica Neue","Lucida Grande",Arial,sans-serif;
  font-weight: bold;
  text-transform: uppercase;
  border-bottom: 1px solid #f2f3f3;
}

.layout--wiki .sidebar .wiki-top-links {
  font-size: .775em;
}

.layout--wiki .sidebar li {
  font-size: .85em;
}

Issues

There is a line in the _layouts/wiki.html to include the wiki sidebar, _site/wiki/_Sidebar.html:

If the file doesn’t exist, Jekyll will throw an error while building the website. It usually happens when you want to delete the old generated files in _site directory and re-build them. This line will always be checked even if it is in a condition that is not TRUE.

A workaround would be to create an empty file at that path manually and after a successful Jekyll build, run the build for the second time to include the wiki sidebar:

touch _site/wiki/_Sidebar.html
bundle exec jekyll build
bundle exec jekyll build