A fun, new, open way to experience social media
Go to file
naskya 72be21467b
2024-02-21 18:11:38 +09:00
.config Update example.yml (add signTo ActivityPubGet: true) 2023-10-24 05:15:19 +00:00
.gitlab fix: replace urls to git.joinfirefish.org with firefish.dev 2024-02-14 13:44:11 +00:00
.vscode chore: update VSCode settings 2024-02-12 17:13:17 +00:00
chart docs: repo move (wip) 2024-02-06 15:38:03 +09:00
custom refactor: 🍱 use webp for error images instead of avif 2023-09-25 20:57:14 -07:00
dev dev: add scripts to prepare dev environment 2024-02-12 02:23:25 +09:00
docs v20240221-1 2024-02-21 18:11:38 +09:00
locales chore: Merge branch 'origin/develop' into Weblate. 2024-02-21 06:25:35 +01:00
packages fix (client): undefined locale 2024-02-21 18:02:13 +09:00
scripts dev: add script to regenerate sea-orm entities 2024-02-21 05:56:43 +09:00
.dockerignore chore (container): dockerignore more files 2024-02-13 01:50:15 +09:00
.envrc Fixed dev enviroment _> documented procedure 2023-05-31 13:52:21 +02:00
.gitignore dev: add scripts to prepare dev environment 2024-02-12 02:23:25 +09:00
.weblate we be renamin 2023-07-15 14:21:17 -07:00
CODE_OF_CONDUCT.md v1.0.1 2023-07-19 15:20:22 -07:00
CONTRIBUTING.md docs: fix ordered list 2024-02-11 17:25:16 +00:00
COPYING feat: Implement module player 2023-09-22 03:48:54 +00:00
Dockerfile chore (container): update Dockerfile 2024-02-15 14:02:31 +09:00
README.md docs: 📑 fewer emojis and badges 2024-02-15 15:15:55 +09:00
SECURITY.md v1.0.1 2023-07-19 15:20:22 -07:00
animated.svg docs: 🚚 new website 2023-07-19 10:06:57 -07:00
biome.json build: ♻️ Rome -> Biome 2023-09-01 21:16:14 -07:00
cliff.toml docs: 📝 1.0.3 changelog 2023-07-25 23:31:03 -07:00
docker-compose.yml docs: repo move (wip) 2024-02-06 15:38:03 +09:00
firefish.apache.conf we be renamin 2023-07-15 14:21:17 -07:00
firefish.nginx.conf we be renamin 2023-07-15 14:21:17 -07:00
flake.lock Fixed dev enviroment _> documented procedure 2023-05-31 13:52:21 +02:00
flake.nix find and replace 2023-07-02 15:18:30 -07:00
gulpfile.js refactor: make `client` and `sw` ES modules 2024-02-16 09:31:32 +08:00
package.json v20240221-1 2024-02-21 18:11:38 +09:00
patrons.json chore: 👥 calckey.social -> firefish.social 2023-07-30 13:11:48 -07:00
pnpm-lock.yaml chore: update dependencies 2024-02-20 17:45:48 +09:00
pnpm-workspace.yaml meta: backend/native-utils -> backend-rs 2024-02-12 23:14:23 +09:00
release.json links 2023-07-19 08:58:59 -07:00
title.svg docs: 🚚 new website 2023-07-19 10:06:57 -07:00


Firefish logo

🌎 Firefish is an open source, decentralized social media platform that's free forever! 🚀

Firefish is based off of Misskey, a powerful microblogging server on ActivityPub with features such as emoji reactions, a customizable web UI, rich chatting, and much more!


Want to get involved? Great!

  • If you have the means to, donations are a great way to keep us going.
  • If you know how to program in TypeScript, Vue, or Rust, read the contributing document.
  • If you know a non-English language, translating Firefish on Weblate help bring Firefish to more people. No technical experience needed!

Getting started

This guide will work for both starting from scratch and migrating from Misskey.



  • At least NodeJS v18.16.0 (v20/v21 recommended)
  • At least PostgreSQL v12 (v16 recommended)
  • At least Redis v7
  • Web Proxy (one of the following)
    • Nginx (recommended)
    • Caddy (recommended)
    • Apache

Optional dependencies

Build dependencies

  • At least Rust v1.74
  • C/C++ compiler & build tools
    • build-essential on Debian/Ubuntu Linux
    • base-devel on Arch Linux
  • Python 3

Get folder ready

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

# nvm install 19 && nvm use 19
sudo corepack enable
corepack prepare pnpm@latest --activate
pnpm install --frozen-lockfile


To install pm2 run:

npm i -g pm2
pm2 install pm2-logrotate

Note pm2-logrotate 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:

CREATE DATABASE firefish WITH encoding = 'UTF8';

or run the following from the command line:

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.


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

Note If you use IPv4: in Sonic's directory, edit the config.cfg file to change inet to "".

In Firefish's directory, fill out the sonic section of .config/default.yml with the correct information.


Meilisearch is better suited for larger deployments. It's faster but uses far more resources and disk space.

Follow Meilisearch's quick start guide

In Firefish's directory, fill out the meilisearch section of .config/default.yml with the correct information.


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.


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

Web proxy

  • 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.
  • Add the following block to your Caddyfile, replacing example.tld with your own domain:
example.tld {
  • Reload your caddy configuration


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!

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