PieFed on Ubuntu 24.04 on Azure User Guide

Overview

PieFed is an open-source federated link aggregator and discussion platform. People post links and text into topic-based communities, others vote on them and reply in threaded discussions, and each community has its own moderators and rules. PieFed speaks ActivityPub, so an instance can federate with the wider fediverse rather than standing alone.

The cloudimg image installs PieFed 1.7.8 from the pinned upstream release, with PostgreSQL 16, Redis 7, a Celery background worker, gunicorn and nginx already installed, tuned to the VM size and wired together. It boots and works standalone, with no external services to sign up for.

Critically, PieFed creates its administrator only through an interactive setup prompt. An image that skipped that step would ship with no owner at all; one that answered it at build time would ship the same password to every buyer. This image creates the administrator during first boot, with a password unique to your VM, and does it before anything will accept a connection. Backed by 24/7 cloudimg support.

What is included:

• PieFed 1.7.8 served on port 80 by nginx, reverse-proxying gunicorn on the loopback interface
• PostgreSQL 16 and Redis 7, both bound to loopback only, with the database cluster on a dedicated Azure data disk at /srv/piefed
• A Celery background worker processing PieFed's celery, background and send queues
• An administrator account plus the Flask signing key, database password and Redis password, all generated uniquely on this VM at first boot
• Registration closed and the instance private in the shipped state, so nobody can sign themselves up before you decide who may
• piefed.service, piefed-celery.service, nginx.service, postgresql.service and redis-server.service as systemd units, enabled and active
• The complete corresponding source at /opt/piefed/app and licence notices at /usr/share/piefed/, as the AGPL requires
• 24/7 cloudimg support

Prerequisites

An active Azure subscription, an SSH key pair, and a VNet plus subnet in the target region. Standard_B2s (2 vCPU / 4 GiB RAM) matches PieFed's documented minimum and is the tested size for this image. NSG inbound: allow 22/tcp from your management network and 80/tcp for the web interface.

Step 1 - Deploy from the Azure Marketplace

Sign in to the Azure Portal, choose Create a resource, search the Marketplace for PieFed by cloudimg, and select Create. On Basics pick your subscription, resource group, region and size; under Administrator account choose SSH public key and paste your key; under Inbound port rules allow SSH (22) and HTTP (80). Review the dedicated data disk on the Disks tab, then Review + create -> Create.

Step 2 - Deploy with the Azure CLI

Run these on your own workstation, not on the VM:

az vm create \
  --resource-group my-resource-group \
  --name my-piefed \
  --image cloudimg:piefed:default:latest \
  --size Standard_B2s \
  --admin-username azureuser \
  --generate-ssh-keys \
  --public-ip-sku Standard
az vm open-port --resource-group my-resource-group --name my-piefed --port 80 --priority 1010

Step 3 - Wait for first boot to finish

First boot generates every per-VM secret, creates your administrator account, seeds the database and only then allows anything to serve. It normally completes within a minute of the VM reaching Running. Check that it has finished:

sudo systemctl is-active piefed-firstboot.service

Expected output:

active

The sentinel file confirms it completed:

sudo test -f /var/lib/cloudimg/piefed-firstboot.done && echo "first boot complete"

Expected output:

first boot complete

Step 4 - Retrieve your per-VM credentials

Every secret below was generated on your VM and exists nowhere else. cloudimg does not know them.

sudo cat /root/piefed-credentials.txt

The file is mode 0600, owned by root, and contains the site URL, your administrator user name and password, and the database and Redis passwords:

sudo stat -c '%a %U:%G %n' /root/piefed-credentials.txt

Expected output:

600 root:root /root/piefed-credentials.txt

Pull out just the values you need to sign in:

sudo grep -E '^PIEFED_(URL|ADMIN_USER|ADMIN_PASSWORD)=' /root/piefed-credentials.txt

Step 5 - Confirm the service is healthy

/nodeinfo/2.0 is PieFed's own unauthenticated status document. It reports the running software version and whether registration is open, which makes it the quickest end-to-end health check:

curl -s -H "Host: <PIEFED_SERVER_NAME>" http://127.0.0.1/nodeinfo/2.0

Expected output (user and post counts will differ):

{"openRegistrations":false,"protocols":["activitypub"],"software":{"name":"piefed","version":"1.7.8"},"usage":{"localComments":0,"localPosts":0,"users":{"activeHalfyear":1,"activeMonth":1,"total":1}},"version":"2.0"}

"openRegistrations":false is the shipped posture: the instance is private and closed to self-signup until you change it in Step 9.

All five services should be active:

systemctl is-active piefed piefed-celery nginx postgresql redis-server

Expected output:

active
active
active
active
active

Step 6 - Sign in

Browse to http://<your-vm-public-ip>/. Because the instance ships private, you are taken straight to the sign-in page. Enter the PIEFED_ADMIN_USER and PIEFED_ADMIN_PASSWORD values from Step 4.

After signing in you land on the main feed. It is empty on a new instance - that is expected, because nothing has been posted yet and the instance is not yet federating.

Step 7 - Create a community and post to it

A community is the topic-based space that posts live in. From the navigation choose Communities, then Create community. Give it a short URL name and a display title.

Open your new community and choose Create post. Give it a title and a body, then submit. The post appears in the community, and you can reply to it in a thread.

You can do the same from PieFed's API, which is useful for scripting or for a health check. Sign in to get a token:

SRV=$(sudo sed -n 's/^PIEFED_SERVER_NAME=//p' /root/piefed-credentials.txt | head -1)
ADMIN_USER=$(sudo sed -n 's/^PIEFED_ADMIN_USER=//p' /root/piefed-credentials.txt | head -1)
ADMIN_PW=$(sudo sed -n 's/^PIEFED_ADMIN_PASSWORD=//p' /root/piefed-credentials.txt | head -1)
curl -s -H "Host: ${SRV}" -H 'Content-Type: application/json' \
  -X POST http://127.0.0.1/api/alpha/user/login \
  -d "{\"username\":\"${ADMIN_USER}\",\"password\":\"${ADMIN_PW}\"}"

The response contains a JWT you can pass as Authorization: Bearer <token> to the rest of the API.

Step 8 - Confirm the background worker is running

PieFed hands federation delivery, notifications and scheduled maintenance to a Celery worker. If that worker is not running, posts still appear locally but background work silently never happens - so it is worth confirming:

sudo -u piefed env -C /opt/piefed/app PYTHONPATH=/opt/piefed/app \
  /opt/piefed/venv/bin/celery -A celery_worker.celery inspect ping --timeout 30

Expected output:

->  celery@my-piefed: OK
        pong

1 node online.

You can watch it process jobs as you use the site:

sudo journalctl -u piefed-celery -n 20 --no-pager

Step 9 - Decide who may register

The instance ships closed: only your administrator account exists, and nobody can sign themselves up. That is deliberate, so an instance is never briefly open while you are still setting it up.

To change it, sign in as the administrator and go to Admin -> Site settings. Registration mode offers:

• Closed - nobody can register (the shipped default)
• Require application - people apply and you approve them
• Open - anyone can register

Require application is the usual choice for a public instance. The same page has a Private instance toggle that controls whether logged-out visitors can read anything at all.

Step 10 - Federation: what it actually needs

This is the part worth being precise about, because it is the most common source of confusion with any fediverse server.

ActivityPub federation requires a real, public DNS name and HTTPS. Remote servers discover your instance by hostname, fetch your actors over TLS, and verify HTTP signatures against the keys published at those hostnames. An instance reached only by IP address cannot federate, and no image can bake in a hostname it does not know. So out of the box this VM is a fully working standalone community - accounts, communities, posts, comments, votes and search all work - and federation is off until you complete the two steps below.

1. Point a DNS name at the VM. Create an A record for the name you want to use, pointing at the VM's public IP address. Wait for it to resolve before continuing.

2. Tell PieFed its new name, and terminate TLS. PieFed builds every absolute ActivityPub URL from SERVER_NAME, so it must match the public name exactly. Open /etc/piefed/piefed.env in an editor and change these three settings, substituting your own domain:

SERVER_NAME='<your-domain>'
HTTP_PROTOCOL='https'
SESSION_COOKIE_SECURE=1

SESSION_COOKIE_SECURE matters: the image ships it as 0 because a browser refuses to send a Secure cookie over plain HTTP, which would silently break sign-in. Once you are serving HTTPS, set it to 1.

Then obtain a certificate, let Certbot configure nginx, and restart PieFed so it picks up the new identity:

sudo apt-get update && sudo apt-get install -y certbot python3-certbot-nginx
sudo certbot --nginx -d <your-domain>
sudo systemctl restart piefed piefed-celery

Confirm the instance now advertises the right name:

curl -s https://<your-domain>/.well-known/nodeinfo

Federation is live once that returns your public hostname over HTTPS. You can then search for a remote community from the PieFed search box using its full address, for example !community@server.example.

Changing SERVER_NAME after content exists. Actor and object URLs already stored in the database keep the old name. Set the hostname you intend to keep before inviting anyone or federating, not after.

Managing the service

Restart the application and its worker:

sudo systemctl restart piefed piefed-celery

Application logs:

sudo journalctl -u piefed -n 20 --no-pager

nginx access and error logs are at /var/log/nginx/piefed.access.log and /var/log/nginx/piefed.error.log.

Where your data lives

Everything that matters is on the dedicated data disk, separate from the OS disk, so it survives a VM resize and can be snapshotted independently:

findmnt -no SOURCE,TARGET,FSTYPE /srv/piefed

Expected output (the device letter may differ):

/dev/sdc /srv/piefed ext4

The PostgreSQL cluster confirms it is on that volume:

sudo -u postgres psql -tAqw -c 'SHOW data_directory'

Expected output:

/srv/piefed/postgresql/16/main

Uploaded images and the Redis persistence files live alongside it, at /srv/piefed/media and /srv/piefed/redis.

To back the instance up, snapshot the data disk from Azure, or take a logical dump:

sudo -u postgres pg_dump -Fc piefed > /tmp/piefed-backup.dump

Maintenance

Operating-system security updates are applied automatically by unattended-upgrades. To patch by hand:

sudo apt-get update && sudo apt-get upgrade -y

PieFed itself is pinned to the release this image was built and tested against, at /opt/piefed/app. Upgrading PieFed means replacing that tree with a newer release and running its database migrations; cloudimg publishes refreshed images for new upstream releases, and moving to a new image is the supported path.

The licence and third-party notices for everything in the image are at /usr/share/piefed/:

ls /usr/share/piefed/

PieFed is free software under the GNU Affero General Public License version 3. Because the AGPL asks anyone who offers the software over a network to offer its source too, the complete corresponding source is kept on the image at /opt/piefed/app.

Support

24/7 support is included with this image. Contact cloudimg support with your Azure subscription ID and the VM name.

---

cloudimg is not affiliated with, endorsed by, or sponsored by the PieFed project. PieFed is the mark of its respective owner and is used here only to identify the software included in this image.