From 661f2f14dd67efe0c6627f2cefdb39fc512c397c Mon Sep 17 00:00:00 2001 From: minish Date: Fri, 8 Dec 2023 14:17:19 -0500 Subject: [PATCH] doc update --- README.md | 81 +++++++++++++++++++++++++++++++++++++++++-------------- 1 file changed, 61 insertions(+), 20 deletions(-) diff --git a/README.md b/README.md index 6401e8c..52f2e9e 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,8 @@ # breeze breeze is a simple, performant file upload server. +The primary instance is https://picture.wtf. + ## Features Compared to the old Express.js backend, breeze has - Streamed uploading @@ -18,7 +20,7 @@ Either way, you need to start off by cloning the Git repository. git clone https://git.min.rip/min/breeze.git ``` -To run it in Docker, I recommend using Docker Compose. An example `docker-compose.yaml` configuration is below. +To run it in Docker, I recommend using Docker Compose. An example `docker-compose.yaml` configuration is below. You can start it using `docker compose up -d`. ``` version: '3.6' @@ -29,20 +31,15 @@ services: volumes: - /srv/uploads:/data + - ./breeze.toml:/etc/breeze.toml ports: - 8000:8000 - - environment: - - BRZ_BASE_URL=http://127.0.0.1:8000 - - BRZ_SAVE_PATH=/data - - BRZ_UPLOAD_KEY=hiiiiiiii - - BRZ_CACHE_UPL_MAX_LENGTH=134217728 # allow files up to ~134 MiB to be cached - - BRZ_CACHE_UPL_LIFETIME=1800 # let uploads stay in cache for 30 minutes - - BRZ_CACHE_SCAN_FREQ=60 # scan the cache for expired files if more than 60 seconds have passed since the last scan - - BRZ_CACHE_MEM_CAPACITY=4294967296 # allow 4 GiB of data to be in the cache at once ``` -For this configuration, it is expected that there is a clone of the Git repository in the `./breeze` folder. You can start it using `docker compose up -d`. +For this configuration, it is expected that: +* there is a clone of the Git repository in the `./breeze` folder. +* there is a `breeze.toml` config file in current directory +* there is a directory at `/srv/uploads` for storing uploads It can also be installed directly if you have the Rust toolchain installed: ```bash @@ -51,15 +48,59 @@ cargo install --path . ## Usage ### Hosting -Configuration is read through environment variables, because I wanted to run this using Docker Compose. -``` -BRZ_BASE_URL - base url for upload urls (ex: http://127.0.0.1:8000 for http://127.0.0.1:8000/p/abcdef.png, http://picture.wtf for http://picture.wtf/p/abcdef.png) -BRZ_SAVE_PATH - this should be a path where uploads are saved to disk (ex: /srv/uploads, C:\brzuploads) -BRZ_UPLOAD_KEY (optional) - if not empty, the key you specify will be required to upload new files. -BRZ_CACHE_UPL_MAX_LENGTH - this is the max length an upload can be in bytes before it won't be cached (ex: 80000000 for 80MB) -BRZ_CACHE_UPL_LIFETIME - this indicates how long an upload will stay in cache (ex: 1800 for 30 minutes, 60 for 1 minute) -BRZ_CACHE_SCAN_FREQ - this is the frequency of full cache scans, which scan for and remove expired uploads (ex: 60 for 1 minute) -BRZ_CACHE_MEM_CAPACITY - this is the amount of memory the cache will hold before dropping entries +Configuration is read through a toml file. + +By default it'll try to read `./breeze.toml`, but you can specify a different path using the `-c`/`--config` command line switch. + +Here is an example config file: +```toml +[engine] +# The base URL that the HTTP server will be accessible on. +# This is used for formatting upload URLs. +# Setting it to "https://picture.wtf" would result in +# upload urls of "https://picture.wtf/p/abcdef.png", etc. +base_url = "http://127.0.0.1:8000" + +# The location that uploads will be saved to. +# It should be a path to a directory on disk that you can write to. +save_path = "/data" + +# OPTIONAL - If set, the static key specified will be required to upload new files. +# If it is not set, no key will be required. +upload_key = "hiiiiiiii" + +# OPTIONAL - specifies what to show when the site is visited on http +# It is sent with text/plain content type. +# There are two variables you can use: +# %uplcount% - total number of uploads present on the server +# %version% - current breeze version (e.g. 0.1.5) +motd = "my image host, currently hosting %uplcount% files" + +[engine.cache] +# The file size (in bytes) that a file must be under +# to get cached. +max_length = 134_217_728 + +# How long a cached upload will remain cached. (in seconds) +upload_lifetime = 1800 + +# How often the cache will be checked for expired uploads. +# It is not a continuous scan, and only is triggered upon a cache operation. +scan_freq = 60 + +# How much memory (in bytes) the cache is allowed to consume. +mem_capacity = 4_294_967_295 + +[http] +# The address that the HTTP server will listen on. (ip:port) +# Use 0.0.0.0 as the IP to listen publicly, 127.0.0.1 only lets your +# computer access it +listen_on = "127.0.0.1:8000" + +[logger] +# OPTIONAL - the current log level. +# Default level is warn. +level = "warn" ``` ### Uploading