Setting up Pelican with Ansible: a beginner's guide

Introduction

If you're looking to create a static website or blog with Python, Pelican is an excellent choice. Combined with Ansible for automation, you can create a reproducible setup process that makes maintaining your site infrastructure straightforward. This guide will walk you through setting up Pelican using Ansible, with a focus on automating the installation process and configuring essential plugins.

By the end of this tutorial, you'll have:

• A working Pelican environment set up through Ansible automation
• Key plugins installed for enhanced functionality, particularly for image handling
• A foundation for extending your static site with additional features

Prerequisites

Before we begin, you should have:

• Basic familiarity with Python
• Ansible installed on your local machine
• A text editor of your choice
• Terminal/command-line access

If you're new to Ansible, don't worry! We'll cover the basics needed for this specific task.

Understanding Pelican and Ansible

What is Pelican?

Pelican is a static site generator written in Python. Unlike dynamic content management systems (CMS) that generate pages on-demand, Pelican converts your content into static HTML files ahead of time. This approach offers several benefits:

• Improved security (no database or server-side processing)
• Faster page loads
• Cheaper and simpler hosting options
• Version control for your entire site

Why use Ansible with Pelican?

Ansible is an automation tool that allows you to define your infrastructure as code. By using Ansible to set up Pelican, you gain:

• Reproducible environments
• Automated setup across multiple machines
• Documentation of your setup process as code
• Easy sharing of your configuration with collaborators

Setting up the Ansible playbook

Let's start by creating an Ansible playbook to automate the Pelican setup process. Create a file named pelican-setup.yml with the following content:

---
- name: Set up Pelican environment
  hosts: localhost
  connection: local
  become: no

  vars:
    pelican_venv_path: "~/pelican_env"
    pelican_project_path: "~/pelican_site"
    python_version: python3

  tasks:
    - name: Ensure Python virtual environment is created
      pip:
        name: virtualenv
        executable: "{{ python_version }}-m pip"
        state: present
      become: yes

    - name: Create Pelican virtual environment
      command: "{{ python_version }} -m venv {{ pelican_venv_path }}"
      args:
        creates: "{{ pelican_venv_path }}"

    - name: Install Pelican and its dependencies
      pip:
        name:
          - pelican
          - markdown
          - typogrify
        virtualenv: "{{ pelican_venv_path }}"
        state: latest

    - name: Create Pelican project directory
      file:
        path: "{{ pelican_project_path }}"
        state: directory

This basic playbook:

1. Ensures the virtualenv package is installed system-wide
2. Creates a Python virtual environment for Pelican
3. Installs Pelican and its common dependencies in that environment
4. Creates a directory for your Pelican project

Adding essential Pelican plugins

Pelican's functionality can be extended with plugins. Let's enhance our playbook to install some useful image-handling plugins:

- name: Install image handling plugins
      pip:
        name:
          - Pillow
          - piexif
        virtualenv: "{{ pelican_venv_path }}"
        state: latest

    - name: Create Pelican plugins directory
      file:
        path: "{{ pelican_project_path }}/plugins"
        state: directory

    - name: Clone Pelican plugins repository
      git:
        repo: https://github.com/pelican-plugins/photos
        dest: "{{ pelican_project_path }}/plugins/photos"
        clone: yes
        update: yes

These tasks:

1. Install Pillow and piexif, Python libraries for image processing
2. Create a plugins directory in your Pelican project
3. Clone the Pelican Photos plugin repository

Understanding the plugins

Let's take a closer look at the plugins we're installing:

Pillow

Pillow is a fork of the Python Imaging Library (PIL) that adds various image processing capabilities. It's essential for many image-related Pelican plugins and enables:

• Image resizing and thumbnailing
• Format conversion
• Image enhancement and filtering
• Metadata extraction

Piexif

Piexif is a Python library that allows you to manipulate EXIF metadata in JPEG images. When used with Pelican, it helps:

• Preserve image metadata when processing
• Extract information like camera settings, date taken, and GPS coordinates
• Modify EXIF data if needed for privacy or display purposes

Photos plugin

The Photos plugin for Pelican provides sophisticated image management features:

• Automatic thumbnail generation
• Image galleries
• Lightbox integration
• EXIF data display

Configuring your Pelican environment

Now let's add a task to create a basic Pelican configuration:

- name: Generate basic Pelican configuration
      copy:
        dest: "{{ pelican_project_path }}/pelicanconf.py"
        content: |
          #!/usr/bin/env python
          # -*- coding: utf-8 -*- #

          AUTHOR = 'Your Name'
          SITENAME = 'My Pelican Site'
          SITEURL = ''

          PATH = 'content'
          TIMEZONE = 'Europe/Paris'
          DEFAULT_LANG = 'en'

          # Feed generation is usually not desired when developing
          FEED_ALL_ATOM = None
          CATEGORY_FEED_ATOM = None
          TRANSLATION_FEED_ATOM = None
          AUTHOR_FEED_ATOM = None
          AUTHOR_FEED_RSS = None

          # Blogroll
          LINKS = (('Pelican', 'https://getpelican.com/'),
                  ('Python.org', 'https://www.python.org/'),
                  ('Ansible', 'https://www.ansible.com/'),)

          # Social widget
          SOCIAL = (('GitHub', 'https://github.com/yourusername'),)

          DEFAULT_PAGINATION = 10

          # Uncomment following line if you want document-relative URLs when developing
          #RELATIVE_URLS = True

          # Plugin configuration
          PLUGIN_PATHS = ['plugins']
          PLUGINS = ['photos']

          # Photos plugin settings
          PHOTO_LIBRARY = "content/images"
          PHOTO_GALLERY = (1024, 768, 80)
          PHOTO_ARTICLE = (760, 506, 80)
          PHOTO_THUMB = (192, 144, 60)

This configuration:

1. Sets up basic site metadata
2. Configures the plugins path
3. Activates the Photos plugin
4. Sets image sizing parameters for galleries, articles, and thumbnails

Running the Ansible playbook

With your playbook complete, you can run it using:

ansible-playbook pelican-setup.yml

Ansible will execute each task in order, showing the results in your terminal. Any skipped or failed tasks will be clearly indicated.

Creating your first Pelican content

After your environment is set up, you can create your first Pelican content. Let's add a task for that:

- name: Create content directories
      file:
        path: "{{ pelican_project_path }}/{{ item }}"
        state: directory
      loop:
        - content
        - content/images
        - content/pages

    - name: Create a sample article
      copy:
        dest: "{{ pelican_project_path }}/content/first-article.md"
        content: |
          ---
          title: My first Pelican article
          date: 2023-01-29
          category: general
          tags: pelican, getting-started
          ---

          # Welcome to my Pelican site!

          This is my first article using Pelican with a setup automated by Ansible.

          ![Sample Image]({photo}sample.jpg)

Generating and previewing your site

Finally, let's add tasks to generate and preview the site:

- name: Generate the Pelican site
      shell: |
        source {{ pelican_venv_path }}/bin/activate
        cd {{ pelican_project_path }}
        pelican content
      args:
        executable: /bin/bash

    - name: Instructions for previewing the site
      debug:
        msg: |
          Your Pelican site has been set up!

          To preview your site, run:

          cd {{ pelican_project_path }}
          source {{ pelican_venv_path }}/bin/activate
          pelican --listen

          Then open http://localhost:8000 in your browser.

Troubleshooting common issues

When setting up Pelican with Ansible, you might encounter some issues:

1. Missing dependencies: Some plugins might require additional system packages. For example, Pillow often needs development libraries for image formats:

- name: Install system dependencies for image libraries
      apt:
        name:
          - libjpeg-dev
          - zlib1g-dev
          - libpng-dev
        state: present
      become: yes
      when: ansible_os_family == "Debian"

2. Plugin compatibility: The Pelican plugins ecosystem is evolving. Always check the compatibility between your Pelican version and plugins.
3. Path issues: Make sure all paths in your configuration are absolute or correctly relative. This is especially important when developing versus publishing.

Extending your setup

This basic setup can be extended in several ways:

1. Additional plugins: Pelican has plugins for SEO, social media integration, and more.
2. Themes: You can add custom themes to your Ansible playbook.
3. Deployment automation: Extend your playbook to deploy your site to GitHub Pages, Netlify, or your own server.
4. Content workflows: Set up automation for content creation and publishing workflows.

Conclusion

By using Ansible to set up Pelican, you've created a reproducible environment for your static site generator. This approach not only saves time but also ensures consistency if you need to set up multiple environments or share your setup with others.

The image handling plugins we've installed (Pillow, piexif, and the Photos plugin) provide powerful capabilities for managing visual content on your site. As you become more comfortable with Pelican, you can explore additional plugins to enhance your site's functionality.

Remember that both Ansible and Pelican configurations are code, which means you can version control your entire infrastructure and content generation process. This is a significant advantage for maintaining your site over time.

For your next steps, consider exploring Pelican themes, additional plugins, or automating your deployment process using Ansible.