{"id":13694004,"url":"https://github.com/philippgille/serve","last_synced_at":"2025-04-25T17:30:28.654Z","repository":{"id":91058691,"uuid":"131625363","full_name":"philippgille/serve","owner":"philippgille","description":"serve starts a simple temporary static file server in your current directory and prints your IP address to share with colleagues","archived":false,"fork":false,"pushed_at":"2023-04-21T07:23:21.000Z","size":228,"stargazers_count":156,"open_issues_count":12,"forks_count":16,"subscribers_count":9,"default_branch":"master","last_synced_at":"2025-04-04T00:51:12.601Z","etag":null,"topics":["cli","file-server","go","golang","serve","server","static-file-server","static-files"],"latest_commit_sha":null,"homepage":null,"language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mpl-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/philippgille.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":".github/CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":".github/CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":".github/SUPPORT.md","governance":null,"roadmap":null,"authors":null}},"created_at":"2018-04-30T17:25:29.000Z","updated_at":"2025-02-08T20:32:39.000Z","dependencies_parsed_at":null,"dependency_job_id":"8bfebaf0-2b11-4348-a8a4-043f8af5aaa8","html_url":"https://github.com/philippgille/serve","commit_stats":null,"previous_names":[],"tags_count":6,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/philippgille%2Fserve","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/philippgille%2Fserve/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/philippgille%2Fserve/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/philippgille%2Fserve/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/philippgille","download_url":"https://codeload.github.com/philippgille/serve/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":250861854,"owners_count":21499181,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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":["cli","file-server","go","golang","serve","server","static-file-server","static-files"],"created_at":"2024-08-02T17:01:22.222Z","updated_at":"2025-04-25T17:30:28.396Z","avatar_url":"https://github.com/philippgille.png","language":"Go","funding_links":[],"categories":["Go"],"sub_categories":[],"readme":"serve\n=====\n\nWindows | macOS | Linux\n--------|-------|------\n[![Build status](https://ci.appveyor.com/api/projects/status/nt16vsv7j1yk9yo2/branch/master?svg=true)](https://ci.appveyor.com/project/philippgille/serve/branch/master) | [![Build Status](https://travis-ci.org/philippgille/serve.svg?branch=master)](https://travis-ci.org/philippgille/serve/branches) | [![CircleCI](https://circleci.com/gh/philippgille/serve.svg?style=svg)](https://circleci.com/gh/philippgille/serve)\n\n[![GitHub Releases](https://img.shields.io/github/release/philippgille/serve.svg)](https://github.com/philippgille/serve/releases)\n\n`serve` starts a simple temporary static file server in your current directory and prints your IP address to share with colleagues.\n\nIt was based on [a Gist](https://gist.github.com/paulmach/7271283/2a1116ca15e34ee23ac5a3a87e2a626451424993) by [Paul Mach](https://github.com/paulmach), but has evolved a lot.\n\nContents\n--------\n\n- [Features](#features)\n  - [Roadmap](#roadmap)\n- [Install](#install)\n    - [Windows](#windows)\n    - [macOS](#macos)\n    - [Linux](#linux)\n    - [Manually](#manually)\n- [Docker](#docker)\n- [Use](#use)\n    - [Example](#example)\n- [Build](#build)\n    - [Packages](#packages)\n- [Related projects](#related-projects)\n\nFeatures\n--------\n\n- [X] Serves static files in any given accessible directory until you hit `Ctrl-C`\n- [X] Prints a table of your network interfaces and their IP addresses and guesses which one you most likely want to share\n- [X] Follows softlinks transparently\n- [X] Optional basic authentication\n- [X] Optionally serve files via HTTPS instead of HTTP, using a temporary self signed certificate that's automatically generated for you on the fly\n- [X] Optionally bind to a specific network interface, for example `localhost` to disable access from other devices\n- [X] Only uses the Go standard library and no external dependencies\n- [X] Single file executable, usable without any installation, or easy automatic updates when using a package manager\n\n### Roadmap\n\n- Find out and print external IP address that's reachable from the Internet\n- Optionally compress files when requested\n- Optionally make your server reachable from the Internet even if it's behind a router with NAT\n  - Via reverse SSH tunnel\n  - Via 3rd party service like [ngrok](https://ngrok.com/), [https://localtunnel.me](https://localtunnel.me), [LabStack Tunnel](https://labstack.com/docs/tunnel) etc.\n  - Via [frp](https://github.com/fatedier/frp)\n- Optionally run a [Tor](https://www.torproject.org/) hidden service (v3) for:\n  - Automatic accessibility from the Internet (via Tor Browser or proxy) even when behind a router with NAT\n  - Encrypted traffic\n  - No exposure of your IP address\n\nInstall\n-------\n\nWe recommend installing `serve` with one of the following package managers, because they provide you with functionality such as automatic updates, instant availability as command in the `PATH`, easy removal, sandboxing (depending on the package manager) etc.  \nBut alternatively you can always install `serve` manually as well, see [Manually](#manually).\n\n### Windows\n\nThe easiest way is to use the package manager [Scoop](http://scoop.sh/):  \n`scoop install serve`\n\nAnother option is [Chocolatey](https://chocolatey.org/):  \n`choco install serve`\n\nYou can also have a look at the description in the Chocolatey Gallery on [https://chocolatey.org/packages/serve/](https://chocolatey.org/packages/serve/).\n\n### macOS\n\nThe easiest way is to use the package manager [Homebrew](https://brew.sh/):  \n`brew tap philippgille/tap`  \n`brew install serve`\n\nOr in a single command:  \n`brew install philippgille/tap/serve`\n\n### Linux\n\nThe easiest way is to use the package manager [Snap](https://snapcraft.io/), which is installed by default on Ubuntu 16.04 and later:  \n`snap install serve`\n\nYou can also have a look at the description in the Snap Store on [https://snapcraft.io/serve](https://snapcraft.io/serve).\n\n\u003e Note: Due to sandboxing by Snap, `serve` can only serve files in the user's `$HOME` directory.\n\n### Manually\n\n#### With Go installed\n\n`go get -u github.com/philippgille/serve`\n\n\u003e Note: Requires your `$GOPATH/bin` directory to be in your `PATH`, which is usually the case.\n\n#### Without Go installed\n\nYou can download the binary for your OS from the [releases](https://github.com/philippgille/serve/releases) simply make it available as command in your `PATH`. See [Manual Installation](https://github.com/philippgille/serve/tree/master/docs#manual-installation) for details.\n\nDocker\n------\n\n`serve` is also available as Docker image in the Docker Hub: [https://hub.docker.com/r/philippgille/serve/](https://hub.docker.com/r/philippgille/serve/)\n\nPlease read [docker/README.md](https://github.com/philippgille/serve/blob/master/docker/README.md) for information on how to use it.\n\nUse\n---\n\n```\n$ serve -h\nUsage of serve:\n  -a string\n        Require basic authentication with the given credentials (e.g. -a \"alice:secret\")\n  -b string\n        Bind to (listen on) a specific interface. \"0.0.0.0\" is for ALL interfaces. \"localhost\" disables access from other devices. (default \"0.0.0.0\")\n  -d string\n        The directory of static files to host (default \".\")\n  -h    Print the usage\n  -p string\n        Port to serve on. 8080 by default for HTTP, 8443 for HTTPS (when using the -s flag) (default \"8080\")\n  -s    Serve via HTTPS instead of HTTP. Creates a temporary self-signed certificate for localhost, 127.0.0.1, \u003chostname\u003e.local, \u003chostname\u003e.lan, \u003chostname\u003e.home and the determined LAN IP address\n  -t    Test / dry run (just prints the interface table)\n  -v    Print the version\n```\n\nPress `Ctrl+C` in the terminal to stop the server.\n\n### Example\n\n```bash\n~/path/to/servable/files$ serve\n\nServing \".\" on all network interfaces (0.0.0.0) on HTTP port: 8080\n\nLocal network interfaces and their IP address so you can pass one to your colleagues:\n\n      Interface      |  IPv4 Address   |              IPv6 Address\n---------------------|-----------------|----------------------------------------\nlo                   | 127.0.0.1       | ::1\neth0                 |                 | \nwlan0                | 192.168.178.123 | fe80::e7b:fdaf:ae5d:3cfa\nvirbr0               | 192.168.122.1   | \nbr-8ef347e8a4e9      | 172.22.0.1      | fe80::42:c9ff:fed3:35a\ndocker_gwbridge      | 172.21.0.1      | \ndocker0              | 172.17.0.1      | fe80::42:c6cf:fe3d:a554\nveth0d522f4          |                 | fe80::307a:7fcf:fe3d:cba4\n\nYou probably want to share:\nhttp://192.168.178.123:8080\n```\n\nWhen opening the URL `http://192.168.178.123:8080` in a browser you see the directory you're serving. For example:\n\n![screenshot](assets/example-2-browser.png)\n\nBuild\n-----\n\nTo build `serve` by yourself:\n\n1. [Install Go](https://golang.org/doc/install)\n2. `cd` into the root directory of this repository\n3. Execute: `go build`\n\n\u003e Note: The binaries in GitHub Releases are shrinked with additional Go linker flags and UPX\n\nTo also make `serve` available as command in other directories:\n\n1. Add `$GOPATH/bin` to your `PATH` if you haven't done that already when installing Go\n2. Execute: `go install`\n\nThere are also build scripts for Windows and Linux for creating release artifacts (shrinked binaries for Windows, macOS and Linux):\n\n- Windows: `build/build.ps1`\n- Linux: `build/build.sh`\n\n\u003e Note: They require Go and UPX to be installed\n\nTo build with a Docker container:\n\n`docker run --rm -v $(pwd):/go/src/github.com/philippgille/serve -w /go/src/github.com/philippgille/serve golang build/build.sh noupx`  \nOr with UPX:  \n`docker run --rm -v $(pwd):/go/src/github.com/philippgille/serve -w /go/src/github.com/philippgille/serve golang bash -c \"apt update \u0026\u0026 apt install -y upx-ucl \u0026\u0026 build/build.sh\"`\n\n\u003e Note: You have to use `${pwd}` instead of `$(pwd)` on Windows.\n\n### Packages\n\nFor Scoop and Homebrew no packages need to be built. They use \"manifests\"/\"formulae\" and the binaries from GitHub Releases.\n\nFor releasing a new version, they need to be updated here:\n\n- Scoop: [https://github.com/lukesampson/scoop/blob/master/bucket/serve.json](https://github.com/lukesampson/scoop/blob/master/bucket/serve.json)\n- Homebrew: [https://github.com/philippgille/homebrew-tap/blob/master/serve.rb](https://github.com/philippgille/homebrew-tap/blob/master/serve.rb)\n\nFor Snap a Git hook is set up in the Snapcraft dashboard to automatically build a new Snap on every commit, so for releasing a new version the file in *this* repository needs to be updated:\n\n- Snap: [https://github.com/philippgille/serve/blob/master/snap/snapcraft.yaml](https://github.com/philippgille/serve/blob/master/snap/snapcraft.yaml)\n\nThe Snap package can also be built manually. In the past this could even be done within a Docker container, but the [official Snapcraft Docker image](https://hub.docker.com/u/snapcoret/snapcraft) (according to the [docs](https://docs.snapcraft.io/build-on-docker/4158)) is outdated (as of 2019-05-01) and doesn't contain the latest version of `snapcraft` (and installing the latest version via `snap` itself, as you'd do nowadays according to the official docs, doesn't work).  \nSo now you can only build the Snap package on Linux, using the following steps:\n\n1. `snap install snapcraft --classic`\n2. `snapcraft`\n\nDepending on the current `serve` version and your CPU's architecture it will create a file like `serve_0.3.2_amd64.snap`, which can manually be installed with `snap install --dangerous serve_0.3.2_amd64.snap`.\n\nThe Chocolatey packages need to be uploaded manually to Chocolatey [here](https://chocolatey.org/packages/upload). The package can be built with this script:\n\n- Windows: `build\\build-chocolatey.ps1`\n\nThe Docker image can be built like this:\n\n`docker build -f docker/Dockerfile -t philippgille/serve .`\n\nRelated projects\n----------------\n\n- `python -m SimpleHTTPServer 8080`\n  - Con: Requires Python, no option to require authentication, no HTTPS\n- [https://github.com/indexzero/http-server](https://github.com/indexzero/http-server)\n  - Pro: Popular (8200 GitHub stars as of 2019-05-02), mature, feature-rich\n  - Con: Requires Node.js\n- [https://github.com/zeit/serve](https://github.com/zeit/serve)\n  - Pro: Popular (4200 GitHub stars as of 2019-05-02), mature\n  - Con: Requires Node.js, no option to require authentication, no HTTPS, can't serve directories other than the current working directory\n- [https://github.com/codeskyblue/gohttpserver](https://github.com/codeskyblue/gohttpserver)\n  - Pro: Nice web UI, shows QR codes for downloading files from a smartphone, OpenID and OAuth2 authentication, optional upload of files from a client, `README.md` preview, directory zip download any many more features\n  - Con: Too many features (\"[feature creep](https://en.wikipedia.org/wiki/Feature_creep)\")? Many dependencies.\n- [https://github.com/syntaqx/serve](https://github.com/syntaqx/serve)\n  - Con: No option to require authentication, no installation packages for Windows or Linux\n- [https://github.com/rhardih/serve](https://github.com/rhardih/serve)\n  - Con: No option to require authentication, no installation packages, no HTTPS when _not_ using HTTP/2, when using HTTP/2 the certificate and private key are written to disk in the current working directory, *which is served by default*, so an attacker can easily download and use them in a Man-in-the-Middle attack without the client noticing (because it's the correct certificate) (as of 2019-05-05 - I created [an issue](https://github.com/rhardih/serve/issues/3) for that and hope it gets fixed soon)\n- Many others!\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fphilippgille%2Fserve","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fphilippgille%2Fserve","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fphilippgille%2Fserve/lists"}