PeerTube Ansible Playbook

The playbook's core lives within the provided peertube role. This contains everything needed to deploy, upgrade and backup a PeerTube instance, tailored for the FSFE's infrastructure and needs.

Setup Ansible environment

git clone --recurse-submodules git@git.fsfe.org:fsfe-system-hackers/peertube.git
cd peertube

ansible-galaxy install -r requirements.yml --force

Test changes

To not have to test changes in production, using a local VM is encouraged. As such a VM should match the target system, the latest official Debian Cloud Image of the nocloud type can be used, e.g., ./bookworm/latest/debian-12-nocloud-amd64.qcow2.

On a Linux host, this image can be used for a QEMU/KVM-based VM. For a fast clicking experience, virt-manager can be used.

After creating a new Storage Volume based on the disk image, fire up this machine, and a password-less root login can be performed.

1. Install the openssh-server and add your SSH public key for the root user.

   curl https://git.fsfe.org/alvar.keys | tee ~/.ssh/authorized_keys
   

2. Install fdisk and resize the partition like:

   $ fdisk /dev/vda
   > p
   > d
   > 1
   > n
   > (default 1)
   > (default first sector, same as in p output from above)
   > (default last sector)
   > (something-something delete ext4 signature) N
   > w
   $ resize2fs /dev/vda1
   

3. Fetch the VM's ip address to create a local /etc/hosts entry mapping ${VM_IP} peertube.example.com.
4. Now the local playbook can be applied, take care to pass the -i inventory_local flag. Please note that this testing environment uses the configuration from roles/peertube/defaults/main.yml and NOT the overwrites from group_vars/peertube.yml.

   ansible-playbook -i inventory_local playbook_local.yml
   

Apply changes

The roles/peertube/tasks/main.yml file referred all steps grouped in blocks. Currently those steps are:

• Install PeerTube, its dependencies and extra files (install)
• Configure PeerTube (config)
• Setup logging and log rotation (logging)
• Backups and its extra steps (backup)
• Finalize and restart services

Each step, excluding the final one, has an Ansible Tag assigned, compare text in brackets. Thus, one can execute a subset of steps, e.g., only using config after changing the configuration. The finalization will be always executed, as it reloads services.

# Perform a complete install:
ansible-playbook playbook_remote.yml

# Only re-install PeerTube:
ansible-playbook playbook_remote.yml --tags install

# Apply configuration changes:
ansible-playbook playbook_remote.yml --tags config

Upgrade PeerTube

To upgrade PeerTube to its latest release, try following these incomplete instructions.

For the update itself, take a close look at the release notes. The minimum would be to bump the version in roles/peertube/defaults/main.yaml.

Take also a look at configuration changes, both for PeerTube and other components like nginx. To diff PeerTube's config, checkout the PeerTube repository locally and inspect the diff at:

OLD=4.2.2 NEW=4.3.0  # Change me!
git diff v${OLD}..v${NEW} config/production.yaml.example

For other configuration changes, take a look at the changes within PeerTube's ./support directory:

git diff --name-only v${OLD}..v${NEW} support

Test locally

If possible, test the changes locally first. Please refer to the Test changes section above.

Deploy remotely

Apply all the changes:

ansible-playbook playbook_remote.yml

And afterwards remove old PeerTube installations from ~peertube/versions/, leaving at least the current and one older version. Also clean up the automatically created PostgreSQL backup generated by the Ansible Role within /var/lib/postgresql/dumps.

Upgrade Ansible Galaxy packages

The sourced Ansible Galaxy packages specified in the requirements.yml file should be checked and updated from time to time or if necessary. To do so, please consult both the changelog as well as the source changes.

After bumping the version, refresh the modules

ansible-galaxy install -r requirements.yml --force

and test the changes as described above.