Installing Iceshrimp.NET

Better than it was before

Better, Stronger, Faster

More Fediverse adventures, this time with installing Iceshrimp.NET

Why?

Iceshrimp JS (as I’ll call the current version) is a hard fork of FireFish which is in itself was a rebranding of Calckey which was a fork of Misskey.

Iceshrimp.NET is a complete rewrite of the code-base.

All of it.

Both front and back end.

Although this doesn’t answer why I want to migrate.

That answer to that is simple, I like tinkering.

Before I begin

Firstly, I have to say a big ‘thank you’ to the Iceshrimp Dev team.

Also, the pace of development is ridiculously rapid considering the small amount of people involved, and is testament to their skills.

Add to that, they are open and approachable and always willing to help an idiot like me when I bungle something.

Kudos!

Before YOU begin

If you are thinking of installing Iceshrimp.NET, please read the documentation .

Preparations

https://kb.iceshrimp.dev/s/docs/doc/production-readiness-Bs0HK2ZXO8

Obligatory Warning I
Note This is alpha (soon to be beta!) software. While the Mastodon client API is relatively complete, the frontend is not. It is therefore not advisable to upgrade existing Iceshrimp instances at present. Setting up staging instances to help us with testing is very appreciated, however, and will help us ensure eventual upgrades go as smoothly as possible.

https://iceshrimp.dev/iceshrimp/Iceshrimp.NET

Obligatory Warning II
The following steps were completed on a Raspberry Pi 4 4GB running Ubuntu Server 22.04.4 LTS
Obviously, the usual caveats apply:
Don’t simply copy and paste lines of code that you find on the Internet.
Also, I am not responsible if any of this breaks your machine.

As I was coming from a previously installed version of Iceshrimp a few of the pieces of this jigsaw were already in place.

Update everything

The following may be a bit of overkill but I run this command quite frequently:

sudo apt update && sudo apt upgrade && sudo apt remove && sudo apt clean && sudo apt autoremove && sudo apt autoclean

Or if you prefer a shorter version, run the following in a Terminal::

sudo apt update && sudo apt upgrade

Install PostgreSQL

PostgreSQL was already in place and I covered how to install in my previously published ‘ Installing Iceshrimp ‘ post.

Full installation instructions are also on the PostgreSQL website .

tl:dr

apt install postgresql

Step by Step

Create a ‘foo’ user

I prefer to run a dedicated processes with a dedicated user.

First, to add a new user, run the following in a Terminal:

sudo adduser foo

Then password protect it:

sudo passwd foo

Install the .net SDK

https://dotnet.microsoft.com/en-us/download/dotnet/8.0

Whilst as the ‘foo‘ user and in the $HOME directory, run the following in a Terminal:

su foo

cd $HOME

Firstly, download the installation script:

wget https://dot.net/v1/dotnet-install.sh -O dotnet-install.sh

Then change the file permissions to enable execution:

chmod +x ./dotnet-install.sh

Finally install:

./dotnet-install.sh --version latest

Add the .net variables

https://learn.microsoft.com/en-us/dotnet/core/install/linux-scripted-manual#set-environment-variables-system-wide

The variables are volatile i.e. they do not persist between Terminal sessions.

For using in the current Terminal session only:

export DOTNET_ROOT=$HOME/.dotnet

export PATH=$PATH:$DOTNET_ROOT:$DOTNET_ROOT/tools

Or, to make the variables persistent and usable between Terminal sessions, execute the following in a Terminal:

nano $HOME/.bashrc

Then, add at the bottom:

# Add the dotnet variables
export DOTNET_ROOT=$HOME/.dotnet
export PATH=$PATH:$DOTNET_ROOT:$DOTNET_ROOT/tools

After doing either of the above, check:

dotnet --list-sdks

The output should be something like:

8.0.204 [/home/foo/.dotnet/sdk]

Install the WebAssembly tools

This step is not entirely necessary but is needed if the build is to include the wasm-tools.

WebAssembly is a type of code that can be run in modern web browsers — it is a low-level assembly-like language with a compact binary format that runs with near-native performance and provides languages such as C/C++, C# and Rust with a compilation target so that they can run on the web.

https://developer.mozilla.org/en-US/docs/WebAssembly

I installed with:

dotnet workload install wasm-tools

Clone Iceshrimp.NET from git

https://kb.iceshrimp.dev/s/docs/doc/installation-guide-cjqv6iTgnS

Whilst as the ‘foo‘ user and in the $HOME directory, run the following in a Terminal::

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

cd iceshrimp.net/Iceshrimp.Backend

Build the project in release configuration

dotnet build -c Release

NOTE: To build with NativeAOT enabled, the wasm-tools workload needs to have been installed:

dotnet build -c Release -p:EnableAOT=true

Create an Iceshrimp.Storage directory

Iceshrimp.NET needs somewhere to store media and the installation will fail if a PATH is not put into the configuration.ini file.

Any storage directory can be created as long as it is writable by the ‘foo‘ user.

I chose the following:

mkdir /$HOME/iceshrimp.net/Iceshrimp.Storage/

Object Storage is also an option however, I don’t use any third party provider for that:

https://kb.iceshrimp.dev/s/docs/doc/object-storage-k2nxHYOocd

Configure

Very little needs to be configured (the database name and domain can be set here even if they don’t exist yet).

nano $HOME/iceshrimp.net/Iceshrimp.Backend/configuration.ini

Change:

WebDomain = shrimp.example.org
AccountDomain = example.org

Database = iceshrimp
Username = iceshrimp
Password = iceshrimp

This is the path to the Iceshrimp.Storage that was created earlier.

Path = /path/to/media/location

Set up certbot

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

sudo certbot certonly

Then put in the domain name e.g. shrimp.example.org

This will create a certificate and the local files to be used in the iceshrimp.nginx.conf file.

Make a note of their path, it will be needed in the next step.

Set up nginx

https://kb.iceshrimp.dev/s/docs/doc/post-install-guide-caco15miOE

I recycled an iceshrimp.nginx.conf from a previous installation.

It goes in /etc/nginx/sites-available/

The iceshrimp.nginx.conf changes are quite straightforward.

Change:

server_name example.com;

To:

server_name shrimp.example.org;

! In two (2) places !

Change the path of the:

• ssl_certificate
• ssl_certificate_key

To the path that certbot provided.

Create the symlink:

sudo ln -s /etc/nginx/sites-available/iceshrimp.nginx.conf /etc/nginx/sites-enabled/

Check the configuration and reload the nginx server:

sudo nginx -t && sudo systemctl reload nginx

Split Domain setup

https://kb.iceshrimp.dev/doc/split-domain-setup-jHgCAvRar2

https://webfinger.net

The following snippet GOES IN THE ROOT DOMAIN.

(It took me far to long to realise this and as a result webfinger never worked properly for me.)

# Webfinger
location /.well-known/webfinger {
    rewrite ^.*$ https://shrimp.example.org/.well-known/webfinger permanent;
}

location /.well-known/host-meta {
    rewrite ^.*$ https://shrimp.example.org/.well-known/host-meta permanent;
}

location /.well-known/nodeinfo {
    rewrite ^.*$ https://shrimp.example.org/.well-known/nodeinfo permanent;
}

Check the configuration and reload the nginx server:

sudo nginx -t && sudo systemctl restart nginx

Create a new PostgreSQL user (if needed)

Irrespective of whether to migrate an existing database or create a fresh one, a PostgreSQL User will need to be exist (if it doesn’t already).

Log into PostgreSQL:

sudo -u postgres psql

CREATE a new User:

CREATE USER "iceshrimp" WITH ENCRYPTED PASSWORD 'super-long-password';

To DROP a User:

DROP USER "iceshrimp";

Database choices

I have both migrated an existing iceshrimp database and started with a clean slate.

Migration is not recommended yet unless you know what you are doing; have read the disclaimers .

https://kb.iceshrimp.dev/s/docs/doc/migration-guide-XRdCqvbu31

I’ll cover how to do both.

To create a new iceshrimp database

Log into PostgreSQL:

sudo -u postgres psql

To LIST the current databases:

\l

Then, to CREATE an empty database:

CREATE DATABASE "iceshrimp" WITH ENCODING = 'UTF8';

Now take ownership:

ALTER DATABASE "iceshrimp" OWNER TO "iceshrimp";

To DROP a database:

DROP DATABASE "iceshrimp_net";

To migrate an existing iceshrimp database

Stop any running iceshrimp.service that is using the database to be duplicated:

sudo systemctl stop iceshrimp.service

sudo systemctl status iceshrimp.service

Log into PostgreSQL:

sudo -u postgres psql

To LIST the current databases:

\l

This next bit is extremely important!

Change to the iceshrimp user:

SET role iceshrimp;

Check you are the correct User:

SELECT current_user, session_user;

Apply the migrations from:

https://kb.iceshrimp.dev/s/docs/doc/migration-guide-XRdCqvbu31

I’m not going to replicate the script here as it may change.

Last step!

Finally, whether creating a new database or migrating an existing one, the last step is to VACUUM and ANALYZE the migrated database.

As the postgres user, run a VACUUM FULL ANALYZE;

SET ROLE postgres;

Check you are the correct User:

SELECT current_user, session_user;

VACUUM FULL ANALYZE;

To quit:

\q

Running Iceshrimp.NET using systemd

I prefer to use systemd to launch a service rather than starting one manually.

This approach has the added benefit of enabling a restart after a reboot if desired.

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

[Unit]
Description=Iceshrimp.net daemon

[Service]
Type=simple
User=foo
WorkingDirectory=/home/foo/iceshrimp.net/Iceshrimp.Backend
ExecStart=/home/foo/.dotnet/dotnet run --migrate-and-start

[Install]
WantedBy=multi-user.target

A copy is also here .

Reload the systemd service:

sudo systemctl daemon-reload

And to make the systemd service restart after a reboot, enable it:

sudo systemctl enable iceshrimp.service

Start the systemd service

sudo systemctl start iceshrimp.service

sudo systemctl status iceshrimp.service

Congratulations!

Iceshrimp.NET should now be up and running.

If all has gone to plan you should see the above when going to the homepage.

Iceshrimp.NET Login Screenshot

When using a new database, it will be empty and a new User will need creating.

Create a new Iceshrimp.NET user

Firstly, turn Registrations ON:

nano iceshrimp.net/Iceshrimp.Backend/configuration.ini

;; Whether to allow instance registrations
;; Options: [Closed, Invite, Open]
Registrations = Open

Then send a PUT request e.g.:

curl -X PUT -H "Content-Type: application/json" http://localhost:3000/api/iceshrimp/auth -d' { "username" : "MyNewUsername", "password" : "super-long-password" }'

Finally, turn Registrations OFF:

nano iceshrimp.net/Iceshrimp.Backend/configuration.ini

;; Whether to allow instance registrations
;; Options: [Closed, Invite, Open]
Registrations = Closed

Updating Iceshrimp.NET

Stop the iceshrimp.net.service

sudo systemctl stop iceshrimp.net.service

Change to the ‘foo‘ user and go to the iceshrimp.net directory:

su foo

cd $HOME/iceshrimp.net

Then:

git pull

PGTune

https://kb.iceshrimp.dev/s/docs/doc/database-maintenance-pibqfnr2he

PGTune provides recommendations for PostgreSQL configuration based on your hardware specs and intended database workload.

There are a couple of Python based scripts on the Internet but I prefer to edit config files manually.

Put in a couple of details about your system in the web form and generate the amendments to be made to /etc/postgresql/16/main/postgresql.conf

https://pgtune.leopard.in.ua

I highly recommended doing this.

Server Load

Just a couple of graphs showing the difference in server load between IceshrimpJS and Iceshrimp.NET

It’s generally lighter and runs faster.

Firstly, the server load whilst running IceshrimpJS:

IceshrimpJS Server Load Screenshot

Secondly, the server load whilst running Iceshrimp.NET:

Iceshrimp.NET Server Load Screenshot

Updating the Blocklist

There was a previous post about how to update the Blocklist when running Iceshrimp.

These scripts have also been updated / added to.

Clients

Given that Iceshrimp.NET currently does not have a front-end, the only way to access an account is by using a third party application.

Web

• Elk
• Phanpy

Mobile

• Tusky

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

pgAdmin Screenshot

However you Fediverse, Enjoy!