Moving to a static website using zola and github pages

2025-02-03T00:00:00+00:00

Static site generators create a website by converting human readable format files i.e markdown</a> into a web page hierarchy.

We recently moved our website from being hosted on a Debian virtual machines using Wordpress to be a static site that we generate and push to github pages for hosting.

We are very happy with the outcome as now we can;

Keep the website content under version control</li>

Forget about having to host or maintain virtual machines</li>

Forget about having to keep updating Debian and Wordpress</li>

Trivially update the web site with a single git push</code> command.</li> </ul> To help others make the transition we have posted some brief notes below, along with our working configurations. Install the required tools on your workstation</h2>Tools used</h3> zola</a> is a web static site generator written in rust</a>. tabi</a> is a zola theme used to customize the look and layout of a zola generated website. github pages</a> supports hosting web pages directly from a github repository. Install zola and tabi</h3> Instal zola and tabi using the tabi-start</a> repository. If you will be hosting your static site on github pages then call your new github repository https://github.com/<username>/<username>.github.io</code> (so we used https://github.com/flocknetworks/flocknetworks.github.io</code>). This is a reserved name in github that indicates you want the output of this repository to be hosted on github pages as your main domain. Create the website content</h2> zola configuration file</h3> You will find the main zola config file in the root of your repository. This config file also holds the config settings for the zola theme you have chosen, in our case tabi. ncarter@zola:~/src/flocknetworks.github.io$ ls config.toml config.toml </code></pre> This configuration file was created when you ran zola init</code></a>. Below are the settings you are most likely to want to edit. # TODO: Change base_url once flocknetworks.com DNS points to the new site at github.io. # base_url = "https://flocknetworks.com" base_url = "https://flocknetworks.github.io" title = "Flock Networks" description = "Next Generation IP Routing Suite" author = "Nick Carter" theme = "tabi" ... menu = [ { name = "brochure", url = "brochure", trailing_slash = true }, { name = "products", url = "products", trailing_slash = true }, { name = "white papers", url = "whitepapers", trailing_slash = true }, { name = "blog", url = "blog", trailing_slash = true }, { name = "tags", url = "tags", trailing_slash = true }, { name = "about", url = "about", trailing_slash = true }, ] </code></pre> Check website content is correctly generated</h3> Run zola serve</code></a> which will build and then serve your website on your development workstations loopback interface on port 1111</a>. ncarter@zola:~/src/flocknetworks.github.io$ zola serve Building site... Checking all internal links with anchors. > Successfully checked 0 internal link(s) with anchors. -> Creating 7 pages (0 orphan) and 7 sections Done in 99ms. Listening for changes in /home/ncarter/src/flocknetworks.github.io/{config.toml,content,static,themes} Press Ctrl+C to stop Web server is available at http://127.0.0.1:1111 (bound to 127.0.0.1:1111) </code></pre> Where to store your content</h3> The content used to generated your website is held in the well named content</code> directory. If you have content that you want to include that is already in its final form (i.e. PDF documents, PNG images, etc) they should be placed under the static</code> directory. ncarter@zola:~/src/flocknetworks.github.io$ ls content/ about archive blog brochure _index.md privacypolicy products whitepapers ncarter@zola:~/src/flocknetworks.github.io$ ls static docs img ncarter@zola:~/src/flocknetworks.github.io$ </code></pre> content/_index.md</code> is your websites homepage stored in markdown format. ncarter@zola:~/src/flocknetworks.github.io$ head -n 6 content/_index.md +++ [extra] header = { title = "Next Generation IP Routing", img = "img/flock-favicon.jpg" } +++ Flock Networks have upgraded the IP routing suite to match the demands of the modern network. Using 30 years of network architecture and network operations experience, we have created the [third generation](https://www.flocknetworks.com/docs/third-gen-routing-suite-2020-07-27.pdf) of IP routing suite. </code></pre> Publish the website content to your custom domain</h2> DNS changes</h3> Change the DNS settings for your domain name to point at github pages # Github pages IPv4 DNS servers A @ 185.199.108.153 A @ 185.199.109.153 A @ 185.199.110.153 A @ 185.199.111.153 # Github pages IPv6 DNS servers AAAA @ 2606:50c0:8000:0:0:0:0:153 AAAA @ 2606:50c0:8001:0:0:0:0:153 AAAA @ 2606:50c0:8002:0:0:0:0:153 AAAA @ 2606:50c0:8003:0:0:0:0:153 # map canonical subdomain name www.flocknetworks.com to flocknetworks.github.io # Do not use an `A` or `AAAA` record to map subdomains or github pages will fail the subdomain DNS check CNAME www flocknetworks.github.io </code></pre> If you already have DNS settings registered with another hosting company then delete all those records. Add CNAME file in the static dir in your main git branch</h3> ncarter@zola:~/src/flocknetworks.github.io$ git status On branch main ncarter@zola:~/src/flocknetworks.github.io$ cat static/CNAME flocknetworks.com </code></pre> If you don’t have a CNAME</code> file then github will create one (in the auto created gh-pages branch). But be warned github pages custom domain settings will be lost on every git push and your site will become unavailable until you manually reinstate the domain settings. Update zola base_url to point at your domain name</h3> diff --git a/config.toml b/config.toml index 7c2819d..e17f9a1 100644 --- a/config.toml +++ b/config.toml @@ -1,5 +1,5 @@ -base_url = "https://flocknetworks.github.io" +base_url = "https://flocknetworks.com" </code></pre> Add github actions YAML file to build and publish your site</h3> Note that the zola version specified should match the version of zola you are running on your workstation. You also need to give github actions write permissions https://github.com/<username>.github.io/<username>/settings/actions</code>. ncarter@zola:~/src/flocknetworks.github.io$ cat .github/workflows/build.yml name: build.yml Deploy Zola site to Pages on: push: branches: - main jobs: deploy: runs-on: ubuntu-latest steps: - name: Checkout uses: actions/checkout@v4 - name: Build and deploy # @v0.19.2 is the zola version to use, when running zola build. # So match the version we are using locally (zola --version) uses: shalzz/zola-deploy-action@v0.19.2 env: PAGES_BRANCH: gh-pages TOKEN: ${{ secrets.GITHUB_TOKEN }} </code></pre> Add a git pre-push hook</h3> By running zola check</code> we prevent pushing a branch that has broken links. ncarter@zola:~/src/flocknetworks.github.io$ cat .git/hooks/pre-push #!/bin/bash # Verify what is about to be pushed. Called by "git push" after it has # checked the remote status, but before anything has been pushed. # If this script exits with a non-zero status nothing will be pushed. zola check if [ $? -ne 0 ]; then exit 1 fi exit 0 </code></pre> Publish your site</h3> This is simply a case of git pushing your main branch. ncarter@zola:~/src/flocknetworks.github.io$ git status On branch main ncarter@zola:~/src/flocknetworks.github.io$ git push Checking site... Checking all internal links with anchors. > Successfully checked 0 internal link(s) with anchors. Checking 31 external link(s). Skipping 0 external link(s). > Checked 31 external link(s): 0 error(s) found. -> Site content: 7 pages (0 orphan), 7 sections Done in 3.0s. Enumerating objects: 8, done. Counting objects: 100% (8/8), done. Delta compression using up to 8 threads Compressing objects: 100% (5/5), done. Writing objects: 100% (5/5), 3.55 KiB | 3.55 MiB/s, done. Total 5 (delta 3), reused 0 (delta 0), pack-reused 0 remote: Resolving deltas: 100% (3/3), completed with 3 local objects. To github.com:flocknetworks/flocknetworks.github.io.git + 3e5e868...646f631 main -> main </code></pre> Your website content will be built in the gh-pages</code> branch (as specified in build.yml) ncarter@zola:~/src/flocknetworks.github.io$ git log origin/gh-pages commit 32d4a17f463bbbcf84ea6d3cfed20ca701d93e73 (origin/gh-pages) Author: GitHub Actions <github-actions-bot@users.noreply.github.com> Date: Wed Feb 26 10:47:17 2025 +0000 Deploy flocknetworks/flocknetworks.github.io to flocknetworks/flocknetworks.github.io:gh-pages </code></pre> Tell github pages to use your custom domain</h3> Visit https://github.com/<username>/<username>.github.io/settings/pages</code> and set the “Custom Domain” to your domain name. If the “Custom Domain” DNS check is failing then check your DNS changes are correct and have come live (DNS records are widely cached so the old entries need time to go stale and expire). ncarter@condor:~$ dig flocknetworks.com | grep flocknetworks.com ; <<>> DiG 9.18.33-1~deb12u2-Debian <<>> flocknetworks.com ;flocknetworks.com. IN A flocknetworks.com. 2954 IN A 185.199.108.153 flocknetworks.com. 2954 IN A 185.199.111.153 flocknetworks.com. 2954 IN A 185.199.110.153 flocknetworks.com. 2954 IN A 185.199.109.153 </code></pre> Enable SSL by clicking on the button. github pages will then get a certificate from the lovely folks at lets encrypt</a> and github pages will automatically renew it for you before the certificate expires. Your website should now be globally accessible at https://<your-domain-name></code> Updating the website with new content</h2> Now everything is set up, updating content on the web site is as simple as; git commit</code></li> git push</code></li> </ul> ncarter@zola:~/src/flocknetworks.github.io$ git status On branch main ncarter@zola:~/src/flocknetworks.github.io$ git commit -a -m "my new content" [main 8a3b1ab] my new content 1 file changed, 7 insertions(+) ncarter@zola:~/src/flocknetworks.github.io$ git push Checking site... Checking all internal links with anchors. > Successfully checked 0 internal link(s) with anchors. Checking 32 external link(s). Skipping 0 external link(s). > Checked 32 external link(s): 0 error(s) found. -> Site content: 7 pages (0 orphan), 7 sections Done in 2.9s. Enumerating objects: 9, done. Counting objects: 100% (9/9), done. Delta compression using up to 8 threads Compressing objects: 100% (5/5), done. Writing objects: 100% (5/5), 570 bytes | 570.00 KiB/s, done. Total 5 (delta 4), reused 0 (delta 0), pack-reused 0 remote: Resolving deltas: 100% (4/4), completed with 4 local objects. To github.com:flocknetworks/flocknetworks.github.io.git 97b67e5..8a3b1ab main -> main </code></pre> References</h2> https://thedataquarry.com/posts/static-site-zola/</a>

Moving from C to Rust

2019-11-27T00:00:00+00:00

I have spent many years systems programming in C. I have been playing around with Rust since 2015 and this year I decided to switch to primarily programming in Rust. This blog post is an attempt to explain why I have made this decision.

Although I have a background in Computer Science, at heart I’m a Developer / Network Engineer who just wants to “get stuff done” ™. I’ve played with many languages over the years and for me it was C and Python that stuck. I’m still a big fan of both of those languages.

When I first started playing with Rust, all my initial projects were checking how it felt as a systems programming language. That is, could I layout structures in memory as required ? How easy was it to call into C libraries using FFI ? And in particular how easy was it to interface with the Linux Kernel and put IP packets ‘on the wire’ ? I found Rust a good fit for this, probably because it is a C like language, so looked and felt familiar. As an aside, many developers who try Rust initially end up “fighting the borrow checker” that is built into the compiler. [In very rough terms the borrow checker makes sure that your code either has a single pointer to a mutable object, or multiple pointers to an immutable object, but never both]. If you are coming from programming in C then you can quite quickly work out why it’s complaining. However, it really makes you think hard about your data model, and who really owns each allocation of data. This can be painful if you are just trying to prototype something, but it is time well spent on anything that will end up in production.

My two compelling reasons for moving to Rust</h2>
Having decided that Rust was a capable systems programming language, I found there were 2 compelling reasons to make the move to Rust.
The first reason is that Rust is memory safe at compile time. This means you can say goodbye to the runtime memory corruption bugs you get in C. In safe Rust there is no ‘reading of’ or ‘writing to’ an invalid pointer. As I said earlier, I like C as a language, but hitting memory corruption bugs in production code is not fun. The worst part is that the point at which the program terminates, say due to a segfault to an invalid address, is likely to be thousands or millions of instructions after the code with the bug has executed. This makes finding the offending code difficult. I once spent over 3 weeks fixing a memory corruption bug in some IP Router software. That’s not something I’m proud of, but nor is it something I’m ashamed of. We could only reproduce the corruption when the device was running in production, and with all logging turned off. Fixing the bug came down to reasoning about 100,000’s of lines of C code. Eventually we came up with a theory about what was happening, wrote a ‘fix’ and the problem was never seen again. Whether we actually fixed the issue, or just changed some timing of events, I will never know. As an engineer this feels wholly inadequate.
The second reason is that Rust is data race free at compile time. As discussed above, memory corruption in single threaded code can be very hard to debug. Memory corruption in multi-threaded code is an order of magnitude more complicated. In my experience, it is possible to write reliable multi-threaded C, but you need to be very conservative and keep the threading model very simple (no bad thing), but refactoring the code is a major undertaking. In multi-threaded code there is such an explosion of event sequences that can happen, it is not possible to have exhaustive testing in place. With CPU frequencies levelling off and being replaced by multiple cores, the future of systems programming will need to be multi-threaded.

Drawbacks of moving to Rust</h2>
Rust certainly has some drawbacks when compared to C. For me the main one is the size of the executable produced by the compiler. In my experience of writing similar applications in C and in Rust, Rust release binaries tend to be around 5x larger than C release binaries. This is a combination of the fact that the Rust compiler optimizes for speed not size</a> and Rust projects suffer from dependency bloat</a>. The Rust binary can be made smaller</a>, and the dependency bloat problem actually comes from the advantage that you can so easily reuse other people’s libraries. But with Rust there is an extra step you need to take before releasing code, and that is to audit what is contributing to the binary size and is it a reasonable trade off? In the same way performance needs to be benchmarked between releases, with Rust binary size also needs to be tracked, to catch and investigate any large increases.
Rust also currently suffers from long compile times, and IDE support using RLS</a> is slow and a CPU hog.

Moving a development team from C to Rust</h2>
Moving a development team from implementing in language A to language B is always going to be a hard sell if they do not already know language B. The team will have years / decades of experience in language A. Rust is a new language so it is likely a team of C programmers will not know Rust.
On top of this, Rust tends to pay back during the final stages of the development life cycle. I would guess that a team that knows both C and Rust, who started working on a new project, would be able to ship the first version of the software earlier if they wrote it in C rather than Rust. Rust tends to catch bugs earlier, at compile time rather than run time, which delays the production of the next binary. Rust forces the developer to iterate over the data model, until it is clean, before the code gets too complex, again delaying the production of the next binary. With Rust the team will probably implement Unit tests and Integration tests as they develop because all the infrastructure is in hand. With C the team may choose to produce the binary first and then possibly wrap some testing around it after. The QA teams will hit runtime panics in Rust that are hidden in C, again pushing out the date that the project ships.
So the sales pitch to management would go something like this. We have a team of highly skilled C developers. I suggest our new product “The IP packet mangler” should be written in Rust. On one hand if we write it in C we will ship it earlier and bring in revenue earlier. On the other hand Rust is shiny and new and would look good on our CV’s. Also the Rust compiler gives very pleasant error messages.
But wait, by catching bugs early, Rust gives you a huge payback in the long term. The C team have shipped a release with more bugs than the Rust team. Customers will be hitting bugs in the C product that don’t exist in the Rust product. As each team is working on the v1.1 features the C team will be interrupted more on bug fixes. This will cause frustration as most bug fixes are more important than implementing new features. The C development team will be getting more randomly timed, high level interrupts of various length, stopping them doing the ‘real work’ of implementing the new features.
Maybe the v1.1 C and Rust versions will ship around the same time. After that the Rust team will pull ahead, as the bug backlog for both teams will now cover multiple releases. The Rust team will probably ship v1.2 and all subsequent releases earlier and to a higher quality.
Obviously there is a lot of conjecture in the above argument, and it is slightly tongue in cheek. However I think the main point stands that it is preferable to pay your development costs upfront and as early as possible.
In summary</h2>
You might be able to prototype faster in C, but I believe you will reach production quality faster in Rust. Also with Rust, keeping that production quality high going forward will be easier.
And that is why I have moved from C to Rust.

Publish the website content to your custom domain</h2>

References</h2>
https://thedataquarry.com/posts/static-site-zola/</a></p>

In summary</h2>
You might be able to prototype faster in C, but I believe you will reach production quality faster in Rust. Also with Rust, keeping that production quality high going forward will be easier.</p>
And that is why I have moved from C to Rust.</p>

Flock Networks

Moving to a static website using zola and github pages

Install the required tools on your workstation</h2>

Tools used</h3>
zola</a> is a web static site generator written in rust</a>. tabi</a> is a zola theme used to customize the look and layout of a zola generated website. github pages</a> supports hosting web pages directly from a github repository.</p>

Great observability via fast JSON serialization

How many OSPF routers can be deployed in one area ?

Moving from C to Rust

Rust in 2020

Hello, World!

Flock Networks

Moving to a static website using zola and github pages

Install the required tools on your workstation</h2>

Tools used</h3> zola</a> is a web static site generator written in rust</a>. tabi</a> is a zola theme used to customize the look and layout of a zola generated website. github pages</a> supports hosting web pages directly from a github repository.</p>

Create the website content</h2> zola configuration file</h3> You will find the main zola config file in the root of your repository. This config file also holds the config settings for the zola theme you have chosen, in our case tabi.</p>

zola configuration file</h3> You will find the main zola config file in the root of your repository. This config file also holds the config settings for the zola theme you have chosen, in our case tabi.</p>

Publish the website content to your custom domain</h2>

DNS changes</h3> Change the DNS settings for your domain name to point at github pages</p>

Updating the website with new content</h2> Now everything is set up, updating content on the web site is as simple as;</p> git commit</code></li>

References</h2> https://thedataquarry.com/posts/static-site-zola/</a></p>

Great observability via fast JSON serialization

How many OSPF routers can be deployed in one area ?

Moving from C to Rust

In summary</h2> You might be able to prototype faster in C, but I believe you will reach production quality faster in Rust. Also with Rust, keeping that production quality high going forward will be easier.</p> And that is why I have moved from C to Rust.</p>

Rust in 2020

Hello, World!

Tools used</h3>
zola</a> is a web static site generator written in rust</a>. tabi</a> is a zola theme used to customize the look and layout of a zola generated website. github pages</a> supports hosting web pages directly from a github repository.</p>

References</h2>
https://thedataquarry.com/posts/static-site-zola/</a></p>

In summary</h2>
You might be able to prototype faster in C, but I believe you will reach production quality faster in Rust. Also with Rust, keeping that production quality high going forward will be easier.</p>
And that is why I have moved from C to Rust.</p>