techdoc

running the HUGO server

created onJanuary 18, 2022
last modified onJune 28, 2022

running HUGO in server mode

Running HUGO server on host idoru, IP 192.168.0.10, port 1414

hugo server --bind 192.168.0.10 --baseUrl http://idoru -p 1414
If the port that HUGO is intended to use is already in use by another process, HUGO cheerfully grabs just another port it can get hold on, preferably on some port in the upper port range from 30k to 40k. You can’t rely on HUGO running on the port you specified unless you’ve checked the port HUGO runs on.

the HUGO log

by default, HUGO logs to . You can log to a file with the parameter , i.e.:

hugo server --log-file /tmp/hugo.$$.log --bind 192.168.0.10 --baseUrl http://idoru -p 1414

the HUGO cache

When running HUGO in server mode, then by default HUGO creates a cache directory named in the systems temp dir, which on Linux is usually . This cache directory is used by HUGO to cache generated pages. Instead of using the default location for the cache, you can specify the cache directory with the parameter . You can prevent HUGO to use a cache for generated pages with the option .

running several instances of HUGO in server mode on the same machine

When running several instances of HUGO in server mode on the same machine, you should set the cache directory explicitly with and start each HUGO dev servers with a different cache location. Starting several HUGO dev servers with the default cache location on the same machine will result one of the following Problems:

  • starting several HUGO dev servers with different users, the first user ‘wins’ and owns the cache directory. Any other user’s attempt to start HUGO in server mode with the cache dir not set to some different location will most likely fail due to the file permissions of the hugo cache dir.
  • starting several HUGO dev servers with the same user, all HUGO dev servers will use the same cache location, which is probably not what you want.

stopping the HUGO server

If you started HUGO in the foreground, HUGO will run and log to the terminal screen until you press . To kill a HUGO dev server running in the background, kill the process with the HUGO dev server’s PID.

starting and stopping HUGO in server mode with hugoctl

Starting HUGO with specified port, log file, cache_dir, IP and base URL will look like:

hugo server --logFile=/tmp/hugo-whatever.log --cacheDir /tmp/hugo_whatever_cache --bind 192.168.0.10 --baseUrl http://somehost -p 9999 > /dev/null 2>&1 &

which is a bit much to type. I usually run hugo in the background, as I don’t care about hugo’s terminal output as long as thing go fine. To stop the HUGO dev server, I have to look up it’s PID to kill it, which is also a bit tedious. I’ve written a script named to start and stop HUGO in server mode, which you can download here (see below).

I also use the script for collaborating with others on the same site, locally. With a terminal program and a user account on my machine, others can use my toolchain. It’s fun sitting next to each other, while working simultaneously on different versions of one site.

download and installation

to install the script:

  • download    hugoctl (internal link fom the files section)
  • download this log.lib:    log.lib (again, internal link fom the files section)
  • drop the log.lib into a suitable directory.
  • drop the script in a directory included in your environment variable . Usually, is a good choice.
  • open the script file and in the third line: , replace the path with the path to the log.lib.
  • drop a hugoctl config file (see below) in your hugo project’s root dir. Edit the config file to suitable values.
  • you’re good to go.

You can start HUGO in server mode with and stop the dev server with .

hugoctl config file

The hugoctl config file has six values. All values are mandatory and the config file must reside in the root of your site project (the directory where your site’s config.toml or config.yaml usually resides).

The config file I use for developing this site on my laptop which has the hostname idoru and the the IP 192.168.0.10 in my LAN, has the following content:

project=codebase baseUrl="http://idoru" bind=192.168.0.10 port=9494 cacheDir=/tmp logFile=/tmp/hugo-dev-${project}.log

The config file is sourced by hugoctl, so in the last line of the config file above, is expanded to the value of in line 1, which results in the value for .

Run or to list the options and config parameters of .

troubleshooting the hugo server

invalid memory address or nil pointer dereference

symptom

Running results in the following runtime error:

panic: runtime error: invalid memory address or nil pointer dereference [signal SIGSEGV: segmentation violation code=0x1 addr=0x50 pc=0x160eab2] ...

cause

The most probable cause is insufficient read/write permissions for files and directories where Hugo creates its cache directory and log file.

fix

Check read and write permissions to log files and cache directory.

running the HUGO server

© 2022 – 2024 Rudolf Held