mirror of https://github.com/Superioz/aqua.git
Add more documentation
This commit is contained in:
parent
1f26fdf87e
commit
e1d6b2f60c
|
@ -1,5 +1,5 @@
|
|||
AUTH_CONFIG_PATH=
|
||||
AUTH_CONFIG_PATH=./auth.yml
|
||||
FILE_STORAGE_PATH=
|
||||
FILE_NAME_LENGTH=
|
||||
FILE_NAME_LENGTH=12
|
||||
FILE_META_DB_PATH=
|
||||
FILE_EXPIRATION_CYCLE=
|
||||
FILE_EXPIRATION_CYCLE=10
|
||||
|
|
94
README.md
94
README.md
|
@ -1,10 +1,84 @@
|
|||
# aqua
|
||||
|
||||
<img src="./.github/assets/aqua_banner.png" height="160" />
|
||||
|
||||
---
|
||||
|
||||
**aqua** is a simple file uploading and sharing server for personal use. It is built to be easy to set up and host on your own server, for example to use it in combination with
|
||||
uploading tools like [ShareX](https://getsharex.com/).
|
||||
|
||||
It is the successor/rework of my previous project [lightf](https://github.com/Superioz/lightf), but this time without trying weird things out and building a complete product instead.
|
||||
# aqua
|
||||
|
||||
<img src="./.github/assets/aqua_banner.png" height="160" />
|
||||
|
||||
---
|
||||
|
||||
**aqua** is a simple file uploading and sharing server for personal use. It is built to be easy to set up and host on your own server, for example to use it in combination with
|
||||
uploading tools like [ShareX](https://getsharex.com/).
|
||||
|
||||
It is the successor/rework of my previous project [lightf](https://github.com/Superioz/lightf), but this time without trying weird things out and building a complete product instead.
|
||||
|
||||
# Installation
|
||||
|
||||
There are as always multiple ways to install the server. The recommended way is to use Docker Compose or deploy it to Kubernetes, but we start with the manual way.
|
||||
|
||||
## Manual
|
||||
|
||||
- download the specific binary from the latest release
|
||||
- rename it however you want
|
||||
- create an auth.yml
|
||||
- do the rest of the configuration like described below (creating environment variables and such)
|
||||
- start the server and open port 8765 to the outside world from your server/machine
|
||||
|
||||
## Docker Compose
|
||||
|
||||
- install docker and docker-compose on your machine
|
||||
- git clone the repository
|
||||
- edit the auth.yml (it has to be in the same directory as the docker-compose)
|
||||
- edit the .env.dist -> rename it to .env and edit it however you want (see Configuration)
|
||||
- `docker-compose up`
|
||||
|
||||
## Kubernetes
|
||||
|
||||
TBD
|
||||
|
||||
# Configuration
|
||||
|
||||
## Environment Variables
|
||||
|
||||
For examplary usage of the environment variables, have a look at the `.env.dist` file in the root directory of the repository.
|
||||
|
||||
| Variable | Description |
|
||||
| -------- | ----------- |
|
||||
| `AUTH_CONFIG_PATH` | Path to the `auth.yml` config file. |
|
||||
| `FILE_STORAGE_PATH` | Path to the directory, where the files should be stored. |
|
||||
| `FILE_NAME_LENGTH` | Length of the file names, that should be randomly generated. Should be long enough to make guessing impossible. |
|
||||
| `FILE_META_DB_PATH` | Path to the directory, where the sqlite database for file metadata should be stored. Recommended to not be the same folder as `FILE_STORAGE_PATH` to prevent overlapping. |
|
||||
| `FILE_EXPIRATION_CYCLE` | Determines the interval of the expiration cycle. `5` means that every 5 seconds the files will be checked for expiration. |
|
||||
|
||||
## Tokens (`auth.yml`)
|
||||
|
||||
Inside the `auth.yml` file you can configure which tokens are valid and for what file types they can be used for. An example file could look like this:
|
||||
|
||||
```yaml
|
||||
validTokens:
|
||||
- token: 71a4c056ab9b0fb965063344cd6616bc
|
||||
fileTypes:
|
||||
- image/png
|
||||
- image/jpeg
|
||||
```
|
||||
|
||||
Each token is an element of the `validTokens` list and can be generated however you want. It is not even necessary for it to be hexadecimal, it can be any kind of string you want (
|
||||
e.g. `my_favorite_password` or something like `X_!]6rk[wC]%7aN^fB>#PzuFd{L,ugsq`).
|
||||
|
||||
But if you want to keep it simple, you can use the `aq` CLI tool to generate it directly like so:
|
||||
|
||||
```shell
|
||||
aq generate --length 32
|
||||
```
|
||||
|
||||
After adding the token to the list you may want to restrict what files can be uploaded with that token. That can be done with the `fileTypes` field. If you leave it empty, all file
|
||||
types are possible, otherwise only the configured ones. Normally we would accept every possible MIME type, but as they behave completely different sometimes and we want to keep it
|
||||
simple, we only support the following ones:
|
||||
|
||||
```
|
||||
application/pdf
|
||||
application/json
|
||||
image/png
|
||||
image/jpeg
|
||||
text/csv
|
||||
text/plain
|
||||
```
|
||||
|
||||
# CLI Tool
|
||||
|
|
Loading…
Reference in New Issue