Tutorial: Hosting Slate Documentation On IPFS
Documentation link here
Shell script link here
Hosting slate documentation on IPFS was a little different than simply adding static files. For the purpose of this tutorial, we’ll use our slate documentation repository as the code-base we reference.
The other part to this was some issues we had loading images through CSS, and fonts. For CSS, we found the easiest solution was to reference versions of the images that were hosted on IPFS, linked through our gateway like so:
One of the main issues we found was that a lot of our files were referencing absolute paths /index.html
.The problem with this was that when viewing the documentation through our gateway navigating to those links would end up redirecting us to https://gateway.temporal.cloud/index.html which wouldn’t work for any IPFS gateway, but for ours these would trigger ACLs redirecting the user to google. The simplest fix was to alter some paths to relative links. However with the desire to not go through and edit a ton of source files, we were able to script this using simple find
and sed
statements.
background-image: url('https://gateway.temporal.cloud/ipfs/QmQ8DTkjxE7emKkfbKxYcaaAeAiiXcSNk7kGhKdstgfAwY');
Fonts were something we had some initial trouble tackling. Due to the source code which gets imported through css imports, we would end up with code that looked like:
@font-face{font-family:"LLAkkuratWeb-Bold";src:url("fonts/lineto-akkurat-bold-s-da650f3e5d121ff3584d6d7df703def6.eot");src:url("fonts/lineto-akkurat-bold-s.eot#iefix"
When browsing through our gateway, we would get 404’s for these fonts. It looks like that when adding the file to IPFS, although the fonts were in a separate folder, IPFS would attempt to load fonts
as if they were under our stylesheets
folder. The trick to this was changing all fonts/
to ...fonts/
. This is something we were again able to fix using simple find
and sed
statements.
When adding the files to IPFS, in order to ensure that all relative links are properly parsed, you’ll want to cd
into the build
directory that is created when running bundle exec middleman build --clean
, and add files recursively, wrapping them in a directory object like so:
#! /bin/bash# used to prep slate build's for hosting on ipfs
# example
# ./slate_ipfs.sh bilbobaggins 192.168.0.1 /home/solidity/go/src/github.com/RTradeLtd/temporal-api-documentation
# after uploading, you'll want to untar the file, and add it with `ipfs add -r -w <directory>`REMOTE_USER="$1"
REMOTE_HOST="$2"
SLATE_REPO="$3"if [[ "$REMOTE_HOST" == "" ]]; then
echo "first argument must be remote host to upload files to"
exit 1
fiif [[ "$REMOTE_USER" == "" ]]; then
echo "second argument must be remote user of the remote host"
exit 1
fiif [[ "$SLATE_REPO" == "" ]]; then
echo "third argument must be the absolute path to the slate repository"
exit 1
fi# change directory to slate repository
cd "$SLATE_REPO" || exit
# clean up old files
rm -rf build build.tar# used to build slate to serve as static files
bundle exec middleman build --clean# change to build directory, exiting if a failure is detected
cd build || exit# updates hrefs to work with ipfs and not redirect to an actual web url
# for example if using non-prepped slate static files with an href like
# href="/account.html" on a domain gateway.temporal.cloud, this will redirect # to gateway.temporal.cloud/account.html
# by trimming the leading / it will be redirected to the ipfs link instead find . -type f -name "*.html" -exec sed -i 's/href="\//href="/g' {} \;
# do the same as the above for css files
find . -type f -name "*.css" -exec sed -i 's/url("\//url("/g' {} \;
# do the same for content links
find . -type f -name "*.html" -exec sed -i 's/content="\//content="/g' {} \;
# do the same for css fonts
find . -type f -name "*.css" -exec sed -i 's/url("fonts/url("..\/fonts/g' {} \;# change back to parent directory
cd .. || exit# tarball the file
tar cvf build.tar build# upload tarballed file to remote host
scp build.tar "$REMOTE_USER"@"$REMOTE_HOST":~/
What can be improved?
- The main area we see for improvement would be a better way of embedding the images, so that they aren’t also requested over a gateway.
- The last part we see room for improvement, would be an ansible playbook that is called after the shell script which logs onto the target IPFS server, and then untars the directory, followed by adding it to IPFS.
We hope this has helped make things a little easier ! Please feel to check out our speedy gateway ! https://gateway.temporal.cloud/ipfs
or https://gateway.temporal.cloud/ipns
For any questions, concerns regarding Temporal or just to say hi, please feel to join our 24/7 support chat.