Motivation

For fun I want to host my portfolio site on a homebrew FreeBSD server running iocage jails. This portfolio site (the one you are reading now) is intented to present some of my explorations in computer science and by the side getting me hired.

For tuning up the site, a development copy must run on my desktop machine, a FreeBSD (13.0-RELEASE) + KDE plasma (5.22). So I installed zola on FreeBSD.

I - Installation on the development computer (desktop)

1 - Zola installation on FreeBSD

dc@kahlo /u/h/dc> pkg search zola
zola-0.15.2                    Fast static site generator
dc@kahlo /u/h/dc> sudo pkg install zola

2 - Visual Studio Code installation

dc@kahlo /u/h/dc> pkg search vscode
vscode-1.63.2                  Visual Studio Code - Open Source ("Code - OSS")
dc@kahlo /u/h/dc> sudo pkg install vscode

II - Installation on the host

1 - Creating the document root

We choose a place to put the code generated by the output of the zola build. In FreeBSD the web sites are located in /usr/local/www so /usr/local/www/portfolio/public directory will be created.

2 - Setting up Apache

2.a - Apache virtual host

The apache server is already installed, so only a virtual host must be written. In FreeBSD apache configs stay in /usr/local/etc/apache24/.

The Includes directory is used to enable the virtual hosts and the Excludes to disable them.

The virtual host config shows as :

<VirtualHost *:80>
             ServerName portfolio.osca.dev:80

             <Directory />

                AllowOverride none
                Require all denied

            </Directory>

            ErrorLog "/var/log/portfolio.error.log"

            <IfModule log_config_module>

                LogFormat "%h %l %u %t \"%r\" %>s %b \"%{Referer}i\" \"%{User-Agent}i\"" combined
                LogFormat "%h %l %u %t \"%r\" %>s %b" common

                <IfModule logio_module>
                  LogFormat "%h %l %u %t \"%r\" %>s %b \"%{Referer}i\" \"%{User-Agent}i\" %I %O" combined
                </IfModule>

                CustomLog "/var/log/portfolio.log" common

            </IfModule>

            DocumentRoot "/usr/local/www/portfolio/public"

            <Directory "/usr/local/www/portfolio/public">

                Options Indexes FollowSymLinks
                AllowOverride All
                Require all granted

            </Directory>
</VirtualHost>

2.b - Checking and reloading the web server config

root@rps_aura:~ # service apache24 configtest
Performing sanity check on apache24 configuration:
Syntax OK
root@rps_aura:~ # service apache24 reload
Performing sanity check on apache24 configuration:
Syntax OK
Performing a graceful restart

III - Developing and Tuning on the desktop machine

1 - Launching zola as a web server

Without --interface and --base-url options the default URL is 127.0.0.1:1111. By setting the interface and base-url options to a valid ip address the developement web site is reachable by the local network (your colleagues).

Note the output directory (public in our case) is deleted when zola as a web server is launched. Building the site before synchronization is mandatory.

dc@kahlo /u/h/d/w/osca.dev (master)> zola serve --interface 192.168.0.18 --base-url 192.168.0.18
Building site...
Checking all internal links with anchors.
> Successfully checked 1 internal link(s) with anchors.
-> Creating 37 pages (4 orphan) and 12 sections
Done in 117ms.

Listening for changes in /usr/home/dc/w/osca.dev{config.toml, content, sass, static, themes}
Press Ctrl+C to stop

Web server is available at http://192.168.0.18:1111

2 - Working in the content directory

The content directory is the place where the markdown files .md are stored. The tree structure is important and so the file naming. For a multilingual zola web site, the language code [cat, oc, en, fr] must be added as an extension to instruct zola that the generated html file must go in its respective subdirectory in the output directory. Here the [en] code is the default language so no need to suffix the filename for the default language.

content
├── _index.cat.md
├── _index.fr.md
├── _index.md
├── _index.oc.md
├── about.cat.md
├── about.fr.md
├── about.md
├── about.oc.md
├── landing
│  ├── portfolio.cat.md
│  ├── portfolio.fr.md
│  ├── portfolio.md
│  └── portfolio.oc.md
├── posts
│  ├── _index.cat.md
│  ├── _index.fr.md
│  ├── _index.md
│  ├── _index.oc.md
│  ├── deploy_zola.md
│  ├── neo4j.md
// //
│  └── ontology.md
└── projects
   ├── _index.cat.md
   ├── _index.fr.md
   ├── _index.md
   ├── _index.oc.md
   ├── calelh.md
   ├── calelh.oc.md
   ├── conjoc.cat.md
   ├── conjoc.md
   └── conjoc.oc.md

• Adding directories inside content results in adding a new section.
• Adding a .md file in a directory results in new page directly accessible by its name.
• Adding a .md file in the post directory results in adding a new post.

You can see the modification of your site, each time you modify a file or create a new one. When the result is ok for you, you can proceed with the synchronization.

IV Building the site and synchronizing

1 - config.toml important variables

base_url and output_dir are config.toml variables used by the build. base_url MUST be the definitive url. output_dir is where the output (the source dir) must be synchronized with the deployment host.

# The URL the site will be built for
base_url = "https://portfolio.osca.dev"

output_dir = "public"

2 - Building the web site

Building the site means generating the web site into the output directory. Its content could then be copied into the host during the deployment phase.

dc@kahlo /u/h/d/w/osca.dev (master)> zola build
Building site...
Checking all internal links with anchors.
> Successfully checked 1 internal link(s) with anchors.
-> Creating 37 pages (4 orphan) and 12 sections
Done in 161ms.

3 - Deploying, synchronizing w/ the host

A bash script takes care of deleting the useless files and copying the new ones to the target machine at the right place. No Apache restart necessary on the host side.

#!/usr/local/bin/bash

BSERVER=rps_aura_srv
EXCLUDE="*~"
BDIR=/usr/local/www/portfolio/.
BUSER=root
OPTS="--delete --exclude ${EXCLUDE} -a -v"
SOURCEDIR=/home/dc/w/osca.dev/public
rsync ${OPTS} ${SOURCEDIR} ${BUSER}@${BSERVER}:${BDIR}