I spent a few days migrating my website to the static site generator Pelican and it was super easy. I the IndieWeb spirit, I wanted to self-host my site along with a number of other apps I have built and this was step one!
If you know the web building basics of html and css than your good to go with Pelican. Bonus if you know a bit of Python as well but it's not really required to get your site up an running. To get started follow the quickstart on the Pelican website to get setup.
Getting Started
I'm hoping you got through the quickstart, and I'm going to follow up with some general advice to help you along the path and then go into how I self hosted the site.
First bit of advice, use the pelican-quickstart as advised, it will save you a bunch of time when it comes to publishing. The one catch here is knowing how you will be publishing before starting. The quick start will setup for publishing with ftp, rsync or even publishing to Amazon S3 and Github Pages. Setting this up early will save some challenges during publishing.
Make your own theme.
Most of the themes I could find for Pelican were fairly plain, even those that I really liked the layout. So I ended up taking the default template and creating my template from that. I found the source code for the default template in the Pelican code, called "notmyidea" and copied it into a folder called /themes in the root of the project (where the /content and /output folders are located). To use your newly copied theme with your site simply add this to the pelicanconf.py configuration file THEME = './themes/your-template-sub-folder'
After that you can dive into the css located in ./themes/your-template-sub-foder/static/css and customize the look all you want! Of course if your interested in messing with the templates they are located in /templates and you can modify whats in the default templates or add new ones!
Self-hosting Steps
AS I mentioned earlier, I am self-hosting my site. My server is a Raspberry Pi 4 with a large card to handle a few apps including this one. I would highly recommend using DietPi as the image for a Pi server as it makes setting up server applications super easy. Check it out!
Server setup is super simple with DietPi, simply ssh into the server and install Nginx from the dietpi-software tool. Then you will need to do some setup steps.
Site configuration for Nginx
Configurations are found in /etc/nginx/sites-available so create a new file called /etc/nginx/sites-available/yoursite.yourdomain.org. The configuration can look different depending on how you set it up, in my case I have configured it to listen to requests on both HTTP (80) and HTTPS (443) and specified the server_name to be a subdomain 'blog.meadowhawk.xyz' which will direct requests fro only that subdomain, allowing the configuration of other subdomains in the future:
server {
listen 80;
listen [::]:80;
server_name blog.meadowhawk.xyz;
root /var/www/blog.meadowhawk.xyz;
index index.html;
location / {
try_files $uri $uri/ =404;
}
error_page 404 /404.html;
return 302 https://$server_name$request_uri;
}
server {
# SSL configuration
listen 443 ssl http2;
listen [::]:443 ssl http2;
ssl_certificate /etc/ssl/cert.pem;
ssl_certificate_key /etc/ssl/key.pem;
server_name blog.meadowhawk.xyz;
root /var/www/blog.meadowhawk.xyz;
index index.html;
location / {
try_files $uri $uri/ =404;
}
error_page 404 /404.html;
}
Also note in the https config on port 443 I reference the certs stored locally. You can create certs in many way, I took the easy route and had mine managed by my CloudFlare config. It was super simple and while having a cert from a provider is perhaps preferable, I don't feel it's required for in this case. Also this was so easy to setup and I can go back and change it later if I decide its a good idea.
Create a symlink to activate the configuration and Restart Nginx
sudo ln -s /etc/nginx/sites-available/yoursite.yourdomain.org /etc/nginx/sites-enabled/
# Test the config before restarting:
sudo nginx -t
#Restart
sudo systemctl reload nginx
Create directory for your website
/var/www/yoursite and make sure the dietpi user (or whatever user you want to upload the site code with) has write permissions on the directory
Multiple subdomains on nginx
You can create multiple websites on your single server..maybe your SO wants a blog too! Simply repeat the last 2 steps and change the subdomain for the file nad in the config!
Setup tasks.py if not already setup during the quickstart
Pelican provides a nice interface you can use for managing the development of the site using 'invoke' and the tasks.py file. You'll probably need to install invoke to use it python3 -m pip install invoke then you can deploy the site to your DietPi using the invoke publish command. This command will rebuild your site and then use rsync to upload it to the server!
Note, if you didn't add rsync as an option during quick start, you will need to add the function and supporting config to the tasks.py file. Here's the important parts that go in tasks.py:
CONFIG = {
# ... more config
# Remote server configuration
"ssh_user": "dietpi",
"ssh_host": "1.1.1.1", #set to your dietpi's actual ip address.
"ssh_port": "22",
"ssh_path": "/var/www/yoursite",
# Host and port for `serve`
"host": "localhost",
"port": 8000,
}
#... more code
@task
def publish(c):
"""Publish to production via rsync"""
pelican_run("-s {settings_publish}".format(**CONFIG))
c.run(
'rsync --delete --exclude ".DS_Store" -pthrvz -c '
'-e "ssh -p {ssh_port}" '
"{} {ssh_user}@{ssh_host}:{ssh_path}".format(
CONFIG["deploy_path"].rstrip("/") + "/", **CONFIG
)
)
Deploy the site and test it out!:
invoke publish with rsync
Wow you made it this far! I hope this was helpful in some way and look for a follow up on how to IndieWebify your Pelican theme!
Notes: Dietpi 9+ doesn't seem to have rsync installed anymore so you''ll need to install it if you are using the invoke publish method.
sudo apt install inotify-tools