Pixelfed needs installation instructions for novice sysadmins

[jhenshaw]

One of Pixelfed's largest barriers to adoption is deploy-ability. Mastodon has provided a good example of one way which this can be alleviated: line-by-line / command-by-command instructions that assume nothing more than a Linux version and root privs.

Today, Pixelfed has a lot list of starting assumptions about the state of a machine. I suggest backing away from those assumptions, and giving more thorough guidance for sysadmins.

For example, in "Preparing your Machine" start with nothing more than "This guide assumes you have Ubuntu XX.XX LTS and root access." From there, give a predictable set of commands to prepare a system. Then a predictable set of commands to deploy Pixelfed.

Another example: "Make sure to set the appropriate permissions. For example, if you are running your processes through the http user/group, then run the following:" leaves a lot of ambiguity for people about what the appropriate permissions are. The example doesn't translate for all cases. Consider replacing that with a few chmod commands that are guaranteed to work for a specific Linux flavor.

Mastodon opens with, "If you are setting up a fresh machine, it is recommended that you secure it first. Assuming that you are running Ubuntu 20.04:" As a result, they give instructions that work VERY reliably for Ubuntu 20.04, making it easy to deploy. Pixelfed has been more black magic.

YUNoHost is a help here to a degree, but requires additional resource overhead. A robust deployment guide on part with Mastodon's would help elicit more Pixelfed adoption.

[trwnh]

one issue, we don't want to make any assumptions with the generic installation guide. there are distro-specific guides that are meant to target different flavours of linux, although currently there is only the guide for arch linux, and i think someone is currently working on contributing an ubuntu guide...

i'm curious, if you read through the arch installation guide at https://docs.pixelfed.org/install-guides/arch.html does that fare better or worse for your expectations of what an installation guide should include?

[jhenshaw]

Indeed, @shleeable has authored one for Ubuntu here: #82
The arch one reads well, but I have not tried to execute through it. It's not quite on part with Mastodon's guide here as it doesn't mention what version to start out with, but overall the steps are clear and I could follow them if I had an Arch system.

[trwnh]

ah yeah, arch doesn't have versions, it's a rolling release so you always just have the latest versions of software that have been verified to work, instead of having to upgrade every 6 months/etc you just install it once and keep it up-to-date. i'm not personally too familiar with ubuntu or debian, although i am aware they tend to be more popular for server deployments.

i guess what i need to do is sit down at some point and try to get distro-specific guides written for other distros, but this is also an area where i think contributions would be welcome -- i wrote the generic install guide with an educational purpose in mind, and everything was tested on arch, but the distro-specific guides are more appropriate if you don't care about learning and just want to get a working deployment.

[jhenshaw]

@trwnh - that's probably what's needed. I'm jumping into the Ubuntu one now and starting to debug it.

I also suspect that we could unlock many people with an official docker image. That'd be a very well-leveraged investment for the project. I'm not a docker expert but can help validate images and deployment instructions for images.

[thisislawatts]

I would be willing to take a shot at building a Docker image, is there a good source of truth that defines the supported software versions? For example: PHP v? @trwnh @jhenshaw

[trwnh]

you'd have to ask @dansup as i believe that the software requirements change somewhat irregularly

[Jetro97]

Big up from here.

I'd like to eventually write a Debian guide, if i ever find out how to make it working