iceshrimp/docs/install.md

Installing Iceshrimp

This document will guide you through manual installation of Iceshrimp on dev branch, for main branch, use Firefish's installation guide.

Dependencies

Build

• C/C++ compiler like GCC or Clang
• Build tools like make
• Python 3

Required

• Node.js v18.16.0+ (v20 recommended)
• PostgreSQL 12+
• Redis 6+
• libvips
• Web proxy
  • nginx
  • Caddy

Optional

• FFmpeg for video transcoding
• Full text search (Choose one)
  Iceshrimp has full text search powered by Postgres by default, however it's very slow, and these are alternatives for that
  • Meilisearch | Installation guide
  • Sonic (More lightweight, but less features) | Installation guide
• Caching server (Choose one)
  This will be used for storing stuff like antennas. If you won't install any, mandatory Redis instance will be used instead
  • DragonflyDB | Installation guide
  • KeyDB | Installation guide
  • Another Redis server

Preparations

Download repository

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

Creating a new user

In case you want to run Iceshrimp as a different user, run adduser --disabled-password --disabled-login iceshrimp
Following steps will require you to run them as the user you have made, so use su - iceshrimp, or sudo -iu iceshrimp, or whatever else method in order to temporarily log in as that user.

Configuration

• Copy .config/example.yml to .config/default.yml
• Edit .config/default.yml with text editor
  • Make sure to set PostgreSQL and Redis section correctly
  • Make sure to set/uncomment caching server and/or text search sections if you have chosen to set up these

Installing project dependencies

corepack enable
corepack prepare yarn@stable --activate
yarn

Building Iceshrimp

yarn build

Database

Creating database

This will create a postgres user with your password and database, while also granting that user all privileges on database.
Using psql prompt:

sudo -u postgres psql

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

First migration

In order for Iceshrimp to work properly, you need to initialise the database using

yarn run init

Optimizing performance

For optimal database performance, it's highly recommended to configure PostgreSQL with PGTune using the "Mixed type of application" profile. This is especially important should your database server use HDD instead of SATA or NVMe SSD storage.

Setting up Webproxy

Nginx

• Run sudo cp docs/examples/iceshrimp.nginx.conf /etc/nginx/sites-available/ && cd /etc/nginx/sites-available/
• Edit iceshrimp.nginx.conf to reflect your server properly
• Run sudo ln -s ./iceshrimp.nginx.conf ../sites-enabled/iceshrimp.nginx.conf
• Run sudo nginx -t to check that the config is valid, then restart the nginx service.

Caddy

• Add the following to your Caddyfile, and replace example.com with your domain

example.com {
  reverse_proxy localhost:3000
}

Running Iceshrimp

Running manually

• Start Iceshrimp by running NODE_ENV=production yarn run start.
  If this is your first run, after Iceshrimp has started successfully, you'll be able to go to the URL you have specified in .config/default.yml and create first user.
• To stop the server, use Ctrl-C.

Running using systemd

• Run sudo cp docs/examples/iceshrimp.service /etc/systemd/system/
• Edit /etc/systemd/system/iceshrimp.service with text editor, and change User, WorkingDir, ExecStart if necessary.
• Run sudo systemctl daemon-reload
• Run sudo systemctl enable --now iceshrimp in order to enable and start Iceshrimp.
• (Optional) Check if instance is running using sudo systemctl status iceshrimp

Updating Iceshrimp

Shut down Iceshrimp and then run these commands

## Run git stash commands only if you have uncommitted changes
git stash
git pull
git stash pop
yarn
yarn build && yarn migrate

Start Iceshrimp back up

Post-install

See post-install.