{"id":50356888,"url":"https://github.com/zhufuyi/stasrv","last_synced_at":"2026-05-29T23:04:29.441Z","repository":{"id":360681474,"uuid":"1245802712","full_name":"zhufuyi/stasrv","owner":"zhufuyi","description":"Lightweight single-binary static file server built with Gin for serving frontend assets in containers, microservices, and local development.","archived":false,"fork":false,"pushed_at":"2026-05-27T11:31:02.000Z","size":46,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-27T13:21:32.180Z","etag":null,"topics":["containers","gin","lightweight","microservices","single-binary","static-file-server"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/zhufuyi.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-21T15:12:59.000Z","updated_at":"2026-05-27T11:32:02.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/zhufuyi/stasrv","commit_stats":null,"previous_names":["zhufuyi/stasrv"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/zhufuyi/stasrv","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zhufuyi%2Fstasrv","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zhufuyi%2Fstasrv/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zhufuyi%2Fstasrv/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zhufuyi%2Fstasrv/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/zhufuyi","download_url":"https://codeload.github.com/zhufuyi/stasrv/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zhufuyi%2Fstasrv/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33673665,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-05-29T02:00:06.066Z","response_time":107,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["containers","gin","lightweight","microservices","single-binary","static-file-server"],"created_at":"2026-05-29T23:04:28.569Z","updated_at":"2026-05-29T23:04:29.425Z","avatar_url":"https://github.com/zhufuyi.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"## English | [中文](readme-cn.md)\n\n\u003cdiv align=\"center\"\u003e\n\n[![Go Report](https://goreportcard.com/badge/github.com/zhufuyi/stasrv)](https://goreportcard.com/report/github.com/zhufuyi/stasrv)\n[![codecov](https://codecov.io/gh/zhufuyi/stasrv/branch/main/graph/badge.svg)](https://codecov.io/gh/zhufuyi/stasrv)\n[![Go Reference](https://pkg.go.dev/badge/github.com/zhufuyi/stasrv.svg)](https://pkg.go.dev/github.com/zhufuyi/stasrv)\n[![CI](https://github.com/zhufuyi/stasrv/actions/workflows/ci.yml/badge.svg)](https://github.com/zhufuyi/stasrv/actions)\n[![License: MIT](https://img.shields.io/github/license/zhufuyi/stasrv)](https://github.com/zhufuyi/stasrv/blob/main/LICENSE)\n\n\u003c/div\u003e\n\n---\n\n`stasrv` is a lightweight static file server built on [Gin](https://github.com/gin-gonic/gin) and distributed as a single binary.  \nIt can run as a standalone service, easily replacing proxies like Nginx to host front-end static assets (HTML, CSS, JS, images, etc.). It is especially suitable for microservice architectures, containerized deployments, or local development scenarios.\n\n## Features\n\n- **Zero-Dependency Deployment**: Compiles into a single executable binary with no runtime dependencies.\n- **Minimalist Configuration**: Simply specify the static file directory to get started.\n- **Flexible Routing**: Supports custom URL base paths, making it easy to mount the service under a subpath.\n- **Configurable Port**: Defaults to 8080, but can be changed to any port.\n- **Production Ready**: Graceful shutdown, suitable for direct exposure or use behind a reverse proxy.\n- **Lightweight \u0026 Efficient**: Powered by Gin's high-performance HTTP engine with minimal resource footprint.\n\n## Installation\n\n```bash\ngo install github.com/zhufuyi/stasrv/cmd/stasrv@latest\n```\n\nAfter installation, ensure that `$GOPATH/bin` is added to your system's `PATH` environment variable, then you can run the `stasrv` command directly.\n\nAlternatively, you can download pre-compiled binaries from the [Releases](https://github.com/zhufuyi/stasrv/releases) page.\n\n## Quick Start\n\n```bash\n# Specify the directory\nstasrv --dir=/var/www/html\n```\n\nOpen your browser and navigate to `http://localhost:8080` to see your `index.html` page.\n\n## Command-Line Arguments\n\n|**Argument**|**Type**|**Default**|**Description**|\n|---|---|---|---|\n|`--dir`|string|`.`|Path to the static file root directory (Required)|\n|`--base-path`|string|`/`|Base URL path. For example, `/app` will mount files under `/app/`|\n|`--cache-age`|int|`31536000`|Seconds for static asset `Cache-Control: max-age` (0 means no cache header)|\n|`--port`|int|`8080`|HTTP service listening port|\n\nFile Caching Strategy:\n\n- Images: Cached\n- JS/CSS with hash: Cached\n- JS/CSS without hash: Not cached\n- HTML: Not cached\n\nExample:\n\n```bash\n# Listen on port 3000, static directory set to ./public, base path set to /static, cache for 1 hour\nstasrv --dir=./public --port=3000 --base-path=/static --cache-age=3600\n```\n\nYou can now access your files via `http://localhost:3000/static/`.\n\n## Docker Deployment\n\n1. Run with Docker CLI\n\n```bash\ndocker run -d \\\n  -p 8080:8080 \\\n  -v $(pwd)/dist:/app/dist \\\n  zhufuyi/stasrv:latest \\\n  --dir=/app/dist --base-path=/app\n```\n\n2. Run with Docker Compose\n\n```yaml\nservices:\n  stasrv:\n    image: zhufuyi/stasrv:latest\n    restart: unless-stopped\n    init: true\n    volumes:\n      - /etc/localtime:/etc/localtime:ro     # Host machine timezone\n      - ./dist:/app/dist:ro                        # Map static assets\n    command:\n      - \"--dir=/app/dist\"      # Website static assets path\n      - \"--base-path=/app\"  # URL prefix\n\n    ports:\n      - 8080:8080\n```\n\nRun `docker-compose up -d` to start the service.\n\nAccess `http://localhost:8080/app/` to view the `index.html` page.\n\n## Comparison with Nginx\n\n|**Scenario**|**stasrv**|**Nginx**|\n|---|---|---|\n|Installation Size|~10 MB single file|A few MBs + dependencies|\n|Config Complexity|Single command|Requires writing `nginx.conf`|\n|Dynamic Routing|Supported via `--base-path`|Configured via `location` directives|\n|Cache Control|One-click `max-age` configuration|Requires manual `expires` headers|\n|Best Used For|Microservice stasrv, local debugging, containerized environments|General reverse proxy, high concurrency scenarios|\n\n`stasrv` is not intended to fully replace Nginx. Instead, it provides a **lighter, zero-configuration** alternative that significantly simplifies deployment in scenarios where complex reverse proxy rules are not required.\n\n## Contributing\n\nIssues and Pull Requests are welcome!\n\nIf you have great ideas or find a bug, please join the discussion on [GitHub Issues](https://github.com/zhufuyi/stasrv/issues).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzhufuyi%2Fstasrv","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fzhufuyi%2Fstasrv","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzhufuyi%2Fstasrv/lists"}