Skip to content
Klutch.sh Docs

Deploying Firefish

Introduction

Firefish is a powerful, open-source federated social network platform built on ActivityPub, offering a modern alternative to centralized social media. As a fork of Misskey, Firefish provides robust features for creating decentralized communities with support for custom emojis, rich text formatting, polls, and seamless federation with other ActivityPub platforms like Mastodon and Pleroma.

Deploying Firefish on Klutch.sh gives you enterprise-grade infrastructure with automatic HTTPS, scalable compute resources, and simplified container management. This comprehensive guide walks you through deploying Firefish using a Dockerfile, configuring persistent storage for media and database files, setting up Redis and PostgreSQL databases, and implementing production-ready security practices.

Whether you’re launching a personal instance or building a social network for your community, this guide provides everything you need to get Firefish running reliably on Klutch.sh with minimal configuration overhead.

Prerequisites

Before you begin deploying Firefish on Klutch.sh, ensure you have:

  • A Klutch.sh account (sign up here)
  • A GitHub repository for your Firefish project (you can fork the official Firefish repository)
  • Basic understanding of Docker, PostgreSQL, and Redis
  • A PostgreSQL database instance (version 12 or higher recommended)
  • A Redis instance for caching and job queues
  • Domain name (optional, for custom domain configuration)

Understanding Firefish Architecture

Firefish consists of several key components:

  • Web Server: Node.js application serving the web interface and API
  • PostgreSQL Database: Stores users, posts, and relational data
  • Redis: Handles caching, real-time updates, and background job queues
  • Object Storage: Stores uploaded media files (local filesystem or S3-compatible storage)

For a production deployment on Klutch.sh, you’ll need to provision separate PostgreSQL and Redis services, which can be deployed as additional apps on the platform.

Sample Dockerfile for Firefish

Klutch.sh automatically detects and uses a Dockerfile when present in the root directory of your repository. Create a Dockerfile in your project root with the following production-ready configuration:

FROM node:20-bullseye-slim


# Set working directory
WORKDIR /firefish


# Install system dependencies
RUN apt-get update && apt-get install -y \
    build-essential \
    python3 \
    ffmpeg \
    git \
    postgresql-client \
    && rm -rf /var/lib/apt/lists/*


# Clone Firefish repository (or copy your files)
# For production, consider using a specific version tag: --branch v1.x.x
RUN git clone --depth=1 https://github.com/firefish-dev/firefish.git . && \
    git submodule update --init --recursive


# Install Node.js dependencies
RUN corepack enable && \
    corepack prepare pnpm@latest --activate && \
    pnpm install --frozen-lockfile


# Build the application
RUN NODE_ENV=production pnpm run build


# Create uploads directory for persistent storage
RUN mkdir -p /firefish/files


# Expose the application port
EXPOSE 3000


# Start Firefish
CMD ["pnpm", "run", "start"]

This Dockerfile:

  • Uses Node.js 20 on Debian Bullseye for stability
  • Installs required system dependencies including FFmpeg for media processing
  • Clones the latest Firefish code (replace with COPY if using your own fork)
  • Builds the application with production optimizations
  • Exposes port 3000 for HTTP traffic
  • Creates a directory for persistent file storage

For advanced customization, you can modify the build command or start command using Nixpacks environment variables:

  • NIXPACKS_BUILD_CMD: Override the build command
  • NIXPACKS_START_CMD: Override the start command

Setting Up Your GitHub Repository

    1. Create or fork the Firefish repository

      Fork the official Firefish repository on GitHub, or create a new repository for your custom deployment.

    2. Add the Dockerfile

      Create the Dockerfile shown above in the root of your repository.

    3. Create a configuration file

      Create a .config/default.yml file for Firefish configuration (this will be overridden by environment variables in production):

    # Basic configuration template
    # Most values will come from environment variables
    url: https://example-app.klutch.sh
    port: 3000
    

    db:
      host: localhost
      port: 5432
      db: firefish
      user: firefish
      pass: your-password
    

    redis:
      host: localhost
      port: 6379
    1. Commit and push your changes
    Terminal window
    git add Dockerfile .config/default.yml
    git commit -m "Add Firefish Dockerfile and configuration"
    git push origin main

Installing Firefish on Klutch.sh

Follow these detailed steps to deploy your Firefish instance on Klutch.sh:

    1. Create a new app in Klutch.sh

      • Navigate to klutch.sh/app
      • Click “Create New App”
      • Connect your GitHub account if you haven’t already
      • Select the repository containing your Firefish Dockerfile

    2. Configure the build settings

      Klutch.sh will automatically detect your Dockerfile in the root directory. You don’t need to manually select Docker as a deployment option—the platform handles this automatically when a Dockerfile is present.

    3. Set up persistent storage

      Firefish requires persistent volumes for storing uploaded media, avatars, and cached files. In the Klutch.sh dashboard:

      • Navigate to the “Volumes” section
      • Click “Add Volume”
      • Set the mount path to /firefish/files
      • Choose a volume size based on your expected media storage needs (start with 10GB minimum)
      • Click “Create Volume”

      Note: You only specify the mount path and size; Klutch.sh automatically manages volume names.

    4. Configure environment variables

      Add the following environment variables in the Klutch.sh app settings. These are essential for Firefish to connect to your database and configure the instance:

      Required Variables:

      • NODE_ENV: production
      • FIREFISH_URL: Your app URL (e.g., https://example-app.klutch.sh)
      • FIREFISH_DB_HOST: Your PostgreSQL host
      • FIREFISH_DB_PORT: 5432 (or your PostgreSQL port)
      • FIREFISH_DB_USER: Your PostgreSQL username
      • FIREFISH_DB_PASS: Your PostgreSQL password (mark as secret)
      • FIREFISH_DB_NAME: firefish
      • FIREFISH_REDIS_HOST: Your Redis host
      • FIREFISH_REDIS_PORT: 6379 (or your Redis port)

      Optional Variables:

      • FIREFISH_REDIS_PASS: Redis password if authentication is enabled
      • FIREFISH_ADMIN_EMAIL: Administrator email for notifications
      • FIREFISH_MAX_NOTE_LENGTH: Maximum post length (default: 3000)

    5. Configure traffic routing

      • In the app settings, select HTTP traffic type (Firefish is a web application)
      • Set the internal port to 3000 (the port Firefish listens on)
      • This tells Klutch.sh to route incoming HTTP traffic to port 3000 inside your container

    6. Deploy the application

      • Review your configuration
      • Click “Deploy” to start the build and deployment process
      • Klutch.sh will build your Docker image and start the container
      • Monitor the build logs to track progress

    7. Initial setup and administration

      Once deployed, access your Firefish instance at the provided URL (e.g., https://example-app.klutch.sh):

      • Complete the initial setup wizard
      • Create your administrator account
      • Configure instance settings (name, description, rules)
      • Customize appearance and branding

Database Configuration

Firefish requires PostgreSQL 12 or higher. You can deploy PostgreSQL on Klutch.sh or use an external managed database service.

Deploying PostgreSQL on Klutch.sh

    1. Create a new app for PostgreSQL using the official PostgreSQL Docker image

    2. Configure the PostgreSQL app:

      • Select TCP traffic type (PostgreSQL uses TCP protocol)
      • Set the internal port to 5432 (PostgreSQL’s default port inside the container)
      • Klutch.sh will expose this on port 8000 for external connections
      • Your Firefish app will connect to PostgreSQL using port 8000
      • Add a persistent volume mounted to /var/lib/postgresql/data (minimum 5GB)

    3. Set PostgreSQL environment variables:

      • POSTGRES_DB: firefish
      • POSTGRES_USER: firefish
      • POSTGRES_PASSWORD: (generate a strong password and mark as secret)

    4. After deployment, use the internal connection details in your Firefish environment variables

Database Initialization

Firefish will automatically initialize the database schema on first run. Monitor the application logs to ensure successful database migration.

Redis Configuration

Redis is essential for Firefish’s real-time features and background job processing.

Deploying Redis on Klutch.sh

    1. Create a new app for Redis using the official Redis Docker image

    2. Configure the Redis app:

      • Select TCP traffic type
      • Set the internal port to 6379 (Redis’s default port inside the container)
      • Klutch.sh will expose this on port 8000 for external connections
      • Your Firefish app will connect to Redis using port 8000
      • Add a persistent volume mounted to /data (2-5GB recommended)

    3. For security, configure Redis authentication by setting:

      • REDIS_PASSWORD: (generate a strong password and mark as secret)

    4. Use the internal connection details in your Firefish configuration

Persistent Storage and Media Management

Firefish stores user-uploaded content including:

  • Profile pictures and banners
  • Post attachments (images, videos, audio)
  • Custom emoji
  • Cached remote media

Configuring Persistent Volumes

In the Klutch.sh dashboard, ensure you have created a volume mounted at /firefish/files as described in the installation steps. This directory must persist across deployments to prevent data loss.

Storage Recommendations

  • Small instances (< 100 users): 10-20GB
  • Medium instances (100-1000 users): 50-100GB
  • Large instances (1000+ users): 200GB+

You can increase volume size at any time through the Klutch.sh dashboard without data loss.

Object Storage (S3-Compatible)

For production deployments with high media storage requirements, consider using S3-compatible object storage:

  1. Configure environment variables for S3:

    • FIREFISH_USE_OBJECT_STORAGE: true
    • FIREFISH_OBJECT_STORAGE_ENDPOINT: Your S3 endpoint
    • FIREFISH_OBJECT_STORAGE_BUCKET: Bucket name
    • FIREFISH_OBJECT_STORAGE_ACCESS_KEY: Access key (mark as secret)
    • FIREFISH_OBJECT_STORAGE_SECRET_KEY: Secret key (mark as secret)

  2. Firefish will automatically upload new media to object storage while keeping local cache

Production Best Practices

Security Hardening

  • Use strong passwords for all database and Redis connections
  • Enable rate limiting in Firefish settings to prevent abuse
  • Configure SMTP for email verification and notifications
  • Set up regular backups of your PostgreSQL database and persistent volumes
  • Keep Firefish updated by regularly rebuilding with the latest version
  • Use environment variables for all secrets—never commit credentials to your repository

Performance Optimization

  • Database connection pooling: Firefish manages this automatically
  • Redis caching: Ensure Redis has sufficient memory (2GB minimum recommended)
  • Media processing: FFmpeg handles image and video optimization
  • CDN integration: Consider using a CDN for media delivery at scale

Monitoring and Maintenance

  • Review application logs regularly through the Klutch.sh dashboard
  • Monitor resource usage (CPU, memory, disk) and scale accordingly
  • Set up health checks to detect and restart failed instances
  • Database maintenance: Perform regular PostgreSQL VACUUM operations
  • Backup strategy: Automate daily backups of PostgreSQL and uploaded media

Scaling Considerations

For high-traffic instances:

  • Scale your PostgreSQL database vertically (more CPU/RAM)
  • Consider Redis clustering for distributed caching
  • Use object storage to offload media serving
  • Implement a CDN for static assets and media delivery

Troubleshooting Common Issues

Application Won’t Start

Symptoms: Container exits immediately or crashes on startup

Solutions:

  • Check that all required environment variables are set correctly
  • Verify database connectivity: FIREFISH_DB_HOST, FIREFISH_DB_PORT, FIREFISH_DB_USER, FIREFISH_DB_PASS
  • Ensure PostgreSQL is running and accessible
  • Review application logs in the Klutch.sh dashboard for specific error messages
  • Confirm the database user has necessary permissions

Database Connection Errors

Symptoms: “Connection refused” or “Authentication failed” errors

Solutions:

  • Verify PostgreSQL is accepting connections on port 8000 (Klutch.sh TCP routing)
  • Check that the internal port for PostgreSQL is set to 5432
  • Confirm database credentials match between Firefish and PostgreSQL environment variables
  • Test database connectivity from the Firefish container using psql

Redis Connection Issues

Symptoms: Real-time features not working, background jobs failing

Solutions:

  • Verify Redis is running and accessible
  • Check FIREFISH_REDIS_HOST and FIREFISH_REDIS_PORT settings
  • If using Redis authentication, ensure FIREFISH_REDIS_PASS is set correctly
  • Test Redis connectivity: redis-cli -h $FIREFISH_REDIS_HOST -p 8000 ping

Media Upload Failures

Symptoms: Users can’t upload images or videos

Solutions:

  • Confirm persistent volume is mounted at /firefish/files
  • Check volume has sufficient free space
  • Verify FFmpeg is installed in the container (included in sample Dockerfile)
  • Review file permission issues in application logs
  • Ensure the upload directory is writable

Performance Issues

Symptoms: Slow page loads, timeouts, high resource usage

Solutions:

  • Increase instance size in Klutch.sh dashboard (more CPU/RAM)
  • Verify Redis is functioning properly for caching
  • Optimize PostgreSQL configuration for your workload
  • Consider enabling object storage for media
  • Review slow query logs in PostgreSQL

Environment Variables Reference

Complete list of Firefish environment variables for Klutch.sh:

VariableRequiredDescriptionExample
NODE_ENVYesNode environmentproduction
FIREFISH_URLYesPublic URLhttps://example-app.klutch.sh
FIREFISH_DB_HOSTYesPostgreSQL hostpostgres-app.klutch.sh
FIREFISH_DB_PORTYesPostgreSQL port8000
FIREFISH_DB_USERYesDatabase userfirefish
FIREFISH_DB_PASSYesDatabase password(secret)
FIREFISH_DB_NAMEYesDatabase namefirefish
FIREFISH_REDIS_HOSTYesRedis hostredis-app.klutch.sh
FIREFISH_REDIS_PORTYesRedis port8000
FIREFISH_REDIS_PASSNoRedis password(secret)
FIREFISH_ADMIN_EMAILNoAdmin emailadmin@example.com
FIREFISH_MAX_NOTE_LENGTHNoMax post length3000
FIREFISH_USE_OBJECT_STORAGENoEnable S3 storagetrue
FIREFISH_OBJECT_STORAGE_ENDPOINTNoS3 endpoints3.amazonaws.com
FIREFISH_OBJECT_STORAGE_BUCKETNoS3 bucketfirefish-media
FIREFISH_OBJECT_STORAGE_ACCESS_KEYNoS3 access key(secret)
FIREFISH_OBJECT_STORAGE_SECRET_KEYNoS3 secret key(secret)

Updating Firefish

To update your Firefish instance to the latest version:

    1. Pull latest changes in your GitHub repository (if using the official repo)
    2. Trigger a rebuild in the Klutch.sh dashboard by pushing a commit or manually triggering a deployment
    3. Review release notes at Firefish Releases for breaking changes
    4. Backup your database before major version upgrades
    5. Monitor deployment logs to ensure successful migration

For custom deployments, update your Dockerfile with the desired Firefish version tag.

Custom Domain Configuration

To use your own domain with Firefish on Klutch.sh:

    1. Add custom domain in the Klutch.sh dashboard (e.g., social.yourdomain.com)
    2. Update DNS records as instructed by Klutch.sh (typically a CNAME or A record)
    3. Update FIREFISH_URL environment variable to match your custom domain
    4. Redeploy the application to apply changes
    5. SSL/TLS certificates are automatically provisioned by Klutch.sh

Federation and ActivityPub

Once deployed, your Firefish instance can federate with other ActivityPub-compatible platforms:

  • Mastodon: Users can follow and interact with Mastodon accounts
  • Pleroma: Full interoperability with Pleroma instances
  • Misskey: Compatible with other Misskey and Misskey-based forks
  • Other platforms: Works with any ActivityPub-compliant service

Configure federation settings in the Firefish admin panel to control:

  • Blocked instances
  • Media proxy settings
  • Federation limits and rate limiting

Resources and Further Reading

Conclusion

Deploying Firefish on Klutch.sh provides a robust, scalable platform for running your own federated social network. With automatic Dockerfile detection, persistent storage, and simplified database management, you can focus on building your community rather than managing infrastructure.

This guide has covered everything from basic deployment to advanced production configurations, security best practices, and troubleshooting. Your Firefish instance on Klutch.sh is now ready to serve your federated social network with enterprise-grade reliability and performance.

For additional support, refer to the official Firefish documentation and Klutch.sh guides linked above. Happy federating!