2024-07-10 19:15:05 +09:00

18 KiB

Raw Blame History

Notice for server administrators

You can skip intermediate versions when upgrading from an old version, but please read the notices and follow the instructions for each intermediate version before upgrading.

Upcoming breaking change (unreleased)

Please take a look at #10947.

Unreleased

For systemd/pm2 users

You can remove the packages/megalodon directory after pulling the latest source code (git pull --ff origin main).

rm --recursive --force packages/megalodon

v20240710

For all users

This is not related to the recent changes, but we have added a new section called "Maintain the server" in the installation guide. We suggest that you take a look at it (and we welcome your docs contributions)!

For systemd/pm2 users

It is highly recommended that you upgrade Node.js, since there is a new security release.

The new versions are:

Node v18.20.4 (v18.x LTS)
Node v20.15.1 (v20.x LTS)
Node v22.4.1 (v22.x)

Node v21.x is end-of-life.

⚠️ For Docker/Podman users

This is a security release for you, since the container image for this version is based on the updated Node.js image.

v20240607

The following environment variables are deprecated and no longer have any effect:

MK_ONLY_QUEUE
MK_ONLY_SERVER
MK_NO_DAEMONS
MK_DISABLE_CLUSTERING
MK_VERBOSE
MK_WITH_LOG_TIME
MK_SLOW

v20240601

For systemd/pm2 users

Required Node.js version has been bumped from v18.17.0 to v18.19.0. Also, as written in the v20240430 note, it is highly recommended that you use an even newer version since v18.19.0 has known vulnerabilities.

v20240523

For all users

We regret to inform you that the upgrade may take a long time to fix a regression we have introduced. The time required to upgrade should be the same as v20240413. This is not a security fix, so please upgrade your server when you have enough time. We are sorry for the inconvenience.

There are two data types in PostgreSQL to store time: timestamptz (timestamp with time zone) and timestamp (timestamp without time zone) [ref].

In Node.js, we manipulate the database using TypeORM. TypeORM handles time data as a JavaScript Date object. Since Date doesn't have timezone information [ref], we don't use the timezone information in the Node.js backend, and both timestamptz and timestamp behave in the same way. (Technically, the type names are a little confusing, and timestamptz (timestamp with time zone) doesn't store the timezone data either. Please read PostgreSQL documentation for more information.)

In Rust, we manipulate the database using SeaORM, which does distinguish between timestamptz and timestamp. timestamptz is converted to DateTime<FixedOffset> type, whereas timestamp is converted to NaiveDateTime.

We are using napi-rs to implement some of the backend features in Rust, which did not support DateTime<FixedOffset>. We used to store time data as timestamptz, but we converted them to timestamp for this reason. As we don't use timezone data, we thought this was okay, and indeed it worked fine.

However, we did not consider the case of migrating a server (hardware) to another timezone. With timestamp, there may be inconsistencies in the time data if you migrate your server to another system with a different timezone setting (Docker/Podman users should not be affected by this, as UTC is always used in containers unless you explicitly set one).

Therefore, we have contributed to napi-rs to add support for DateTime<FixedOffset> (https://github.com/napi-rs/napi-rs/pull/2074) and decided to migrate back from timestamp to timestamptz to properly address this problem. The migration process takes time roughly proportional to the number of stored posts.

For systemd/pm2 users

There is a bug where pnpm install --frozen-lockfile may fail on Linux 6.9.0, 6.9.1, and 6.9.2 (GitHub issue).

To check your Linux kernel version, run:

uname --kernel-release

v20240516

For all users

Firefish is now compatible with Node v22. The pre-built OCI container image will still be using the latest LTS version (v20.13.1 as of now).

v20240430

For all users

You can control the verbosity of the server log by adding maxLogLevel in .config/default.yml. logLevels has been deprecated in favor of this setting. (see also: https://firefish.dev/firefish/firefish/-/blob/eac0c1c47cd23789dcc395ab08b074934409fd96/.config/example.yml#L152)

For systemd/pm2 users

You need to install Perl to build Firefish. Since Git depends on Perl in many packaging systems, you probably already have Perl installed on your system. You can check the Perl version by this command:
```
perl --version
```
Not only Firefish but also Node.js has recently fixed a few security issues:
- https://nodejs.org/en/blog/vulnerability/april-2024-security-releases
- https://nodejs.org/en/blog/vulnerability/april-2024-security-releases-2
So, it is highly recommended that you upgrade your Node.js version as well. The new versions are
- Node v18.20.2 (v18.x LTS)
- Node v20.12.2 (v20.x LTS)
- Node v21.7.3 (v21.x)
You can check your Node.js version by this command:
```
node --version
```
Node v22 was also released several days ago, but we have not yet tested Firefish with this version.

v20240413

For all users

Upgrading may take a long time due to the large changes in the database. Please make sure to perform the operations when you have time.

The time required to upgrade varies greatly depending on the database size and the environment. For reference, we have checked that the database migration takes

70 seconds if the database stores 600,000 posts
28 minutes if the database stores 12,000,000 posts

(i.e., it takes roughly (𝑛 / 470,000) minutes where 𝑛 is the number of posts) on a server with 2 GB of RAM. You may want to tweak your database configuration (postgres.conf) if the process is significantly slower than our experimental result.

The number of posts stored on your database can be found at https://yourserver.example.com/admin/database (or notesCount of stats API response).

For systemd/pm2 users

Please remove packages/backend-rs/target before building Firefish.
```
rm --recursive --force packages/backend-rs/target
```
Please do not terminate pnpm run migrate even if it appears to be frozen.

For Docker/Podman users

You may not be able to access your server for a while after starting the container.

v20240326

For Docker/Podman users

The Firefish OCI container image is now based on docker.io/node:20-alpine (migrated from Debian to Alpine). This is a notification only and no action is required.

v20240319

The full-text search engine used in Firefish has been changed to PGroonga. This is no longer an optional feature, so please enable PGroonga on your system. If you are using Sonic, Meilisearch, or Elasticsearch, you can also uninstall it from your system and remove the settings from .config/default.yml.

For systemd/pm2 users

Required Node.js version has been bumped from v18.16.0 to v18.17.0.
You need to install PGroonga on your system. Please follow the instructions below.

[Edit (2024/03/23 23:55 UTC+9)] Warning: You may fail to install PGroonga, since the package registry of Apache Arrow (one of the subdependencies of PGroonga) is currently down (GitHub issue). We recommend that you hold off on upgrading until this problem is resolved.

[Edit (2024/03/25 22:31 UTC+9)] The Apache Arrow repository is now back up and running again.

1. Install PGroonga

Please execute psql --version to check your PostgreSQL major version. This will print a message like this:

psql (PostgreSQL) 16.1

In this case, your PostgreSQL major version is 16.

There are official installation instructions for many operating systems on https://pgroonga.github.io/install, so please follow the instructions on this page. However, since many users are using Ubuntu LTS or Debian, and there are no instructions for Arch Linux and Fedora, we explicitly list the instructions for Ubuntu LTS, Debian, Arch Linux and Fedora here. Please keep in mind that this is not official information and the procedures may change.

Ubuntu LTS

Install subdependencies

sudo apt install -y software-properties-common
sudo add-apt-repository -y universe
sudo add-apt-repository -y ppa:groonga/ppa
sudo apt install -y wget lsb-release
wget https://packages.groonga.org/ubuntu/groonga-apt-source-latest-$(lsb_release --codename --short).deb
sudo apt install -y -V ./groonga-apt-source-latest-$(lsb_release --codename --short).deb

Install PGroonga (replace 16 with your PostgreSQL version)

sudo apt install postgresql-16-pgdg-pgroonga

# Depending on your PostgreSQL installation method,
# the above command may fail and you need to run
# the following instead:
# sudo apt install postgresql-16-pgroonga

Debian

Install subdependencies

sudo apt install -y -V ca-certificates lsb-release wget
wget https://apache.jfrog.io/artifactory/arrow/$(lsb_release --id --short | tr 'A-Z' 'a-z')/apache-arrow-apt-source-latest-$(lsb_release --codename --short).deb
sudo apt install -y -V ./apache-arrow-apt-source-latest-$(lsb_release --codename --short).deb
wget https://packages.groonga.org/debian/groonga-apt-source-latest-$(lsb_release --codename --short).deb
sudo apt install -y -V ./groonga-apt-source-latest-$(lsb_release --codename --short).deb

Install PGroonga (replace 16 with your PostgreSQL version)

sudo apt install postgresql-16-pgdg-pgroonga

# Depending on your PostgreSQL installation method,
# the above command may fail and you need to run
# the following instead:
# sudo apt install postgresql-16-pgroonga

Arch Linux

You can install PGroonga from the Arch User Repository.

git clone https://aur.archlinux.org/pgroonga.git && cd pgroonga && makepkg -si
# or paru -S pgroonga
# or yay -S pgroonga

Fedora

You need to build PGroonga from source and create a policy package.

sudo dnf install make groonga-devel postgresql-server-devel redhat-rpm-config
wget https://packages.groonga.org/source/pgroonga/pgroonga-3.1.8.tar.gz
tar xvf pgroonga-3.1.8.tar.gz
cd pgroonga-3.1.8
make
sudo make install

cat > pgroonga.te << EOF
module pgroonga 1.0;

require {
    type postgresql_t;
    type postgresql_db_t;
    class file map;
}

allow postgresql_t postgresql_db_t:file map;
EOF

checkmodule -M -m -o pgroonga.mod pgroonga.te
semodule_package -o pgroonga.pp -m pgroonga.mod
sudo semodule -i pgroonga.pp

2. Enable PGroonga

After the instllation, please execute this command to enable PGroonga:

sudo --user=postgres psql --dbname=your_database_name --command='CREATE EXTENSION pgroonga;'

The database name can be found in .config/default.yml.

db:
  port: 5432
  db: database_name  # substitute your_database_name with this
  user: firefish
  pass: password

For Docker/Podman users

Please edit your docker-compose.yml to replace the database container image from docker.io/postgres to docker.io/groonga/pgroonga.

The list of tags can be found on https://hub.docker.com/r/groonga/pgroonga/tags. Tags are named as {PGroonga version}-{alpine or debian}-{PostgreSQL major version}.

Please make sure to use the same PostgreSQL version. If you are using docker.io/postgres:16-alpine (PostgreSQL v16), the corresponding image is docker.io/groonga/pgroonga:3.1.8-alpine-16 (or docker.io/groonga/pgroonga:3.1.8-alpine-16-slim). There are also tags called latest-alpine-16 and latest-alpine-16-slim, but please be careful if you use these tags since PGroonga may introduce breaking changes, similar to PostgreSQL.

db:
  restart: unless-stopped
  image: docker.io/groonga/pgroonga:3.1.8-alpine-16-slim  # change here
  container_name: firefish_db

After that, execute this command to enable PGroonga:

docker-compose up db --detach && sleep 5 && docker-compose exec db sh -c 'psql --user="${POSTGRES_USER}" --dbname="${POSTGRES_DB}" --command="CREATE EXTENSION pgroonga;"'
# or podman-compose up db --detach && sleep 5 && podman-compose exec db sh -c 'psql --user="${POSTGRES_USER}" --dbname="${POSTGRES_DB}" --command="CREATE EXTENSION pgroonga;"'

Once this is done, you can start Firefish as usual.

docker pull registry.firefish.dev/firefish/firefish && docker-compose up --detach
# or podman pull registry.firefish.dev/firefish/firefish && podman-compose up --detach

v20240301

For all users

A new setting item has been added to control the log levels, so please consider updating your .config/default.yml. (example settings)

v20240225

For Docker/Podman users

The bug where custom directory was not working has (finally) been fixed. Please add the custom directory to volumes in your docker-compose.yml:

services:
  web:
    image: registry.firefish.dev/firefish/firefish:latest
    # and so on ...

    volumes:
      - ./custom:/firefish/custom:ro  # <- Please add this line
      - ./files:/firefish/files
      - ./.config:/firefish/.config:ro

v20240222

For Docker/Podman users

You only need to pull the new container image (docker/podman pull) to upgrade your server, so we assume that many of you don't update the code (git pull --ff), but it's still worth noting here that we have renamed docker-compose.yml to docker-compose.example.yml in the repository, and docker-compose.yml is now set to be untracked by git.
- Since docker-compose.yml may be edited by users (e.g., change port number, add reverse proxy), it shouldn't have been tracked by git in the first place.
- If you want to update the repository (git pull --ff), please take the following steps to keep your docker-compose.yml:
  1. Backup (make a copy) your docker-compose.yml
```
cp docker-compose.yml /tmp/my-docker-compose.yml  # or somewhere else
```
  2. Restore the original docker-compose.yml so it doesn't conflict with the upstream changes
```
git checkout -- docker-compose.yml
```
  3. Pull the new code
```
git switch main
git pull --ff
```
  4. Bring back your docker-compose.yml
```
mv /tmp/my-docker-compose.yml docker-compose.yml
```
- If any modifications are needed to docker-compose.yml in the future, we will provide a notice.
- Also, PostgreSQL v12.2 (docker.io/postgres:12.2-alpine) has been used in this compose file, but we highly recommend that you upgrade it to a newer version (e.g., docker.io/postgres:16-alpine).
  - Note: some manual (painful) operations are needed to upgrade the PostgreSQL major version, so please be careful when performing upgrades: https://github.com/docker-library/postgres/issues/37

v20240214

For systemd/pm2 users

Required Rust version has been bumped from v1.70 to v1.74.

cargo --version  # check version
rustup update    # update version

v20240213

For systemd/pm2 users

packages/backend/native-utils can be removed.
- This directory was removed in the repository, but it's not completely removed from your system by git pull --ff, because some folders like packages/backend/native-utils/built are not tracked by git.
```
rm --recursive --force packages/backend/native-utils
```

v20240206

For all users

The git repository has been moved, so please update the git remote url.

git remote set-url origin https://firefish.dev/firefish/firefish.git

For systemd/pm2 users

Required Rust version has been bumped from v1.68 to v1.70.
libvips is no longer required (unless your server OS is *BSD), so you may uninstall it from your system. Make sure to execute the following commands after that:
```
pnpm clean-npm
pnpm install
```

For Docker/Podman users

The image tag has been changed to registry.firefish.dev/firefish/firefish:latest, so please update docker-compose.yml.

18 KiB Raw Blame History Unescape Escape

Notice for server administrators

Upcoming breaking change (unreleased)

Unreleased

For systemd/pm2 users

v20240710

For all users

For systemd/pm2 users

⚠️ For Docker/Podman users

v20240607

v20240601

For systemd/pm2 users

v20240523

For all users

For systemd/pm2 users

v20240516

For all users

v20240430

For all users

For systemd/pm2 users

v20240413

For all users

For systemd/pm2 users

For Docker/Podman users

v20240326

For Docker/Podman users

v20240319

For systemd/pm2 users

1. Install PGroonga

Ubuntu LTS

Debian

Arch Linux

Fedora

2. Enable PGroonga

For Docker/Podman users

v20240301

For all users

v20240225

For Docker/Podman users

v20240222

For Docker/Podman users

v20240214

For systemd/pm2 users

v20240213

For systemd/pm2 users

v20240206

For all users

For systemd/pm2 users

For Docker/Podman users

18 KiB

Raw Blame History