The road even less travelled

I’ve always made life difficult for myself, and my self-hosting journey is no different; from Calckey through Firefish, my Fediverse journey has led me to here; installing Iceshrimp.

What is Iceshrimp?

From the project web page.

https://iceshrimp.dev/iceshrimp/iceshrimp

There is a full ‘ How-To ‘ in the Iceshrimp git repo but these are my notes on how I installed Iceshrimp on my Pi.

Installing Iceshrimp – Overclocking

I’d seen from my Calckey and Firefish hosting that I need to overclock my Pi.

Run the following in a Terminal to overclock:

sudo nano /boot/firmware/config.txt

# Overclocking
over_voltage=6
arm_freq=2000
gpu_freq=700

And reboot using sudo reboot

Run the following in a Terminal to install a monitor and see the CPU speed in real-time:

watch -n 1 cat /sys/devices/system/cpu/cpu0/cpufreq/scaling_cur_freq

Installing Iceshrimp – Preparations

Firstly update everything and add a couple of packages that may or may not already be present:

sudo apt update; sudo apt install git wget; sudo apt full-upgrade -y; sudo reboot

Build Dependencies

The following may already be in place:

  • C/C++ compiler like GCC or Clang
    • Can be checked by running gcc --version in a Terminal
  • Build tools like make
    • Can be checked by running make --version in a Terminal
  • Python 3
    • Can be checked by running python3 --version in a Terminal

The meta package ‘build-essential’ is useful too:

sudo apt install build-essential

Install PostgreSQL

PostgreSQL: The World’s Most Advanced Open Source Relational Database

https://www.postgresql.org/

Full installation instructions are on the PostgreSQL website .

# Create the file repository configuration:
sudo sh -c 'echo "deb https://apt.postgresql.org/pub/repos/apt $(lsb_release -cs)-pgdg main" > /etc/apt/sources.list.d/pgdg.list'

# Import the repository signing key:
wget --quiet -O - https://www.postgresql.org/media/keys/ACCC4CF8.asc | sudo apt-key add -

# Update the package lists:
sudo apt-get update

# Install the latest version of PostgreSQL.
# If you want a specific version, use 'postgresql-12' or similar instead of 'postgresql':
sudo apt-get -y install postgresql

Configure PostgreSQL for Iceshrimp

Iceshrimp also needs a database to store its info in.

To add the Iceshrimp database run the following in a Terminal:

sudo -u postgres psql

create database iceshrimp with encoding = 'UTF8';
create user iceshrimp with encrypted password 'super_long_postgres_password';
grant all privileges on database iceshrimp to iceshrimp;
\q

The ‘iceshrimp’ db needs to be owned by role ‘iceshrimp’ so ALTER the database OWNER by running the following:

sudo -u postgres psql

\l

ALTER DATABASE iceshrimp OWNER TO iceshrimp;

Install Redis

The open source, in-memory data store used by millions of developers as a database, cache, streaming engine, and message broker.

https://redis.io/

As with PostgreSQL I already have a working Redis server as I use it alongside my WordPress installation.

However, if Redis is not installed, full instructions are on the Redis website .

curl -fsSL https://packages.redis.io/gpg | sudo gpg --dearmor -o /usr/share/keyrings/redis-archive-keyring.gpg

echo "deb [signed-by=/usr/share/keyrings/redis-archive-keyring.gpg] https://packages.redis.io/deb $(lsb_release -cs) main" | sudo tee /etc/apt/sources.list.d/redis.list

sudo apt-get update
sudo apt-get install redis

Install NodeJS

Node.js® is an open-source, cross-platform JavaScript runtime environment.

https://nodejs.org/en/

NodeJS is responsible for the interaction between the client (the browser) and the server (my Pi).

NodeJS creates the dynamic page content and opens, modifies and closes files on the server: it is managed by Node Version Manager (NVM):

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.3/install.sh | bash

Confirm the installed version by running nvm -v in a Terminal.

The result should be ‘0.39.3’ or higher.

To list the available Node versions run nvm ls-remote in a Terminal.

Pick the latest version to install, in my case v21.1.0, install and use:

nvm install v21.1.0 && nvm use v21.1.0

This can be checked by running node -v and looking at the result (it should be the same as the version in the nvm install command).

NOTE: nvm is not ‘persistent’, it will only use that version for the lifetime of the current shell.

To ensure that the latest version is remembered run the following in a Terminal:

nvm alias default v21.1.0

Create a ‘foo’ user

I prefer to run dedicated processes with a dedicated user.

To add a new user run the following in a Terminal:

sudo adduser foo

And password protect it:

sudo passwd foo

Installing Iceshrimp

Finally, it’s time to install Iceshrimp.

Change to the newly created user:

sudo su foo

And clone the latest repository:

git clone https://iceshrimp.dev/iceshrimp/iceshrimp

Copy the ‘example.yml‘ and edit:

cp /home/foo/iceshrimp/.config/example.yml /home/foo/iceshrimp/.config/default.yml

sudo nano /home/foo/iceshrimp/.config/default.yml

# Final accessible URL seen by a user.
url: https://social.example.com/

# PostgreSQL configuration
db:
  host: localhost
  port: 5432
  db: iceshrimp
  user: iceshrimp
  pass: super_long_postgres_password

# Redis configuration
redis:
  host: localhost
  port: 6379
  pass: super_long_redis_password

NOTE: There is a ‘super_long_redis_password’ here.

This is not the password that restricts access to the Redis configuration settings found in /etc/redis/redis.conf

Redis works differently to other databases in that there are no predefined schemas, tables etc.

Out of the box, a Redis instance supports 16 logical databases. These databases are effectively siloed off from one another, and when you run a command in one database, it doesn’t affect any of the data stored in other databases in your Redis instance.

https://www.digitalocean.com/community/cheatsheets/how-to-manage-redis-databases-and-keys

So that ‘super_long_redis_password’ is the password for the logical database that Iceshrimp is using.

To watch Redis working, run the following in a Terminal:

redis-cli

monitor

Install project dependencies

Corepack is an experimental tool to help with managing versions of your package managers.

https://nodejs.org/api/corepack.html

As it is experimental, corepack needs enabling:

corepack enable

corepack prepare yarn@stable --activate

yarn

Build Iceshrimp

yarn build

First migration

yarn run init

Certbot

Certbot is a free, open source software tool for automatically using Let’s Encrypt certificates on manually-administrated websites to enable HTTPS.

Certbot is made by the Electronic Frontier Foundation (EFF), a 501(c)3 nonprofit based in San Francisco, CA, that defends digital privacy, free speech, and innovation.

https://certbot.eff.org/pages/about

I already have a HTTPS site running on this server (you are reading it) so there was no need for me to install the extra Certbot software.

Though, if needed Certbot is a Terminal command away:

sudo apt install certbot python3-certbot-nginx

To only get a certificate before editing the nginx conf file:

sudo certbot certonly

Then put in the domain name e.g. social.example.com to create the certificate.

Configure nginx

Copy the ‘iceshrimp.nginx.conf‘:

sudo cp /home/foo/iceshrimp/docs/examples/iceshrimp.nginx.conf /etc/nginx/sites-available/EXAMPLE

Edit accordingly:

sudo nano /etc/nginx/sites-available/EXAMPLE

server {
    listen 80;
    listen [::]:80;
    server_name social.example.com;

    # For SSL domain validation
    root /var/www/html;
    location /.well-known/acme-challenge/ { allow all; }
    location /.well-known/pki-validation/ { allow all; }
    location / { return 301 https://$server_name$request_uri; }
}

And:

server {
    listen 443 ssl http2;
    listen [::]:443 ssl http2;
    server_name social.example.com;

    ssl_session_timeout 1d;
    ssl_session_cache shared:ssl_session_cache:10m;
    ssl_session_tickets off;

    # To use Let's Encrypt certificate
    ssl_certificate     /etc/letsencrypt/live/social.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/social.example.com/privkey.pem;
}

Then, ‘enable’ the site by creating a symlink:

sudo ln -s /etc/nginx/sites-available/EXAMPLE /etc/nginx/sites-enabled/

Check and reload nginx

Then make sure it all works:

sudo nginx -t && sudo systemctl reload nginx

Running iceshrimp using systemd

I want Iceshrimp to start up after a reboot so I create a systemd unit file and enable it.

Copy the ‘iceshrimp.service‘ and edit:

sudo cp /home/foo/iceshrimp/docs/examples/iceshrimp.service /etc/systemd/system/

Edit accordingly:

sudo nano /etc/systemd/system/iceshrimp.service

[Unit]
Description=Iceshrimp daemon

[Service]
Type=simple
User=foo
ExecStart=/usr/bin/yarn start
WorkingDirectory=/home/foo/iceshrimp
Environment="NODE_ENV=production"
TimeoutSec=60
SyslogIdentifier=iceshrimp
Restart=always

[Install]
WantedBy=multi-user.target

Reload the systemctl daemon and enable the iceshrimp service:

sudo systemctl daemon-reload

sudo systemctl enable --now iceshrimp

And that should pretty much be everything!

Installing Iceshrimp – Updating

Updates are regular and some of them significant.

I keep an eye on the releases page to see when this needs doing.

EDIT: I’ve just noticed that there is a notification on the Admin Control Panel saying ‘There might be an update available!’, although I rarely get to see this as I hardly ever log in as an Admin.

Update everything

sudo apt update && sudo apt upgrade

There may be a sudo systemctl daemon-reload after an apt update if a package with a systemd unit file has been updated.

However, if the kernel has been updated, there will need to be a sudo reboot.

Update node.js

node -v

nvm ls-remote

This will list the updates available; choose the latest one.

nvm install 21.1.0 && nvm use 21.1.0

Stop the iceshrimp service

sudo systemctl stop iceshrimp

sudo systemctl status iceshrimp

Change to the foo user

sudo su foo

cd /home/foo/iceshrimp

Git commands

Git commands are a bit of dark art that I don’t fully comprehend, so these commands are from the Iceshrimp installation instructions .

I pull the latest repository by running the following Git commands in a Terminal:

git pull

yarn

yarn build && yarn migrate

Return to the normal user

exit

Start the iceshrimp service

sudo systemctl start iceshrimp

sudo systemctl status iceshrimp

Finally

(I did mention this in a prior post but it bears repeating.)

For anyone interested in getting into the SQL side, pgAdmin is a useful tool.

I installed it using:

curl -fsS https://www.pgadmin.org/static/packages_pgadmin_org.pub | sudo gpg --dearmor -o /usr/share/keyrings/packages-pgadmin-org.gpg

sudo sh -c 'echo "deb [signed-by=/usr/share/keyrings/packages-pgadmin-org.gpg] https://ftp.postgresql.org/pub/pgadmin/pgadmin4/apt/jammy pgadmin4 main" > /etc/apt/sources.list.d/pgadmin4.list && apt update'

sudo apt update

sudo apt install pgadmin4

A screenshot of the Linux application pgAdmin, used to administer PostgreSQL databases. The Calckey Fediverse Server uses PostgreSQL as its back end darabase engine. pgAdmin Screenshot

However you Fediverse, Enjoy!

UPDATE 1

As of version 2023.11.1 Iceshrimp uses Git-LFS.

Git LFS is a command line extension and specification for managing large files with Git.

https://github.com/git-lfs/git-lfs/tree/main

Iceshrimp will not update past 2023.11 without installing Git-LFS.

This repository uses Git LFS. Please make sure it is installed before cloning this repository.

https://iceshrimp.dev/iceshrimp/iceshrimp/wiki/Git-LFS

Update everything once more

sudo apt update && sudo apt upgrade

Install Git-LFS

I installed Git-LFS by running the following in a Terminal:

curl -s https://packagecloud.io/install/repositories/github/git-lfs/script.deb.sh | sudo bash

sudo apt-get install git-lfs

Stop the iceshrimp service once more

sudo systemctl stop iceshrimp

sudo systemctl status iceshrimp

Change to the foo user once more

sudo su foo

cd /home/foo/iceshrimp

Git commands once more

I pulled the latest repository by running the following Git commands in a Terminal:

git fetch

git reset --hard origin/dev

yarn

yarn build && yarn migrate

Return to the normal user once more

exit

Start the iceshrimp service once more

sudo systemctl start iceshrimp

sudo systemctl status iceshrimp

UPDATE 2

Iceshrimp is moving to a .NET framework.

A further comprehensive walk through can be found here .