HoovesSocial/hippofish
2
0
Fork 0
Code Issues 3 Pull requests 1 Projects Releases Packages Wiki Activity Actions

Merge branch 'docs/develop' into 'develop'

Browse source 
feat(dev): add new docker-based dev env to replace broken nix dev env.

Co-authored-by: 老周部落 <laozhoubuluo@gmail.com>

Closes #10081, #10715, #10727, and #10811

See merge request firefish/firefish!10690
This commit is contained in:
naskya 2024-03-18 15:24:45 +00:00
commit 3ec9867692
24 changed files with 823 additions and 1041 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

44
.config/devenv.yml
View file

@ -1,38 +1,28 @@
url: http://localhost:3000
port: 3000
url: http://localhost:3030
port: 3030
db:
host: 127.0.0.1
host: firefish_db
port: 5432
db: firefish
db: firefish_db
user: firefish
pass: firefish
pass: password
redis:
host: localhost
host: firefish_redis
port: 6379
family: 4
#sonic:
# host: localhost
# port: 1491
# auth: SecretPassword
# collection: notes
# bucket: default
#elasticsearch:
# host: localhost
# port: 9200
# ssl: false
# user:
# pass:
id: 'aid'
reservedUsernames:
- root
- admin
- administrator
- me
- system
#allowedPrivateNetworks: [
# '10.69.1.0/24'
#]
logLevel: [
'error',
'success',
'warning',
'debug',
'info'
]

9
.config/example.yml
View file

@ -41,11 +41,11 @@ db:
port: 5432
#ssl: false
# Database name
db: firefish
db: firefish_db
# Auth
user: example-firefish-user
pass: example-firefish-pass
user: firefish
pass: password
# Whether disable Caching queries
#disableCache: true
@ -181,9 +181,6 @@ logLevel: [
# Proxy remote files (default: false)
#proxyRemoteFiles: true
# Use authorized fetch for outgoing requests
signToActivityPubGet: true
#allowedPrivateNetworks: [
# '127.0.0.1/32'
#]

2
.dockerignore
View file

@ -45,8 +45,6 @@ docker-compose.yml
docker-compose.example.yml
firefish.apache.conf
firefish.nginx.conf
flake.lock
flake.nix
title.svg
/.gitlab
/chart

4
.envrc
View file

@ -1,4 +0,0 @@
if ! has nix_direnv_version || ! nix_direnv_version 2.3.0; then
source_url "https://raw.githubusercontent.com/nix-community/nix-direnv/2.3.0/direnvrc" "sha256-Dmd+j63L84wuzgyjITIfSxSD57Tx7v51DMxVZOsiUD8="
fi
use flake . --impure

8
.gitignore vendored
View file

@ -60,6 +60,10 @@ packages/backend/assets/LICENSE
packages/megalodon/lib
packages/megalodon/.idea
dev/container/firefish
dev/container/db
dev/container/redis
# blender backups
*.blend1
*.blend2
@ -71,10 +75,6 @@ packages/megalodon/.idea
.yarn
yarn*
# Nix Development shell items
.devenv
.direnv
# Cargo cache for Docker
/.cargo-cache
/.cargo-target

248
CONTRIBUTING.md
View file

@ -22,7 +22,17 @@ Before creating an issue, please check the following:
> **Warning**
> Do not close issues that are about to be resolved. It should remain open until a commit that actually resolves it is merged.
## Before implementation
## Coding
### Preparing a development environment
You can prepare your local Firefish environment in multiple ways:
- [Run Firefish and databases on your host](../dev/docs/local-installation.md)
- [Run Firefish on your host and databases in containers](../dev/docs/db-container.md)
- [Run Firefish and databases in containers](../dev/docs/container.md)
### Before implementation
When you want to add a feature or fix a bug, **first have the design and policy reviewed in an Issue** (if it is not there, please make one). Without this step, there is a high possibility that the MR will not be merged even if it is implemented.
At this point, you also need to clarify the goals of the MR you will create, and make sure that the other members of the team are aware of them.
@ -30,14 +40,14 @@ MRs that do not have a clear set of do's and don'ts tend to be bloated and diffi
Also, when you start implementation, assign yourself to the Issue (if you cannot do it yourself, ask another member to assign you). By expressing your intention to work the Issue, you can prevent conflicts in the work.
## Well-known branches
### Well-known branches
- The **`main`** branch is tracking the latest release and used for production purposes.
- The **`develop`** branch is where we work for the next release.
- When you create a MR, basically target it to this branch. **But create a different branch**
- The **`l10n_develop`** branch is reserved for localization management.
- **`feature/*`** branches are reserved for the development of a specific feature
## Creating a merge request (MR)
### Creating a merge request (MR)
Thank you for your MR! Before creating a MR, please check the following:
- If possible, prefix the title with a keyword that identifies the type of this MR, as shown below.
- `fix` / `refactor` / `feat` / `enhance` / `perf` / `chore` etc. You are also welcome to use gitmoji. This is important as we use these to A) easier read the git history and B) generate our changelog. Without propper prefixing it is possible that your MR is rejected.
@ -68,235 +78,3 @@ Be willing to comment on the good points and not just the things you want fixed
- Does the test ensure the expected behavior?
- Are there any omissions or gaps?
- Does it check for anomalies?
## Preparing the development environment
1. Install the following software
- nodejs
- rustup
- cargo
- sea-orm-cli
- podman
- podman-compose
2. Copy the config file
```sh
cp .config/dev.example.yml .config/default.yml
```
3. Start postgres/redis containers
```sh
pnpm run dev:up
```
4. Build Firefish
```sh
pnpm install
pnpm run build:debug
pnpm run migrate
```
5. Start Firefish on your localhost
```sh
pnpm run start
```
You can use the following commands to initialize the database:
```sh
pnpm run dev:init
pnpm run migrate
```
Make sure to clear your browser local storage after initializing the dev instance.
## Deploy (SOON)
The `/deploy` command by issue comment can be used to deploy the contents of a MR to the preview environment.
```
/deploy sha=<commit hash>
```
An actual domain will be assigned so you can test the federation.
# THE FOLLOWING IS OUTDATED:
## Merge
## Release
### Release Instructions
1. Commit version changes in the `develop` branch ([package.json](https://github.com/misskey-dev/misskey/blob/develop/package.json))
2. Create a release PR.
- Into `master` from `develop` branch.
- The title must be in the format `Release: x.y.z`.
- `x.y.z` is the new version you are trying to release.
3. Deploy and perform a simple QA check. Also verify that the tests passed.
4. Merge it.
5. Create a [release of GitHub](https://github.com/misskey-dev/misskey/releases)
- The target branch must be `master`
- The tag name must be the version
## Development
During development, it is useful to use the `pnpm run dev` command.
This command monitors the server-side and client-side source files and automatically builds them if they are modified.
In addition, it will also automatically start the Firefish server process.
## Testing
- Test codes are located in [`/test`](/test).
### Run test
Create a config file.
```
cp test/test.yml .config/
```
Prepare DB/Redis for testing.
```
docker-compose -f test/docker-compose.yml up
```
Alternatively, prepare an empty (data can be erased) DB and edit `.config/test.yml`.
Run all test.
```
yarn test
```
#### Run specify test
```
TS_NODE_FILES=true TS_NODE_TRANSPILE_ONLY=true TS_NODE_PROJECT="./test/tsconfig.json" pnpx mocha test/foo.ts --require ts-node/register
```
## Vue
Firefish uses Vue(v3) as its front-end framework.
- Use TypeScript.
- **When creating a new component, please use the Composition API (with [setup syntax](https://v3.vuejs.org/api/sfc-script-setup.html) and [ref syntax](https://github.com/vuejs/rfcs/discussions/369)) instead of the Options API.**
- Some of the existing components are implemented in the Options API, but it is an old implementation. Refactors that migrate those components to the Composition API are also welcome.
## nirax
niraxは、Misskeyで使用しているオリジナルのフロントエンドルーティングシステムです。
**vue-routerから影響を多大に受けているので、まずはvue-routerについて学ぶことをお勧めします。**
### ルート定義
ルート定義は、以下の形式のオブジェクトの配列です。
``` ts
{
name?: string;
path: string;
component: Component;
query?: Record<string, string>;
loginRequired?: boolean;
hash?: string;
globalCacheKey?: string;
children?: RouteDef[];
}
```
> **Warning**
> 現状、ルートは定義された順に評価されます。
> たとえば、`/foo/:id`ルート定義の次に`/foo/bar`ルート定義がされていた場合、後者がマッチすることはありません。
### 複数のルーター
vue-routerとの最大の違いは、niraxは複数のルーターが存在することを許可している点です。
これにより、アプリ内ウィンドウでブラウザとは個別にルーティングすることなどが可能になります。
## Notes
### How to resolve conflictions occurred at yarn.lock?
Just execute `yarn` to fix it.
### INSERTするときにはsaveではなくinsertを使用する
#6441
### placeholder
SQLをクエリビルダで組み立てる際、使用するプレースホルダは重複してはならない
例えば
``` ts
query.andWhere(new Brackets(qb => {
for (const type of ps.fileType) {
qb.orWhere(`:type = ANY(note.attachedFileTypes)`, { type: type });
}
}));
```
と書くと、ループ中で`type`というプレースホルダが複数回使われてしまいおかしくなる
だから次のようにする必要がある
```ts
query.andWhere(new Brackets(qb => {
for (const type of ps.fileType) {
const i = ps.fileType.indexOf(type);
qb.orWhere(`:type${i} = ANY(note.attachedFileTypes)`, { [`type${i}`]: type });
}
}));
```
### Not `null` in TypeORM
```ts
const foo = await Foos.findOne({
bar: Not(null)
});
```
のようなクエリ(`bar`が`null`ではない)は期待通りに動作しない。
次のようにします:
```ts
const foo = await Foos.findOne({
bar: Not(IsNull())
});
```
### `null` in SQL
SQLを発行する際、パラメータが`null`になる可能性のある場合はSQL文を出し分けなければならない
例えば
``` ts
query.where('file.folderId = :folderId', { folderId: ps.folderId });
```
という処理で、`ps.folderId`が`null`だと結果的に`file.folderId = null`のようなクエリが発行されてしまい、これは正しいSQLではないので期待した結果が得られない
だから次のようにする必要がある
``` ts
if (ps.folderId) {
query.where('file.folderId = :folderId', { folderId: ps.folderId });
} else {
query.where('file.folderId IS NULL');
}
```
### `[]` in SQL
SQLを発行する際、`IN`のパラメータが`[]`(空の配列)になる可能性のある場合はSQL文を出し分けなければならない
例えば
``` ts
const users = await Users.find({
id: In(userIds)
});
```
という処理で、`userIds`が`[]`だと結果的に`user.id IN ()`のようなクエリが発行されてしまい、これは正しいSQLではないので期待した結果が得られない
だから次のようにする必要がある
``` ts
const users = userIds.length > 0 ? await Users.find({
id: In(userIds)
}) : [];
```
### 配列のインデックス in SQL
SQLでは配列のインデックスは**1始まり**。
`[a, b, c]`の `a`にアクセスしたいなら`[0]`ではなく`[1]`と書く
### null IN
nullが含まれる可能性のあるカラムにINするときは、そのままだとおかしくなるのでORなどでnullのハンドリングをしよう。
### `undefined`にご用心
MongoDBの時とは違い、findOneでレコードを取得する時に対象レコードが存在しない場合 **`undefined`** が返ってくるので注意。
MongoDBは`null`で返してきてたので、その感覚で`if (x === null)`とか書くとバグる。代わりに`if (x == null)`と書いてください
### Migration作成方法
packages/backendで:
```sh
pnpm dlx typeorm migration:generate -d ormconfig.js -o <migration name>
```
- 生成後、ファイルをmigration下に移してください
- 作成されたスクリプトは不必要な変更を含むため除去してください
### コネクションには`markRaw`せよ
**Vueのコンポーネントのdataオプションとして**misskey.jsのコネクションを設定するとき、必ず`markRaw`でラップしてください。インスタンスが不必要にリアクティブ化されることで、misskey.js内の処理で不具合が発生するとともに、パフォーマンス上の問題にも繋がる。なお、Composition APIを使う場合はこの限りではない(リアクティブ化はマニュアルなため)。
### JSONのimportに気を付けよう
TypeScriptでjsonをimportすると、tscでコンパイルするときにそのjsonファイルも一緒にdistディレクトリに吐き出されてしまう。この挙動により、意図せずファイルの書き換えが発生することがあるので、jsonをimportするときは書き換えられても良いものかどうか確認すること。書き換えされて欲しくない場合は、importで読み込むのではなく、`fs.readFileSync`などの関数を使って読み込むようにすればよい。
### コンポーネントのスタイル定義でmarginを持たせない
コンポーネント自身がmarginを設定するのは問題の元となることはよく知られている
marginはそのコンポーネントを使う側が設定する
## その他
### HTMLのクラス名で follow という単語は使わない
広告ブロッカーで誤ってブロックされる

213
README.md
View file

@ -15,213 +15,22 @@ Firefish is based off of Misskey, a powerful microblogging server on ActivityPub
<div style="clear: both;"></div>
# Documents
- [Installation guide](./docs/install.md)
- [Contributing guide](./CONTRIBUTING.md)
- [Changelog](./docs/changelog.md)
# Links
### Want to get involved? Great!
- If you have the means to, [donations](https://opencollective.com/Firefish) are a great way to keep us going.
- If you know how to program in TypeScript, Vue, or Rust, read the [contributing](./CONTRIBUTING.md) document.
- If you know a non-English language, translating Firefish on [Weblate](https://hosted.weblate.org/engage/firefish/) help bring Firefish to more people. No technical experience needed!
### Links
- Donations:
- OpenCollective: <https://opencollective.com/Firefish>
- Donations: <https://opencollective.com/Firefish>
- Matrix space: <https://matrix.to/#/#firefish-community:nitro.chat>
- Official account: <a href="https://info.firefish.dev/@firefish" rel="me">`@firefish@info.firefish.dev`</a>
- Weblate: <https://hosted.weblate.org/engage/firefish/>
# Getting started
# Want to get involved? Great!
This guide will work for both **starting from scratch** and **migrating from Misskey**.
- If you know how to program in TypeScript, Vue, or Rust, please read the [contributing guide](./CONTRIBUTING.md).
- If you have the means to, [donations](https://opencollective.com/Firefish) are a great way to keep us going.
- If you know a non-English language, translating Firefish on [Weblate](https://hosted.weblate.org/engage/firefish/) help bring Firefish to more people. No technical experience needed!
<!-- ## Easy installers
If you have access to a server that supports one of the sources below, I recommend you use it! Note that these methods *won't* allow you to migrate from Misskey without manual intervention.
[![Install on Ubuntu](https://pool.jortage.com/voringme/misskey/3b62a443-1b44-45cf-8f9e-f1c588f803ed.png)](https://firefish.dev/firefish/ubuntu-bash-install)　　[![Install on the Arch User Repository](https://pool.jortage.com/voringme/misskey/ba2a5c07-f078-43f1-8483-2e01acca9c40.png)](https://aur.archlinux.org/packages/firefish)　　[![Install Firefish with YunoHost](https://install-app.yunohost.org/install-with-yunohost.svg)](https://install-app.yunohost.org/?app=firefish) -->
## Containerization
- [How to run Firefish with Docker](https://firefish.dev/firefish/firefish/-/blob/develop/docs/docker.md)
- [How to run Firefish with Kubernetes/Helm](https://firefish.dev/firefish/firefish/-/blob/develop/docs/kubernetes.md)
## Dependencies
- At least [NodeJS](https://nodejs.org/en/) v18.17.0 (v20/v21 recommended)
- At least [PostgreSQL](https://www.postgresql.org/) v12 (v16 recommended)
- At least [Redis](https://redis.io/) v7
- Web Proxy (one of the following)
- Nginx (recommended)
- Caddy (recommended)
- Apache
### Optional dependencies
- [FFmpeg](https://ffmpeg.org/) for video transcoding
- Caching server (one of the following)
- [DragonflyDB](https://www.dragonflydb.io/) (recommended)
- [KeyDB](https://keydb.dev/)
- Another [Redis](https://redis.io/) server
### Build dependencies
- At least [Rust](https://www.rust-lang.org/) v1.74
- C/C++ compiler & build tools
- `build-essential` on Debian/Ubuntu Linux
- `base-devel` on Arch Linux
- [Python 3](https://www.python.org/)
## Get folder ready
```sh
git clone https://firefish.dev/firefish/firefish.git
cd firefish/
```
> **Note**
> By default, you're on the develop branch. Run `git checkout main` to switch to the Main branch.
## Install dependencies
```sh
# nvm install 19 && nvm use 19
sudo corepack enable
corepack prepare pnpm@latest --activate
pnpm install --frozen-lockfile
```
### pm2
To install pm2 run:
```
npm i -g pm2
pm2 install pm2-logrotate
```
> **Note**
> [`pm2-logrotate`](https://github.com/keymetrics/pm2-logrotate/blob/master/README.md) ensures that log files don't infinitely gather size, as Firefish produces a lot of logs.
## Create database
In PostgreSQL (`psql`), run the following command:
```sql
CREATE DATABASE firefish WITH encoding = 'UTF8';
```
or run the following from the command line:
```sh
psql postgres -c "create database firefish with encoding = 'UTF8';"
```
In Firefish's directory, fill out the `db` section of `.config/default.yml` with the correct information, where the `db` key is `firefish`.
## Caching server
If you experience a lot of traffic, it's a good idea to set up another Redis-compatible caching server. If you don't set one one up, it'll fall back to the mandatory Redis server. DragonflyDB is the recommended option due to its unrivaled performance and ease of use.
## Set up search
### Sonic
Sonic is better suited for self hosters with smaller deployments. It uses almost no resources, barely any any disk space, and is relatively fast.
Follow sonic's [installation guide](https://github.com/valeriansaliou/sonic#installation)
> **Note**
> If you use IPv4: in Sonic's directory, edit the `config.cfg` file to change `inet` to `"0.0.0.0:1491"`.
In Firefish's directory, fill out the `sonic` section of `.config/default.yml` with the correct information.
### Meilisearch
Meilisearch is better suited for larger deployments. It's faster but uses far more resources and disk space.
Follow Meilisearch's [quick start guide](https://www.meilisearch.com/docs/learn/getting_started/quick_start)
In Firefish's directory, fill out the `meilisearch` section of `.config/default.yml` with the correct information.
### ElasticSearch
Please don't use ElasticSearch unless you already have an ElasticSearch setup and want to continue using it for Firefish. ElasticSearch is slow, heavy, and offers very few benefits over Sonic/Meilisearch.
## Customize
- To add custom CSS for all users, edit `./custom/assets/instance.css`.
- To add static assets (such as images for the splash screen), place them in the `./custom/assets/` directory. They'll then be available on `https://yourserver.tld/static-assets/filename.ext`.
- To add custom locales, place them in the `./custom/locales/` directory. If you name your custom locale the same as an existing locale, it will overwrite it. If you give it a unique name, it will be added to the list. Also make sure that the first part of the filename matches the locale you're basing it on. (Example: `en-FOO.yml`)
- To add custom error images, place them in the `./custom/assets/badges` directory, replacing the files already there.
- To add custom sounds, place only mp3 files in the `./custom/assets/sounds` directory.
- To update custom assets without rebuilding, just run `pnpm run gulp`.
- To block ChatGPT, CommonCrawl, or other crawlers from indexing your instance, uncomment the respective rules in `./custom/robots.txt`.
## Configuring a new server
- Run `cp .config/example.yml .config/default.yml`
- Edit `.config/default.yml`, making sure to fill out required fields.
- Also copy and edit `.config/docker_example.env` to `.config/docker.env` if you're using Docker.
## Migrating from Misskey/FoundKey to Firefish
For migrating from Misskey v13, Misskey v12, and FoundKey, read [this document](https://firefish.dev/firefish/firefish/-/blob/develop/docs/migrate.md).
## Web proxy
### Nginx (recommended)
- Run `sudo cp ./firefish.nginx.conf /etc/nginx/sites-available/ && cd /etc/nginx/sites-available/`
- Edit `firefish.nginx.conf` to reflect your server properly
- Run `sudo ln -s ./firefish.nginx.conf ../sites-enabled/firefish.nginx.conf`
- Run `sudo nginx -t` to validate that the config is valid, then restart the NGINX service.
### Caddy (recommended)
- Add the following block to your `Caddyfile`, replacing `example.tld` with your own domain:
```caddy
example.tld {
reverse_proxy http://127.0.0.1:3000
}
```
- Reload your caddy configuration
### Apache
> **Warning**
> Apache has some known problems with Firefish. Only use it if you have to.
- Run `sudo cp ./firefish.apache.conf /etc/apache2/sites-available/ && cd /etc/apache2/sites-available/`
- Edit `firefish.apache.conf` to reflect your server properly
- Run `sudo a2ensite firefish.apache` to enable the site
- Run `sudo service apache2 restart` to reload apache2 configuration
## Build and launch!
### NodeJS + pm2
#### `git pull` and run these steps to update Firefish in the future!
```sh
# git pull
pnpm install
NODE_ENV=production pnpm run build && pnpm run migrate
pm2 start "NODE_ENV=production pnpm run start" --name Firefish
```
## Tips & Tricks
- When editing the config file, please don't fill out the settings at the bottom. They're designed *only* for managed hosting, not self hosting. Those settings are much better off being set in Firefish's control panel.
- Port 3000 (used in the default config) might be already used on your server for something else. To find an open port for Firefish, run `for p in {3000..4000}; do ss -tlnH | tr -s ' ' | cut -d" " -sf4 | grep -q "${p}$" || echo "${p}"; done | head -n 1`. Replace 3000 with the minimum port and 4000 with the maximum port if you need it.
- I'd recommend you use a S3 Bucket/CDN for Object Storage, especially if you use Docker.
- When using object storage, setting a proper `Access-Control-Allow-Origin` response header is highly recommended.
- I'd ***strongly*** recommend against using CloudFlare, but if you do, make sure to turn code minification off.
- For push notifications, run `npx web-push generate-vapid-keys`, then put the public and private keys into Control Panel > General > ServiceWorker.
- For translations, make a [DeepL](https://deepl.com) account and generate an API key, then put it into Control Panel > General > DeepL Translation.
- To add another admin account:
- Go to the user's page > 3 Dots > About > Moderation > turn on "Moderator"
- Go back to Overview > click the clipboard icon next to the ID
- Run `psql -d firefish` (or whatever the database name is)
- Run `UPDATE "user" SET "isAdmin" = true WHERE id='999999';` (replace `999999` with the copied ID)
- Restart your Firefish server

65
dev/container/docker-entrypoint.sh Executable file
View file

@ -0,0 +1,65 @@
#!/bin/sh
set -xeu
node --version
# Check Environment Initialized Flag
if [ ! -f '/.firefish_env_initialized' ]; then
# Install entrypoint dependencies
apt-get update
DEBIAN_FRONTEND='noninteractive' apt-get install -y --no-install-recommends wget curl ca-certificates lsb-release gnupg
# Create the PostgreSQL file repository configuration
sh -c 'echo "deb https://apt.postgresql.org/pub/repos/apt $(lsb_release -cs)-pgdg main" > /etc/apt/sources.list.d/pgdg.list'
# Import the PostgreSQL repository signing key
wget --quiet -O - https://www.postgresql.org/media/keys/ACCC4CF8.asc | apt-key add -
# Install compilation dependencies
apt-get update
DEBIAN_FRONTEND='noninteractive' apt-get install -y --no-install-recommends build-essential python3 ffmpeg git postgresql-client-12
curl -vvv --proto '=https' --tlsv1.2 --show-error --fail https://sh.rustup.rs | sh -s -- -y
# Add Cargo PATH
PATH="/root/.cargo/bin:${PATH}"
# If Firefish not exist
if [ ! -f '/firefish/README.md' ]; then
# Clone Firefish
cd /
git clone -v https://firefish.dev/firefish/firefish.git
# Configuring a new server
cd /firefish
cp .config/devenv.yml .config/default.yml
URL="$(echo "${URL}" | sed 's#/#\\/#g')"
sed -i'.bak' "s/http:\/\/localhost:3030/${URL}/" .config/default.yml
fi
# Configure postgres, add pgroonga search
psql --user=firefish --host=firefish_db --dbname=firefish_db --command='CREATE EXTENSION IF NOT EXISTS pgroonga;'
# Configure pnpm, and install dev mode dependencies for compilation
cd /firefish
corepack enable
corepack prepare pnpm@latest --activate
pnpm install --prod false
fi
# Add Environment Initialized Flag
touch /.firefish_env_initialized
# Add Cargo PATH
PATH="/root/.cargo/bin:${PATH}"
# Start a new server
cd /firefish
pnpm install --prod false
pnpm run build:debug
pnpm run migrate
pnpm run start

0
dev/install.sql → dev/db-container/install.sql
View file

17
dev/docker-compose.yml
View file

@ -1,17 +0,0 @@
version: "3"
services:
redis:
image: docker.io/redis:7-alpine
ports:
- "26379:6379"
db:
image: docker.io/groonga/pgroonga:latest-alpine-16-slim
environment:
- "POSTGRES_PASSWORD=password"
- "POSTGRES_USER=firefish"
- "POSTGRES_DB=firefish_db"
ports:
- "25432:5432"
volumes:
- "./install.sql:/docker-entrypoint-initdb.d/install.sql:ro"

30
dev/docs/container.md Normal file
View file

@ -0,0 +1,30 @@
# Set up a fully-containerized development environment
## Prerequisites
- Container runtime installation
- [Docker](https://docs.docker.com/get-docker/)
- [Podman](https://podman.io/docs/installation) and [Podman Compose](https://github.com/containers/podman-compose)
- [containerd](https://github.com/containerd/containerd) and [nerdctl](https://github.com/containerd/nerdctl)
- or whatever you want to use
- The following ports are not in use
- 3030
- 25432
- 26379
## Start up the environment
1. Download the [`dev/container` directory](./dev/container) and execute `chmod +x docker-entrypoint.sh`
- Alternatively, you can use `git clone https://firefish.dev/firefish/firefish.git && cd firefish/dev/container`, although this will clone the entire repository.
1. Edit `docker-compose.yml` and set `URL` to the URL you want to use (or leave it as `http://localhost:3030`)
1. Run `docker compose up`
- This will build the environment, install dependencies and prepare the needed config files.
- If you use Podman, you should run `podman-compose up` instead.
1. Wait until the following message shows up
```log
DONE * [core boot] All workers started
DONE * [core boot] Now listening on port 3030 on https://your_firefish_url.example.com
```
1. A fresh Firefish environment is created on the URL you have set!
When you want to restart the dev server, you just need to terminate the process (a.k.a. press `Ctrl+C`) and run `docker compose up` again.

98
dev/docs/db-container.md Normal file
View file

@ -0,0 +1,98 @@
# Set up database containers and run Firefish locally
## Prerequisites
- Dependencies
- git
- Node.js
- pnpm
- Rust toolchain
- FFmpeg
- Container runtime
- [Docker](https://docs.docker.com/get-docker/)
- [Podman](https://podman.io/docs/installation) and [Podman Compose](https://github.com/containers/podman-compose)
- [containerd](https://github.com/containerd/containerd) and [nerdctl](https://github.com/containerd/nerdctl)
- or whatever you want to use
- The following ports are not in use
- 25432
- 26379
You can refer to [local-installation.md](./local-installation.md) to install the dependencies.
## Configure the environment
1. Fork the Firefish repository on GitLab
1. Clone your Firefish repository
```sh
git clone https://firefish.dev/your-user-name/firefish.git
cd firefish
```
1. Create `.config/default.yml` with the following content
```yaml
# You can change the port if 3000 is already used
url: http://localhost:3000
port: 3000
db:
host: localhost
port: 25432
db: firefish_db
user: firefish
pass: password
redis:
host: localhost
port: 26379
logLevel: [
'error',
'success',
'warning',
'info'
]
```
1. Start database containers
```sh
cd dev/db-container
docker compose up --detach
# or podman-compose up --detach
# or whatever
# go back to the repository root
cd ../..
```
## Build and start Firefish
1. Build Firefish
```sh
pnpm install
pnpm run build:debug
```
1. Execute database migrations
```sh
pnpm run migrate
```
1. Start Firefish
```sh
pnpm run start
```
You can access to the local Firefish server on http://localhost:3000 after this message shows up!
```
DONE * [core boot] All workers started
DONE * [core boot] Now listening on port 3000 on http://localhost:3000
```
## Reset the environment
You can recreate a fresh local Firefish environment by recreating the database containers:
```sh
cd dev/db-container
docker compose down
docker compose up --detach
cd ../..
pnpm run migrate
pnpm run start
```

173
dev/docs/local-installation.md Normal file
View file

@ -0,0 +1,173 @@
# Set up a development environment by installing all dependencies locally
This document demonstrates an example procedure to set up a Firefish development environment on Debian 12. You can refer to this document if you prefer to install all dependencies (Node.js, PostgreSQL, Redis, etc.) locally.
Make sure that you can use the `sudo` command before proceeding.
## 1. Install dependencies
### Utilities
```sh
sudo apt update
sudo apt install build-essential python3 curl wget git lsb-release
```
### Node.js
Firefish requires Node.js v18.17.0 or later. While you can choose any versions between v18.17.0 and the latest version (v21.6.2 as of writing), we recommend that you install v18.x so as not to use new features inadvertently and introduce incompatibility issues.
Instructions can be found at [this repository](https://github.com/nodesource/distributions).
```sh
NODE_MAJOR=18
curl -fsSL "https://deb.nodesource.com/setup_${NODE_MAJOR}.x" | sudo -E bash -
sudo apt install nodejs
# check version
node --version
```
### Rust toolchain
Instructions can be found at [this page](https://www.rust-lang.org/tools/install).
```sh
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
. "${HOME}/.cargo/env"
# check version
cargo --version
```
### PostgreSQL and PGroonga
PostgreSQL install instructions can be found at [this page](https://www.postgresql.org/download/).
```sh
sudo sh -c 'echo "deb https://apt.postgresql.org/pub/repos/apt $(lsb_release -cs)-pgdg main" > /etc/apt/sources.list.d/pgdg.list'
wget --quiet -O - https://www.postgresql.org/media/keys/ACCC4CF8.asc | sudo apt-key add -
sudo apt update
sudo apt install postgresql-12
sudo systemctl enable --now postgresql
# check version
psql --version
```
PGroonga install instructions can be found at [this page](https://pgroonga.github.io/install/).
```sh
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 "./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 "./groonga-apt-source-latest-$(lsb_release --codename --short).deb"
sudo apt update
sudo apt install postgresql-12-pgdg-pgroonga
rm "apache-arrow-apt-source-latest-$(lsb_release --codename --short).deb" "groonga-apt-source-latest-$(lsb_release --codename --short).deb"
```
### Redis
Instructions can be found at [this page](https://redis.io/docs/install/install-redis/).
```sh
curl -fsSL https://packages.redis.io/gpg | sudo gpg --dearmor -o /usr/share/keyrings/redis-archive-keyring.gpg
echo "deb [signed-by=/usr/share/keyrings/redis-archive-keyring.gpg] https://packages.redis.io/deb $(lsb_release -cs) main" | sudo tee /etc/apt/sources.list.d/redis.list
sudo apt update
sudo apt install redis
sudo systemctl enable --now redis-server
# check version
redis-cli --version
```
### FFmpeg
```sh
sudo apt install ffmpeg
```
## 2. Set up a database
1. Create a database user
```sh
sudo -u postgres createuser --no-createdb --no-createrole --no-superuser --encrypted --pwprompt firefish
```
If you forgot the password you typed, you can reset it by executing `sudo -u postgres psql -c "ALTER USER firefish PASSWORD 'password';"`.
2. Create a database
```sh
sudo -u postgres createdb --encoding='UTF8' --owner=firefish firefish_db
```
3. Enable PGronnga extension
```sh
sudo -u postgres psql --command='CREATE EXTENSION pgroonga;' --dbname=firefish_db
```
## 3. Configure Firefish
1. Fork the Firefish repository on GitLab
1. Clone your Firefish repository
```sh
git clone https://firefish.dev/your-user-name/firefish.git
```
1. Create the config file
```sh
cd firefish
vim .config/default.yml
```
```yaml
url: http://localhost:3000
port: 3000
db:
host: localhost
port: 5432
db: firefish_db
user: firefish
pass: password
redis:
host: localhost
port: 6379
logLevel: [
'error',
'success',
'warning',
'info'
]
```
## 4. Build and start Firefish
1. Install pnpm
```sh
sudo corepack enable
corepack prepare pnpm@latest --activate
# check version
pnpm --version
```
1. Build
```sh
pnpm install
pnpm run build:debug
```
1. Execute database migrations
```sh
pnpm run migrate
```
1. Start Firefish
```sh
pnpm run start
```
You can access to the local Firefish server on http://localhost:3000 after this message shows up!
```
DONE * [core boot] All workers started
DONE * [core boot] Now listening on port 3000 on http://localhost:3000
```

108
docs/development.md
View file

@ -1,108 +0,0 @@
# Firefish Developer Docs
## Nix Dev Environment
The Firefish repo comes with a Nix-based shell environment to help make development as easy as possible!
Please note, however, that this environment will not work on Windows outside of a WSL2 environment.
### Prerequisites
- Installed the [Nix Package Manager](https://nixos.org/download.html) (use the comman on their website)
- Installed [direnv](https://direnv.net/docs/installation.html) and added its hook to your shell. (package manager)
Once the repo is cloned to your computer, follow these next few steps inside the Firefish folder:
- Run `direnv allow`. This will build the environment and install all needed tools.
- Run `install-deps`, then `prepare-config`, to install the node dependencies and prepare the needed config files.
- In a second terminal, run `devenv up`. This will spawn a **Redis** server, a **Postgres** server, and the **Firefish** server in dev mode.
- Once you see the Firefish banner printed in your second terminal, run `migrate` in the first.
- Once migrations finish, open http://localhost:3000 in your web browser.
- You should now see the admin user creation screen!
Note: When you want to restart a dev server, all you need to do is run `devenv up`, no other steps are necessary.
# Possible Troubles with the dev enviroment
(this doesn't have to be done under normal conditions, this is for future reference)
### direnv
If you have any trouble with `direnv allow`
Check that the contents of `.envrc` have the same version of nix-direnv that is specified here:
> nix-direnv under -> installation -> using direnv source url
> https://github.com/nix-community/nix-direnv#direnv-source_url
there should be no errors during `direnv allow`
### outdated nix packages
if `install-deps` or any subsequent command doesn't run due to versioning problems
`flake.nix` and `flake.lock` may be outdated
delete `flake.lock`, or better, run `nix flake update --extra-experimental-features flakes --extra-experimental-features nix-command`
after that, run `direnv rebuild`
if there are any errors, you might have to change `flake.nix`
(because the available options can change between versions - consider getting support in [the matrix channel](https://matrix.to/#/#firefish-community:nitro.chat))
### after changing a node version
in my case, i had to change the node version from 19, to 18
! before proceeding, make sure to delete all build artifacts!
remove `node_modules` and `built` folders, and maybe `.devenv` and `.direnv` as well
manually, or run `npm cache clean --force` and `pnpm cleanall`
### Windows Subsystem for Linux
if `devenv up` terminates because of wrong folder permissions,
create the file `/etc/wsl.conf` in your distro and add
```shell
[automount]
options = "metadata"
```
this allows `chmod` calls to actually have an effect.
the build scripts DO actually set the permissions, it just needs to work in wsl.
### devenv up
devenv up may take a looong time. (some say this is fake news, maybe it was bad luck in my case)
do not get spooked by this error:
```
> firefish@14.0.0-dev32 start /mnt/.../firefish
> pnpm --filter backend run start
> backend@ start /mnt/.../firefish/packages/backend
> pnpm node ./built/index.js
node:internal/modules/cjs/loader:1078
throw err;
^
Error: Cannot find module '/mnt/.../firefish/packages/backend/built/index.js'
at Module._resolveFilename (node:internal/modules/cjs/loader:1075:15)
at Module._load (node:internal/modules/cjs/loader:920:27)
at Function.executeUserEntryPoint [as runMain] (node:internal/modules/run_main:81:12)
at node:internal/main/run_main_module:23:47 {
code: 'MODULE_NOT_FOUND',
requireStack: []
}
Node.js v18.16.0
undefined
/mnt/.../firefish/packages/backend:
 ERR_PNPM_RECURSIVE_RUN_FIRST_FAIL  backend@ start: `pnpm node ./built/index.js`
Exit status 1
 ELIFECYCLE  Command failed with exit code 1.
```
the script is designed to constantly try to start the server, while the build is still running.
this just means that the build isn't finished yet.
at some point you should see a banner that says "Firefish" in big letters -
then you're good to go and can run `migrate` (in another terminal)!
if you don't see the banner,
and it's for some reason stuck on `Finished 'build' after 917 ms` for a view minutes,
just leave devenv running and open another terminal in the folder
run `migrate` and then `pnpm --filter backend run start` by yourself
the server should start

39
docs/docker.md → docs/install-container.md
View file

@ -1,19 +1,13 @@
# Running a Firefish server with Docker
# Running a Firefish server with containers
## Pre-built docker container
[registry.firefish.dev/firefish/firefish](https://firefish.dev/firefish/firefish/container_registry)
## Prerequisites
## `docker-compose`
- Latest [Docker](https://docs.docker.com/get-docker/) installation
- You can also use [Podman](https://podman.io/docs/installation) and [Podman Compose](https://github.com/containers/podman-compose).
There are example config files that you can use to build the container from source
## Configuration
- docker-compose.example.yml (**compose file**)
- .config/docker_example.env (**db config settings**)
- .config/default.yml (**firefish server settings**)
## Configuring
Copy the files:
Copy the example config files:
```sh
cp docker-compose.example.yml docker-compose.yml
@ -23,20 +17,31 @@ cp .config/docker_example.env .config/docker.env
then edit them according to your environment.
You can configure `docker.env` with anything you like, but you will have to pay attention to the `default.yml` file:
- `url` should be set to the URL you will be hosting the web interface for the server at.
- `host`, `db`, `user`, `pass` will have to be configured in the `PostgreSQL configuration` section - `host` is the name of the postgres container (eg: *firefish_db_1*), and the others should match your `docker.env`.
- `host`will need to be configured in the *Redis configuration* section - it is the name of the redis container (eg: *firefish_redis_1*)
- `auth` will need to be configured in the *Sonic* section - cannot be the default `SecretPassword`
Everything else can be left as-is.
## Running docker-compose
## Pull the container image
The [prebuilt container for firefish](https://firefish.dev/firefish/firefish/container_registry) is fairly large, and may take a few minutes to download and extract using docker.
The image tag is [`registry.firefish.dev/firefish/firefish:latest`](https://firefish.dev/firefish/firefish/container_registry).
Copy `docker-compose.yml` and the `config/` to a directory, then run the **docker-compose** command:
`docker-compose up -d`.
```sh
docker pull registry.firefish.dev/firefish/firefish:latest
# or podman pull registry.firefish.dev/firefish/firefish:latest
```
## Run
```sh
docker compose up --detach
# or podman-compose up --detach
```
NOTE: This will take some time to come fully online, even after download and extracting the container images, and it may emit some error messages before completing successfully. Specifically, the `db` container needs to initialize and so isn't available to the `web` container right away. Only once the `db` container comes online does the `web` container start building and initializing the firefish tables.
Once the server is up you can use a web browser to access the web interface at `http://serverip:3000` (where `serverip` is the IP of the server you are running the firefish server on).
To publish your server, please follow the instructions in [section 5 of this installation guide](./install.md#5-preparation-for-publishing-a-server).

316
docs/install.md Normal file
View file

@ -0,0 +1,316 @@
# Install Firefish
This document shows an example procedure for installing Firefish on Debian 12. Note that there is much room for customizing the server setup; this document merely demonstrates a simple installation.
If you want to use the pre-built container image, please refer to [`install-container.md`](./install-container.md).
Make sure that you can use the `sudo` command before proceeding.
## 1. Install dependencies
### Utilities
```sh
sudo apt update
sudo apt install build-essential python3 curl wget git lsb-release
```
### Node.js and pnpm
Instructions can be found at [this repository](https://github.com/nodesource/distributions).
```sh
NODE_MAJOR=20
curl -fsSL "https://deb.nodesource.com/setup_${NODE_MAJOR}.x" | sudo -E bash -
sudo apt install nodejs
# check version
node --version
```
You also need to enable `pnpm`.
```sh
sudo corepack enable
corepack prepare pnpm@latest --activate
# check version
pnpm --version
```
### PostgreSQL and PGroonga
PostgreSQL install instructions can be found at [this page](https://www.postgresql.org/download/).
```sh
sudo sh -c 'echo "deb https://apt.postgresql.org/pub/repos/apt $(lsb_release -cs)-pgdg main" > /etc/apt/sources.list.d/pgdg.list'
wget --quiet -O - https://www.postgresql.org/media/keys/ACCC4CF8.asc | sudo apt-key add -
sudo apt update
sudo apt install postgresql-16
sudo systemctl enable --now postgresql
# check version
psql --version
```
PGroonga install instructions can be found at [this page](https://pgroonga.github.io/install/).
```sh
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 "./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 "./groonga-apt-source-latest-$(lsb_release --codename --short).deb"
sudo apt update
sudo apt install postgresql-16-pgdg-pgroonga
rm "apache-arrow-apt-source-latest-$(lsb_release --codename --short).deb" "groonga-apt-source-latest-$(lsb_release --codename --short).deb"
```
### Redis
Instructions can be found at [this page](https://redis.io/docs/install/install-redis/).
```sh
curl -fsSL https://packages.redis.io/gpg | sudo gpg --dearmor -o /usr/share/keyrings/redis-archive-keyring.gpg
echo "deb [signed-by=/usr/share/keyrings/redis-archive-keyring.gpg] https://packages.redis.io/deb $(lsb_release -cs) main" | sudo tee /etc/apt/sources.list.d/redis.list
sudo apt update
sudo apt install redis
sudo systemctl enable --now redis-server
# check version
redis-cli --version
```
### FFmpeg
```sh
sudo apt install ffmpeg
```
## 2. Set up a database
1. Create a database user
```sh
sudo -u postgres createuser --no-createdb --no-createrole --no-superuser --encrypted --pwprompt firefish
```
If you forgot the password you typed, you can reset it by executing `sudo -u postgres psql -c "ALTER USER firefish PASSWORD 'password';"`.
2. Create a database
```sh
sudo -u postgres createdb --encoding='UTF8' --owner=firefish firefish_db
```
3. Enable PGronnga extension
```sh
sudo -u postgres psql --command='CREATE EXTENSION pgroonga;' --dbname=firefish_db
```
## 3. Configure Firefish
1. Create an user for Firefish and switch user
```sh
sudo useradd --create-home --user-group --shell /bin/bash firefish
sudo su --login firefish
# check the current working directory
# the result should be /home/firefish
pwd
```
1. Install Rust toolchain
Instructions can be found at [this page](https://www.rust-lang.org/tools/install).
```sh
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
. "${HOME}/.cargo/env"
# check version
cargo --version
```
3. Clone the Firefish repository
```sh
git clone --branch=main https://firefish.dev/firefish/firefish.git
```
1. Copy and edit the config file
```sh
cd firefish
cp .config/example.yml .config/default.yml
nano .config/default.yml
```
```yaml
url: https://your-server-domain.example.com # change here
port: 3000
db:
host: localhost
port: 5432
db: firefish_db
user: firefish
pass: your-database-password # and here
```
## 4. Build Firefish
1. Build
```sh
pnpm install --frozen-lockfile
NODE_ENV=production pnpm run build
```
1. Execute database migrations
```sh
pnpm run migrate
```
1. Logout from `firefish` user
```sh
exit
```
## 5. Preparation for publishing a server
### 1. Set up a firewall
To expose your server securely, you may want to set up a firewall. We use [ufw](https://launchpad.net/ufw) in this instruction.
```sh
sudo apt install ufw
# if you use SSH
# SSH_PORT=22
# sudo ufw limit "${SSH_PORT}/tcp"
sudo ufw default deny
sudo ufw allow 80
sudo ufw allow 443
sudo ufw --force enable
# check status
sudo ufw status
```
### 2. Set up a reverse proxy
In this instruction, we use [Caddy](https://caddyserver.com/) to make the Firefish server accesible from internet. However, you can also use [Nginx](https://nginx.org/en/) if you want ([example Nginx config file](../firefish.nginx.conf)).
1. Install Caddy
```sh
sudo apt install debian-keyring debian-archive-keyring apt-transport-https
curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/gpg.key' | sudo gpg --dearmor -o /usr/share/keyrings/caddy-stable-archive-keyring.gpg
curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/debian.deb.txt' | sudo tee /etc/apt/sources.list.d/caddy-stable.list
sudo apt update
sudo apt install caddy
# check version
caddy version
```
1. Replace the config file
```sh
sudo mv /etc/caddy/Caddyfile /etc/caddy/Caddyfile.bak
sudo nano /etc/caddy/Caddyfile
```
```Caddyfile
your-server-domain.example.com {
reverse_proxy http://127.0.0.1:3000
log {
output file /var/log/caddy/firefish.log
}
}
```
1. Restart Caddy
```sh
sudo systemctl restart caddy
```
## 6. Publish your Firefish server
1. Create a service file
```sh
sudo nano /etc/systemd/system/firefish.service
```
```service
[Unit]
Description=Firefish daemon
Requires=redis.service caddy.service postgresql.service
After=redis.service caddy.service postgresql.service network-online.target
[Service]
Type=simple
User=firefish
Group=firefish
UMask=0027
ExecStart=/usr/bin/pnpm run start
WorkingDirectory=/home/firefish/firefish
Environment="NODE_ENV=production"
Environment="npm_config_cache=/tmp"
# uncomment the following line if you use jemalloc (note that the path varies on different environments)
# Environment="LD_PRELOAD=/usr/lib/x86_64-linux-gnu/libjemalloc.so.2"
StandardOutput=journal
StandardError=journal
SyslogIdentifier=firefish
TimeoutSec=60
Restart=always
CapabilityBoundingSet=
DevicePolicy=closed
NoNewPrivileges=true
LockPersonality=true
PrivateDevices=true
PrivateIPC=true
PrivateMounts=true
PrivateUsers=true
ProtectClock=true
ProtectControlGroups=true
ProtectHostname=true
ProtectKernelTunables=true
ProtectKernelModules=true
ProtectKernelLogs=true
ProtectProc=invisible
RestrictNamespaces=true
RestrictRealtime=true
RestrictSUIDSGID=true
SecureBits=noroot-locked
SystemCallArchitectures=native
SystemCallFilter=~@chown @clock @cpu-emulation @debug @ipc @keyring @memlock @module @mount @obsolete @privileged @raw-io @reboot @resources @setuid @swap
SystemCallFilter=capset pipe pipe2 setpriority
[Install]
WantedBy=multi-user.target
```
1. Start Firefish
```sh
sudo systemctl enable --now firefish
```
## Upgrading
Please refer to the [upgrade instruction](./upgrade.md). Be sure to switch to `firefish` user and go to the Firefish directory before performing `pnpm install --frozen-lockfile`:
```sh
sudo su --login firefish
cd ~/firefish
```
## Customize
- To add custom CSS for all users, edit `./custom/assets/instance.css`.
- To add static assets (such as images for the splash screen), place them in the `./custom/assets/` directory. They'll then be available on `https://yourserver.tld/static-assets/filename.ext`.
- To add custom locales, place them in the `./custom/locales/` directory. If you name your custom locale the same as an existing locale, it will overwrite it. If you give it a unique name, it will be added to the list. Also make sure that the first part of the filename matches the locale you're basing it on. (Example: `en-FOO.yml`)
- To add custom error images, place them in the `./custom/assets/badges` directory, replacing the files already there.
- To add custom sounds, place only mp3 files in the `./custom/assets/sounds` directory.
- To update custom assets without rebuilding, just run `pnpm run gulp`.
- To block ChatGPT, CommonCrawl, or other crawlers from indexing your instance, uncomment the respective rules in `./custom/robots.txt`.
## Tips & Tricks
- When editing the config file, please don't fill out the settings at the bottom. They're designed *only* for managed hosting, not self hosting. Those settings are much better off being set in Firefish's control panel.
- Port 3000 (used in the default config) might be already used on your server for something else. To find an open port for Firefish, run `for p in {3000..4000}; do ss -tlnH | tr -s ' ' | cut -d" " -sf4 | grep -q "${p}$" || echo "${p}"; done | head -n 1`. Replace 3000 with the minimum port and 4000 with the maximum port if you need it.
- We'd recommend you use a S3 Bucket/CDN for Object Storage, especially if you use containers.
- When using object storage, setting a proper `Access-Control-Allow-Origin` response header is highly recommended.
- We'd recommend against using CloudFlare, but if you do, make sure to turn code minification off.
- For push notifications, run `npx web-push generate-vapid-keys`, then put the public and private keys into Control Panel > General > ServiceWorker.
- For translations, make a [DeepL](https://deepl.com) account and generate an API key, then put it into Control Panel > General > DeepL Translation.
- To add another admin account:
- Go to the user's page > 3 Dots > About > Moderation > turn on "Moderator"
- Go back to Overview > click the clipboard icon next to the ID
- Run `psql -d firefish` (or whatever the database name is)
- Run `UPDATE "user" SET "isAdmin" = true WHERE id='999999';` (replace `999999` with the copied ID)
- Restart your Firefish server

46
docs/notice-for-admins.md
View file

@ -1,13 +1,17 @@
# Unreleased
# 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](./upgrade.md).
## Unreleased
The full-text search engine used in Firefish has been changed to [PGroonga](https://pgroonga.github.io/). 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
### 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.
### 1. Install PGroonga
#### 1. Install PGroonga
Please execute `psql --version` to check your PostgreSQL major version. This will print a message like this:
@ -19,7 +23,7 @@ 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, and there are no instructions for Arch Linux, we explicitly list the instructions for Ubuntu and Arch Linux here. Please keep in mind that this is not official information and the procedures may change.
#### Ubuntu
##### Ubuntu
1. Add apt repository
```sh
@ -39,7 +43,7 @@ There are official installation instructions for many operating systems on <http
sudo apt install postgresql-16-pgdg-pgroonga
```
#### Arch Linux
##### Arch Linux
You can install PGroonga from the Arch User Repository.
@ -49,7 +53,7 @@ git clone https://aur.archlinux.org/pgroonga.git && cd pgroonga && makepkg -si
# or yay -S pgroonga
```
### 2. Enable PGroonga
#### 2. Enable PGroonga
After the instllation, please execute this command to enable PGroonga:
@ -66,7 +70,7 @@ db:
pass: password
```
## For Docker/Podman users
### 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`.
@ -95,15 +99,15 @@ docker pull registry.firefish.dev/firefish/firefish && docker-compose up --detac
# or podman pull registry.firefish.dev/firefish/firefish && podman-compose up --detach
```
# v20240301
## v20240301
## For all users
### 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](https://firefish.dev/firefish/firefish/-/blob/e7689fb302a0eed192b9515162258a39800f838a/.config/example.yml#L170-179))
# v20240225
## v20240225
## For Docker/Podman users
### 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`:
```yaml
@ -118,9 +122,9 @@ A new setting item has been added to control the log levels, so please consider
- ./.config:/firefish/.config:ro
```
# v20240222
## v20240222
## For Docker/Podman users
### 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.
@ -146,9 +150,9 @@ A new setting item has been added to control the log levels, so please consider
- 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
## v20240214
## For systemd/pm2 users
### For systemd/pm2 users
- Required Rust version has been bumped from v1.70 to v1.74.
```sh
@ -156,9 +160,9 @@ A new setting item has been added to control the log levels, so please consider
rustup update # update version
```
# v20240213
## v20240213
## For systemd/pm2 users
### 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.
@ -167,16 +171,16 @@ A new setting item has been added to control the log levels, so please consider
rm --recursive --force packages/backend/native-utils
```
# v20240206
## v20240206
## For all users
### For all users
- The git repository has been moved, so please update the `git remote` url.
```sh
git remote set-url origin https://firefish.dev/firefish/firefish.git
```
## For systemd/pm2 users
### 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:
@ -185,6 +189,6 @@ A new setting item has been added to control the log levels, so please consider
pnpm install
```
## For Docker/Podman users
### For Docker/Podman users
- The image tag has been changed to `registry.firefish.dev/firefish/firefish:latest`, so please update `docker-compose.yml`.

41
docs/upgrade.md Normal file
View file

@ -0,0 +1,41 @@
# Upgrade instruction
## For systemd/pm2 users
1. Check [`docs/notice-for-admins.md`](./notice-for-admins.md)
1. Stop the server
```sh
sudo systemctl stop your-firefish-service.service
# or pm2 stop firefish
```
1. Pull the latest source code
```sh
git checkout -- packages/backend/assets
git pull --ff origin main
```
1. Build Firefish and apply changes to the database
```sh
corepack prepare pnpm@latest --activate
pnpm install --frozen-lockfile
NODE_ENV='production' NODE_OPTIONS='--max_old_space_size=3072' pnpm run rebuild
pnpm run migrate
```
1. Start the server
```sh
sudo systemctl start your-firefish-service.service
# or pm2 start firefish
```
## For Docker/Podman users
1. Check [`docs/notice-for-admins.md`](./notice-for-admins.md)
1. Pull the latest container image
```sh
docker pull registry.firefish.dev/firefish/firefish:latest
# or podman pull registry.firefish.dev/firefish/firefish:latest
```
1. Start the container
```sh
docker compose up --detach
# or podman-compose up --detach
```

13
firefish.apache.conf
View file

@ -1,13 +0,0 @@
# Replace example.tld with your domain
<VirtualHost *:80>
ServerName example.tld
# For WebSocket
ProxyPass "/streaming" "ws://127.0.0.1:3000/streaming/"
# Proxy to Node
ProxyPass "/" "http://127.0.0.1:3000/"
ProxyPassReverse "/" "http://127.0.0.1:3000/"
ProxyPreserveHost On
# For files proxy
AllowEncodedSlashes On
</VirtualHost>

294
flake.lock
View file

@ -1,294 +0,0 @@
{
"nodes": {
"devenv": {
"inputs": {
"flake-compat": "flake-compat",
"nix": "nix",
"nixpkgs": "nixpkgs",
"pre-commit-hooks": "pre-commit-hooks"
},
"locked": {
"lastModified": 1685521914,
"narHash": "sha256-0fdFP5IASLwJ0PSXrErW8PZon9TVYmi8VRF8OtjGkV4=",
"owner": "cachix",
"repo": "devenv",
"rev": "e206d8f2e3e8d6aa943656052f15bdfea8146b8d",
"type": "github"
},
"original": {
"owner": "cachix",
"repo": "devenv",
"type": "github"
}
},
"fenix": {
"inputs": {
"nixpkgs": [
"nixpkgs"
],
"rust-analyzer-src": "rust-analyzer-src"
},
"locked": {
"lastModified": 1685514167,
"narHash": "sha256-urRxF0ZGSNeZjM4kALNg3wTh7fBscbqQmS6S/HU7Wms=",
"owner": "nix-community",
"repo": "fenix",
"rev": "3abfea51663583186f687c49a157eab1639349ca",
"type": "github"
},
"original": {
"owner": "nix-community",
"repo": "fenix",
"type": "github"
}
},
"flake-compat": {
"flake": false,
"locked": {
"lastModified": 1673956053,
"narHash": "sha256-4gtG9iQuiKITOjNQQeQIpoIB6b16fm+504Ch3sNKLd8=",
"owner": "edolstra",
"repo": "flake-compat",
"rev": "35bb57c0c8d8b62bbfd284272c928ceb64ddbde9",
"type": "github"
},
"original": {
"owner": "edolstra",
"repo": "flake-compat",
"type": "github"
}
},
"flake-parts": {
"inputs": {
"nixpkgs-lib": "nixpkgs-lib"
},
"locked": {
"lastModified": 1685457039,
"narHash": "sha256-bEFtQm+YyLxQjKQAaBHJyPN1z2wbhBnr2g1NJWSYjwM=",
"owner": "hercules-ci",
"repo": "flake-parts",
"rev": "80717d11615b6f42d1ad2e18ead51193fc15de69",
"type": "github"
},
"original": {
"owner": "hercules-ci",
"repo": "flake-parts",
"type": "github"
}
},
"flake-utils": {
"locked": {
"lastModified": 1667395993,
"narHash": "sha256-nuEHfE/LcWyuSWnS8t12N1wc105Qtau+/OdUAjtQ0rA=",
"owner": "numtide",
"repo": "flake-utils",
"rev": "5aed5285a952e0b949eb3ba02c12fa4fcfef535f",
"type": "github"
},
"original": {
"owner": "numtide",
"repo": "flake-utils",
"type": "github"
}
},
"gitignore": {
"inputs": {
"nixpkgs": [
"devenv",
"pre-commit-hooks",
"nixpkgs"
]
},
"locked": {
"lastModified": 1660459072,
"narHash": "sha256-8DFJjXG8zqoONA1vXtgeKXy68KdJL5UaXR8NtVMUbx8=",
"owner": "hercules-ci",
"repo": "gitignore.nix",
"rev": "a20de23b925fd8264fd7fad6454652e142fd7f73",
"type": "github"
},
"original": {
"owner": "hercules-ci",
"repo": "gitignore.nix",
"type": "github"
}
},
"lowdown-src": {
"flake": false,
"locked": {
"lastModified": 1633514407,
"narHash": "sha256-Dw32tiMjdK9t3ETl5fzGrutQTzh2rufgZV4A/BbxuD4=",
"owner": "kristapsdz",
"repo": "lowdown",
"rev": "d2c2b44ff6c27b936ec27358a2653caaef8f73b8",
"type": "github"
},
"original": {
"owner": "kristapsdz",
"repo": "lowdown",
"type": "github"
}
},
"nix": {
"inputs": {
"lowdown-src": "lowdown-src",
"nixpkgs": [
"devenv",
"nixpkgs"
],
"nixpkgs-regression": "nixpkgs-regression"
},
"locked": {
"lastModified": 1676545802,
"narHash": "sha256-EK4rZ+Hd5hsvXnzSzk2ikhStJnD63odF7SzsQ8CuSPU=",
"owner": "domenkozar",
"repo": "nix",
"rev": "7c91803598ffbcfe4a55c44ac6d49b2cf07a527f",
"type": "github"
},
"original": {
"owner": "domenkozar",
"ref": "relaxed-flakes",
"repo": "nix",
"type": "github"
}
},
"nixpkgs": {
"locked": {
"lastModified": 1678875422,
"narHash": "sha256-T3o6NcQPwXjxJMn2shz86Chch4ljXgZn746c2caGxd8=",
"owner": "NixOS",
"repo": "nixpkgs",
"rev": "126f49a01de5b7e35a43fd43f891ecf6d3a51459",
"type": "github"
},
"original": {
"owner": "NixOS",
"ref": "nixpkgs-unstable",
"repo": "nixpkgs",
"type": "github"
}
},
"nixpkgs-lib": {
"locked": {
"dir": "lib",
"lastModified": 1682879489,
"narHash": "sha256-sASwo8gBt7JDnOOstnps90K1wxmVfyhsTPPNTGBPjjg=",
"owner": "NixOS",
"repo": "nixpkgs",
"rev": "da45bf6ec7bbcc5d1e14d3795c025199f28e0de0",
"type": "github"
},
"original": {
"dir": "lib",
"owner": "NixOS",
"ref": "nixos-unstable",
"repo": "nixpkgs",
"type": "github"
}
},
"nixpkgs-regression": {
"locked": {
"lastModified": 1643052045,
"narHash": "sha256-uGJ0VXIhWKGXxkeNnq4TvV3CIOkUJ3PAoLZ3HMzNVMw=",
"owner": "NixOS",
"repo": "nixpkgs",
"rev": "215d4d0fd80ca5163643b03a33fde804a29cc1e2",
"type": "github"
},
"original": {
"owner": "NixOS",
"repo": "nixpkgs",
"rev": "215d4d0fd80ca5163643b03a33fde804a29cc1e2",
"type": "github"
}
},
"nixpkgs-stable": {
"locked": {
"lastModified": 1678872516,
"narHash": "sha256-/E1YwtMtFAu2KUQKV/1+KFuReYPANM2Rzehk84VxVoc=",
"owner": "NixOS",
"repo": "nixpkgs",
"rev": "9b8e5abb18324c7fe9f07cb100c3cd4a29cda8b8",
"type": "github"
},
"original": {
"owner": "NixOS",
"ref": "nixos-22.11",
"repo": "nixpkgs",
"type": "github"
}
},
"nixpkgs_2": {
"locked": {
"lastModified": 1685399834,
"narHash": "sha256-Lt7//5snriXSdJo5hlVcDkpERL1piiih0UXIz1RUcC4=",
"owner": "nixos",
"repo": "nixpkgs",
"rev": "58c85835512b0db938600b6fe13cc3e3dc4b364e",
"type": "github"
},
"original": {
"owner": "nixos",
"ref": "nixpkgs-unstable",
"repo": "nixpkgs",
"type": "github"
}
},
"pre-commit-hooks": {
"inputs": {
"flake-compat": [
"devenv",
"flake-compat"
],
"flake-utils": "flake-utils",
"gitignore": "gitignore",
"nixpkgs": [
"devenv",
"nixpkgs"
],
"nixpkgs-stable": "nixpkgs-stable"
},
"locked": {
"lastModified": 1682596858,
"narHash": "sha256-Hf9XVpqaGqe/4oDGr30W8HlsWvJXtMsEPHDqHZA6dDg=",
"owner": "cachix",
"repo": "pre-commit-hooks.nix",
"rev": "fb58866e20af98779017134319b5663b8215d912",
"type": "github"
},
"original": {
"owner": "cachix",
"repo": "pre-commit-hooks.nix",
"type": "github"
}
},
"root": {
"inputs": {
"devenv": "devenv",
"fenix": "fenix",
"flake-parts": "flake-parts",
"nixpkgs": "nixpkgs_2"
}
},
"rust-analyzer-src": {
"flake": false,
"locked": {
"lastModified": 1685465261,
"narHash": "sha256-aJ2nUinUrNcFi+pb47bS5IIAeSiUEEPLJY8W4Q8Pcjk=",
"owner": "rust-lang",
"repo": "rust-analyzer",
"rev": "d2b3caa5b5694125fad04a9699e919444439f6a2",
"type": "github"
},
"original": {
"owner": "rust-lang",
"ref": "nightly",
"repo": "rust-analyzer",
"type": "github"
}
}
},
"root": "root",
"version": 7
}

86
flake.nix
View file

@ -1,86 +0,0 @@
{
description = "Firefish development flake";
inputs = {
nixpkgs.url = "github:nixos/nixpkgs/nixpkgs-unstable";
# Flake Parts framework(https://flake.parts)
flake-parts.url = "github:hercules-ci/flake-parts";
# Devenv for better devShells(https://devenv.sh)
devenv.url = "github:cachix/devenv";
# Fenix for rust development
fenix.url = "github:nix-community/fenix";
fenix.inputs.nixpkgs.follows = "nixpkgs";
};
outputs = inputs@{ flake-parts, ... }:
flake-parts.lib.mkFlake { inherit inputs; } {
imports = [
inputs.devenv.flakeModule
];
# Define the systems that this works on. Only tested with x66_64-linux, add more if you test and it works.
systems = [
"x86_64-linux"
];
# Expose these attributes for every system defined above.
perSystem = { config, pkgs, ... }: {
# Devenv shells
devenv = {
shells = {
# The default shell, used by nix-direnv
default = {
name = "firefish-dev-shell";
# Add additional packages to our environment
packages = [
pkgs.nodePackages.pnpm
pkgs.python3
];
# No need to warn on a new version, we'll update as needed.
devenv.warnOnNewVersion = false;
# Enable typescript support
languages.typescript.enable = true;
# Enable javascript for NPM and PNPM
languages.javascript.enable = true;
languages.javascript.package = pkgs.nodejs_18;
# Enable stable Rust for the backend
languages.rust.enable = true;
languages.rust.version = "stable";
processes = {
dev-server.exec = "pnpm run dev";
};
scripts = {
build.exec = "pnpm run build";
clean.exec = "pnpm run clean";
clear-state.exec = "rm -rf .devenv/state/redis .devenv/state/postgres";
format.exec = "pnpm run format";
install-deps.exec = "pnpm install";
migrate.exec = "pnpm run migrate";
prepare-config.exec = "cp .config/devenv.yml .config/default.yml";
};
services = {
postgres = {
enable = true;
package = pkgs.postgresql_12;
initialDatabases = [{
name = "firefish";
}];
initialScript = ''
CREATE USER firefish WITH PASSWORD 'firefish';
ALTER USER firefish WITH SUPERUSER;
GRANT ALL ON DATABASE firefish TO firefish;
'';
listen_addresses = "127.0.0.1";
port = 5432;
};
redis = {
enable = true;
bind = "127.0.0.1";
port = 6379;
};
};
};
};
};
};
};
}

6
package.json
View file

@ -19,10 +19,10 @@
"gulp": "gulp build",
"watch": "pnpm run dev",
"dev": "pnpm node ./scripts/dev.mjs",
"dev:up": "pnpm node ./scripts/dev-up.mjs",
"dev:down": "pnpm node ./scripts/dev-down.mjs",
"dev:init": "pnpm run dev:down && pnpm run dev:up",
"dev:staging": "NODE_OPTIONS=--max_old_space_size=3072 NODE_ENV=development pnpm run build && pnpm run start",
"db:up": "pnpm node ./scripts/db-up.mjs",
"db:down": "pnpm node ./scripts/db-down.mjs",
"db:init": "pnpm run dev:down && pnpm run dev:up",
"lint": "pnpm -r --parallel run lint",
"debug": "pnpm run build:debug && pnpm run start",
"build:debug": "pnpm run clean && pnpm node ./scripts/dev-build.mjs && pnpm run gulp",

2
scripts/dev-down.mjs → scripts/db-down.mjs
View file

@ -6,7 +6,7 @@ import { execa } from "execa";
const __dirname = path.dirname(fileURLToPath(import.meta.url));
execa("podman-compose", ["down"], {
cwd: join(__dirname, "/../dev"),
cwd: join(__dirname, "/../dev/db-container"),
stdio: "inherit",
});
})();

2
scripts/dev-up.mjs → scripts/db-up.mjs
View file

@ -6,7 +6,7 @@ import { execa } from "execa";
const __dirname = path.dirname(fileURLToPath(import.meta.url));
execa("podman-compose", ["up", "--detach"], {
cwd: join(__dirname, "/../dev"),
cwd: join(__dirname, "/../dev/db-container"),
stdio: "inherit",
});
})();