jormungandr-bite/docs/install.md

Installing Iceshrimp

This document will guide you through manual installation of Iceshrimp. We also provide prebuilt packages for various platforms, should you prefer those over a manual install.

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+ (including modules, usually packaged as postgresql-contrib)
• Valkey (or any other Redis 6 compatible fork)
• libvips
• Web proxy
  • nginx
  • Caddy

Optional

• FFmpeg for video transcoding

Preparations

Download repository

Make sure you have git-lfs installed and have run git lfs install before cloning the repo, as we are using Git LFS for efficient storage of binary blobs.

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

If you don't want to run the latest development version, pick a version from here and run git checkout <version> before continuing.

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

Installing project dependencies

This project uses corepack to manage yarn versions, please make sure you don't have a globally installed non-corepack yarn binary (e.g. by having run npm install -g yarn in the past, or via your operating system's package manager)

corepack enable
corepack prepare --activate
yarn

Note: If you get a lot of The remote archive doesn't match the expected checksum errors, please make sure you installed git-lfs and ran git lfs install && git lfs pull.

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;
alter database iceshrimp owner to iceshrimp;
\q

First migration

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

yarn run init

Optimizing performance

If you are running Iceshrimp on a system with more than one CPU thread, you might want to set the clusterLimit config option to about half of your thread count, depending on your system configuration. Please note that each worker requires around 10 PostgreSQL connections, so be sure to set max_connections appropriately (aim for (10 * no_workers) + 10, if you have no other applications accessing the PostgreSQL database).

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

Environment variables

• ICESHRIMP_CONFIG (default: .config/default.yml) to change where the the config file is located
• ICESHRIMP_SECRETS (default: unset) if you want to keep your secrets in a separate config file
• ICESHRIMP_MEDIA_DIR (default: files) to change where internally stored files are located
• ICESHRIMP_CUSTOM_DIR (default: custom) to change where custom assets and locales are located (caution: assets are copied at build time or when running yarn gulp, not during startup!)

Make sure you are specifying absolute paths when setting environment variables.

Updating Iceshrimp

Before you start, if you cloned the iceshrimp repository before the Git LFS migration, please follow these instructions to get your repository back in sync.

First, stop the Iceshrimp service and then run the following commands:

## Run git stash commands only if you have uncommitted changes
git stash

If you were previously running a tagged release and/or want to upgrade to one, run:

git fetch --tags
git checkout <new-version>

If you were previously running a development version, and want to continue doing so or switch to the latest commit, run:

git switch dev
git pull

Regardless of which of the above you picked, run:

git stash pop
yarn
yarn build && yarn migrate

Note: If you get a lot of The remote archive doesn't match the expected checksum errors, please make sure you installed git-lfs and ran git lfs install && git lfs pull.

Now restart the Iceshrimp service and everything should be up to date.

Post-install

See post-install.