/!\ Deprecated /!\
In this article I used the static folder to overwrite the fe files, but Pleroma has better front-end management now. You can use different folders for different fe's and versions.
See https://docs-develop.pleroma.social/backend/configuration/cheatsheet/#frontend-management
Introduction
I have my own single-user Pleroma instance. It is not advised to use the Pleroma develop branch, because this branch may be highly unstable, contain a lot of bugs, and there is no way to get back to the stable branch other than waiting for a new release. The same isn't true for the pleroma-fe, however. Pleroma-fe is packaged with the Pleroma installation, but can be build and run separately. Returning to the old fe is as easy as removing the new fe and making sure the old one is (still) in place. There were some features in the new fe (namely an emoji-picker) that I wanted, so because this is rather safe, I decided to update the fe. To accomplish this I used the Pleroma knowledge I already had and the small guide from the pleroma-fe README.md[1].
I'm going to start this guide with how to build everything yourself. If you just want the latest fe from the develop branch, there is an easier way. See "The easy way" at the end of the article.
Some basic preparations
This has been done on a pleroma that used the from-source installation using git. I haven't tried the OTP releases yet, so I'm not sure how well it translates to OTP releases, but I assume it's trivial so don't give up yet just because you used OTP (which is actually the proper way to install Pleroma). First we'll need to build the new fe. You can do that from your PC or from your server. Since we'll eventually need the files on the server anyhow, I do it on the server. My server is running Yunohost, which is a Debian derivative. I also do the whole thing as root.
First we ssh into the server and make sure we run as root. I assume this is something you know how to do.
ssh user@host
sudo su
Then I make sure I have a folder to work in
cd ~
mkdir pleroma_fe
cd pleroma_fe
Since I can't be sure what folder your pleroma is located, I'll refer to that folder as $pleroma_home. If you want to be able to just copy paste the commands, and you have the pleroma folder in /opt/pleroma you can use the following commands. If you have it in another folder, you can just switch out /opt/pleroma for your own folder of course. I also assume the user that runs Pleroma is called Pleroma . Again, feel free to change the name to the user you have if it's different.
pleroma_home="/opt/pleroma"
pleroma_user="pleroma"
Installing dependencies
Building the Pleroma-fe needs npm. Npm is part of node.js, so we install this first. You could try apt install nodejs, but this package is possibly too old and won't work.
The best thing to do is to check https://nodejs.org and see how to install it on your system. I'm on Debian so I used https://nodejs.org/en/download/package-manager/
This told me to do
curl -sL https://deb.nodesource.com/setup_12.x | bash -
apt-get install -y nodejs
For those who are not sure what this does; curl gets the content of whatever the url points to. The -s option means that it won't output progress information to the terminal, the -L option tells curl that it should follow redirects (together they are shortened to -sL). The content of the url is a script that is directly piped into bash so it will be executed immediately. The dash - at the end means that the script should be executed from the home folder from the current user.
There are people who feel it is unsafe to pipe a script via curl directly into bash. If that's the case for you, you can do curl -OL https://deb.nodesource.com/setup_12.x which will download the script. The -O option makes it so that the script is saved locally. You can then check out the script and run it from your PC/server. It's also a nice way to get an idea of what it actually does. It seems the script checks your distro and makes sure it can install the correct version. There also seems to be a check to see if the version you're getting is still supported. In the end it seems like it adds /etc/apt/sources.list.d/nodesource.list and the relevant lines there and then does apt-get update. It should also give a warning if the version your installing is too old.
If you want to do it that way:
curl -OL https://deb.nodesource.com/setup_12.x
ls
# I see the script called 'setup_12.x'
nano setup_12.x
# After you checked and approved you can then run the script
bash setup_12.x
# You still have the script on your server, you can keep it or do 'rm setup_12.x' to remove it
apt-get install -y nodejs
Building
Alright! Luckily that was the only dependency! Now let's start building! First of all we'll need to clone the repository and go to the branch you want to have. Here I'll use develop
git clone https://git.pleroma.social/pleroma/pleroma-fe
cd pleroma-fe
# You can check what branches there are and what branch you're on with
git branch -l
# If you want to switch (I'll switch to develop, but this wasn't actually needed because I was already there)
git checkout develop
Alright! We're set, let's start the actual building!
npm install -g yarn
yarn
ls # This is just so you know what files you had before the build
npm run build
ls
As you can see, you now have an extra folder dist. This contains the build. If you check the content with ls dist, you may notice it looks a lot like $pleroma_home/priv/static/. $pleroma_home/priv/ is a folder that contains all kind of stuff like emojis, images and also the pleroma-fe. This folder is tracked with git, however, so we're not just going to overwrite these files as this would give problems during upgrade. Pleroma allows for a folder $pleroma_home/instance/. The idea is that $pleroma_home/instance/ is used first and that $pleroma_home/priv/static/ is used as a fallback. From this follows that we're going to make sure $pleroma_home/instance/static exists and then copy the content of dist into $pleroma_home/instance/static and make sure the Pleroma users owns them.
Pro-tip: To customize your instance you can use the instance folder to overwrite other stuff from the priv folder. In fact, that is the proper way to do it.
Warning: If you already used this folder to overwrite things of the fe, like the terms-of-service or extra themes, then the following steps will overwrite them! Make sure you have a backup somewhere so you can copy the files back. I assume you know how to do that as you've already put them there in the first place.
mkdir -p "$pleroma_home/instance/static"
cp -r dist/. "$pleroma_home/instance/static"
chown -R $pleroma_user:$pleroma_user "$pleroma_home/instance/static"
ls "$pleroma_home/instance/static"
Now we see that the content has been copied over. You don't need to restart or anything, you can just go to your instance in a new tab and enjoy the new fe!
The easy way
As I said in the beginning of the article, there is an easier way that doesn't require you to build the fe. Gitlab already does builds that you can download using the format https://gitlab.instance/api/v4/projects/${project_id}/jobs/artifacts/${branch}/download?job=${job}[2]. Assuming you have the pleroma folder in /opt/pleroma, you can install the latest fe from the develop branch by doing:
Warning: Same as I said before, if you already used the instance folder to overwrite things of the fe, like the terms-of-service or extra themes, then the following steps will overwrite them! Make sure you have a backup somewhere so you can copy the files back.
pleroma_home="/opt/pleroma"
pleroma_user="pleroma"
cd $pleroma_home
curl -OL https://git.pleroma.social/api/v4/projects/1/jobs/artifacts/develop/download?job=build
unzip 'download?job=build'
mkdir -p "instance/static"
cp -r dist/. "instance/static"
rm 'download?job=build'
rm -r dist
chown -R $pleroma_user:$pleroma_user "instance/static"
Updates
2021-01-20 I added a deprecation warning because I'm overwriting directly in the static-folder while Pleroma now allows overwriting the fe.
2020-04-19 I noticed I don't chown the folder and files after copying to pleroma. I also put the $pleroma_home var and paths in double brackets. I also changed the "The easy way" to cd to pleroma. The reason is that it's easier then to just copy paste the rest without setting the variable.
2020-02-17 When I first made the article, the theme broke codeblock. This is fixed now, so I redid the syntaxt of the article.
2019-11-17 Added "The easy way". Also added the warning that files in the instance folder can be overwritten and added Updates and Sources section (sources where listed, but not in a seperate section). Also added labels.
before 2019-11-17 (don't know when exactly) I changed it so we create the instance folder. I had it originally and assumed this would always be the case, but it isn't.
Sources
[1] pleroma-fe repo: https://git.pleroma.social/pleroma/pleroma-fe
[2] https://pleroma.site/notice/9nRwk5K4D9ukZudsW0
Comments
No comments yet. Be the first to react!