PieFed

Prerequisites

You need an active Azure subscription, an SSH key pair, and a VNet with a 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.

Configure the network security group (NSG) to allow inbound 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 SecureAnyCloud, and select Create.

On the Basics tab, 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 select Review + create and Create.

Step 2 - Deploy with the Azure CLI

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

az vm image terms accept --urn sac1647283583153:piefed:default:latest
az vm create \
  --resource-group my-resource-group \
  --name my-piefed \
  --image sac1647283583153: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 and seeds the database. Only then does it allow 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

Confirm that the sentinel file exists:

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

Expected output:

first boot complete

Step 4 - Retrieve your per-VM credentials

Every secret in the credentials file was generated on your VM and exists nowhere else. SecureAnyCloud does not know them. Read the file with root privileges:

sudo cat /root/piefed-credentials.txt

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

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

Expected output:

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

Extract only 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

Query /nodeinfo/2.0, 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 state. The instance is private and closed to self-signup until you change it in Step 9.

Confirm that all five services are 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>/. The instance ships private, so PieFed takes you straight to the sign-in page. Enter the PIEFED_ADMIN_USER and PIEFED_ADMIN_PASSWORD values from Step 4.

After you sign in, the main feed opens. It is empty on a new instance, as expected: 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. Enter 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 through 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. Pass it 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 the worker is not running, posts still appear locally, but background work silently never happens. Ping the worker to confirm that it is running:

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.

Watch the worker 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. This is deliberate, so that 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 three options:

• 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 - Enable federation

Federation is the most common source of confusion with any fediverse server, so here is exactly what it needs.

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.

Out of the box, this VM is a fully working standalone community: accounts, communities, posts, comments, votes and search all work. Federation stays off until you complete the two parts below.

Part 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 you continue.

Part 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 serve HTTPS, set it to 1.

Next, obtain a certificate and let Certbot configure nginx. Then restart PieFed so that 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 that the instance now advertises the right name:

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

Federation is live once that command 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 you invite anyone or start federating.

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. It survives a VM resize and can be snapshotted independently. Confirm the mount:

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

Expected output (the device letter may differ):

/dev/sdc /srv/piefed ext4

Check that the PostgreSQL cluster 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 up the instance, 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. SecureAnyCloud 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. The AGPL asks anyone who offers the software over a network to offer its source too, so the complete corresponding source is kept on the image at /opt/piefed/app.

Support

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

SecureAnyCloud 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.

Deploy on Azure

Launch PieFed on Ubuntu 24.04 LTS on Azure with 24/7 support from SecureAnyCloud.

View this image

Need Help?

Our support team is available 24/7.

sales@secureanycloud.com