httpserve

README

httpserve

Lightweight file server written in Go. A modern replacement for python3 -m http.server.

Single binary with embedded templates and static assets. Zero external dependencies.

Features

• Partial content (HTTP 206) for range requests
• Directory browsing with list and grid views
• File previews for images, video, audio, markdown, text/code, and PDFs
• Sortable listings by name, size, and modified time
• Client-side search to filter files instantly
• Optional password protection via HTTP Basic Auth
• Show/hide dotfiles toggle
• JSON or text request logging to stdout
• Responsive layout with dark mode support
• Download files via ?download=true
• Download folders as .zip archives via ?download=zip

Install

go build -o httpserve ./cmd/httpserve/

Release tags named v* build Linux, macOS, and Windows archives through GitHub Actions.

Usage

./httpserve [flags]

  --host=0.0.0.0              host or interface to listen on
  --port=8080                 port to listen on
  --directory=.               directory to serve
  --allow=                    allowed client IP or CIDR (repeat or comma-separate)
  --password=                 password for Basic Auth (empty = no auth)
  --password-file=            file containing the Basic Auth password
  --show-hidden=false         show hidden files by default
  --open=false                open the served URL in the default browser
  --quiet=false               suppress startup and request logs
  --version=false             print version information and exit
  --upload=false              enable browser uploads into served directories
  --qr=false                  print a terminal QR code for the share URL
  --log-format=json           request log format: json, text, or none
  --max-preview-bytes=1048576 maximum bytes to read for text-like previews
  --max-upload-bytes=33554432 maximum upload size in bytes
  --read-timeout=0s           maximum duration for reading a full request
  --read-header-timeout=5s    maximum duration for reading request headers
  --write-timeout=0s          maximum duration before timing out response writes
  --idle-timeout=1m           maximum idle keep-alive connection time
  --shutdown-timeout=5s       maximum graceful shutdown duration

Any username works with the password — only the password is validated.

You can also provide the password with the HTTPSERVE_PASSWORD environment variable. Explicit flags take precedence over environment values.

By default, dotfiles are hidden from listings and direct file access. Use --show-hidden or the in-browser hidden-file toggle when you intentionally want to expose them.

Use --allow when you want the server to answer only specific clients:

./httpserve --allow 192.168.1.0/24 --allow 127.0.0.1

Project structure

cmd/httpserve/
  main.go                entry point, flag parsing, server setup

internal/
  access/access.go       IP and CIDR allowlist middleware
  handler/handler.go     request routing, directory listing, file serving, path safety
  auth/auth.go           HTTP Basic Auth middleware (password only)
  browser/browser.go     default browser opener for --open
  config/config.go       CLI flag, environment, and timeout configuration
  logger/logger.go       JSON request logger middleware
  content/
    content.go           go:embed, template loading, content type detection, helpers
    templates/
      layout.html        base HTML layout
      browse.html        directory listing (list/grid, search, toggles)
      preview.html       file preview (image, video, audio, markdown)
    static/
      style.css          minimal responsive CSS with dark mode
      file-icon.svg      file icon
      folder-icon.svg    folder icon
  markdown/markdown.go   minimal markdown-to-HTML renderer

Contributing

1. Fork the repo
2. Create a branch (git checkout -b my-change)
3. Make your changes
4. Run go vet ./... and go build ./cmd/httpserve/ to verify
5. Commit and push
6. Open a pull request

Keep changes small and focused. No new dependencies unless there is a strong reason — the goal is standard library only.