Skip to content
Klutch.sh Docs

Deploying a Filestash App

Introduction

Filestash is a powerful, self-hosted file manager that transforms how you interact with your data across multiple storage backends. Built as a universal file manager, Filestash provides a modern web interface to access and manage files from over 20 different protocols and storage systems including S3, FTP, SFTP, WebDAV, Dropbox, Google Drive, Azure Blob Storage, and many more—all from a single, unified interface.

Filestash stands out for its:

  • Universal Storage Support: Connect to 20+ protocols including S3, FTP, SFTP, WebDAV, Dropbox, Google Drive, and more
  • Modern Web Interface: Clean, intuitive UI with drag-and-drop functionality
  • Self-Hosted Control: Complete ownership and privacy of your file management
  • Rich Media Support: Built-in viewers for images, videos, documents, and code files
  • File Sharing: Secure file sharing with password protection and expiration dates
  • Plugin System: Extensible architecture for custom functionality
  • Mobile-Friendly: Responsive design works seamlessly on all devices
  • Zero External Dependencies: No external database required—uses embedded storage

This comprehensive guide walks you through deploying Filestash on Klutch.sh using Docker, including detailed installation steps, sample Dockerfile configurations, persistent storage setup, and production-ready best practices.

Prerequisites

Before you begin, ensure you have the following:

Installation and Setup

Step 1: Create Your Project Directory

First, create a new directory for your Filestash deployment project:

Terminal window
mkdir filestash-klutch
cd filestash-klutch
git init

Step 2: Create the Dockerfile

Create a Dockerfile in your project root directory. This will define your Filestash container configuration:

FROM machines/filestash:latest


# Expose the default Filestash port
EXPOSE 8334


# The container will use /app/data/state/ for persistent data
VOLUME ["/app/data/state"]


# Start Filestash
CMD ["/app/filestash"]

Note: This Dockerfile uses the official Filestash image which includes all necessary dependencies. The application stores configuration and state data in /app/data/state/, which should be mounted to a persistent volume.

Step 3: Advanced Dockerfile with Custom Configuration

For a production setup with pre-configured settings, you can create a custom Dockerfile:

FROM machines/filestash:latest


# Install additional tools if needed
RUN apt-get update && apt-get install -y \
    curl \
    ca-certificates \
    && rm -rf /var/lib/apt/lists/*


# Create necessary directories
RUN mkdir -p /app/data/state


# Optional: Copy custom configuration
# COPY config.json /app/data/state/config/config.json


# Expose Filestash port
EXPOSE 8334


# Health check
HEALTHCHECK --interval=30s --timeout=3s --start-period=40s --retries=3 \
  CMD curl -f http://localhost:8334/about || exit 1


# Start Filestash
CMD ["/app/filestash"]

Step 4: Create Environment Configuration

Create a .env.example file to document the available environment variables:

Terminal window
# Application Configuration
# These settings will be configured through the Filestash web interface after deployment


# Optional: Set custom application name
APPLICATION_URL=https://example-app.klutch.sh


# Storage Backend Configuration
# Configure through the web interface at /admin after first deployment:
# - S3, Azure Blob, Google Cloud Storage
# - FTP, SFTP, WebDAV
# - Dropbox, Google Drive
# - Local filesystem and more

Security Note: Never commit actual credentials or sensitive data to your repository. Configure storage backends through the Filestash web interface after deployment.

Step 5: Create a README

Create a README.md file with deployment instructions:

# Filestash Deployment on Klutch.sh


## About Filestash


Filestash is a universal file manager that connects to multiple storage backends through a modern web interface.


## Supported Storage Backends


- **Cloud Storage**: S3, Azure Blob, Google Cloud Storage, Backblaze B2
- **File Transfer**: FTP, SFTP, FTPS, WebDAV
- **Cloud Services**: Dropbox, Google Drive
- **Other**: Git, Local filesystem, Samba/CIFS


## Initial Setup


After deployment:


1. Access your Filestash instance at your app URL
2. Complete the initial setup wizard
3. Configure your storage backends at `/admin`
4. Set up authentication and security settings


## Security Recommendations


- Enable HTTPS (automatic on Klutch.sh)
- Configure strong authentication
- Use separate credentials for storage backends
- Enable 2FA where available
- Regular backups of `/app/data/state/`

Step 6: Test Locally (Optional)

Before deploying to Klutch.sh, you can test your Filestash setup locally:

Terminal window
# Build the Docker image
docker build -t my-filestash .


# Create a volume for persistent data
docker volume create filestash-data


# Run the container
docker run -d \
  --name filestash-test \
  -p 8334:8334 \
  -v filestash-data:/app/data/state \
  my-filestash


# View logs
docker logs -f filestash-test


# Access Filestash at http://localhost:8334


# Stop and remove the test container when done
docker stop filestash-test
docker rm filestash-test
docker volume rm filestash-data

Step 7: Push to GitHub

Commit your Dockerfile and configuration files to your GitHub repository:

Terminal window
git add Dockerfile .env.example README.md
git commit -m "Add Filestash Dockerfile and configuration"
git remote add origin https://github.com/yourusername/filestash-klutch.git
git push -u origin main

Deploying to Klutch.sh

Now that your Filestash project is ready and pushed to GitHub, follow these steps to deploy it on Klutch.sh with persistent storage.

Deployment Steps

    1. Log in to Klutch.sh

      Navigate to klutch.sh/app and sign in to your account.

    2. Create a New Project

      Click on “Create Project” and give your project a meaningful name (e.g., “Filestash File Manager”).

    3. Create a New App

      Click on “Create App” within your project and configure the following settings:

    4. Select Your Repository

      • Choose GitHub as your Git source
      • Select the repository containing your Dockerfile
      • Choose the branch you want to deploy (usually main or master)

    5. Configure Traffic Type

      • Traffic Type: Select HTTP (Filestash serves a web interface via HTTP)
      • Internal Port: Set to 8334 (the default port that Filestash listens on)

    6. Attach Persistent Volume

      Filestash requires persistent storage for configuration, user data, and application state:

      • Navigate to the “Volumes” section in your app settings
      • Click “Add Volume”
      • Mount Path: Enter /app/data/state
      • Size: Allocate appropriate storage (start with 5GB, adjust based on your needs)
      • Click “Add” to attach the volume

      Important: This volume stores all Filestash configuration, user settings, and cached data. Always ensure it’s properly backed up.

    7. Deploy Your Application

      Click “Deploy” to start the deployment process. Klutch.sh will automatically:

      • Detect your Dockerfile in the repository root
      • Build the Docker image
      • Deploy the container with the configured settings
      • Map the internal port 8334 to a public URL

    8. Monitor Deployment

      Watch the build logs in the Klutch.sh dashboard to ensure your deployment completes successfully. The initial build may take a few minutes.

Initial Configuration

After your Filestash instance is deployed and running, you’ll need to complete the initial setup:

Step 1: Access Your Instance

Navigate to your app’s URL (e.g., https://example-app.klutch.sh) in your web browser.

Step 2: Complete Initial Setup

On first access, Filestash will guide you through the initial configuration:

  1. Welcome Screen: You’ll see the Filestash welcome page
  2. Admin Setup: Navigate to /admin to access the administration panel
  3. Configure Authentication: Set up your preferred authentication method
  4. Set Admin Password: Create a secure admin password

Step 3: Configure Storage Backends

From the admin panel (/admin), configure your storage backends:

    1. Navigate to Backends Section

      Click on “Backends” in the admin menu.

    2. Add Storage Backend

      Choose from available options:

      • S3-Compatible: AWS S3, MinIO, Wasabi, Backblaze B2
      • FTP/SFTP: Traditional file transfer protocols
      • WebDAV: CalDAV, CardDAV compatible servers
      • Cloud Services: Dropbox, Google Drive
      • Local: Local filesystem (if needed)

    3. Configure Backend Settings

      For S3 example:

      Access Key ID: your-access-key
      Secret Access Key: your-secret-key
      Endpoint: s3.amazonaws.com (or custom endpoint)
      Region: us-east-1
      Bucket: your-bucket-name

    4. Test Connection

      Use the built-in connection test to verify your configuration.

    5. Set as Default (Optional)

      You can set a backend as the default login option.

Environment Variables and Configuration

While Filestash is primarily configured through its web interface, you can set environment variables in Klutch.sh for specific use cases:

Available Environment Variables

You can configure these in the Klutch.sh dashboard under “Environment Variables”:

  • APPLICATION_URL: The public URL of your Filestash instance (e.g., https://example-app.klutch.sh)
  • GDPR_CONSENT: Set to true to enable GDPR compliance features
  • COOKIE_TIMEOUT: Session timeout in minutes (default: 60)

Nixpacks Configuration

If you need to customize the build or start commands, you can use Nixpacks environment variables:

  • NIXPACKS_BUILD_CMD: Custom build command (usually not needed for Filestash)
  • NIXPACKS_START_CMD: Custom start command if different from default

Note: The default Dockerfile configuration handles all necessary setup, so these are rarely needed.

Advanced Configuration

Custom Domain Setup

To use a custom domain with your Filestash instance:

    1. Add Domain in Klutch.sh

      Navigate to your app settings and add your custom domain (e.g., files.yourdomain.com).

    2. Update DNS Records

      Point your domain’s DNS to the Klutch.sh provided address:

      • Add a CNAME record pointing to your Klutch.sh app URL
      • Or add an A record with the IP address provided

    3. Update APPLICATION_URL

      Set the APPLICATION_URL environment variable to your custom domain:

      APPLICATION_URL=https://files.yourdomain.com

    4. Verify SSL Certificate

      Klutch.sh automatically provisions SSL certificates for custom domains.

For detailed instructions, see the Custom Domains guide.

Authentication Configuration

Filestash supports multiple authentication methods:

  • Built-in Authentication: Username and password
  • LDAP: Integrate with LDAP directories
  • SSO: Single sign-on integration
  • Public Access: Allow anonymous access to specific backends

Configure these in the admin panel under “Authentication” settings.

Plugin Configuration

Filestash supports plugins for extended functionality. To enable plugins:

  1. Navigate to /admin/plugins in your Filestash instance
  2. Browse available plugins
  3. Enable desired plugins
  4. Configure plugin settings as needed

Popular plugins include:

  • Enhanced image viewer
  • Video transcoding
  • Document preview
  • Search functionality
  • Audit logs

Storage Backends Configuration

S3-Compatible Storage

To configure S3 or S3-compatible storage (MinIO, Wasabi, Backblaze B2):

Backend Type: S3
Access Key ID: AKIAIOSFODNN7EXAMPLE
Secret Access Key: wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
Endpoint: s3.amazonaws.com
Region: us-east-1
Bucket: my-files-bucket
Path Prefix: /uploads/
Encryption: AES256

FTP/SFTP Configuration

For FTP or SFTP servers:

Backend Type: SFTP
Hostname: ftp.example.com
Port: 22
Username: ftpuser
Password: your-secure-password
Path: /home/ftpuser/files

WebDAV Configuration

For WebDAV-compatible servers:

Backend Type: WebDAV
URL: https://webdav.example.com/remote.php/webdav/
Username: webdavuser
Password: your-secure-password

Google Drive Configuration

For Google Drive integration:

  1. Create a Google Cloud project
  2. Enable the Google Drive API
  3. Create OAuth 2.0 credentials
  4. Configure in Filestash with:
    • Client ID
    • Client Secret
    • Redirect URI: https://example-app.klutch.sh/api/session/auth/

Performance Optimization

Resource Allocation

For optimal performance, consider these resource recommendations:

  • Small deployments (< 10 users): 512MB RAM, 1 CPU
  • Medium deployments (10-50 users): 1GB RAM, 2 CPUs
  • Large deployments (50+ users): 2GB+ RAM, 4+ CPUs

Adjust your Klutch.sh instance size accordingly.

Caching Configuration

Filestash implements intelligent caching. Configure cache settings in the admin panel:

  • Thumbnail Cache: Enable for faster image loading
  • File Listing Cache: Reduces backend API calls
  • Session Cache: Improves login performance

Volume Performance

For better I/O performance:

  • Use SSD-backed volumes when available
  • Allocate sufficient space for caching and temporary files
  • Monitor disk usage and expand volumes as needed

Security Best Practices

Authentication Security

    1. Strong Passwords

      • Use strong, unique passwords for admin access
      • Enforce password complexity for users
      • Implement password rotation policies

    2. Two-Factor Authentication

      Enable 2FA through the authentication settings for an additional security layer.

    3. Session Management

      • Set appropriate session timeouts
      • Enable automatic logout on browser close
      • Monitor active sessions

    4. IP Whitelisting (Optional)

      Configure IP restrictions in the admin panel to limit access to trusted networks.

Storage Backend Security

  • Separate Credentials: Use dedicated credentials for each storage backend
  • Least Privilege: Grant only necessary permissions to storage accounts
  • Encryption: Enable encryption at rest and in transit
  • Regular Audits: Review access logs and permissions regularly

Network Security

  • HTTPS Only: Always use HTTPS (automatic on Klutch.sh)
  • CORS Configuration: Configure CORS policies appropriately
  • Security Headers: Enable security headers in the admin panel

Data Protection

  • Regular Backups: Back up the /app/data/state/ volume regularly
  • Backup Verification: Test backup restoration procedures
  • Backup Encryption: Encrypt backups if they contain sensitive data
  • Retention Policy: Implement appropriate backup retention policies

Monitoring and Maintenance

Health Monitoring

Monitor your Filestash instance health:

  • Check application logs in the Klutch.sh dashboard
  • Monitor resource usage (CPU, memory, disk)
  • Set up alerts for service downtime
  • Track response times and error rates

Log Management

Access logs through the Klutch.sh dashboard:

Terminal window
# Application logs show:
# - User authentication events
# - Backend connection status
# - File operation activities
# - Error messages and warnings

Update Strategy

Keep Filestash up to date for security and features:

    1. Monitor Releases

      Watch the Filestash GitHub repository for new releases.

    2. Update Dockerfile

      Update the version tag in your Dockerfile:

      FROM machines/filestash:v0.4

    3. Test Updates

      Test updates in a staging environment before production deployment.

    4. Deploy Update

      Push changes to GitHub and redeploy through Klutch.sh.

    5. Verify Functionality

      Verify all storage backends and features work after the update.

Backup Procedures

Regular backup procedures are critical:

    1. Create Volume Snapshot

      Use Klutch.sh volume snapshot feature if available, or:

    2. Manual Backup

      Copy the state directory periodically:

      Terminal window
      # From a debug/maintenance container
      tar -czf /tmp/filestash-backup-$(date +%Y%m%d).tar.gz /app/data/state/

    3. Store Off-site

      Transfer backups to secure off-site storage:

      • S3 bucket with versioning
      • Remote backup service
      • Separate geographic location

    4. Test Restoration

      Regularly test backup restoration to ensure data integrity.

Troubleshooting

Common Issues and Solutions

Application Won’t Start

Symptoms: Container crashes or won’t start

Solutions:

  • Check container logs in Klutch.sh dashboard
  • Verify the volume is properly mounted to /app/data/state
  • Ensure sufficient disk space in the volume
  • Confirm the internal port is set to 8334

Can’t Access Web Interface

Symptoms: Unable to reach Filestash URL

Solutions:

  • Verify the app is running in Klutch.sh dashboard
  • Check that traffic type is set to HTTP
  • Confirm internal port is 8334
  • Test DNS resolution for your domain

Storage Backend Connection Failed

Symptoms: Error connecting to S3, FTP, or other backend

Solutions:

  • Verify credentials in backend configuration
  • Check network connectivity to backend service
  • Confirm firewall rules allow outbound connections
  • Test credentials with CLI tools independently

Slow Performance

Symptoms: Slow file loading or interface responsiveness

Solutions:

  • Increase instance resources (CPU/RAM)
  • Enable caching in admin panel
  • Optimize backend configurations
  • Check volume I/O performance
  • Review concurrent user load

Upload Failures

Symptoms: Files fail to upload or timeout

Solutions:

  • Check volume disk space
  • Verify backend storage quotas
  • Review file size limits in configuration
  • Examine network bandwidth
  • Check storage backend permissions

Debug Mode

Enable debug logging for troubleshooting:

  1. Access the admin panel at /admin
  2. Navigate to “Settings” > “Advanced”
  3. Enable debug logging
  4. Reproduce the issue
  5. Check logs in Klutch.sh dashboard
  6. Disable debug logging after troubleshooting

Getting Help

If you continue experiencing issues:

Scaling Considerations

Horizontal Scaling

For high-availability deployments:

  • Deploy multiple Filestash instances behind a load balancer
  • Use shared storage for the /app/data/state/ volume
  • Implement session affinity (sticky sessions)
  • Consider read replicas for storage backends

Vertical Scaling

For single-instance performance improvements:

  • Increase CPU allocation for faster file processing
  • Add more RAM for better caching
  • Use faster storage volumes (SSD/NVMe)
  • Optimize backend configurations

Load Balancing

When scaling horizontally:

  • Configure TCP load balancing in Klutch.sh
  • Enable session persistence
  • Monitor health checks
  • Implement connection draining for updates

Migration from Other Platforms

Migrating from Existing Filestash Instance

To migrate an existing Filestash deployment to Klutch.sh:

    1. Backup Current Instance

      Export your current configuration and state:

      Terminal window
      tar -czf filestash-migration.tar.gz /path/to/current/data/state/

    2. Deploy New Instance

      Follow the deployment steps in this guide to create a new Filestash instance on Klutch.sh.

    3. Transfer Configuration

      Copy your backed-up state to the new persistent volume:

      • Extract the backup
      • Upload to the new instance’s volume
      • Restart the application

    4. Verify Configuration

      • Test all storage backend connections
      • Verify user authentication
      • Confirm settings transferred correctly

    5. Update DNS

      Point your domain to the new Klutch.sh instance.

Migrating from Other File Managers

When migrating from other file management systems:

  • Export user lists and permissions
  • Document storage backend configurations
  • Map equivalent settings in Filestash
  • Plan testing period with both systems running
  • Communicate changes to users

Use Cases and Examples

Personal Cloud Storage

Configure Filestash as a personal cloud to access multiple storage services:

  • Connect Google Drive, Dropbox, and local storage
  • Access all your files from one interface
  • Share files securely with others
  • Mobile access from anywhere

Team File Collaboration

Deploy Filestash for team file management:

  • Shared storage backends (S3, SFTP)
  • Role-based access control
  • Audit logging for compliance
  • Guest access with expiring links

Media Library Management

Use Filestash as a media library:

  • Connect to media storage (S3, local)
  • Built-in image and video viewers
  • Thumbnail generation
  • Organize and tag media files

FTP Replacement

Modernize legacy FTP access:

  • SFTP/FTP backend configuration
  • Web-based file transfer
  • Better security than FTP
  • User-friendly interface

Cost Optimization

Resource Efficiency

Optimize costs on Klutch.sh:

  • Start with minimal resources and scale as needed
  • Use auto-scaling if available
  • Monitor resource usage regularly
  • Optimize caching to reduce backend API calls

Storage Optimization

Reduce storage costs:

  • Use object storage (S3) for bulk files
  • Keep only configuration in persistent volumes
  • Implement data lifecycle policies
  • Regular cleanup of temporary files

Bandwidth Optimization

Reduce bandwidth usage:

  • Enable compression in Filestash settings
  • Use CDN for static assets if serving media
  • Implement caching strategies
  • Optimize image thumbnails

Resources and Further Reading

Official Documentation

Klutch.sh Resources

Storage Backend Documentation

Conclusion

Deploying Filestash on Klutch.sh provides a powerful, self-hosted solution for managing files across multiple storage backends. With this guide, you have everything needed to:

  • Deploy Filestash using Docker on Klutch.sh
  • Configure persistent storage for data retention
  • Set up multiple storage backends
  • Implement security best practices
  • Scale and optimize for production use
  • Troubleshoot common issues

Your Filestash instance on Klutch.sh offers a secure, scalable, and cost-effective way to unify file access across all your storage systems. Whether for personal use, team collaboration, or enterprise file management, Filestash on Klutch.sh delivers a modern, web-based file management experience.

For additional support and updates, regularly check the Filestash documentation and Klutch.sh guides to stay current with the latest features and best practices.