Deploying miniserve

Introduction

miniserve is a fast, minimal file server written in Rust that makes sharing files over HTTP effortless. With a clean, responsive interface and no configuration required, miniserve transforms any directory into a browsable file server in seconds.

Unlike heavyweight file servers, miniserve focuses on doing one thing extremely well: serving files quickly and beautifully. It’s perfect for temporary file sharing, hosting static websites, or providing simple file access to a directory.

Key highlights of miniserve:

• Lightning Fast: Written in Rust for maximum performance
• Beautiful Interface: Clean, responsive file listing with icons
• Zero Configuration: Works out of the box
• File Upload: Optional upload support for receiving files
• QR Codes: Generate QR codes for easy mobile access
• Authentication: Optional username/password protection
• Directory Indexing: Automatic index.html detection
• Archive Downloads: Download directories as ZIP/TAR
• CORS Support: Enable cross-origin requests
• Color Themes: Multiple color schemes available
• Single Binary: No dependencies, easy deployment
• 100% Open Source: MIT licensed

This guide walks through deploying miniserve on Klutch.sh using Docker, configuring file serving, and enabling optional features.

Why Deploy miniserve on Klutch.sh

Deploying miniserve on Klutch.sh provides several advantages:

Simple File Hosting: Share files with a direct URL and clean interface.

Static Site Hosting: Serve static websites with minimal overhead.

Persistent Storage: Files survive restarts and redeployments.

HTTPS by Default: Secure file access with automatic SSL certificates.

Minimal Resources: Rust efficiency means lower hosting costs.

Custom Domains: Serve files from your own domain.

Prerequisites

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

• A Klutch.sh account
• A GitHub account with a repository for your configuration
• Files or a static website to serve
• Basic familiarity with Docker

Understanding miniserve Architecture

miniserve has an extremely simple architecture:

Rust HTTP Server: Handles all HTTP requests with high performance.

File System Access: Directly serves files from the specified directory.

Template Engine: Renders the beautiful file listing interface.

Optional Features: Upload, auth, and other features enabled by flags.

Preparing Your Repository

Create a GitHub repository for your miniserve deployment.

Repository Structure

miniserve-deploy/
├── Dockerfile
├── public/
│   └── index.html (optional)
├── README.md
└── .dockerignore

Creating the Dockerfile

Create a Dockerfile in the root of your repository:

FROM docker.io/svenstaro/miniserve:latest

# Create data directory
RUN mkdir -p /data

# Set default serving directory
WORKDIR /data

# Expose the web server port
EXPOSE 8080

# Serve files with directory listing
ENTRYPOINT ["miniserve"]
CMD ["--port", "8080", "--interfaces", "0.0.0.0", "/data"]

Dockerfile with Upload Support

Enable file uploads:

FROM docker.io/svenstaro/miniserve:latest

# Create data directory
RUN mkdir -p /data

WORKDIR /data

EXPOSE 8080

# Enable uploads and directory listing
ENTRYPOINT ["miniserve"]
CMD ["--port", "8080", "--interfaces", "0.0.0.0", "--upload-files", "/data"]

Dockerfile with Authentication

Password protect your files:

FROM docker.io/svenstaro/miniserve:latest

# Create data directory
RUN mkdir -p /data

WORKDIR /data

EXPOSE 8080

# Enable authentication
# Username and password passed via environment
ENTRYPOINT ["sh", "-c", "miniserve --port 8080 --interfaces 0.0.0.0 --auth ${MINISERVE_USER}:${MINISERVE_PASSWORD} /data"]

Full-Featured Dockerfile

All common options enabled:

FROM docker.io/svenstaro/miniserve:latest

# Create data directory
RUN mkdir -p /data

WORKDIR /data

EXPOSE 8080

# Start script with configurable options
COPY <<'EOF' /start.sh
#!/bin/sh
ARGS="--port 8080 --interfaces 0.0.0.0"

# Authentication
if [ -n "$MINISERVE_USER" ] && [ -n "$MINISERVE_PASSWORD" ]; then
    ARGS="$ARGS --auth ${MINISERVE_USER}:${MINISERVE_PASSWORD}"
fi

# Upload support
if [ "$MINISERVE_UPLOAD" = "true" ]; then
    ARGS="$ARGS --upload-files"
fi

# Show hidden files
if [ "$MINISERVE_HIDDEN" = "true" ]; then
    ARGS="$ARGS --hidden"
fi

# QR code
if [ "$MINISERVE_QR" = "true" ]; then
    ARGS="$ARGS --qrcode"
fi

# Color scheme
if [ -n "$MINISERVE_COLOR" ]; then
    ARGS="$ARGS --color-scheme $MINISERVE_COLOR"
fi

exec miniserve $ARGS /data
EOF

RUN chmod +x /start.sh

ENTRYPOINT ["/start.sh"]

Environment Variables Reference

Variable	Required	Default	Description
MINISERVE_USER	No	-	Username for authentication
MINISERVE_PASSWORD	No	-	Password for authentication
MINISERVE_UPLOAD	No	false	Enable file uploads
MINISERVE_HIDDEN	No	false	Show hidden files
MINISERVE_QR	No	false	Show QR code in terminal
MINISERVE_COLOR	No	squirrel	Color scheme (archlinux, monokai, squirrel, zenburn)

Deploying miniserve on Klutch.sh

Prepare Your Files

Organize the files you want to serve:

public/
├── index.html
├── styles.css
├── images/
│   └── logo.png
└── downloads/
    └── document.pdf

Push Your Repository to GitHub

Initialize and push your repository:

git init
git add Dockerfile .dockerignore README.md public/
git commit -m "Initial miniserve deployment"
git remote add origin https://github.com/yourusername/miniserve-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 named “miniserve” or “files”.

Create a New App

Within your project, create a new app. Connect your GitHub account and select the repository containing your Dockerfile.

Configure HTTP Traffic

In the deployment settings:

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

Set Environment Variables (optional)

For authentication or features:

Variable	Value
MINISERVE_USER	Your username
MINISERVE_PASSWORD	Your password
MINISERVE_UPLOAD	true (if enabling uploads)
MINISERVE_COLOR	squirrel (or your preferred theme)

Attach Persistent Volumes

Add storage for your files:

Mount Path	Recommended Size	Purpose
/data	Varies	Your file storage

Deploy Your Application

Click Deploy to start the build process.

Access miniserve

Once deployed, access your file server at https://your-app-name.klutch.sh.

Using miniserve

Browsing Files

Navigate your files through the web interface:

• Click folders to enter
• Click files to download
• Use breadcrumbs to navigate up
• Sort by name, size, or date

Downloading Files

Download individual files or entire directories:

• Click any file to download
• Click the archive icon to download folders as ZIP

Uploading Files

If uploads are enabled:

1. Navigate to the target directory
2. Drag and drop files
3. Or use the upload button
4. Files appear after upload

Static Website Hosting

Serving a Static Site

miniserve automatically serves index.html:

/data/
├── index.html    <- Served at /
├── about.html    <- Served at /about.html
├── css/
│   └── style.css
└── js/
    └── app.js

Single Page Applications

For SPAs with client-side routing, miniserve works with hash-based routing:

<!-- Use hash-based routing -->
<a href="#/about">About</a>

Color Themes

Choose from available color schemes:

Theme	Description
archlinux	Arch Linux colors
monokai	Monokai dark theme
squirrel	Default warm theme
zenburn	Low-contrast dark theme

Set via environment variable or command line:

miniserve --color-scheme monokai /data

Security Features

Authentication

Protect files with basic auth:

miniserve --auth user:password /data

Multiple users:

miniserve --auth user1:pass1 --auth user2:pass2 /data

Hiding Files

Control file visibility:

• Hidden files (starting with .) are hidden by default
• Use --hidden to show them

Advanced Configuration

Custom Headers

Add custom HTTP headers:

miniserve --header "Cache-Control: max-age=3600" /data

CORS Support

Enable cross-origin requests:

miniserve --enable-cors /data

Markdown Rendering

Render Markdown files as HTML:

miniserve --render-markdown /data

Troubleshooting

Files Not Appearing

• Verify files are in the correct directory
• Check file permissions
• Ensure volume is mounted correctly

Upload Failures

• Confirm --upload-files is enabled
• Check available storage space
• Verify write permissions

Authentication Issues

• Check username and password are correct
• Verify environment variables are set
• Test credentials in a new browser

Additional Resources

• miniserve GitHub Repository
• miniserve Documentation
• miniserve Docker Hub
• Klutch.sh Persistent Volumes
• Klutch.sh Deployments

Conclusion

Deploying miniserve on Klutch.sh gives you a lightning-fast, beautiful file server with zero configuration. Whether you’re sharing files, hosting a static website, or setting up a simple file upload server, miniserve’s Rust-powered performance and elegant interface make file serving effortless.

Serve your files with style using miniserve on Klutch.sh.