Installing WireGuard on pfsense

• pfsense version 2.5.2
• WireGuard version 0.1.5

Navigate to System > Package Manager > Available Packages

Search for WireGuard and Install.

Configuring WireGuard Server

Create Tunnel

Navigate to VPN > WireGuard

Create a tunnel by clicking Add Tunnel

• Disable Tunnel
• Add a Description
• Change the listen port or leave at default of 51820
• Generate New Keys
• Copy Public Key, you’ll need it later when configuring a client

Click Save Tunnel

Configure Interface and Enable Tunnel

Navigate to Interfaces > Assignments

On the Available Network Ports row, select the tun_wg0 interface and click add.

• Enable Interface
• Add a Description
• Static IPv4
• IPv6: None (unless preferred)
• IPv4 Address: Choose an IPv4 Address and Subnet Mask

Click Save

Navigate to VPN > WireGuard

Click Edit on your new tunnel and enable the tunnel

Configure Firewall

Navigate to Firewall > Rules

Create a new WAN Rule

• Action: Pass
• Interface: WAN
• Address Family: IPv4
• Protocol: UDP
• Source: any
• Destination: WAN Address
• Destination Port Range: 51820
• Log Packets, if preferred
• Add a description
• Tag: vpn (if desired, not used but could be in other rules)

Click Save

Create a new VPN Rule (VPN is the name of the interface)

• Action: Pass
• Interface: VPN
• Address Family: IPv4
• Protocol: Any
• Source: any
• Destination: LAN net

Click Save

Repeat the VPN rules to allow all desired access

Configuring a Client

I will use a CentOS Stream system for this example but any client can be used the configuration is the same, installations will differ though.

Install WireGuard

WireGuard Installation

For CentOS I followed Method 2

sudo yum install elrepo-release epel-release
sudo yum install kmod-wireguard wireguard-tools

Key Generation

Once installed you can follow these instructions to generate a key Key Generation

umask 077
wg genkey | tee privatekey | wg pubkey > publickey

Your private key is stored in a file ‘privatekey’, use this in the next step Your public key is stored in a file ‘publickey’, use this when adding the peer in pfsense later

Interface Config File

vim /etc/wireguard/wg0.conf
[Interface]
PrivateKey = YLzz2QbAowMXx913RyXsr33FVlcNZ+wx96vVKtdL9nk= (privatekey generated in previous step)
Address = IP Address assigned to this client in VPN Subnet

[Peer]
PublicKey = iQSIKmjCbWR57bu0kk774Sg03t80dRyV64UXIv2ADFY= (public key generated during tunnel creation)
AllowedIPs = 192.168.0.0/24 (Any Subnets you want this client to route through the VPN Tunnel, can use 0.0.0.0/0 if you want all traffic routed through VPN)
EndPoint = 1.2.3.4:51820 (PFsense Router WAN IP Address or DNS Name and Wirguard Port configured on tunnel)

Adding a Peer

Descriptions on the configurations below can be found here

Navigate to VPN > WireGuard > Peers

Add Peer

• Enable Peer
• Select the tunnel we created
• Add a description of the peer
• Public Key generated on client during configuring a client
• Allowed IPs should be the Interface Address from the client.

The Allowed IPs is what was a source of confusion for me when setting up the WireGuard Server. I couldn’t have more than one peer and it was due to setting the allowed IPs to 0.0.0.0/0 for both peers. Remember the Allowed IPs are what traffic is routed through the tunnel, you can’t have 2 default routes in this case.

Click Save Peer

Testing Client

On your client run the following command

wg-quick up wg0

You should see some routes created

[#] ip link add wg0 type wireguard
[#] wg setconf wg0 /dev/fd/63
[#] ip -4 address add 10.10.10.10/32 dev wg0
[#] ip link set mtu 1420 up dev wg0
[#] ip -4 route add 0.0.0.0/0 dev wg0

You should now be able to test connectivity by pinging your WireGuard tunnel interface IP Address This was set when the interface was assigned and you chose your WireGuard subnet Configure Interface

To ensure the interface is configured at startup after any reboots use the following command

systemctl enable wg-quick@wg0

VIM can be hard. Remembering all the neat shortcuts achieved by such an awesome tool is harder.

This won’t be a cheat sheet that helps with the basics but rather an ever expanding post on shortcuts that I discover to help improve efficiency.

If you would like me to write a post on these pre-requisites. Please let me know in the comments!

Pre-Requisites

Domain, VPS, and nginx Configuration

Setup your A Record to point your domain name to your webserver

nginx install

Create simple nginx configuration file, /etc/nginx/conf.d/<domain>.conf

server {
    server_name  <domain-name> www.<domain-name>;
    root         /var/www/<domain-name>/public;

    index index.html;

    location / {
        try_files $uri $uri/ =404;
        add_header Permissions-Policy interest-cohort=();
    }

    listen       80;
    listen       [::]:80;
    return 404; 
}

Create a temporary index.html in your website’s root directory, /var/www/<domain>/public/index.html

<html>
<p><domain></p>
</html>

Start and Enable nginx

systemctl enable --now nginx.service

If necessary, allow HTTP and HTTPS through firewall

firewall-cmd --add-service=http --permanent
firewall-cmd --add-service=https --permanent
firewall-cmd reload

You should be able to verify access to your webserver over port 80 at this point.

After a successful verification you can continue finishing the configuration.

SSL with acme.sh

For SSL you can find all Let’s Encrypt client options here

I recommend acme.sh

Install acme.sh

get.acme.sh

Issue cert for your domain

acme.sh --issue -d <domain> -w /var/lib/nginx/<domain>

Install certificate to an nginx directory

acme.sh --install-cert -d <domain> \
--key-file       /etc/nginx/<domain>/key.pem  \
--fullchain-file /etc/nginx/<domain>/cert.pem \
--reloadcmd     "service nginx force-reload"

acme registers a cron job to run daily. This will ensure your certificate is always valid and will restart your webserver.

Create Hugo Website

Hugo Installation

Locate a Hugo theme you’d like to use

I’m using PaperMod

PaperMod installation instructions are here

Once you have followed the installation instructions for your theme you can begin customizing your site.

Again, each theme has their own configuration options; however, I’ll explain the general layout of the hugo folder structure to help you understand where to go.

Ensure you are inside the websites directory.

cd ~/Projects/davidspencer.xyz

tree -L 1 .
.
├── archetypes
├── config.yml
├── content
├── layouts
├── resources
├── static
└── themes

Most of the configuration will be done in the config.yml file You can see my exact configuration at my repo

baseURL: https://davidspencer.xyz
languageCode: en-us
title: Title of Website
theme: Theme Name
env: production

outputs:
  home:
    - HTML
    - RSS
    - JSON

params:
  assets:
    disableHLJS: true
    disableFingerprinting: false
    favicon: "/favicon.ico>"
    favicon16x16: "/favicon-16x16.png"
    favicon32x32: "/favicon-32x32.png"
    apple_touch_icon: "/apple-touch-icon.png"
    safari_pinned_tab: "/safari-pinned-tab.svg"

  socialIcons:
    - name: "linkedin"
      url: "https://www.linkedin.com/in/davidjspencer/"
    - name: "github"
      url: "https://github.com/Elevate08"
    - name: "email"
      url: "mailto:david@davidspencer.xyz"
    - name: "rss"
      url: "/index.xml"

  editPost:
      URL: "https://github.com/Elevate08/davidspencer.xyz/blob/master/content"
      Text: "Suggest Changes" # edit text
      appendFilePath: true # to append file path to Edit link

  fuseOpts:
    minMatchCharLength: 3
    keys: ["title", "content", "summary"]

menu:
  main:
    - identifier: tags
      name: tags
      url: /tags/
      weight: 20
    - identifier: search
      name: search
      url: /search/
      weight: 30

markup:
  highlight:
    codeFences: true
    guessSyntax: false
    style: native
    tabWidth: 4

Once you have some settings in place for your site you can create a new post.

hugo new posts/first-post.md

Using your editor of choice, write up your first post using Markdown.

You can learn about Markdown here Markdown Guide

Once you have some content created run the following command

hugo server

Watching for config changes in /home/elevate/Projects/davidspencer.xyz/config.yml
Environment: "development"
Serving pages from memory
Running in Fast Render Mode. For full rebuilds on change: hugo server --disableFastRender
Web Server is available at http://localhost:1313/ (bind address 127.0.0.1)

You should now be able to access your hugo website at the location provided.

This is how most development / testing of new content can be done.

Click around and test out your new site.

Deploying Hugo Website using GitHub Actions

Up until now we have just been working locally. You should have a working development environment where you can access your site locally.

To make deployment to your VPS easier and allow you to focus on just creating new content, let’s setup some GitHub Actions to do some work for us!

cd ~/Projects/davidspencer.xyz
git init

Usually at this point I’d run git add .; however, you most likely need to configure the git submodule for your theme.

We want to be able to pull a fresh version from the repo every time we deploy.

You should be able to run the following command without error.

git submodule add <theme clone url>

If you do run into an error let me know in the comments and I’ll help you troubleshoot.

Once the theme repo is properly added as a submodule we can continue.

At this time you should login to GitHub and create a new repo. Grab the clone URL.

git add .
git commit -m "initial upload"
git remote add origin git@github.com:/Elevate08/davidspencer.xyz
git push -u origin master

Now to make our github action file, we will need to create a couple directories.

mkdir -p .github/workflows
touch .github/workflows/main.yml

Add the following text to your main.yml file

name: Hugo to VPS

on:
  push:
    branches:
      - master  # Set a branch to deploy
  pull_request:

jobs:
  deploy:
    runs-on: ubuntu-20.04
    steps:
      - uses: actions/checkout@v2
        with:
          submodules: true  # Fetch Hugo themes (true OR recursive)
          fetch-depth: 0    # Fetch all history for .GitInfo and .Lastmod

      - name: Setup Hugo
        uses: peaceiris/actions-hugo@v2
        with:
          hugo-version: 'latest'
          # extended: true

      - name: Build
        run: hugo --minify

      - name: Deploy
        uses: appleboy/scp-action@master
        with:
          host: ${{ secrets.HOST }}
          port: ${{ secrets.PORT }}
          username: ${{ secrets.USERNAME }}
          key: ${{ secrets.KEY }}
          source: "./public"
          target: "/var/www/davidspencer.xyz"

In my workflow, i’m using scp-action to copy the generated website files to my server.

This means we’ll need to create some secrets on our repo.

In your repository on GitHub create the following secrets Settings > Secrets > New repository secret

• HOST
• KEY
• PORT
• USERNAME

I’ll assume you have knowledge on SSH and what the secrets should contain.

I’d encourage you to generate a unique key pair and user for this action.

cd ~/Projects/davidspencer.xyz
git add .
git commit -m "adding github action for automated deployments"
git push

You can now watch the action run on GitHub and monitor your VPS for the website files to be copied over.

Setup

• Install neovim
• Install Python

neovim configuration

All of the config files for neovim will be in our config directory. If any of the folders or files do not exist we will create them now.

mkdir -p ~/.config/nvim/lua
touch ~/.config/nvim/init.vim
touch ~/.config/nvim/lua/{lua_config,lsp_config}.lua

Using neovim, we will edit the init.vim

syntax on                       "syntax highlighting, see :help syntax
filetype plugin indent on       "file type detection, see :help filetype
set number                      "display line number
set relativenumber              "display relative line numbers
set path+=**                    "improves searching, see :help path
set noswapfile                  "disable use of swap files
set wildmenu                    "completion menu
set backspace=indent,eol,start  "ensure proper backspace functionality
set undodir=~/.cache/nvim/undo  "undo ability will persist after exiting file
set undofile                    "see :help undodir and :help undofile
set incsearch                   "see results while search is being typed, see :help incsearch
set smartindent                 "auto indent on new lines, see :help smartindent
set ic                          "ignore case when searching
set colorcolumn=80              "display color when line reaches pep8 standards
set expandtab                   "expanding tab to spaces
set tabstop=4                   "setting tab to 4 columns
set shiftwidth=4                "setting tab to 4 columns
set softtabstop=4               "setting tab to 4 columns
set showmatch                   "display matching bracket or parenthesis
set hlsearch incsearch          "highlight all pervious search pattern with incsearch

highlight ColorColumn ctermbg=9 "display ugly bright red bar at color column number

" Keybind Ctrl+l to clear search
nnoremap <C-l> :nohl<CR><C-l>:echo "Search Cleared"<CR>

" When python filetype is detected, F5 can be used to execute script 
autocmd FileType python nnoremap <buffer> <F5> :w<cr>:exec '!clear'<cr>:exec '!python3' shellescape(expand('%:p'), 1)<cr>

I set colorcolumn to 80 instead of 79 due to preferring the red wall, this way I can type up to the wall instead of having one character on the wall.

ref: pep8

Installing vim-plug and LSP Plugins

vim-plug is my plugin manager of choice. If you use a different plugin manager you can do so.

vim-plug neovim install

There are two plugins we will need

• nvim-lspconfig
• completion-nvim

To install these using vim-plug we will add the following section to our init.vim

"vim-plug configuration, plugins will be installed in ~/.config/nvim/plugged
call plug#begin('$XDG_CONFIG_HOME/nvim/plugged') 

Plug 'neovim/nvim-lspconfig'
Plug 'nvim-lua/completion-nvim'

call plug#end()

Install plugins

nvim
:PlugInstall

Configuring neovim Language Server Protocol (lsp)

We have a pretty good setup at this point. But to make it better we can add a Language Server using the Language Server Client built into neovim

You can read all about it here. neovim lsp

Essentially each programming language has it’s own language server that needs installed. The nvim-lspconfig plugin we installed earlier ensures language servers are launched appropriately when needed. However, for this to work we have to install language servers ourselves.

There are other projects that aim to automate the installation of language servers; however, I have not tested them. automatic language server installation

I will continue with the manual installation of a language server.

The nvim-lspconfig repo has an exhaustive list of language server options. I recommend using this when looking for a language server to use.

For python, I use pylsp.

pip3 install -U setuptools pip
pip3 install 'python-lsp-server[all]'

With that installed, we can now configure neovim so that it will load pylsp when we are working on a python project.

Earlier we created some files

• ~/.config/nvim/lua/lsp_config.lua
• ~/.config/nvim/lua/lua_config.lua

Lets edit lua_config.lua first. Add the following to the lua_config.lua file.

require('lsp_config')

Add the following to the lsp_config.lua file

local lsp = require('lspconfig')
local completion = require('completion')

local custom_attach = function()
    completion.on_attach()
    -- Python specifically isn't setting omnifunc correctly, ftplugin conflict
    vim.api.nvim_buf_set_option(0, 'omnifunc', 'v:lua.vim.lsp.omnifunc')
end

lsp.pylsp.setup{on_attach=custom_attach}

The lsp_config.lua file contains a couple functions to make loading multiple language servers a bit cleaner.

If you want to add any additional language servers you can add a line to the bottom using the following template.

lsp.<language_server>.setup{on_attach=custom_attach}

The final step will be to add a configuration to our init.vim

Open ~/.config/nvim/init.vim and add the following lines.

" neovim LSP Configuration
lua require('lua_config')

" Enable Tab / Shift Tab to cycle completion options
inoremap <expr> <Tab>   pumvisible() ? "\<C-n>" : "\<Tab>"
inoremap <expr> <S-Tab> pumvisible() ? "\<C-p>" : "\<S-Tab>"
let g:completion_enable_fuzzy_match = 1
set completeopt=menuone,noinsert,noselect

Conclusion

You should now be able to open any python file without any errors.

Additionally, you should have auto-complete and linting enabled.

You should be able to navigate between auto-complete options using Tab / Shift Tab. Or natively Ctrl+n or Ctrl+p.

You will need to have a few things in order before we can get started

• GitHub Account
• Docker Hub Account
• Podman Installation

Creating Website Files

Create your project directory wherever you prefer. For this tutorial I’ll be using ~/Projects/container-demo for the project folder.

In your terminal, navigate to this project folder and create a content folder.

cd ~/Projects/container-demo
mkdir content

Using your editor of choice, create an index.html file inside the content folder with the following content

<html>
Hello World!
</html>

Great, now we have our simple website that we’re ready to use and Generate our versioned Docker Image.

Running Container Locally

Now that we have the website data we would like to use, we can add this to an existing Docker image like nginx. We will start by testing the website files on a nginx container to ensure functionality prior to building the image.

If you’re confident, you can skip this step and go to the next section Building a Docker Image.

podman run -d -p 8008:80 -v ./content:/usr/share/nginx/html:Z,ro nginx

At this point you should be able to navigate to the website. In my case the url is http://pod1.davidspencer.xyz:8008.

Yours would most likely be http://localhost:8008 or replace localhost with the hostname/ip of your podman host.

After you have successfully accessed your Hello World! Website, you can stop and remove your container

podman container list
podman container stop <container-name>
podman container rm <container-name>

Building a Docker Image

We can now build our custom Image.

There are a few benefits to this; however one point I’d like to make is that doing this will make it so that we don’t have to mount our local files to the container every time.

Add the following text to a new file ~/Projects/container-demo/Dockerfile

FROM nginx
COPY content /usr/share/nginx/html

With this file created, you can now run the following command to build and image locally.

podman build -t container-demo .

You should see container-demo in your images now

podman image list container-demo

REPOSITORY                TAG     IMAGE ID      CREATED        SIZE
localhost/container-demo  latest  02e3e1343eda  8 seconds ago  137 MB

We can now create a container using this image to see our Hello World! Website

podman run -d -p 8008:80 localhost/container-demo

Test the site using the same URL from earlier

After a successful test, stop and remove the new container.

podman container list
podman container stop <container-name>
podman container rm <container-name>

You can delete the image after you have removed the container.

podman image rm <image id>

Initialize GitHub Repo

Ensure you are logged into GitHub

Click New

Enter a name for the repo

Click “Create Repository” at the bottom

Copy either the HTTPS or SSH URL Depending on how you use git

Back to your terminal, we’ll push our existing content to GitHub

cd ~/Projects/container-demo
git init
git add .
git commit -m "Initial Upload"
git remote add origin <repo_url>
git push -u origin master

Now we should have our repo in GitHub with our project. We are now ready to build out the GitHub Actions and really tie this whole thing together.

Build GitHub Actions

cd ~/Projects/container-demo
mkdir -p .github/workflows

Add the following text to a new file,

~/Projects/container-demo/.github/workflows/main.yml

name: CI to Docker Hub

on:
  # Triggers the workflow on push events but only when they are tagged with v*.*.*
  push:
    tags:
      - "v*.*.*"

  workflow_dispatch:

jobs:
  build:
    runs-on: ubuntu-latest

    steps:
      # Check Out Repo to work with project files
      - name: Check out Repo
        uses: actions/checkout@v2
        
      # Login to Docker Hub
      - name: Login to Docker Hub
        uses: docker/login-action@v1
        with:
          username: ${{ secrets.DOCKER_HUB_USERNAME }}
          password: ${{ secrets.DOCKER_HUB_ACCESS_TOKEN }}
          
      # Uses Cache to improve build time
      - name: Cache Docker layers
        uses: actions/cache@v2
        with:
          path: /tmp/.buildx-cache
          key: ${{ runner.os }}-buildx-${{ github.sha }}
          restore-keys: |
            ${{ runner.os }}-buildx-

      # Checks-out your repository under $GITHUB_WORKSPACE,
      # so your job can access it.
      - name: Set up Docker Buildx
        id: buildx
        uses: docker/setup-buildx-action@v1

      # Sets the steps.get_version.outputs.VERSION variable
      # for proper Docker Hub Image versioning.
      - name: Get the version
        id: get_version
        run: echo ::set-output name=VERSION::${GITHUB_REF/refs\/tags\//}
        
      # Build Docker Image and push latest / v*.*.* to Docker Hub
      - name: Build and push
        id: docker_build
        uses: docker/build-push-action@v2
        with:
          context: ./
          file: ./Dockerfile
          builder: ${{ steps.buildx.outputs.name }}
          push: true
          tags: |
            ${{ secrets.DOCKER_HUB_USERNAME }}/container-demo:latest
            ${{ secrets.DOCKER_HUB_USERNAME }}/container-demo:${{ steps.get_version.outputs.VERSION }}
          cache-from: type=local,src=https://davidspencer.xyz/tmp/.buildx-cache
          cache-to: type=local,dest=/tmp/.buildx-cache
      
      - name: Image digest
        run: echo ${{ steps.docker_build.output.digest }}

Let’s push our changes to the repo now.

git add .
git commit -m "Adding GitHub Workflow"
git push

Now we can generate our Docker Hub personal token We will also setup our GitHub Secrets.

Follow the directions here for generating your access token

Once you have your token go to your Repo on GitHub.com

Click on Secrets

Click on New Repository Secrets

Repeat the same process for DOCKER_HUB_ACCESS_TOKEN

Push image to Docker Hub

Open content/index.html in your editor and make a change

<html>
Hello World!
v1.0.0
</html>

git add .
git tag -a v1.0.0 -m "v1.0.0"
git commit -m "releasing v1.0.0"
git push -u origin v1.0.0

You can track the action status from the Action tab on your repo

You should eventually see the image in your Docker Hub

Lastly you can even see the tags on the image, v1.0.0 and latest

The latest tag will always be the latest and you’ll have a history of versions associated with the image as you make changes.

Conclusion

I hope you have found this tutorial informative and helpful. If you have any suggestions on how this can be improved, please use the “Suggest Edits” button at the top or send me an email.