https://github.com/proofrock/fileway
A self hosted real-time file transfer service for CLI or browser
https://github.com/proofrock/fileway
file-transfer homeserver http tunneling
Last synced: 6 months ago
JSON representation
A self hosted real-time file transfer service for CLI or browser
- Host: GitHub
- URL: https://github.com/proofrock/fileway
- Owner: proofrock
- License: apache-2.0
- Created: 2024-11-25T21:17:17.000Z (10 months ago)
- Default Branch: main
- Last Pushed: 2025-03-23T08:37:36.000Z (7 months ago)
- Last Synced: 2025-03-23T09:30:28.179Z (7 months ago)
- Topics: file-transfer, homeserver, http, tunneling
- Language: Go
- Homepage:
- Size: 309 KB
- Stars: 22
- Watchers: 2
- Forks: 1
- Open Issues: 2
-
Metadata Files:
- Readme: README.adoc
- License: LICENSE
Awesome Lists containing this project
README
= 🚠fileway v0.9.0
@proofrock
:toc:
:sectnums:
:source-highlighter: highlightjs
== tl;dr
Fileway is a real-time file transfer service that works through a web browser or command line. It lets two users exchange files through an intermediary server without storing data or requiring direct access to each other's systems - like a live-streaming version of WeTransfer(TM)footnote:[WeTransfer(TM) is a trademark of WeTransfer B.V.].
[NOTE]
====
While it's called _file_-way, it can also transfer text; useful for config snippets or similar.
====
You can jump in following the xref:#TUT[tutorial] or read on for an architectural overview.
== Overview
`fileway` is a client/server application that transfer single files (xref:docs/uploading.adoc#ZIP[well, technically...]) or text snippets. It accepts an upload and blocks it until a download is initiated, then processes the upload and sends the data to the downloading client.
It can be used to relay files (or text) from a server to another, if the two servers can't easily "see" each other but can see a third server, where `fileway` is installed.
.Sequence diagram
image::resources/seq_diagram.png[Sequence diagram]
The transfer is secure: a unique link is generated, and you should only take care to serve it via HTTPS (<>).
Uploads can be done with a web interface - works on mobile, too - or via a python3 script, for shells. Downloads can be done via a browser or using the commandline, e.g. `curl`. The uploading script or web session must be kept online until the transfer is done. Of course, multiple concurrent transfers are possible, and it transfers one file/text at a time.
`fileway` doesn't store anything on the server, it just keeps a buffer to make transfers smooth. It doesn't have any dependency other than `go`. It's distributed as a docker image, but you can easily build it yourself. Also provided, a docker image that includes `caddy` for simple HTTPS provisioning.
xref:docs/server.adoc#RAB[Builds are reproducible].
== Tutorial [[TUT]]
For a quick test, you can run it locally. Prerequisites are `docker`, a file to upload, nothing else.
Run the server:
[source,bash]
----
docker run --rm -p 8080:8080 -e FILEWAY_SECRET_HASHES='$2a$10$I.NhoT1acD9XkXmXn1IMSOp0qhZDd63iSw1RfHZP7nzyg/ItX5eVa' ghcr.io/proofrock/fileway:latest
----
[TIP]
====
The hash is in BCrypt format, so it has some `$`; it must be escaped appropriately. In this case, using single quotes.
====
Then open http://localhost:8080 to access the upload web page. Put `mysecret` as the secret, and choose a file; or select the right radio button and input a text.
Press the Upload button.
In the two boxes that will be displayed, you'll find an URL to be open directly in a browser; and a `curl` commandline to download the file.
[NOTE]
====
You can use anything to download a file URL, as long as it supports taking the filename from the `Content-Disposition` header. That's the `-J` switch for `curl` and the `--content-disposition` one for `wget` (still marked experimental).
====
== Documentation
* xref:docs/server.adoc[About the *server*] and how to configure it, build it and add a reverse proxy;
* xref:docs/uploading.adoc[About the *upload* methods], which one to choose and how to use them best;
* xref:docs/downloading.adoc[About the *download* links] and all the design choices.
Let me know if you need more info!