diff --git a/.editorconfig b/.editorconfig index f9a4e91..9a8bc38 100644 --- a/.editorconfig +++ b/.editorconfig @@ -9,3 +9,6 @@ insert_final_newline = true [.yml] indent_style = space indent_size = 2 + +[.md] +max_line_length = off diff --git a/.github/assets/aqua_structure.drawio b/.github/assets/aqua_structure.drawio deleted file mode 100644 index 3faa692..0000000 --- a/.github/assets/aqua_structure.drawio +++ /dev/null @@ -1 +0,0 @@ -zZdNb4IwGIB/DcclLeXzKChuybaLhyW7VXkVYqGkVtH9+tVRUGZMtkSsF9I+fdvSp+RtsUhc7KeCVtkbT4FZNkr3Fhlbth0GWD2P4NAA1/MbsBJ52iB8ArP8CzREmm7zFDa9QMk5k3nVhwtelrCQPUaF4HU/bMlZf9aKruACzBaUXdKPPJVZQwPbP/FnyFdZOzP2wqaloG2wXskmoymvzxCZWCQWnMumVOxjYEd3rZemX3KltXsxAaX8Swf+WaxR+QLM26GPzfb9dT6tntxmlB1lW71g/bLy0BoQfFumcBwEWSSqs1zCrKKLY2uttlyxTBZM1bAqbqTga4g540KRkpcqLFrmjLXIsokfxkkcKq7nBiFhf3VRuFOlPjHgBUhxUCG6g6PlHvrV+myrNMrOdqkNo/rjWHXjnvypglb4D52eAZ3OeOSEySA6A8M6fQM6cexHvj+ITmwb9hkY8ImQ67h4GJ+eYZ+hAZ+jcYwSchufncAHSZ/toX/f4ygJxtFAQk0nUIwNCPWQFwU3yqC/hRpPodg2YJSMHOTaAxk1nUSxiUsTIc7cudEdtNP1KFnUxLUpdOeYwq2O+XsJVdXTD9hP29lfLJl8Aw== \ No newline at end of file diff --git a/.github/assets/aqua_structure.png b/.github/assets/aqua_structure.png new file mode 100644 index 0000000..3ff1973 Binary files /dev/null and b/.github/assets/aqua_structure.png differ diff --git a/README.md b/README.md index 30fbfec..8e734c8 100644 --- a/README.md +++ b/README.md @@ -4,11 +4,12 @@ --- -**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/). +**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_structure](./.github/assets/aqua_structure.png) + # 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. @@ -17,8 +18,7 @@ There are as always multiple ways to install the server. The recommended way is This is only for those people, that are still living in the 90s or are not comfortable with a Docker installation. -1. First download the specific binary from the [releases](https://github.com/Superioz/aqua/releases) and put it somewhere (e.g. with `wget` on Linux). Also, add execution permission - with `chmod +x aq-linux-amd64`. +1. First download the specific binary from the [releases](https://github.com/Superioz/aqua/releases) and put it somewhere (e.g. with `wget` on Linux). Also, add execution permission with `chmod +x aq-linux-amd64`. 2. Do the configuration you want (e.g. setting environment variables and creating an `auth.yml`). See [Configuration](#configuration) 3. Execute the downloaded binary and don't forget to open port `8765` on your machine/server. @@ -35,7 +35,13 @@ Before following the steps, make sure you have [Docker](https://docs.docker.com/ ## Kubernetes -TBD +Make sure to have a Kubernetes cluster running somewhere (either on bare-metal or on GCP, AWS or some other provider) and check beforehand if pods inside the cluster can access `ghcr.io`, which is the GitHub Docker registry, which we need for our aqua server image. Of course, you also need `kubectl` to be installed on your system. + +1. Clone the repository or copy at least the `/kubernetes` folder into some directory +2. Create a namespace called `aqua` with `kubectl create ns aqua` +3. Apply the configuration files from the `/kubernetes` folder with `kubectl apply -k ./kubernetes/`. The `-k` flag is part of the newer versions of kubectl and allows [Kustomize](https://kustomize.io/) to work. +4. Either create an Ingress or connect to the cluster via `kubectl port-forward svc/aqua-server 8765` +5. Done. Finito. You should now be able to access the server. # Configuration @@ -73,8 +79,7 @@ user@host:~$ aq generate --length 32 L1dLUm12!Lb%7Nz1ep4h5Vo+Fn531&EU ``` -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. +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: @@ -89,8 +94,7 @@ text/plain # CLI Tool -Installing the CLI tool is fairly simple. Just download the respective binary from [releases](https://github.com/Superioz/aqua/releases), rename it and put it somewhere in your `$PATH`. -Don't forget to add execution permissions `chmod +x aq`. +Installing the CLI tool is fairly simple. Just download the respective binary from [releases](https://github.com/Superioz/aqua/releases), rename it and put it somewhere in your `$PATH`. Don't forget to add execution permissions `chmod +x aq`. Now to upload a local file, you just have to execute the following command: @@ -103,3 +107,29 @@ To upload multiple files at the same time, just do it like this: ```sh aq upload --host https://my-domain.com:8765 --token my_token local_file1.png local_file2.txt [...] ``` + +# ShareX + +As mentioned in the first section, you can easily configure ShareX to use aqua as server. For that you can copy the contents below to a file with the `.sxcu` ending like `aqua.sxcu`. Edit it now to your own needs, i.e. replacing the `your-domain.com` with the address of your installation and maybe adjusting the `expiration`, `-1` means that the files won't expire. + +After that you can import it to your custom upload goals in the ShareX UI. + +```json +{ + "Version": "12.4.0", + "DestinationType": "ImageUploader, TextUploader", + "RequestMethod": "POST", + "RequestURL": "https://your-domain.com/upload", + "Headers": { + "Authorization": "Bearer your-generated-token-here" + }, + "Body": "MultipartFormData", + "Arguments": { + "metadata": "{ \"expiration\": 3600 }" + }, + "FileFormName": "file", + "URL": "https://your-domain.com/$json:id$" +} +``` + +More information can be found here: [ShareX Custom Uploader Guide](https://getsharex.com/docs/custom-uploader). diff --git a/cmd/aqua/main.go b/cmd/aqua/main.go index 3b32a45..b8b4033 100644 --- a/cmd/aqua/main.go +++ b/cmd/aqua/main.go @@ -12,8 +12,6 @@ import ( "time" ) -// TODO add documentation on Kubernetes -// TODO add documentation of how to configure it with ShareX // TODO add structure diagram (api for uploading, file backend with metadata database, scheduler for expiration) func main() { @@ -47,6 +45,6 @@ func main() { s.StartAsync() r.Static("/", env.StringOrDefault("FILE_STORAGE_PATH", storage.EnvDefaultFileStoragePath)) - + _ = r.Run(":8765") } diff --git a/kubernetes/kustomization.yaml b/kubernetes/kustomization.yaml index 2c809ce..00750a3 100644 --- a/kubernetes/kustomization.yaml +++ b/kubernetes/kustomization.yaml @@ -3,5 +3,4 @@ kind: Kustomization namespace: aqua resources: - configmap.yaml - - deployment.yaml - - pvc.yaml + - statefulset.yaml diff --git a/kubernetes/statefulset.yaml b/kubernetes/statefulset.yaml index 2a5dc48..c84ef88 100644 --- a/kubernetes/statefulset.yaml +++ b/kubernetes/statefulset.yaml @@ -24,15 +24,16 @@ spec: - name: FILE_STORAGE_PATH value: /var/lib/aqua/ - name: FILE_NAME_LENGTH - value: 16 + value: "8" - name: FILE_META_DB_PATH value: /var/lib/aqua/ - name: FILE_EXPIRATION_CYCLE - value: 5 + value: "5" volumeMounts: - name: auth mountPath: /etc/aqua/ - name: aqua-files + mountPath: /var/lib/aqua volumes: - name: auth configMap: