Fresh Installation

Before you start, you really need:

• an always-on machine that can receive connections from the Internet
• a domain name to dedicate to your Sharkey instance, resolving to the address(es) of that machine
• a web server running on that machine, with valid TLS certificates for the domain name

Please note that the first registered user account of your instance is subject to some restrictions and cannot be migrated, for example. Therefore, the account should not be used as a normal user account.

With Docker#

Prerequisites:

• Docker
• Compose Plugin

Refer to Docker Engine’s install page to get Docker and Compose onto your machine.

Create the directories you’ll need:

mkdir Sharkey && mkdir Sharkey/.config

Fetch all required examples and enter directory:

wget -O Sharkey/docker-compose.yml https://activitypub.software/TransFem-org/Sharkey/-/raw/stable/compose_example.yml
wget -O Sharkey/.config/default.yml https://activitypub.software/TransFem-org/Sharkey/-/raw/stable/.config/docker_example.yml
wget -O Sharkey/.config/docker.env https://activitypub.software/TransFem-org/Sharkey/-/raw/stable/.config/docker_example.env
cd Sharkey

Edit .config/default.yml, there are comments explaining what each option means. In particular, we’re going to assume you have:

url: https://{YOUR DOMAIN NAME}/

(replace {YOUR DOMAIN NAME} with the domain name we talked about at the start).

You should also change the setupPassword value, so that your new instance will be protected between when you start it and when you create your first user.

Refer to the Configuration Options page for all the various ways you can set configuration values.

Edit docker-compose.yml, there are multiple comments there as well. If you want to set up note search with meilisearch, uncomment all of meilisearch options (but also check out all the search engine options), otherwise proceed to do the following changes in the services: / web: section:

• uncomment the line that starts with image:
• comment out the line that starts with build: .

It should look like this:

services:
  web:
    image: registry.activitypub.software/transfem-org/sharkey:latest
    # build: .
    …

Start the containers:

docker compose up -d

You can now open your instance’s URL in your browser, to complete the setup.

If you have problems uploading files to the drive, are not using S3, you may need to run either:

sudo chown -R 991:991 Sharkey/files/

or:

docker compose exec --user=root web chown -R sharkey:sharkey /sharkey/files

to fix the permissions on that directory.

Manually#

These instructions are very similar to Misskey’s manual installation instructions.

Prerequisites:

• more than 2GB of free RAM, we recommend at least 4GB
• Node.js version 22.11 or later, with both npm and pnpm installed (corepack enable should suffice, make sure you run it as root if you’re using your system Node.js)
• PostgreSQL version 15 or later
• Redis
• FFmpeg
• all the various packages to compile and build C code, and Python (on Debian-style systems, that’s build-essential & python)
• some system libraries and their development headers: pango, cairo, pixman, librsvg (on Debian-style systems, that’s libpango1.0-dev libcairo2-dev libpixman-1-dev librsvg2-2)
• some fonts (on Debian-style systems, fonts-noto or similar will do)

Create a sharkey user:

adduser --disabled-password --disabled-login sharkey

Start a shell as that user:

sudo -u sharkey bash

(or something like that), then clone the Sharkey repository, and copy the example configuration file:

git clone --recurse-submodules -b stable https://activitypub.software/TransFem-org/Sharkey.git
cd Sharkey
pnpm install --frozen-lockfile
cp .config/example.yml .config/default.yml

Edit .config/default.yml, there are comments explaining what each option means. In particular, we’re going to assume you have:

url: https://{YOUR DOMAIN NAME}/
db:
  host: localhost
  port: 5432
  db: sharkey
  user: sharkey
  pass: {YOUR PASSWORD}

(replace {YOUR PASSWORD} with an actual password you make up for this, and {YOUR DOMAIN NAME} with the domain name we talked about at the start)

You should also change the setupPassword value, so that your new instance will be protected between when you start it and when you create your first user.

Refer to the Configuration Options page for all the various ways you can set configuration values, and check out all the search engine options.

Build Sharkey:

pnpm run build

Create the PostgreSQL user and database, either with createuser and createdb or with sudo -u postgres psql and then running these commands inside psql:

CREATE DATABASE sharkey WITH ENCODING = 'UTF8';
CREATE USER sharkey WITH ENCRYPTED PASSWORD '{YOUR_PASSWORD}';
GRANT ALL PRIVILEGES ON DATABASE sharkey TO sharkey;
ALTER DATABASE sharkey OWNER TO sharkey;
\q

(replace {YOUR PASSWORD} with the same password as before)

Then create the schema:

pnpm run init

And start Sharkey:

pnpm start

you should see a series of colourful lines, ending with something like:

Now listening on port 3000 on https://example.tld

but with a different URL at the end (you did change the url setting in the config file, right?). Stop that process (control-C is enough), and set up a system service for Sharkey.

With systemd#

Create a file /etc/systemd/system/sharkey.service containing:

[Unit]
Description=Sharkey daemon

[Service]
Type=simple
User=sharkey
ExecStart=/usr/bin/pnpm start
WorkingDirectory=/home/sharkey/Sharkey
Environment="NODE_OPTIONS=--max-old-space-size=8192"
Environment="NODE_ENV=production"
TimeoutSec=60
StandardOutput=journal
StandardError=journal
SyslogIdentifier=sharkey
Restart=always

[Install]
WantedBy=multi-user.target

(you may need to change that /usr/bin/pnpm if you’re not using your system Node.js).

Then:

sudo systemctl daemon-reload
sudo systemctl enable sharkey
sudo systemctl start sharkey

After that, systemctl status sharkey should show that it’s running.

You can now open your instance’s URL in your browser, to complete the setup.

With OpenRC#

Create a file /etc/init.d/sharkey containing:

#!/sbin/openrc-run

name=sharkey
description="Sharkey daemon"

command="/usr/bin/pnpm"
command_args="start"
command_user="sharkey"

supervisor="supervise-daemon"
supervise_daemon_args=" -d /home/sharkey/Sharkey -e NODE_ENV=production -e \"NODE_OPTIONS=--max-old-space-size=8192\""

pidfile="/run/${RC_SVCNAME}.pid"

depend() {
  need net
  use logger nginx
}

(you may need to change that /usr/bin/pnpm if you’re not using your system Node.js).

Then:

sudo rc-update add sharkey
sudo rc-service sharkey start

After that, rc-service sharkey status should show that it’s running.

You can now open your instance’s URL in your browser, to complete the setup.

Configure the web server#

NGINX#

See Misskey’s instructions about configuring NGINX. They provide a good starting point that can be modified to fit your needs.

HAProxy#

Heads up - Sharkey doesn’t officially support HAProxy, but you can still find community support for it within the discord.

Add these lines to your frontend:

  acl sharkey hdr(Host) -i sharkey.example
  use_backend sharkey-be if sharkey

And these to your backend:

  backend sharkey-be
    http-reuse aggressive
    option forwarded
    option forwardfor
    mode http
    option redispatch
    timeout queue 15s
    http-request set-header X-Real-IP %[src]
    http-request set-header X-Forwarded-Proto https
    server sharkey-server <ip>:3000 check observe layer7 error-limit 10 on-error mark-down inter 2s rise 10 slowstart 10s

Check out Latte Macchiato’s guide to making your fedi instance not suck for more optimization tricks with HAProxy.

Traefik#

Heads up - Sharkey doesn’t officially support Traefik, but you can still find community support for it within the discord.

Our configs will make the assumptions that sharkey is listening to port 3000, your https(443) entrypoint is called webSecure and that you have a certificate resolver ready called myResolver. Change these as necessary. Remember to change sharkey.example to your instances domain name.

Docker Labels#

Append these labels to your sharkey service in docker-compose.yml:

    ...[your docker config]...
    labels:
      - "traefik.http.routers.sharkey.rule=Host(`sharkey.example`)"
      - "traefik.http.services.sharkey.loadbalancer.server.port=3000"
      - "traefik.http.routers.sharkey.tls=true"
      - "traefik.http.routers.sharkey.tls.certresolver=myResolver"
    ...[your docker config]...

Dynamic Config#

insert this into your dynamic config:

http:
  routers:
      sharkey:
        entryPoints: ["web", "webSecure"]
        rule: "Host(`sharkey.example`)"
        service: "sharkey-be"
        tls:
          certresolver: myResolver

  services:
    sharkey-be:
      loadBalancer:
        servers:
          - url: "http://<ip>:3000"

Caddy#

Heads up - Sharkey doesn’t officially support Caddy, but you can still find community support for it within the discord.

In your Caddyfile, insert the following instructions. Change sharkey.example to your instance domain. Change the port specified if you changed the host port for your Docker container.

sharkey.example {
reverse_proxy localhost:3000
}

Apache#

Something like this works for Apache 2.4.47 or later:

<VirtualHost *>
 DocumentRoot /var/empty
 ServerName sharkey.example

 SSLEngine On
 RequestHeader set X-Forwarded-Proto "https"

 AllowEncodedSlashes NoDecode

 ProxyPreserveHost On

 ProxyPass "/" "http://127.0.0.1:3000/" upgrade=websocket
 ProxyPassReverse "/" "https://sharkey.example/"
 ProxyPassReverse "/" "http://127.0.0.1:3000/"

 # or, if your Sharkey listens on a UNIX socket
 # ProxyPass "/" "unix:/opt/sharkey/sharkey.sock|http://127.0.0.1/" upgrade=websocket
 # ProxyPassReverse "/" "https://sharkey.example/"
 # ProxyPassReverse "/" "unix:/opt/sharkey/sharkey.sock|http://127.0.0.1/"

</VirtualHost>

Update Sharkey#

With Docker#

Fetch the latest image, restart:

docker compose pull && docker compose up -d

NOTE: if you are upgrading from 2024.3.1 or earlier, and are not using S3 or similar, you will have to change the ownership of the files on your disk, otherwise uploads won’t work anymore. This is because previous versions ran Sharkey as the root user, but we no longer do that.

Run either:

sudo chown -R 991:991 Sharkey/files/

or:

docker compose exec --user=root web chown -R sharkey:sharkey /sharkey/files

Manually#

Very similar to the installation process.

You should stop Sharkey (sudo systemctl stop sharkey or rc-service sharkey stop), then:

sudo -u sharkey bash
cd Sharkey
git checkout stable
git pull --recurse-submodules
pnpm install --frozen-lockfile
pnpm run build
pnpm run migrate

After that, restart the service (sudo systemctl restart sharkey or rc-service sharkey restart).

If there’s problems with updating, you can run pnpm run clean and/or pnpm run clean-all which will remove all the effects of a previous build, then you can install+build+migrate+restart again.

You do not need to stop Sharkey before updating, but it helps minimise potential problems (e.g. the database migrations may deadlock with the normal Sharkey operations, in which case you have to keep running pnpm run migrate until it completes successfully).

NOTE: if you are upgrading from 2024.9.4 or earlier, Sharkey now needs Node.js 22.11, and you will almost certainly need to run pnpm run clean-all before pnpm install, otherwise you’ll end up with some dependencies (e.g. re2) linked to the wrong libraries.

NOTE: if you upgrading from 2024.11.2 or earlier, Sharkey now needs some system libraries and their development headers: pango, cairo, pixman (on Debian-style systems, that’s libpango1.0-dev libcairo2-dev libpixman-1-dev)

NOTE: if you upgrading from 2024.4.2 or earlier, Sharkey now needs some system libraries (librsvg) and some fonts (on Debian-style systems, that’s librsvg2-2 and fonts-noto)

Caching issues#

It’s possible that the web server (or the CDN, if you’ve configured one) caches some of our assets for longer than needed, which may show up as broken icons after updating to a new Sharkey release. You may therefore need to clear whatever cache you have.

Clear NGINX cache#

You may clear NGINX’s cache by manually deleting the cache directory or all of the cached files within it.

• First, we must locate the cache directory. This is a configured by the proxy_cache_path directive, which is found in the global section of any NGINX configuration file. Under typical circumstances, there should only be one directive and it should be located in the primary configuration file. Some templates and example configurations have erroneously placed the directive within a virtual host, so you should check all configuration files to be sure. When you’ve found the directive, the cache directory will be listed in the first parameter. Here’s an example:

  # Here, the cache directory is "/var/cache/nginx".
  proxy_cache_path /var/cache/nginx levels=1:2 keys_zone=cache1:16m max_size=1g inactive=720m use_temp_path=off;

• Next, we need to stop the NGINX server. We cannot clear the cache while NGINX is running; this can cause corruption and failed requests. Steps to exit the server will vary by operating system, but the follow command can be used under systemd environments: systemctl stop nginx. For the rare platforms that use systemd services with a different init system (notably, WSL), this alternate command should be used: service nginx stop.

• Now we can actually clear the cache. As mentioned above, this is done by removing all files from the cache directory that we located in step 1. You will likely need root permissions to modify this directory. You can use this command to remove the directory:

  sudo rm ${path_to_cache:?}

  Make sure to replace ${path_to_cache:?} with the actual path we determined in step 1!

• We’re done! It’s finally time to re-start NGINX. As before, the commands will vary between platforms. Systemd environments can use systemctl start nginx, others can use service nginx start. On startup, NGINX will automatically re-create the empty cache and resume using it.