Skip to content
Klutch.sh Docs

Deploying Chibisafe

Chibisafe is a lightweight, self-hosted file sharing and management platform designed for simplicity and privacy. It provides a clean interface for uploading, organizing, and sharing files without relying on third-party services. With features like password protection, expiring links, custom domains, and comprehensive file management, Chibisafe is ideal for individuals, teams, and organizations that need secure file sharing capabilities while maintaining complete control over their data.

This guide will walk you through deploying Chibisafe on Klutch.sh, a modern cloud platform that simplifies containerized application deployment. By the end of this guide, you’ll have a fully functional file sharing service ready for your team.

Why Deploy Chibisafe on Klutch.sh?

Klutch.sh provides an excellent platform for hosting Chibisafe:

  • Docker-native deployment - Klutch.sh automatically detects and deploys Dockerized applications
  • Lightning-fast file transfers - Serve files with minimal latency from optimized infrastructure
  • Persistent storage - Reliable file storage with configurable volume sizes
  • Custom domains - Use your own domain for branded file sharing
  • Environment configuration - Manage secrets and configuration through the dashboard
  • Automatic scaling - Handle varying file upload volumes with ease
  • Security-focused - Built-in HTTPS and modern security practices

Prerequisites

Before deploying Chibisafe on Klutch.sh, you’ll need:

  • A Klutch.sh account (sign up for free)
  • Access to the Klutch.sh dashboard
  • A GitHub repository to store your Chibisafe deployment configuration
  • A custom domain (optional but recommended for branded file sharing)
  • Basic understanding of Docker and containerization

Deployment Steps

  1. Create a Dockerfile

    Create a Dockerfile in the root of your repository to containerize Chibisafe:

    FROM node:20-alpine
    

    # Install system dependencies
    RUN apk add --no-cache \
        build-base \
        python3 \
        git \
        curl \
        ffmpeg
    

    # Set working directory
    WORKDIR /app
    

    # Clone Chibisafe repository
    RUN git clone https://github.com/chibisafe/chibisafe.git . && \
        git checkout main
    

    # Install dependencies
    RUN npm install
    

    # Build the application
    RUN npm run build
    

    # Create necessary directories
    RUN mkdir -p /app/public /app/storage /app/logs
    

    # Expose port
    EXPOSE 8000
    

    # Health check
    HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \
        CMD node -e "require('http').get('http://localhost:8000/api/health', (r) => {if (r.statusCode !== 200) throw new Error(r.statusCode)})" || exit 1
    

    # Start the application
    CMD ["npm", "start"]

  2. Create Environment Configuration File

    Create a .env.example file to document required environment variables:

    # Chibisafe Environment Configuration
    

    # Application Settings
    NODE_ENV=production
    PORT=8000
    HOST=0.0.0.0
    

    # Database Configuration
    DATABASE_URL=postgresql://chibisafe:chibisafepass@localhost:5432/chibisafe
    DB_HOST=db
    DB_PORT=5432
    DB_NAME=chibisafe
    DB_USER=chibisafe
    DB_PASSWORD=secure_password_change_in_production
    

    # Redis Configuration (for caching and sessions)
    REDIS_URL=redis://redis:6379
    REDIS_DB=0
    

    # Application Base URL
    BASE_URL=https://example-app.klutch.sh
    API_URL=https://example-app.klutch.sh/api
    

    # Storage Configuration
    STORAGE_PATH=/app/storage
    MAX_FILE_SIZE=5368709120
    MAX_FILES_PER_UPLOAD=100
    

    # Security Settings
    APP_SECRET=your-app-secret-change-in-production
    JWT_SECRET=your-jwt-secret-change-in-production
    ENCRYPTION_KEY=your-encryption-key-change-in-production
    

    # File Upload Configuration
    ALLOWED_MIME_TYPES=image/*,video/*,audio/*,.pdf,.doc,.docx,.xls,.xlsx,.ppt,.pptx,.txt,.zip,.rar,.7z
    UPLOAD_DIR=/app/storage/uploads
    TEMP_DIR=/app/storage/temp
    

    # Upload Limits
    RATE_LIMIT_ENABLED=true
    RATE_LIMIT_WINDOW=900000
    RATE_LIMIT_MAX_REQUESTS=100
    

    # Authentication
    ENABLE_USER_REGISTRATION=true
    REQUIRE_EMAIL_VERIFICATION=false
    JWT_EXPIRATION=7d
    

    # Email Configuration (Optional)
    SMTP_HOST=smtp.gmail.com
    SMTP_PORT=587
    SMTP_USER=your-email@gmail.com
    SMTP_PASSWORD=your-app-password
    SMTP_FROM=noreply@example-app.klutch.sh
    

    # Admin Settings
    ADMIN_EMAIL=admin@example.com
    ADMIN_PASSWORD=change-me-in-production
    ADMIN_USERNAME=admin
    

    # API Configuration
    API_ENABLED=true
    API_RATE_LIMIT=200
    CORS_ORIGIN=https://example-app.klutch.sh
    

    # File Retention
    ENABLE_EXPIRATION=true
    DEFAULT_EXPIRATION_DAYS=30
    MAX_EXPIRATION_DAYS=365
    

    # Feature Flags
    ENABLE_PASSWORD_PROTECTION=true
    ENABLE_DOWNLOAD_TOKENS=true
    ENABLE_FILE_SCANNING=false
    ENABLE_ANALYTICS=true
    ENABLE_BULK_OPERATIONS=true
    

    # Logging
    LOG_LEVEL=info
    LOG_DIR=/app/logs
    

    # CDN Configuration (Optional)
    CDN_ENABLED=false
    CDN_URL=https://cdn.example-app.klutch.sh
    

    # Thumbnail Generation
    ENABLE_THUMBNAILS=true
    THUMBNAIL_SIZE=300
    

    # Media Processing
    ENABLE_VIDEO_PREVIEW=true
    ENABLE_IMAGE_OPTIMIZATION=true

  3. Create Application Configuration File

    Create a config.js file for application-specific settings:

    module.exports = {
      app: {
        name: 'Chibisafe',
        version: '1.0.0',
        environment: process.env.NODE_ENV || 'production',
        port: process.env.PORT || 8000,
        host: process.env.HOST || '0.0.0.0',
        baseUrl: process.env.BASE_URL || 'http://localhost:8000',
        apiUrl: process.env.API_URL || 'http://localhost:8000/api'
      },
      database: {
        url: process.env.DATABASE_URL,
        host: process.env.DB_HOST,
        port: parseInt(process.env.DB_PORT) || 5432,
        name: process.env.DB_NAME,
        user: process.env.DB_USER,
        password: process.env.DB_PASSWORD,
        pool: {
          min: 2,
          max: 20,
          idleTimeoutMillis: 30000,
          connectionTimeoutMillis: 2000
        }
      },
      redis: {
        url: process.env.REDIS_URL,
        db: parseInt(process.env.REDIS_DB) || 0,
        retryStrategy: (times) => Math.min(times * 50, 2000),
        maxRetriesPerRequest: null
      },
      storage: {
        path: process.env.STORAGE_PATH || '/app/storage',
        uploadDir: process.env.UPLOAD_DIR || '/app/storage/uploads',
        tempDir: process.env.TEMP_DIR || '/app/storage/temp',
        maxFileSize: parseInt(process.env.MAX_FILE_SIZE) || 5368709120,
        maxFilesPerUpload: parseInt(process.env.MAX_FILES_PER_UPLOAD) || 100
      },
      security: {
        appSecret: process.env.APP_SECRET,
        jwtSecret: process.env.JWT_SECRET,
        encryptionKey: process.env.ENCRYPTION_KEY,
        jwtExpiration: process.env.JWT_EXPIRATION || '7d'
      },
      upload: {
        allowedMimeTypes: (process.env.ALLOWED_MIME_TYPES || '').split(','),
        enableExpiration: process.env.ENABLE_EXPIRATION === 'true',
        defaultExpirationDays: parseInt(process.env.DEFAULT_EXPIRATION_DAYS) || 30,
        maxExpirationDays: parseInt(process.env.MAX_EXPIRATION_DAYS) || 365,
        enablePasswordProtection: process.env.ENABLE_PASSWORD_PROTECTION === 'true',
        enableDownloadTokens: process.env.ENABLE_DOWNLOAD_TOKENS === 'true'
      },
      auth: {
        enableUserRegistration: process.env.ENABLE_USER_REGISTRATION === 'true',
        requireEmailVerification: process.env.REQUIRE_EMAIL_VERIFICATION === 'true'
      },
      api: {
        enabled: process.env.API_ENABLED === 'true',
        rateLimit: parseInt(process.env.API_RATE_LIMIT) || 200
      },
      cors: {
        origin: process.env.CORS_ORIGIN || 'http://localhost:8000'
      },
      email: {
        host: process.env.SMTP_HOST,
        port: parseInt(process.env.SMTP_PORT) || 587,
        user: process.env.SMTP_USER,
        password: process.env.SMTP_PASSWORD,
        from: process.env.SMTP_FROM || 'noreply@chibisafe.local'
      },
      media: {
        enableThumbnails: process.env.ENABLE_THUMBNAILS === 'true',
        enableVideoPreview: process.env.ENABLE_VIDEO_PREVIEW === 'true',
        enableImageOptimization: process.env.ENABLE_IMAGE_OPTIMIZATION === 'true',
        thumbnailSize: parseInt(process.env.THUMBNAIL_SIZE) || 300
      },
      logging: {
        level: process.env.LOG_LEVEL || 'info',
        dir: process.env.LOG_DIR || '/app/logs'
      }
    };

  4. Create Database Initialization Script

    Create an init-db.sh file to set up the PostgreSQL database:

    #!/bin/bash
    

    set -e
    

    echo "Initializing Chibisafe database..."
    

    # Wait for PostgreSQL to be ready
    until PGPASSWORD=$DB_PASSWORD psql -h "$DB_HOST" -U "$DB_USER" -d "postgres" -c "\q"; do
      echo 'Waiting for postgres...'
      sleep 1
    done
    

    echo "PostgreSQL is ready!"
    

    # Create database if it doesn't exist
    PGPASSWORD=$DB_PASSWORD psql -h "$DB_HOST" -U "$DB_USER" -d "postgres" << EOF
    CREATE DATABASE $DB_NAME;
    EOF
    

    echo "Database created!"
    

    # Run migrations
    echo "Running database migrations..."
    npm run migrate
    

    # Seed initial data
    echo "Seeding initial data..."
    npm run seed || true
    

    echo "Database initialization complete!"

    Make it executable:

    Terminal window
    chmod +x init-db.sh

  5. Create Docker Compose for Local Development

    Create a docker-compose.yml file for local development and testing (not used for Klutch.sh deployment):

    version: '3.8'
    

    services:
      chibisafe:
        build: .
        container_name: chibisafe-dev
        ports:
          - "8000:8000"
        environment:
          - NODE_ENV=development
          - DATABASE_URL=postgresql://chibisafe:chibisafepass@db:5432/chibisafe
          - DB_HOST=db
          - DB_PORT=5432
          - DB_NAME=chibisafe
          - DB_USER=chibisafe
          - DB_PASSWORD=chibisafepass
          - REDIS_URL=redis://redis:6379
          - BASE_URL=http://localhost:8000
          - APP_SECRET=dev-secret-change-in-production
          - JWT_SECRET=dev-jwt-secret-change-in-production
          - ENCRYPTION_KEY=dev-encryption-key-change-in-production
          - ENABLE_USER_REGISTRATION=true
          - ENABLE_ANALYTICS=true
        depends_on:
          - db
          - redis
        volumes:
          - ./storage:/app/storage
          - ./src:/app/src
        networks:
          - chibisafe-network
    

      db:
        image: postgres:16-alpine
        container_name: chibisafe-db
        environment:
          - POSTGRES_USER=chibisafe
          - POSTGRES_PASSWORD=chibisafepass
          - POSTGRES_DB=chibisafe
        volumes:
          - chibisafe_db_data:/var/lib/postgresql/data
        networks:
          - chibisafe-network
        healthcheck:
          test: ["CMD-SHELL", "pg_isready -U chibisafe"]
          interval: 10s
          timeout: 5s
          retries: 5
    

      redis:
        image: redis:7-alpine
        container_name: chibisafe-redis
        networks:
          - chibisafe-network
        healthcheck:
          test: ["CMD", "redis-cli", "ping"]
          interval: 10s
          timeout: 5s
          retries: 5
    

    volumes:
      chibisafe_db_data:
    

    networks:
      chibisafe-network:
        driver: bridge

  6. Create .gitignore File

    Create a .gitignore file to exclude sensitive data from version control:

    # Environment files
    .env
    .env.local
    .env.*.local
    

    # Node.js
    node_modules/
    npm-debug.log
    yarn-error.log
    package-lock.json
    yarn.lock
    

    # Build artifacts
    dist/
    build/
    .next/
    out/
    

    # Data and uploads
    storage/
    uploads/
    public/uploads/
    

    # Logs
    logs/
    *.log
    

    # IDE
    .vscode/
    .idea/
    *.swp
    *.swo
    *~
    .DS_Store
    

    # Cache
    .cache/
    .turbo/
    

    # Database
    *.sqlite
    *.sqlite3
    

    # Temporary files
    temp/
    tmp/
    .tmp/

  7. Push Configuration to GitHub

    Push your repository to GitHub with all configuration files:

    Terminal window
    git add Dockerfile .env.example config.js init-db.sh \
      docker-compose.yml .gitignore
    git commit -m "Initial Chibisafe deployment configuration for Klutch.sh"
    git push origin main

  8. Deploy on Klutch.sh

    1. Navigate to klutch.sh/app and log in to your dashboard
    2. Click Create New App
    3. Connect your GitHub repository containing the Chibisafe deployment files (the Dockerfile will be automatically detected)
    4. Configure your application settings:
      • Set your preferred app name
      • Review the detected Dockerfile configuration
      • Select a region for deployment
    5. Click Deploy to start the deployment process
    6. Monitor the deployment progress in the dashboard
    7. Wait for the deployment to complete and your app to become active

  9. Configure Environment Variables

    1. In your app dashboard, navigate to Environment Variables section
    2. Add all required variables from your .env.example file:
      • DATABASE_URL: Your PostgreSQL connection string
      • DB_HOST: Your PostgreSQL hostname
      • DB_NAME: Database name (chibisafe)
      • DB_USER: Database user
      • DB_PASSWORD: Secure database password
      • REDIS_URL: Your Redis connection string
      • BASE_URL: Set to https://example-app.klutch.sh (or your custom domain)
      • APP_SECRET: Generate a secure secret with openssl rand -base64 32
      • JWT_SECRET: Generate a secure JWT secret with openssl rand -base64 32
      • ENCRYPTION_KEY: Generate a secure encryption key with openssl rand -base64 32
      • ADMIN_EMAIL and ADMIN_PASSWORD: Administrator credentials
    3. Click Save to apply the environment variables
    4. Your application will automatically restart with the new configuration

  10. Configure Traffic Routes

    1. In your app dashboard, navigate to Traffic settings
    2. Select HTTP as the traffic type
    3. Set the internal port to 8000 (Chibisafe Node.js server default)
    4. Configure any custom domain settings if you have a domain
    5. Save your traffic configuration

  11. Attach Persistent Volumes

    Chibisafe requires persistent storage for uploaded files, temporary files, and logs.

    1. In your app dashboard, navigate to Volumes settings
    2. Click Add Volume to create storage for uploaded files:
      • Enter mount path: /app/storage/uploads
      • Set volume size to 100GB (adjust based on expected file volume)
      • Click Attach to create and mount the volume
    3. Click Add Volume again for temporary files and cache:
      • Enter mount path: /app/storage/temp
      • Set volume size to 10GB
      • Click Attach to create and mount the volume
    4. Click Add Volume again for application logs:
      • Enter mount path: /app/logs
      • Set volume size to 5GB
      • Click Attach to create and mount the volume

    Your Chibisafe application will now be accessible at your configured domain or at example-app.klutch.sh.

Initial Setup and Configuration

After deploying Chibisafe on Klutch.sh, complete the initial setup to prepare your file sharing service.

Access Your Chibisafe Instance

  1. Navigate to https://example-app.klutch.sh in your web browser
  2. You’ll see the Chibisafe home page
  3. Click Register to create an account or Login if you have existing credentials
  4. If this is your first deployment, navigate to /admin for administrator setup
  5. Log in with the admin credentials you set in environment variables
  6. Complete the initial configuration wizard

Configure Your Chibisafe Instance

Once logged in, configure these essential settings:

Site Settings:

  • Set your site name and branding
  • Configure the file upload base URL
  • Set maximum file size limits
  • Configure storage cleanup policies

File Upload Settings:

  • Define allowed file types
  • Set maximum files per upload
  • Configure expiration defaults
  • Enable/disable password protection
  • Set rate limiting thresholds

User Management:

  • Create additional administrator accounts if needed
  • Configure user registration settings
  • Set email verification requirements
  • Configure user roles and permissions

Storage Settings:

  • Monitor storage usage
  • Configure automatic cleanup policies
  • Set file retention periods
  • Monitor quota limits

Create Administrator Account

  1. Access the admin panel at /admin
  2. Use the credentials configured in environment variables
  3. Change the default password immediately
  4. Enable two-factor authentication for security
  5. Configure additional admin users as needed

Configure User Registration

To control user access:

  1. In admin panel, navigate to Settings → Users
  2. Enable or disable public registration
  3. Set email verification requirements
  4. Configure user quotas and limits
  5. Set default user roles and permissions

File Sharing Best Practices

Managing File Uploads

  • Regularly review uploaded files for compliance
  • Monitor storage usage against available volumes
  • Implement file retention policies
  • Archive old files for compliance if needed
  • Set up automated cleanup for expired files

Security Considerations

  • Enable password protection for sensitive files
  • Use download tokens for time-limited access
  • Monitor access logs for suspicious patterns
  • Implement IP whitelisting if necessary
  • Regularly audit user access permissions
  • Enable virus scanning for file safety

Performance Optimization

  • Monitor file upload speeds and bandwidth
  • Enable caching for frequently downloaded files
  • Optimize thumbnail generation for media files
  • Implement CDN integration for faster downloads
  • Monitor database query performance

Analytics and Monitoring

  • Track file upload and download statistics
  • Monitor user activity patterns
  • Review storage usage trends
  • Set up alerts for quota approaching
  • Generate reports on file sharing patterns

Deployment Best Practices

Security Measures

  • Keep Chibisafe updated to the latest version
  • Use strong, unique passwords for all accounts
  • Enable two-factor authentication for administrators
  • Configure firewall rules to restrict access if needed
  • Use HTTPS for all communications (automatic with Klutch.sh)
  • Regularly review user access permissions
  • Implement rate limiting on uploads

Monitoring and Maintenance

  • Monitor disk usage for storage volumes
  • Set up alerts for deployment failures
  • Review logs regularly for errors or security issues
  • Schedule maintenance windows for updates
  • Test file recovery procedures regularly
  • Monitor database performance
  • Implement automated backups

Scaling Considerations

As your file sharing service grows:

  • Increase storage volume sizes proactively
  • Monitor database performance and optimize queries
  • Implement file analytics archiving
  • Consider read replicas for analytics queries
  • Archive old file records for performance

Accessing Chibisafe

Once deployment is complete and configured:

  1. Users access Chibisafe at your configured domain or example-app.klutch.sh
  2. Users can upload files through the web interface
  3. Users can generate shareable links with custom settings
  4. Users can set password protection on shared files
  5. Users can track download statistics for their files
  6. Admin panel provides full service management

Troubleshooting Deployment Issues

Application Won’t Start

Check the following:

  • Verify all required environment variables are set
  • Ensure database connection string is correct
  • Check that Redis is accessible
  • Review application logs in the dashboard
  • Verify Node.js version compatibility

Database Connection Errors

Steps to resolve:

  • Verify DATABASE_URL environment variable format
  • Ensure database is running and accessible
  • Check database user credentials
  • Verify network connectivity between services
  • Test database connectivity from application logs

File Upload Issues

Possible solutions:

  • Verify application has write permissions to storage directories
  • Check available disk space on volumes
  • Ensure database is not at capacity
  • Verify MAX_FILE_SIZE environment variable is appropriate
  • Review upload error logs for specific issues

Performance Issues

Optimization steps:

  • Increase application memory allocation
  • Enable Redis caching for sessions
  • Optimize database queries
  • Monitor and archive old file records
  • Enable thumbnail caching for media files

Advanced Configuration

Environment Variables for Customization

You can customize Chibisafe behavior with these environment variables:

Terminal window
# File Upload Configuration
MAX_FILE_SIZE=5368709120
MAX_FILES_PER_UPLOAD=100
ALLOWED_MIME_TYPES=image/*,video/*,audio/*,.pdf,.doc,.docx,.txt


# Storage Configuration
STORAGE_PATH=/app/storage
UPLOAD_DIR=/app/storage/uploads
TEMP_DIR=/app/storage/temp


# Database Connection Pool
DB_POOL_MIN=2
DB_POOL_MAX=20
DB_IDLE_TIMEOUT=30000


# File Retention
DEFAULT_EXPIRATION_DAYS=30
MAX_EXPIRATION_DAYS=365


# Feature Flags
ENABLE_PASSWORD_PROTECTION=true
ENABLE_DOWNLOAD_TOKENS=true
ENABLE_THUMBNAILS=true
ENABLE_VIDEO_PREVIEW=true
ENABLE_IMAGE_OPTIMIZATION=true


# Cache Configuration
REDIS_DB=0
CACHE_TTL=3600


# Security
ENFORCE_HTTPS=true
SECURE_COOKIES=true
RATE_LIMIT_MAX_REQUESTS=100

Custom Domain Setup

To use a custom domain with your Chibisafe instance:

  1. In your Klutch.sh dashboard, navigate to Domains
  2. Add your custom domain
  3. Follow the DNS configuration instructions
  4. Update your environment variables with the new domain:
    • BASE_URL=https://your-domain.com
  5. Save and redeploy your application

API Integration

To enable API access for programmatic file uploads:

  1. In Chibisafe admin panel, navigate to API Settings
  2. Generate API keys for your applications
  3. Configure API rate limits
  4. Document API endpoints for developers
  5. Set up API usage monitoring

Additional Resources

Learn more about Chibisafe and Klutch.sh:

Conclusion

You now have a fully functional Chibisafe instance running on Klutch.sh! Your self-hosted file sharing service is ready for users to upload and share files securely.

With the robust infrastructure provided by Klutch.sh and the powerful features of Chibisafe, you can create a branded file sharing solution with complete control. Remember to:

  • Keep your application updated with the latest Chibisafe releases
  • Monitor file upload trends and storage usage
  • Maintain regular backups of your database
  • Follow security best practices for file handling
  • Scale your infrastructure as your file volume grows

For additional support or questions about deploying Chibisafe on Klutch.sh, refer to the documentation and community resources linked above.