Skip to content
Klutch.sh Docs

Deploying Fugu

Introduction

Fugu is a powerful open-source team chat and collaboration platform designed for modern teams who need reliable, self-hosted communication tools. Built with scalability and extensibility in mind, Fugu provides real-time messaging, file sharing, channel management, and team collaboration features without the vendor lock-in of proprietary solutions.

Deploying Fugu on Klutch.sh gives you enterprise-grade infrastructure with automatic Docker detection, persistent storage for chat history and files, secure environment variable management, and seamless scaling. Whether you’re running a small team or managing organization-wide communications, this guide will walk you through deploying Fugu with a Dockerfile on Klutch.sh from scratch to production.

This comprehensive guide covers everything you need: installing and setting up Fugu locally, creating a production-ready Dockerfile, configuring persistent volumes for data retention, managing environment variables securely, deploying to Klutch.sh, and following production best practices for reliability and performance.

Prerequisites

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

  • A Klutch.sh account with access to the dashboard
  • A GitHub account and repository for your Fugu project
  • Basic familiarity with Docker, containers, and environment variables
  • (Recommended for production) Access to a managed PostgreSQL or MySQL database
  • Node.js and npm installed locally for development and testing

Getting Started: Installing Fugu Locally

Before deploying to Klutch.sh, it’s helpful to understand how Fugu works by running it locally. This section guides you through installing Fugu, understanding its architecture, and creating a basic setup.

1. Clone and Set Up Fugu

First, create a new directory for your Fugu project and initialize it:

Terminal window
mkdir fugu-app
cd fugu-app
npm init -y

2. Install Fugu Dependencies

Install Fugu and its core dependencies:

Terminal window
npm install fugu-core fugu-server

3. Create a Basic Configuration File

Create a config.json file in your project root with basic settings:

{
  "port": 3000,
  "database": {
    "type": "sqlite",
    "path": "./data/fugu.db"
  },
  "storage": {
    "type": "local",
    "path": "./data/uploads"
  },
  "session": {
    "secret": "your-session-secret-change-this"
  }
}

4. Create a Start Script

Create a start.js file to bootstrap Fugu:

// start.js - Example startup script
// Note: Adjust based on your specific Fugu installation method
const config = require('./config.json');


// Example using Express-based setup
const app = require('./app');


const PORT = config.port || 3000;


app.listen(PORT, '0.0.0.0', () => {
  console.log(`Fugu is running on port ${PORT}`);
});

5. Test Locally

Run Fugu locally to verify everything works:

Terminal window
node start.js

Visit http://localhost:3000 in your browser. You should see the Fugu interface and be able to create an account.

Sample Code: Basic Configuration Example

Here’s a simple example of environment-based configuration:

// config.js - Environment-based configuration
module.exports = {
  port: process.env.PORT || 3000,
  host: process.env.HOST || '0.0.0.0',


  database: {
    type: process.env.DATABASE_TYPE || 'sqlite',
    host: process.env.DATABASE_HOST,
    port: process.env.DATABASE_PORT,
    name: process.env.DATABASE_NAME,
    user: process.env.DATABASE_USER,
    password: process.env.DATABASE_PASSWORD,
  },


  session: {
    secret: process.env.SESSION_SECRET || 'change-this-in-production',
  },


  storage: {
    path: process.env.STORAGE_PATH || '/app/data/uploads',
  }
};

Creating a Production-Ready Dockerfile

Klutch.sh automatically detects a Dockerfile if present in your repository’s root directory. Here’s how to create a production-ready Dockerfile for Fugu.

Basic Dockerfile

Create a Dockerfile in your project root:

# Use official Node.js LTS image
FROM node:18-alpine


# Set working directory
WORKDIR /app


# Copy package files
COPY package*.json ./


# Install dependencies
RUN npm ci --production --no-audit


# Copy application files
COPY . .


# Create data directories
RUN mkdir -p /app/data/uploads /app/data/logs


# Set environment to production
ENV NODE_ENV=production


# Expose Fugu port
EXPOSE 3000


# Health check
HEALTHCHECK --interval=30s --timeout=10s --start-period=40s --retries=3 \
  CMD node -e "require('http').get('http://localhost:3000/health', (r) => {process.exit(r.statusCode === 200 ? 0 : 1)})"


# Start Fugu
CMD ["node", "start.js"]

Advanced Multi-Stage Dockerfile

For optimized production deployments, use a multi-stage build:

# Build stage
FROM node:18-alpine AS builder


WORKDIR /app


# Install build dependencies
COPY package*.json ./
RUN npm ci --include=dev


# Copy source code
COPY . .


# Build Fugu (if applicable)
RUN npm run build || true


# Production stage
FROM node:18-alpine


# Install dumb-init for proper signal handling
RUN apk add --no-cache dumb-init


# Create non-root user
RUN addgroup -g 1001 fugu && \
    adduser -D -u 1001 -G fugu fugu


WORKDIR /app


# Copy package files and install production dependencies
COPY package*.json ./
RUN npm ci --production --no-audit && \
    npm cache clean --force


# Copy built application from builder
COPY --from=builder --chown=fugu:fugu /app .


# Create necessary directories with proper permissions
RUN mkdir -p /app/data/uploads /app/data/logs && \
    chown -R fugu:fugu /app/data


# Switch to non-root user
USER fugu


# Set production environment
ENV NODE_ENV=production


# Expose port
EXPOSE 3000


# Health check
HEALTHCHECK --interval=30s --timeout=10s --start-period=40s --retries=3 \
  CMD node -e "require('http').get('http://localhost:3000/health', (r) => {process.exit(r.statusCode === 200 ? 0 : 1)})"


# Use dumb-init to handle signals properly
ENTRYPOINT ["dumb-init", "--"]


# Start application
CMD ["node", "start.js"]

Dockerfile with Database Support

If using PostgreSQL or MySQL, here’s a configuration-ready Dockerfile:

FROM node:18-alpine


WORKDIR /app


# Install system dependencies
RUN apk add --no-cache \
    postgresql-client \
    mysql-client \
    ca-certificates


COPY package*.json ./
RUN npm ci --production --no-audit


COPY . .


RUN mkdir -p /app/data/uploads /app/data/logs


ENV NODE_ENV=production


EXPOSE 3000


HEALTHCHECK --interval=30s --timeout=10s --start-period=40s --retries=3 \
  CMD node -e "require('http').get('http://localhost:3000/health', (r) => {process.exit(r.statusCode === 200 ? 0 : 1)})"


CMD ["node", "start.js"]

Configuring Persistent Storage

Fugu requires persistent storage for chat messages, uploaded files, user data, and configuration. Without persistent volumes, all data will be lost when the container restarts.

Required Storage Paths

Fugu typically stores data in these locations:

  • /app/data - Main data directory for databases (if using SQLite)
  • /app/data/uploads - User-uploaded files, images, and attachments
  • /app/data/logs - Application logs
  • /app/config - Configuration files (if not using environment variables)

Setting Up Volumes in Klutch.sh

    1. In the Klutch.sh dashboard, navigate to your app settings

    2. Go to the Volumes section

    3. Click Add Volume and configure:

      • Mount Path: /app/data
      • Size: 10GB (adjust based on expected usage)

    4. For larger deployments with many files, add a separate volume for uploads:

      • Mount Path: /app/data/uploads
      • Size: 50GB or more

    5. Save your volume configuration

Volume Configuration Example

When creating your app, you’ll specify mount paths for persistent volumes. Here’s what the configuration looks like:

Mount Path: /app/data
Size: 10GB


Mount Path: /app/data/uploads
Size: 50GB

Important Notes:

  • Volumes persist across deployments and container restarts
  • Data in volumes is not deleted when you update your app
  • Ensure your Dockerfile creates these directories with proper permissions
  • For production, regularly back up your volumes using Klutch.sh’s backup features

Environment Variables Configuration

Fugu requires several environment variables for secure operation. Configure these in the Klutch.sh dashboard before deploying.

Essential Environment Variables

Terminal window
# Application Settings
NODE_ENV=production
PORT=3000
BASE_URL=https://example-app.klutch.sh


# Database Configuration (PostgreSQL example)
DATABASE_TYPE=postgresql
DATABASE_HOST=your-postgres-host.klutch.sh
DATABASE_PORT=5432
DATABASE_NAME=fugu_production
DATABASE_USER=fugu_user
DATABASE_PASSWORD=your-secure-password


# Session Security
SESSION_SECRET=your-long-random-session-secret-change-this
JWT_SECRET=your-long-random-jwt-secret-change-this


# File Storage
STORAGE_TYPE=local
STORAGE_PATH=/app/data/uploads
MAX_FILE_SIZE=10485760


# Email Configuration (for notifications)
SMTP_HOST=smtp.example.com
SMTP_PORT=587
SMTP_USER=notifications@example.com
SMTP_PASSWORD=your-smtp-password
SMTP_FROM=noreply@example.com


# Redis (optional, for scaling)
REDIS_HOST=redis.klutch.sh
REDIS_PORT=6379
REDIS_PASSWORD=your-redis-password


# Security
ENABLE_RATE_LIMITING=true
RATE_LIMIT_WINDOW=900000
RATE_LIMIT_MAX_REQUESTS=100


# Logging
LOG_LEVEL=info
LOG_PATH=/app/data/logs

Database Options

SQLite (Development/Small Teams)

Terminal window
DATABASE_TYPE=sqlite
DATABASE_PATH=/app/data/fugu.db
Terminal window
DATABASE_TYPE=postgresql
DATABASE_HOST=postgres.example.com
DATABASE_PORT=5432
DATABASE_NAME=fugu
DATABASE_USER=fugu_user
DATABASE_PASSWORD=secure_password
DATABASE_SSL=true
DATABASE_POOL_MIN=2
DATABASE_POOL_MAX=10

MySQL

Terminal window
DATABASE_TYPE=mysql
DATABASE_HOST=mysql.example.com
DATABASE_PORT=3306
DATABASE_NAME=fugu
DATABASE_USER=fugu_user
DATABASE_PASSWORD=secure_password

Setting Environment Variables in Klutch.sh

    1. Log in to Klutch.sh dashboard

    2. Navigate to your Fugu app

    3. Go to Settings → Environment Variables

    4. Click Add Variable for each environment variable

    5. Mark sensitive variables (passwords, secrets) as Secret to prevent them from being displayed in logs

    6. Save your configuration

Customizing Build and Start Commands with Nixpacks

If you need to customize Fugu’s build or start behavior, use Nixpacks environment variables:

Terminal window
# Custom build command
BUILD_COMMAND=npm run build && npm run migrate


# Custom start command
START_COMMAND=node --max-old-space-size=2048 start.js


# Install additional dependencies
NIXPACKS_INSTALL_CMD=npm ci && npm install sharp

Deploying to Klutch.sh

Now that you have your Dockerfile, configuration, and environment variables ready, let’s deploy Fugu to Klutch.sh.

Step-by-Step Deployment

    1. Push Your Code to GitHub

      Commit your Dockerfile and application code to your GitHub repository:

      Terminal window
      git init
      git add .
      git commit -m "Initial Fugu setup with Dockerfile"
      git remote add origin https://github.com/yourusername/fugu-app.git
      git push -u origin main

    2. Log in to Klutch.sh

      Visit klutch.sh/app and log in to your account.

    3. Create a New Project

      If you don’t have a project yet:

      • Click Create Project
      • Give it a descriptive name like “Team Communication”
      • Click Create

    4. Create a New App

      • Click Create App or Create a new app
      • Enter your app name (e.g., “fugu-production”)
      • Select your GitHub repository from the list
      • Choose the branch to deploy (e.g., main)

    5. Configure App Settings

      Klutch.sh automatically detects your Dockerfile in the root directory.

      • Traffic Type: Select HTTP (Fugu is a web application)
      • Internal Port: Enter 3000 (the port Fugu listens on inside the container)
      • Region: Choose a region close to your users
      • Compute: Select appropriate resources (minimum 1GB RAM recommended)
      • Instances: Start with 1, scale up as needed

    6. Add Environment Variables

      Go to the Environment Variables section and add all the variables from the previous section. Remember to mark sensitive values as secrets.

    7. Attach Persistent Volumes

      In the Volumes section:

      • Add a volume with mount path /app/data and size 10GB
      • Add another volume with mount path /app/data/uploads and size 50GB

    8. Deploy

      • Review your configuration
      • Click Create to start the deployment
      • Klutch.sh will build your Docker image and deploy your app

    9. Monitor Deployment

      Watch the build logs in real-time. The deployment process includes:

      • Pulling your code from GitHub
      • Building the Docker image from your Dockerfile
      • Creating and attaching volumes
      • Starting the container
      • Health checks

    10. Access Your App

      Once deployed, your Fugu instance will be available at:

      https://example-app.klutch.sh

      Replace example-app with your actual app name.

Verifying the Deployment

After deployment completes:

  1. Visit your app URL in a browser
  2. You should see the Fugu login/signup page
  3. Create an admin account
  4. Test creating a channel and sending messages
  5. Upload a file to verify storage is working
  6. Check the Klutch.sh dashboard for metrics and logs

Production Best Practices

Database Configuration

For production deployments, always use an external database:

  • PostgreSQL (recommended): Offers excellent performance, JSONB support, and full-text search
  • MySQL: Good alternative with wide ecosystem support
  • Deploy your database on Klutch.sh or use a managed service
  • Enable SSL/TLS connections between Fugu and the database
  • Use connection pooling to handle concurrent users efficiently

Security Hardening

    1. Strong Secrets

      • Generate long, random values for SESSION_SECRET and JWT_SECRET
      • Use a password manager or openssl rand -base64 32

    2. HTTPS Only

      • Klutch.sh provides automatic HTTPS for all apps
      • Set BASE_URL to use https://

    3. Rate Limiting

      • Enable rate limiting to prevent abuse
      • Configure appropriate limits based on expected usage

    4. Regular Updates

      • Keep Fugu and dependencies updated
      • Monitor security advisories
      • Use Dependabot or Renovate for automated dependency updates

    5. Access Control

      • Implement strong password policies
      • Enable two-factor authentication if supported
      • Use SSO/SAML for enterprise deployments

Performance Optimization

    1. Redis for Session Storage

      For multi-instance deployments, use Redis:

      Terminal window
      REDIS_HOST=redis.klutch.sh
      REDIS_PORT=6379
      SESSION_STORE=redis

    2. CDN for Static Assets

      Serve uploaded files through a CDN for better performance:

      Terminal window
      STORAGE_TYPE=s3
      S3_BUCKET=fugu-uploads
      S3_REGION=us-east-1
      CDN_URL=https://cdn.example.com

    3. Database Indexing

      Ensure proper indexes on:

      • Message tables (channel_id, created_at)
      • User tables (username, email)
      • Search fields for full-text queries

    4. Horizontal Scaling

      • Increase instances in Klutch.sh for higher load
      • Use Redis for shared session state
      • Configure load balancing (handled by Klutch.sh)

    5. Monitoring and Logging

      • Set LOG_LEVEL=warn in production to reduce noise
      • Use structured logging with JSON output
      • Monitor CPU, memory, and database connections
      • Set up alerts for error rates and response times

Backup Strategy

    1. Database Backups

      • Configure automated daily backups
      • Test restoration procedures regularly
      • Keep backups for at least 30 days

    2. Volume Backups

      • Regularly backup the /app/data/uploads volume
      • Store backups in a separate region/provider
      • Implement retention policies

    3. Configuration Backups

      • Version control all environment variables
      • Document any manual configuration changes
      • Keep encrypted backups of secrets

Scaling Considerations

    1. Vertical Scaling

      • Start with 1GB RAM, 1 CPU
      • Monitor resource usage
      • Scale up to 2-4GB RAM for 100+ concurrent users

    2. Horizontal Scaling

      • Use multiple instances for high availability
      • Configure Redis for session sharing
      • Database connection pooling becomes critical

    3. Traffic Management

      • Set internal port to 3000
      • Klutch.sh handles HTTPS termination and load balancing
      • Traffic type should be HTTP for web socket support

Troubleshooting Common Issues

App Won’t Start

Symptoms: Container starts but app doesn’t respond

Solutions:

  • Check environment variables are set correctly
  • Verify database connection (host, port, credentials)
  • Check logs in Klutch.sh dashboard for error messages
  • Ensure internal port is set to 3000 (or your configured port)

Database Connection Errors

Symptoms: “Connection refused” or “Authentication failed”

Solutions:

  • Verify database host is reachable from Klutch.sh
  • Check database credentials in environment variables
  • Ensure database allows connections from Klutch.sh IP ranges
  • Test connection using database client tools

File Upload Failures

Symptoms: Files won’t upload or uploads return errors

Solutions:

  • Verify volumes are properly attached
  • Check directory permissions in Dockerfile
  • Ensure MAX_FILE_SIZE is set appropriately
  • Monitor available disk space on volumes

High Memory Usage

Symptoms: App restarts frequently, out of memory errors

Solutions:

  • Increase instance size in Klutch.sh
  • Check for memory leaks in application logs
  • Reduce DATABASE_POOL_MAX connections
  • Optimize large file handling

Slow Performance

Symptoms: Slow message delivery, high latency

Solutions:

  • Add Redis for session caching
  • Enable database query logging and optimize slow queries
  • Increase instance count for horizontal scaling
  • Use CDN for static assets and uploads
  • Check database connection pool settings

Updating Your Deployment

When you need to update Fugu:

    1. Update Your Code

      Terminal window
      git pull origin main
      # Make your changes
      git add .
      git commit -m "Update Fugu configuration"
      git push origin main

    2. Trigger Redeployment

      • Klutch.sh automatically rebuilds when you push to GitHub
      • Or manually trigger a rebuild in the dashboard
      • Monitor the build logs

    3. Database Migrations If updating includes database schema changes:

      Terminal window
      # Add to Dockerfile or use a migration job
      RUN npm run migrate

    4. Zero-Downtime Updates

      • Klutch.sh performs rolling updates automatically
      • New containers start before old ones stop
      • Health checks ensure new version is ready

Advanced Configuration

Custom Domain Setup

    1. In Klutch.sh dashboard, go to your app settings
    2. Navigate to Domains section
    3. Click Add Custom Domain
    4. Enter your domain (e.g., chat.example.com)
    5. Follow DNS configuration instructions
    6. Update BASE_URL environment variable to match your domain
    7. Klutch.sh automatically provisions SSL/TLS certificates

Email Notifications

Configure SMTP for user notifications:

Terminal window
SMTP_HOST=smtp.sendgrid.net
SMTP_PORT=587
SMTP_USER=apikey
SMTP_PASSWORD=your-sendgrid-api-key
SMTP_FROM=notifications@example.com
ENABLE_EMAIL_NOTIFICATIONS=true

Webhooks Integration

Enable webhooks for external integrations:

Terminal window
ENABLE_WEBHOOKS=true
WEBHOOK_SECRET=your-webhook-secret
ALLOWED_WEBHOOK_DOMAINS=example.com,api.example.com

Real-Time Features

Optimize WebSocket connections:

Terminal window
WEBSOCKET_ENABLED=true
WEBSOCKET_PATH=/socket
WEBSOCKET_PING_INTERVAL=25000
WEBSOCKET_PING_TIMEOUT=60000

Resources

For more information about Fugu and Klutch.sh:

Conclusion

You now have a comprehensive understanding of deploying Fugu on Klutch.sh with Docker. This guide covered installation, Dockerfile creation, persistent storage configuration, environment variables, deployment steps, and production best practices.

Fugu on Klutch.sh provides a powerful, self-hosted team collaboration platform with the reliability and scalability of modern cloud infrastructure. Whether you’re running a small team chat or enterprise-wide communications, Klutch.sh’s automatic Docker detection, persistent volumes, and seamless scaling capabilities make it an ideal platform for hosting Fugu.

Start deploying today and give your team the chat platform they deserve!