Deploying Gossa

Introduction

Gossa is a light and simple web server for your files, built with simplicity and minimalism at its core. With under 300 lines of Go code and zero external dependencies, Gossa is easy to audit, deploy, and maintain while providing essential file browsing and management capabilities.

Following a do-one-thing-well philosophy, Gossa focuses solely on serving files through a clean web interface. Authentication and HTTPS are intentionally left to reverse proxies, keeping the codebase minimal and secure.

Key highlights of Gossa:

• Minimal Codebase: Under 300 lines of Go, easy to audit
• Zero Dependencies: No external libraries or frameworks required
• Fast Performance: Efficient file serving with minimal overhead
• Resumable Uploads: Upload large files without losing progress
• File Operations: Browse, upload, download, rename, and delete files
• Drag and Drop: Easy file uploads via drag and drop
• Mobile Friendly: Responsive interface works on any device
• Cross-Platform: Runs on Linux, macOS, Windows, and more
• Single Binary: Easy deployment with no configuration files
• 100% Open Source: Licensed under MIT

This guide walks through deploying Gossa on Klutch.sh using Docker, configuring file storage, and setting up a simple file server.

Why Deploy Gossa on Klutch.sh

Deploying Gossa on Klutch.sh provides several advantages for file serving:

Simplified Deployment: Klutch.sh automatically detects your Dockerfile and builds Gossa without complex orchestration. Push to GitHub and your file server deploys automatically.

Persistent Storage: Attach persistent volumes for your files. Content survives container restarts.

HTTPS by Default: Klutch.sh provides automatic SSL certificates for secure file transfers.

GitHub Integration: Connect your configuration repository directly from GitHub. Updates trigger automatic redeployments.

Scalable Resources: Allocate CPU and memory based on expected traffic and file sizes.

Custom Domains: Assign a custom domain for your file server.

Always-On Availability: Your file server remains accessible 24/7.

Prerequisites

Before deploying Gossa on Klutch.sh, ensure you have:

• A Klutch.sh account
• A GitHub account with a repository for your Gossa configuration
• Basic familiarity with Docker and containerization concepts
• Files you want to serve or share

Understanding Gossa Architecture

Gossa is intentionally minimal:

Go Backend: Written in pure Go with no external dependencies.

File-Based Storage: Serves files directly from the filesystem.

Web Interface: Simple HTML/CSS/JavaScript frontend for file browsing.

No Database: File metadata comes directly from the filesystem.

Delegated Security: HTTPS and authentication handled by reverse proxy.

Preparing Your Repository

To deploy Gossa on Klutch.sh, create a GitHub repository containing your Dockerfile.

Repository Structure

gossa-deploy/
├── Dockerfile
├── README.md
└── .dockerignore

Creating the Dockerfile

Create a Dockerfile in the root of your repository:

FROM pldubouilh/gossa:latest

# Create directory for shared files
RUN mkdir -p /shared

# Expose the web interface port
EXPOSE 8001

# Run Gossa serving the /shared directory
CMD ["-h", "0.0.0.0", "-p", "8001", "/shared"]

Advanced Dockerfile with Options

For more configuration:

FROM pldubouilh/gossa:latest

# Create directory for shared files
RUN mkdir -p /shared

# Environment variables for configuration
ENV GOSSA_HOST=0.0.0.0
ENV GOSSA_PORT=8001
ENV GOSSA_PATH=/shared

# Read-only mode (uncomment to disable writes)
# ENV GOSSA_READONLY=true

# Expose the web interface port
EXPOSE 8001

# Health check
HEALTHCHECK --interval=30s --timeout=10s --start-period=10s --retries=3 \
  CMD wget --no-verbose --tries=1 --spider http://localhost:8001/ || exit 1

# Run Gossa
CMD ["-h", "0.0.0.0", "-p", "8001", "/shared"]

Read-Only Mode

For a read-only file server:

FROM pldubouilh/gossa:latest

# Create directory for shared files
RUN mkdir -p /shared

EXPOSE 8001

# Run in read-only mode with -ro flag
CMD ["-h", "0.0.0.0", "-p", "8001", "-ro", "/shared"]

Creating the .dockerignore File

Create a .dockerignore file:

.git
.github
*.md
README.md
LICENSE
.gitignore
*.log
.DS_Store

Command Line Options Reference

Option	Default	Description
-h	127.0.0.1	Host to listen on
-p	8001	Port to listen on
-ro	false	Read-only mode (no uploads/deletes)
-prefix	/	URL prefix for the server
-verb	false	Verbose logging
[path]	.	Directory to serve

Deploying Gossa on Klutch.sh

Once your repository is prepared, follow these steps to deploy Gossa:

Push Your Repository to GitHub

Initialize your repository and push to GitHub:

git init
git add Dockerfile .dockerignore README.md
git commit -m "Initial Gossa deployment configuration"
git remote add origin https://github.com/yourusername/gossa-deploy.git
git push -u origin main

Create a New Project on Klutch.sh

Navigate to the Klutch.sh dashboard and create a new project. Give it a descriptive name like “gossa” or “file-server”.

Create a New App

Within your project, create a new app. Connect your GitHub account if you haven’t already, then select the repository containing your Gossa Dockerfile.

Configure HTTP Traffic

Gossa serves its web interface over HTTP. In the deployment settings:

• Select HTTP as the traffic type
• Set the internal port to 8001

Attach Persistent Volumes

Persistent storage is essential for Gossa. Add the following volume:

Mount Path	Recommended Size	Purpose
/shared	50 GB	Files to serve and share

Deploy Your Application

Click Deploy to start the build process. Klutch.sh will:

• Detect your Dockerfile automatically
• Build the container image
• Attach the persistent volumes
• Start the Gossa container
• Provision an HTTPS certificate

Access Gossa

Once deployment completes, access your Gossa file server at https://your-app-name.klutch.sh. You can immediately start browsing and uploading files.

Using Gossa

Browsing Files

Navigate through your files:

1. Access your Gossa URL
2. Click on folders to navigate into them
3. Click the breadcrumb path to go back
4. Files display with size and modification date

Uploading Files

To upload files (unless in read-only mode):

1. Drag and drop files onto the browser window
2. Or click the upload button to select files
3. Large uploads are resumable - refresh to continue if interrupted

Downloading Files

To download files:

1. Click on a file to download it
2. Or right-click and save link as

Managing Files

Basic file operations (unless in read-only mode):

• Rename: Click the pencil icon next to a file
• Delete: Click the trash icon next to a file
• Create Folder: Click the folder icon in the toolbar

Adding Initial Content

Pre-populating Files

Upload files to your persistent volume before or after deployment:

1. Use web interface to upload files
2. Use file transfer tools to add content directly to the volume
3. Sync files from other sources

Organizing Content

Structure your files logically:

/shared/
├── Documents/
│   ├── Reports/
│   └── Templates/
├── Media/
│   ├── Images/
│   └── Videos/
├── Downloads/
└── Public/

Security Considerations

Access Control

Gossa intentionally doesn’t include authentication. For secure deployments:

• Reverse Proxy Auth: Add HTTP Basic Auth via Nginx or Caddy
• VPN Access: Restrict access to VPN users
• IP Restrictions: Limit access to specific IP addresses

Read-Only Mode

For public file sharing, use read-only mode:

CMD ["-h", "0.0.0.0", "-p", "8001", "-ro", "/shared"]

This prevents:

• File uploads
• File deletions
• File renaming
• Folder creation

HTTPS

Klutch.sh provides HTTPS by default. Always access Gossa over HTTPS.

Sensitive Files

• Don’t store sensitive files without authentication
• Use separate instances for public and private content
• Consider encryption for sensitive data

Adding Authentication

Since Gossa doesn’t include authentication, add it via reverse proxy. Example Nginx configuration:

server {
    listen 80;
    server_name files.example.com;

    auth_basic "File Server";
    auth_basic_user_file /etc/nginx/.htpasswd;

    location / {
        proxy_pass http://localhost:8001;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}

For Klutch.sh deployments, consider deploying a separate auth proxy container.

Troubleshooting Common Issues

Files Not Appearing

Symptoms: Uploaded files don’t show up.

Solutions:

• Refresh the browser page
• Verify the persistent volume is mounted correctly
• Check file permissions
• Ensure you’re not in a different directory

Upload Failures

Symptoms: Cannot upload files.

Solutions:

• Verify you’re not in read-only mode
• Check available disk space
• Try smaller files to test
• Check browser console for errors

Cannot Delete Files

Symptoms: Delete button doesn’t work.

Solutions:

• Verify you’re not in read-only mode
• Check file permissions on the volume
• Ensure the file isn’t locked/in use

Slow Performance

Symptoms: File listing or downloads are slow.

Solutions:

• Reduce number of files per directory
• Increase container resources
• Check persistent volume performance
• Verify network connectivity

Additional Resources

• Gossa GitHub Repository
• Gossa Docker Hub
• Klutch.sh Persistent Volumes
• Klutch.sh Deployments

Conclusion

Deploying Gossa on Klutch.sh gives you a minimal, fast file server with a clean web interface. The combination of Gossa’s simplicity and Klutch.sh’s deployment ease means you can serve files without complex infrastructure.

With its tiny codebase, zero dependencies, and focus on doing one thing well, Gossa is perfect for scenarios where you need a straightforward file server without the overhead of full-featured solutions. Whether you’re sharing documents with a team or hosting files for download, Gossa on Klutch.sh delivers reliable, efficient file serving.