fresh.md

---
title: "Fresh Installation"
weight: 1100
toc: true
---

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](https://docs.docker.com/engine/install/) to get Docker and
Compose onto your machine.

Create the directories you'll need:

```bash
mkdir Sharkey && mkdir Sharkey/.config
```

Fetch all required examples and enter directory:

```bash
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:

```yaml
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](../configuration/) 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](../../customisation/search/)), 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:

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

Start the containers:

```bash
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:

```bash
sudo chown -R 991:991 Sharkey/files/
```

or:

```bash
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](https://misskey-hub.net/en/docs/install/manual.html).

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 (on Debian-style systems, that's `libpango1.0-dev
  libcairo2-dev libpixman-1-dev`)

Create a `sharkey` user:

```bash
adduser --disabled-password --disabled-login sharkey
```

Start a shell as that user:

```bash
sudo -u sharkey bash
```

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

```bash
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:

```yaml
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](../configuration/) for all
the various ways you can set configuration values, and check out [all
the search engine options](../../customisation/search/).

Build Sharkey:

```bash
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`:

```sql
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:

```bash
pnpm run init
```

And start Sharkey:

```bash
pnpm start
```

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

```text
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:

```ini
[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:

```bash
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:

```bash
#!/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:

```bash
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](https://misskey-hub.net/en/docs/for-admin/install/resources/nginx/)
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:

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

And these to your backend:

```haproxy
  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](https://blog.lattemacchiato.dev/how-to-make-your-fedi-instance-performance-not-suck/) 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:

```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:

```yml
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.

```Caddyfile
sharkey.example {
reverse_proxy localhost:3000
}
```

### Apache

Something like this works for Apache 2.4.47 or later:

```apacheconf
<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:

```bash
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:

```bash
sudo chown -R 991:991 Sharkey/files/
```

or:

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

### Manually

Very similar to the installation process:

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

Then 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.

**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`)

### 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:

  ```nginx
  # 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:

  ```bash
  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.