mirror-yaf/README.md

# jaf - Just Another Fileshare
jaf is a simple, zero-dependency Go program to handle file uploads.
If you also want to serve the uploaded files, consider a web server like [nginx](https://nginx.org/en/).

## Installation
**Clone** the directory:
```bash
git clone https://github.com/leon-richardt/jaf.git
```
**Build** the executable:
```bash
go build
```
Run **tests** (optional):
```bash
go test
```

If you plan on using a systemd service or another init system, you might want to move the `jaf` executable to a different directory (e.g. `/opt`) at this point; you know your setup best.

## Configuration
### jaf
There are just a few parameters that need to be configured for jaf.
Refer to the `example.conf` file:
```
Port:       4711
# a comment
LinkPrefix: https://jaf.example.com/
FileDir:    /var/www/jaf.example.com/
LinkLength: 5
```

Option       | Use
------------ | -------------------------------------------------------------------
`Port`       | the port number jaf will listen on
`LinkPrefix` | a string that will be prepended to the file name generated by jaf
`FileDir`    | path to the directory jaf will save uploaded files in
`LinkLength` | the number of characters the generated file name is allowed to have

Make sure the user running jaf has suitable permissions to read, and write to, `FileDir`.
Also note that `LinkLength` directly relates to the number of files that can be saved.
Since jaf only uses alphanumeric characters for file name generation, a maximum of `(26 + 26 + 10)^LinkLength` names can be generated.

### nginx
If you use a reverse-proxy to forward requests to jaf, make sure to correctly forward the original request headers.
For nginx, this is achieved via the `proxy_pass_request_headers on;` option.

If you want to limit access to jaf (e.g. require basic authentication), you will also need to do this via your reverse-proxy.

## Running
After adjusting the configuration file to your needs, run:
```bash
jaf -configFile example.conf
```
Of course, you can also write a init system script to handle this for you.

### Running from Docker
Running it from the GitHub Container Registry
```bash
docker run \
    -p 4712:4711 \
    -v /path/to/your/config.conf:/app/jaf.conf \
    -v /path/to/where/you/want/your/files/to/be/stored:/FileDir/in/your/config \
    ghcr.io/leon-richardt/jaf:latest
```

Building the Docker image and running it locally
```bash
docker build -t jaf .
docker run \
    -p 4712:4711 \
    -v /path/to/your/config.conf:/app/jaf.conf \
    -v /path/to/where/you/want/your/files/to/be/stored:/FileDir/in/your/config \
    jaf
```

Port 4711 is the default port for the server in `example.conf`, if you've changed this in your config you'll need to change this in the `docker run` invocations above too.  
The above runs forwards the jaf port from 4711 in the container to 4712 on your local system.

## Usage
You can use jaf with any application that can send POST requests (e.g. ShareX/ShareNix or just `curl`).
Make sure the file you want to upload is attached as a `multipart/form-data` field named `file`.
In `curl`, a request to upload the file `/home/alice/foo.txt` could look like this:
```bash
curl -L -F "file=@/home/alice/foo.txt" jaf.example.com/upload
```
The response will include a link to the newly uploaded content.
Note that you may have to add additional header fields to the request, e.g. if you have basic authentication enabled.

## Inspiration
- [i](https://github.com/fourtf/i) by [fourtf](https://github.com/fourtf) – a project very similar in scope and size
- [filehost](https://github.com/nuuls/filehost) by [nuuls](https://github.com/nuuls) – a more integrated, fully-fledged solution that offers a web interface and also serves the files