{"id":13645667,"url":"https://github.com/xarantolus/upduck","last_synced_at":"2025-04-21T14:31:58.572Z","repository":{"id":47435047,"uuid":"280512437","full_name":"xarantolus/upduck","owner":"xarantolus","description":"simple web server that integrates with DuckDNS \u0026 Let's Encrypt","archived":true,"fork":false,"pushed_at":"2021-09-07T12:16:04.000Z","size":98,"stargazers_count":99,"open_issues_count":2,"forks_count":0,"subscribers_count":3,"default_branch":"master","last_synced_at":"2024-11-09T18:43:18.642Z","etag":null,"topics":["duckdns","http","http-server","https","https-server","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/xarantolus.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}},"created_at":"2020-07-17T19:50:48.000Z","updated_at":"2024-10-28T18:14:17.000Z","dependencies_parsed_at":"2022-09-23T03:10:13.707Z","dependency_job_id":null,"html_url":"https://github.com/xarantolus/upduck","commit_stats":null,"previous_names":[],"tags_count":5,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xarantolus%2Fupduck","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xarantolus%2Fupduck/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xarantolus%2Fupduck/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xarantolus%2Fupduck/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/xarantolus","download_url":"https://codeload.github.com/xarantolus/upduck/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":250070237,"owners_count":21369841,"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":["duckdns","http","http-server","https","https-server","static-file-server"],"created_at":"2024-08-02T01:02:39.372Z","updated_at":"2025-04-21T14:31:58.318Z","avatar_url":"https://github.com/xarantolus.png","language":"Go","funding_links":[],"categories":["Go"],"sub_categories":[],"readme":"# upduck\nUpduck is a simple HTTP and HTTPS static file server that integrates with [DuckDNS](https://www.duckdns.org/). It is meant for quickly sharing static files beyond your local network over an HTTPS connection but can also be used within your local network (without HTTPS).\n\n**Disclaimer**: This project has no affiliation with DuckDNS or Let's Encrypt and is not endorsed or supported by them.\n\n**Disclaimer**: Using this program with the `-email` flag signifies your acceptance to the [Let's Encrypt's Subscriber Agreement and/or Terms of Service](https://letsencrypt.org/repository/).\n\n### How to use\nThe help section of the program tries to be as helpful as possible, make sure you read the section with examples:\n\n```\n$ upduck -h\nupduck, a simple HTTP and HTTPs file server\n\nCommand-line flags:\n  -dir string\n    \tDirectory that should be served (default \".\")\n  -disallow-listings\n    \tDisable directory listings and downloads\n  -email string\n    \tEmail sent to LetsEncrypt for certificate registration\n  -p int\n    \tHTTP server port (default 8080)\n  -save\n    \tSave the given command line arguments to a config file located in your home directory\n  -site string\n    \tYour duckdns.org subdomain name, e.g. \"test\" for test.duckdns.org\n  -sp int\n    \tHTTPS server port (default 443)\n  -token string\n    \tThe token you get from duckdns.org\n\nExamples:\n  Start a simple HTTP server on the default port:\n\n    \u003e upduck \n\n  Start a simple HTTP server on port 2020 that doesn't show directory listings:\n\n    \u003e upduck -p 2020 -disallow-listings\n\n  Serve files from a specific directory (default is working directory):\n\n    upduck -dir path/to/dir\n\n  Start a HTTP server and a HTTPs server:\n\n    \u003e upduck -email your@email.com -token DuckDNSToken -site mysite\n\n    For this one, your router must forward any incoming connection on a port of your choosing to port 443 (or the one set with the -sp option) of the device upduck runs on. \n    This external chosen port you set in the router must be put after the DuckDNS URL, e.g. https://mysite.duckdns.org:525/ for port 525.\n    If you're not sure about how this works, search for \"port forward tutorial\" and your router model/vendor.\n\n  Start a HTTP server and a HTTPs server on custom ports:\n\n    \u003e upduck -p 2020 -sp 2121 -email your@email.com -token DuckDNSToken -site mysite\n\n    Here, the above notice also applies - ports (in this case 2121) must be forwarded in your router.\n\n  You can also save your configuration so you don't need to type out everything all the time. Just run it normal and add the -save flag:\n\n    \u003e upduck -save -p 2020 -email your@email.com -token DuckDNSToken -site mysite\n\n    This will save your current command line. The next time, you will just need to run upduck without arguments to start the same configuration.\n    You can also add the -p flag without impacting your HTTPs configuration.\n\nUser configuration:\n  Upduck allows protecting your files by creating user accounts from the command-line.\n  \n  Create a new user account (or replace an existing one):\n\n    \u003e upduck adduser \u003cusername\u003e \u003cpassword\u003e\n\n  Delete a user:\n    \n    \u003e upduck deluser \u003cusername\u003e\n    \n  Reset all user data:\n\n    \u003e upduck resetusers\n\n  If any user accounts are configured, you need to log in before accessing files.\n```\n\n### Install\nYou can either compile this program or download a release.\n\n#### Downloading\nYou can [download a version for your system](https://github.com/xarantolus/upduck/releases/latest) and move it anywhere you want. It is recommended to put the executable in a directory from your [`$PATH`](https://superuser.com/a/284351).\n\nOn a Raspberry Pi the following command should download the right executable:\n\n    arch=$(uname -m) \u0026\u0026 wget -O upduck \"https://github.com/xarantolus/upduck/releases/latest/download/upduck-raspberrypi-${arch%l}\"\n\n\nMark it as executable:\n\n    chmod +x upduck\n\nThen move it to your `$PATH` to make it accessible everywhere:\n\n    mv upduck /usr/bin/upduck\n\nNow you should be able to run `upduck` from anywhere. This is especially useful if you set `-dir .` while [saving settings](#saving-settings), as now it always serves directory you're currently in.\n\nIf you want to use ports below `1024` and run `upduck` without root (sudo), you can [set the `CAP_NET_BIND_SERVICE` permission](https://stackoverflow.com/a/414258):\n\n    setcap 'cap_net_bind_service=+ep' /usr/bin/upduck\n\n#### Compiling\nSince this is a normal Go program, compiling works like this:\n\n    go build\n\nIf you're compiling for another operating system, you can set environment variables. You can see the [`release.sh`](release.sh) script to see how it's done for building releases.\n\n\u003cdetails\u003e\u003csummary\u003eYou can also run \u003ccode\u003eupduck\u003c/code\u003e on Android (using \u003ca rel=\"nofollow\" href=\"https://termux.com/\"\u003eTermux\u003c/a\u003e).\u003c/summary\u003e\n\nYou'll likely need root though. I tested this on my phone (which has root), so I'm not 100% sure but it probably doesn't work without. It also doesn't seem to work when cross-compiling from Windows to Android, but when compiling directly on the device it's used on it works.\n\nStart by installing Termux from an app store.\n\n1. After that, you can open Termux and install Go and Git:\n\n```\npkg install golang git\n```\n\nNow the command `go version` should output something like `go version go1.15.3 android/arm64`.\n\n2. Clone this repo and cd into it:\n\n```\ngit clone https://github.com/xarantolus/upduck.git \u0026\u0026 cd upduck\n```\n\n3. Compile the program:\n\n```\ngo build\n```\n\n4. Move it to your `$PATH`:\n\n```\nmv upduck ~/../usr/bin/\n```\n\nNow you can run it just like shown in the help section above.\nPlease also make sure that the Termux app has the storage permission.\n\nI recommend using the [Termux Widget](https://wiki.termux.com/wiki/Termux:Widget) for `upduck`. For that, you can put scripts to start \u0026 stop this server in `~/.shortcuts/tasks`, they could look like this (after configuring this server once with the `-save` flag):\n\nA script to start the server:\n\n`upduck`:\n```sh\n#!/usr/bin/bash\nsudo upduck -dir /storage/emulated/0 # Fill in any path you like\n```\n\nA script to stop the server running in the background:\n\n`stopduck`:\n```sh\n#!/usr/bin/bash\nsudo killall upduck\n```\n\nNow you can tap the widget any time to start/stop the server, which means that you'll never have to get up to find a cable ever again. At least when you're in a network where you configured `upduck` correctly.\n\u003c/details\u003e\n\n### Obtaining a DuckDNS domain and setting up HTTPS\nTo get a DuckDNS subdomain, you'll need to register [on their site](https://www.duckdns.org) and then [create a domain](https://www.duckdns.org/domains). The prefix you type in is the `-site` parameter of your program, your token is for the `-token` option.\n\nNow that we have the domain, we'll need to make sure the router is set up correctly. For this, you'll need to forward a port in your router to port `443` (or the one set with `-sp`) of the device `upduck` is running on. This port will be part of your external address, e.g. `mysite.duckdns.org:port`, where `port` is a number.\n\nWhen you did that, you can run `upduck` like this:\n\n    upduck -email your@email.com -token DuckDNSToken -site mysite\n\nThe email address will be sent to [Let's Encrypt](https://letsencrypt.org/) as part of obtaining an HTTPS certificate.\n\nThis should start a local HTTP web server on port `8080` and an HTTPS server on port `443`. The second one should receive the requests that are forwarded from your router.\n\n### Saving settings\nSince typing out all arguments can become tiresome, you can save them quite easily. They will then be reloaded on the next start.\n\n**Disclaimer**: Writing your credentials to disk is a security risk since other programs might read that file. They could gain control over your DuckDNS account or find out your email address.\n\nTo save settings, just add the `-save` flag to your normal command line. The next time, your credentials will be restored and you don't have to remember them or type them every time.\n\n### Loading settings\nSaved settings are loaded automatically if no new options for DuckDNS are given.\n\nWhen the config file is loaded, the following settings can be overwritten by command line flags: port with `-p` and directory listings with `-disallow-listings`. This means that you can run `upduck -p 2020` to get the local server while *still* getting the DuckDNS server if it was ever set up with `-save`.\n\n### User accounts\nYou can create user accounts to control access as outlined in the \"User configuration\" section of the help output.\nThese accounts are loaded with every start of the server, so you only need to set it up once.\n\nLogging in is done using [HTTP Basic Auth](https://en.wikipedia.org/wiki/Basic_access_authentication). This means that the login duration\ndepends on how long a browser saves the given username/password combination. \n\n### Contributions\nContributions, suggestions, questions and any issue reports are very welcome. Please don't hesistate to ask :)\n\n### [License](LICENSE)\nThis is free as in freedom software. Do whatever you like with it.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fxarantolus%2Fupduck","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fxarantolus%2Fupduck","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fxarantolus%2Fupduck/lists"}