diff --git a/.config/example.yml b/.config/example.yml index 43f6d7e923..678f9641c9 100644 --- a/.config/example.yml +++ b/.config/example.yml @@ -44,8 +44,8 @@ db: db: firefish # Auth - user: example-firefish-user - pass: example-firefish-pass + user: firefish + pass: password # Whether disable Caching queries #disableCache: true @@ -77,9 +77,9 @@ redis: # A Redis-compatible server (DragonflyDB, Keydb, Redis) for caching # If left blank, it will use the Redis server from above -#cacheServer: - #host: localhost - #port: 6379 +cacheServer: + host: localhost + port: 6380 #family: 0 # 0=Both, 4=IPv4, 6=IPv6 #pass: example-pass #prefix: example-prefix @@ -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' #] diff --git a/README.md b/README.md index 6edbd5efbd..af2d77be1e 100644 --- a/README.md +++ b/README.md @@ -31,6 +31,14 @@ Firefish is based off of Misskey, a powerful microblogging server on ActivityPub - Official account: `@firefish@info.firefish.dev` - Weblate: +# Release cycle + +We use a rolling release cycle now. Small updates will be frequently merged into the main branch, so please upgrade regularly at your convenience. We will use the commit date (e.g., 20240206) as the version number. + +Any special operations required for an upgrade (e.g., installing new dependencies, editing docker-compose.yml) will be noted on [docs/notice-for-admins.md](docs/notice-for-admins.md) , so please check it before upgrading. + +**As always, please take a backup first before starting update.** Whether it is a server snapshot backup or a complete database and file backup, it will be of great help to your recovery process. + # Getting started This guide will work for both **starting from scratch** and **migrating from Misskey**. @@ -46,14 +54,18 @@ If you have access to a server that supports one of the sources below, I recomme - [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 +## Install Production Environment + +For install production environment details, read [this document](https://firefish.dev/firefish/firefish/-/blob/develop/docs/install.md). + +## Software Dependencies - At least [NodeJS](https://nodejs.org/en/) v18.16.0 (v20/v21 recommended) -- At least [PostgreSQL](https://www.postgresql.org/) v12 (v16 recommended) +- At least [PostgreSQL](https://www.postgresql.org/) v12 (v16 recommended) with [PGroonga](https://pgroonga.github.io/) extension - At least [Redis](https://redis.io/) v7 - Web Proxy (one of the following) + - Caddy (recommended for new users) - Nginx (recommended) - - Caddy (recommended) - Apache ### Optional dependencies @@ -72,156 +84,6 @@ If you have access to a server that supports one of the sources below, I recomme - `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 diff --git a/dev/README.md b/dev/README.md new file mode 100644 index 0000000000..9da0fc0946 --- /dev/null +++ b/dev/README.md @@ -0,0 +1,27 @@ +# Firefish Developers' Corner + +## Changelog + +You can find more about software change [here](../docs/changelog.md), and API change [here](../docs/api-change.md). + +## API documentation + +You can find interactive API documentation at any Firefish instance /api-doc endpoint. By the way, API console can be found at /api-console endpoint. + +You can also find more about firefish-js [here](../packages/firefish-js/README.md). + +## Environment build + +We support multiple methods to build a development environment, and you can choose the method you like. + +### Containerized Environment + +You can find documentation at [Here](docker/README.md). + +### Containerized Database Environment + +You can find documentation at [Here](docker-dbonly/README.md). + +### Manually Make Development Environment + +You can find documentation at [Here](manually/README.md). diff --git a/dev/docker/README.md b/dev/docker/README.md index 79288c12b2..4a7f15822d 100644 --- a/dev/docker/README.md +++ b/dev/docker/README.md @@ -19,7 +19,7 @@ The Firefish repo comes with a new containerized environment to help make develo 1. Run `docker compose up`. This will build the environment, 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 ``` diff --git a/dev/manually/README.md b/dev/manually/README.md new file mode 100644 index 0000000000..8a5fe70f82 --- /dev/null +++ b/dev/manually/README.md @@ -0,0 +1,184 @@ +# Manually Make Development Environment + +For scenarios with special needs, you may want to manually create a development environment. Hope this article can help you. + +## Introduction + +This article is written based on the Debian Bookworm. Other systems can refer to this article for deployment. However, it is recommended that new users use the same system or Docker environment as ours to avoid wasting time on environment configuration issues. + +The versions of Node.js, Rust, PostgreSQL, DragonflyDB that come with Debian Bookworm are low or not have, the latest official versions of these components are used to install them. Other components are installed using the apt package manager that comes with the system. + +## Allow `sudo` command + +```sh +su - +apt install -y -V sudo +# user is your username +usermod -aG sudo user +reboot +``` + +## Install Base Requirements + +```sh +sudo apt update +sudo apt install -y -V wget curl git ca-certificates +``` + +## Install Node.js + +The latest version at the time of writing is v21.6.2. Please replace it with the latest Node.js version number during installation. Details can be found in [nodejs.org](https://nodejs.org) . + +1. Download and extract. + +```sh +VERSION=v21.6.2 +DISTRO=linux-x64 +sudo mkdir -p /usr/local/lib/nodejs +wget https://nodejs.org/dist/v21.6.2/node-$VERSION-$DISTRO.tar.xz +sudo tar -xJvf node-$VERSION-$DISTRO.tar.xz -C /usr/local/lib/nodejs +``` + +2. Open your `.profile` and `/root/.profile` files. + +```sh +nano ~/.profile +sudo nano /root/.profile +``` + +3. Add below content at below of this two file to set the environment variable. + +```sh +# Nodejs +VERSION=v21.6.2 +DISTRO=linux-x64 +export PATH=/usr/local/lib/nodejs/node-$VERSION-$DISTRO/bin:$PATH +``` + +4. Refresh `PATH` and test. + +```sh +. ~/.profile +node -v +# Switching to root +sudo -i +. ~/.profile +node -v +exit +``` + +## Install Rust + +1. Running this script and choose "Proceed with installation" option. + +```sh +curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh +. ~/.profile +cargo -V +``` + +## Install PostgreSQL with PGroonga extension + +```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 -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 +echo "deb http://apt.postgresql.org/pub/repos/apt/ $(lsb_release --codename --short)-pgdg main" | sudo tee /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 -y -V postgresql-16-pgdg-pgroonga +``` + +## Configuration PostgreSQL + +1. Execute this to running `psql` as `postgres` user. + +```sh +sudo -u postgres psql +``` + +2. Create Firefish database, user and PGroonga extension. **Please change the password.** + +```sql +CREATE DATABASE firefish_db WITH ENCODING = 'UTF8'; +\connect firefish_db +CREATE EXTENSION IF NOT EXISTS pgroonga; +CREATE USER firefish WITH PASSWORD 'password'; +ALTER USER firefish WITH SUPERUSER; +GRANT ALL ON DATABASE firefish_db TO firefish; +``` + +3. Run `exit` to return. + +## Install Redis, Python 3 and build-essential + +```sh +sudo apt update +sudo apt install -y -V redis python3 build-essential +``` + +## Download and configuration Firefish + +1. Download Firefish and Copy example configuration file. + +```sh +# cd /path/to/your/firefish +git clone https://firefish.dev/firefish/firefish.git +cd firefish/ +cp .config/devenv.yml .config/default.yml +sed -i "s/host: firefish_db/host: localhost/" .config/default.yml +sed -i "s/host: firefish_redis/host: localhost/" .config/default.yml +``` + +2. Open your `default.yml` files and make changes like `URL`, `db/host` `redis/host`. + +```sh +nano .config/default.yml +``` + +## Install package + +1. Let corepack enable. + +```sh +# Switching to root +sudo -i +# cd /path/to/your/firefish +cd /home/user/firefish +corepack enable +exit +``` + +2. Install dependency. + +```sh +corepack prepare pnpm@latest --activate +pnpm install --frozen-lockfile --prod false +``` + +## Start + +1. Build and migrate + +```sh +pnpm install --prod false +NODE_ENV=production +pnpm run build:debug +pnpm run migrate +``` + +2. Start Firefish + +```sh +pnpm run start +``` + +2. 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 +``` + +3. A fresh Firefish environment is created on the URL you have set! diff --git a/docs/development.md b/docs/development.md deleted file mode 100644 index 0ff66c4970..0000000000 --- a/docs/development.md +++ /dev/null @@ -1,11 +0,0 @@ -# Firefish Developer Docs - -We support multiple methods to build a development environment, and you can choose the method you like. - -## Containerized Environment - -You can find documentation at [Here](../dev/docker/README.md). - -## Containerized Database Environment - -You can find documentation at [Here](../dev/docker-dbonly/README.md). diff --git a/docs/docker.md b/docs/docker.md index 2b8667d1e1..569c6a6c7c 100644 --- a/docs/docker.md +++ b/docs/docker.md @@ -1,15 +1,27 @@ # Running a Firefish server with Docker +## Prerequisites + +- Latest [Docker](https://docs.docker.com/get-docker/) installation + - Alternatively, you can use [Podman](https://podman.io/docs/installation) and [Podman Compose](https://github.com/containers/podman-compose). +- The following ports are not in use + - 80 + - 443 + - 3000 + - 5432 + - 6379 + ## Pre-built docker container + [registry.firefish.dev/firefish/firefish](https://firefish.dev/firefish/firefish/container_registry) -## `docker-compose` +## Config files There are example config files that you can use to build the container from source - docker-compose.example.yml (**compose file**) - .config/docker_example.env (**db config settings**) -- .config/default.yml (**firefish server settings**) +- .config/default.yml (**Firefish server settings**) ## Configuring @@ -23,20 +35,51 @@ 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 +## Running 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. -Copy `docker-compose.yml` and the `config/` to a directory, then run the **docker-compose** command: -`docker-compose up -d`. +Copy `docker-compose.yml` and the `config/` to a directory, then run the **docker compose** command: `docker compose up -d` . + - If you use Podman, you should run `podman-compose up` instead. 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). + +## Install reverse proxy + +### Caddy (recommended for new users) + +- 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 + +### 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. + +### 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 diff --git a/docs/install.md b/docs/install.md new file mode 100644 index 0000000000..c4cbdf7801 --- /dev/null +++ b/docs/install.md @@ -0,0 +1,282 @@ +# Install Production Environment + +Hope this article can help you about install production environment. + +## Introduction + +This article is written based on the Debian Bookworm. Other systems can refer to this article for deployment. However, it is recommended that new users use the same system or Docker environment as ours to avoid wasting time on environment configuration issues. + +The versions of Node.js, Rust, PostgreSQL that come with Debian Bookworm are low, the latest official versions of these components are used to install them. Other components are installed using the apt package manager that comes with the system. + +## Allow `sudo` command + +```sh +su - +apt install -y -V sudo +# user is your username +usermod -aG sudo user +reboot +``` + +## Install Base Requirements + +```sh +sudo apt update +sudo apt install -y -V wget curl git ca-certificates +``` + +## Install Node.js + +The latest version at the time of writing is v21.6.2. Please replace it with the latest Node.js version number during installation. Details can be found in [nodejs.org](https://nodejs.org) . + +1. Download and extract. + +```sh +VERSION=v21.6.2 +DISTRO=linux-x64 +sudo mkdir -p /usr/local/lib/nodejs +wget https://nodejs.org/dist/v21.6.2/node-$VERSION-$DISTRO.tar.xz +sudo tar -xJvf node-$VERSION-$DISTRO.tar.xz -C /usr/local/lib/nodejs +``` + +2. Open your `.profile` and `/root/.profile` files. + +```sh +nano ~/.profile +sudo nano /root/.profile +``` + +3. Add below content at below of this two file to set the environment variable. + +```sh +# Nodejs +VERSION=v21.6.2 +DISTRO=linux-x64 +export PATH=/usr/local/lib/nodejs/node-$VERSION-$DISTRO/bin:$PATH +``` + +4. Refresh `PATH` and test. + +```sh +. ~/.profile +node -v +# Switching to root +sudo -i +. ~/.profile +node -v +exit +``` + +## Install Rust + +1. Running this script and choose "Proceed with installation" option. + +```sh +curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh +. ~/.profile +cargo -V +``` + +## Install PostgreSQL with PGroonga extension + +```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 -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 +echo "deb http://apt.postgresql.org/pub/repos/apt/ $(lsb_release --codename --short)-pgdg main" | sudo tee /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 -y -V postgresql-16-pgdg-pgroonga +``` + +## Configuration PostgreSQL + +1. Execute this to running `psql` as `postgres` user. + +```sh +sudo -u postgres psql +``` + +2. Create Firefish database, user and PGroonga extension. **Please change the password.** + +```sql +CREATE DATABASE firefish WITH ENCODING = 'UTF8'; +\connect firefish +CREATE EXTENSION IF NOT EXISTS pgroonga; +CREATE USER firefish WITH PASSWORD 'password'; +ALTER USER firefish WITH SUPERUSER; +GRANT ALL ON DATABASE firefish TO firefish; +``` + +3. Run `exit` to return. + +## Install DragonflyDB (Cache) + +```sh +wget https://dragonflydb.gateway.scarf.sh/latest/dragonfly_amd64.deb +sudo dpkg -i dragonfly_amd64.deb +``` + +## Configuration DragonflyDB + +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. + +1. Open your `dragonfly.conf` files. + +```sh +sudo nano /etc/dragonfly/dragonfly.conf +``` + +2. Add content at below of this file to set the different port variable because default port is 6379. + +```conf +--port=6380 +``` + +3. Run `sudo systemctl restart dragonfly` to restart it. + +## Install Caddy, Redis, Python 3 and build-essential + +If you already have experience using nginx, you can consider replacing caddy with nginx here. + +```sh +sudo apt update +sudo apt install -y -V caddy redis python3 build-essential +``` + +## Configuration Caddy + +If you replaced nginx in the previous step, please refer to the "Other reverse proxy server" chapter in the document for configuration. + +1. Run this to modify caddy configuration. + +```sh +sudo nano /etc/caddy/Caddyfile +``` + +2. Add this below, should change `example.tld` to your domain. + +```conf +example.tld { + reverse_proxy http://127.0.0.1:3000 +} +``` + +3. Running `sudo ystemctl restart caddy` to apply. + +## Download and configuration Firefish + +1. Download Firefish and Copy example configuration file. + +```sh +# cd /path/to/your/firefish +git clone https://firefish.dev/firefish/firefish.git +cd firefish/ +git checkout main +cp .config/example.yml .config/default.yml +``` + +> **Note** +> By default, you're on the develop branch. Run `git checkout main` to switch to the Main branch. + +2. Open your `default.yml` files and make changes like `URL`, `db` and `reservedUsernames`. + +```sh +nano .config/default.yml +``` + +## Install Firefish + +**run these steps to update Firefish in the future!** + +1. Let corepack enable. + +```sh +# Switching to root +sudo -i +# cd /path/to/your/firefish +cd /home/user/firefish +npm i -g pm2 +corepack enable +exit +``` + +2. Install dependency. + +```sh +corepack prepare pnpm@latest --activate +pnpm install --frozen-lockfile --prod false +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. + +3. Build and migrate + +```sh +pnpm install --prod false +NODE_ENV=production pnpm run build && pnpm run migrate +``` + +4. Start Firefish + +```sh +pm2 start "NODE_ENV=production pnpm run start" --name Firefish +pm2 logs Firefish +``` + +5. Wait until the following message shows up. + +```log +1|Firefish | DONE * [core boot] All workers started +1|Firefish | DONE * [core boot] Now listening on port 3000 on https://your_firefish_url.example.com (default value: https://localhost:3000) +``` + +6. A fresh Firefish environment is created on the URL you have set! + +7. By the way, Please use content at below to generate vapid keys to enable Push-Notifications. + +```sh +# Switching to root +sudo -i +npm install -g web-push +web-push generate-vapid-keys +exit +``` + +## 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`. + +## Other reverse proxy server + +### Nginx + +- 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. + +## 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 diff --git a/firefish.apache.conf b/firefish.apache.conf deleted file mode 100644 index b0c69d51df..0000000000 --- a/firefish.apache.conf +++ /dev/null @@ -1,13 +0,0 @@ -# Replace example.tld with your domain - - - 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 - \ No newline at end of file