Workflow automation

Estimated reading time: 3 minutes.
Last update:

Soupault intentionally doesn't have a built-in web server, deployment automation, or a snake game (though a snake game may be added in future versions, stay tuned). That's the UNIX philosophy: do one thing and do it well. The big idea is to provide configurable workflows rather than force a workflow on you. Here's my workflow that you can use as an example if you like it, or disagree with and make your own—the choice is yours.

For a really low-tech workflow, you can just run soupault, point your browser to the build directory, and then copy generated pages by hand to the server. This will quickly get annoying if you update the site frequently.

There's a huge selection of tools to help you, and they can help you with many other tasks, not just with automating a soupault workflow, so you should learn about them if you haven't already.

Myself I'm using a pretty classic UNIX workflow with GNU Make. All the tools I use are cross-platform and will work on any OS, though you may want to go for OS-specific tools as well, like PowerShell on Windows or JCL batch jobs on IBM mainframes.

This is my makefile for this website:

BUILD_DIR := build

# In practice it's in my ~/.local/bin
SOUPAULT := soupault

.PHONY: site
site:
	$(SOUPAULT)

.PHONY: assets
assets:
	cp -r assets/* $(BUILD_DIR)/

.PHONY: all
all: site assets

.PHONY: clean
clean:
	rm -rf $(BUILD_DIR)/*

.PHONY: serve
serve:
	python3 -m http.server --directory $(BUILD_DIR)

.PHONY: deploy
deploy:
	neocities push $(BUILD_DIR)

Remember that build directory path is configurable (the build_dir option in [settings]), so it's a good idea to make it a variable, that's why I have BUILD_DIR := build there.

I keep the soupault binary in my ~/.local/bin, which is in my $PATH so I can just call it by name. The main reason I made it a variable is that it's easy to try a dev build by editing just one line.

While you can keep assets (images, CSS stylesheets etc.) together with pages in site/ and soupault will copy them unchanges, I like to keep them separately. That's why I made an assets target and specified it as a dependency for all.

For live testing the site, I use the web server that comes with Python. It's more than sufficient for testing and you can make it serve files from a directory in just one command.

Finally, the deploy target for this site is just neocities push—it uses the Neocities CLI tool. For baturin.org, it's rsync -a -e "ssh" $(BUILD_DIR)/ www.baturin.org:/var/www/vhosts/baturin.org since it's hosted on my own server.

There are no right or wrong ways to do it though. Use the tools that you like and that work well for you.