From 8c27805733d8748de66e7e582fa0b280cac043e8 Mon Sep 17 00:00:00 2001 From: asonix Date: Sat, 30 Sep 2023 23:16:35 -0500 Subject: [PATCH] More readme changes --- README.md | 100 +++++++++++++++++++----------------------------------- 1 file changed, 34 insertions(+), 66 deletions(-) diff --git a/README.md b/README.md index 769a0fa..9ed6648 100644 --- a/README.md +++ b/README.md @@ -59,13 +59,16 @@ Usage: pict-rs [OPTIONS] Commands: run Runs the pict-rs web server migrate-store Migrates from one provided media store to another + migrate-repo Migrates from one provided repo to another help Print this message or the help of the given subcommand(s) Options: -c, --config-file Path to the pict-rs configuration file - --old-db-path + --old-repo-path Path to the old pict-rs sled database + --old-repo-cache-capacity + The cache capacity, in bytes, allowed to sled for in-memory operations --log-format Format of logs printed to stdout [possible values: compact, json, normal, pretty] --log-targets @@ -83,65 +86,20 @@ Options: --save-to File to save the current configuration for reproducible runs -h, --help - Print help information + Print help -V, --version - Print version information -``` - -``` -$ pict-rs run -h -Runs the pict-rs web server - -Usage: pict-rs run [OPTIONS] [COMMAND] - -Commands: - filesystem Run pict-rs with filesystem storage - object-storage Run pict-rs with object storage - help Print this message or the help of the given subcommand(s) - -Options: - -a, --address
- The address and port to bind the pict-rs web server - --api-key - The API KEY required to access restricted routes - --worker-id - ID of this pict-rs node. Doesn't do much yet - --media-preprocess-steps - Optional pre-processing steps for uploaded media - --media-skip-validate-imports - Whether to validate media on the "import" endpoint [possible values: true, false] - --media-max-width - The maximum width, in pixels, for uploaded media - --media-max-height - The maximum height, in pixels, for uploaded media - --media-max-area - The maximum area, in pixels, for uploaded media - --media-max-file-size - The maximum size, in megabytes, for uploaded media - --media-max-frame-count - The maximum number of frames allowed for uploaded GIF and MP4s - --media-enable-silent-video - Whether to enable GIF and silent video uploads [possible values: true, false] - --media-enable-full-video - Whether to enable full video uploads [possible values: true, false] - --media-video-codec - Enforce a specific video codec for uploaded videos [possible values: h264, h265, av1, vp8, vp9] - --media-audio-codec - Enforce a specific audio codec for uploaded videos [possible values: aac, opus, vorbis] - --media-filters - Which media filters should be enabled on the `process` endpoint - --media-format - Enforce uploaded media is transcoded to the provided format [possible values: avif, jpeg, jxl, png, webp] - -h, --help - Print help information (use `--help` for more detail) + Print version ``` Try running `help` commands for more runtime configuration options ```bash +$ pict-rs run -h $ pict-rs run filesystem -h $ pict-rs run object-storage -h $ pict-rs run filesystem sled -h +$ pict-rs run filesystem postgres -h $ pict-rs run object-storage sled -h +$ pict-rs run object-storage postgres -h ``` See [`pict-rs.toml`](./pict-rs.toml) for more @@ -507,8 +465,8 @@ pict-rs offers the following endpoints: The following endpoints are protected by an API key via the `X-Api-Token` header, and are disabled -unless the `--api-key` option is passed to the binary or the PICTRS__SERVER__API_KEY environment variable is -set. +unless the `--api-key` option is passed to the binary or the PICTRS__SERVER__API_KEY environment +variable is set. A secure API key can be generated by any password generator. - `POST /internal/import` for uploading an image while preserving the filename as the first alias. @@ -631,7 +589,8 @@ A secure API key can be generated by any password generator. } } ``` - Note that some fields in this response are optional (including `next`, `prev`, `current`, `details` and `frames`) + Note that some fields in this response are optional (including `next`, `prev`, `current`, + `details` and `frames`) Available query options: - empty: this fetches the first page of the results (e.g. the newest media) @@ -856,7 +815,8 @@ $ sudo docker compose run pictrs sh # launch a shell in the pict-rs container $ vi docker-compose.yml # edit the docker-compose yaml however you like to edit it, make sure all the variables described below are set $ sudo docker compose up -d pictrs # start pict-rs again after the migration. Note that this is not 'docker compose start'. using the `up` subcommand explicitly reloads configurations ``` -depending on your version of docker or docker-compose, you might need to use the following command to open a shell: +depending on your version of docker or docker-compose, you might need to use the following command +to open a shell: ```bash $ sudo docker-compose run -i pictrs sh ``` @@ -1071,7 +1031,8 @@ sufficient to create a development environment for pict-rs on any linux distribu is installed. #### With direnv and nix-direnv -With these tools, the pict-rs development environment can be automatically loaded when entering the pict-rs directory +With these tools, the pict-rs development environment can be automatically loaded when entering the +pict-rs directory Setup (only once): ``` @@ -1120,19 +1081,21 @@ $ sudo docker run --rm -it -p 8080:8080 -v "$(pwd):/mnt" alpine:3.18 ## Contributing -Feel free to open issues for anything you find an issue with. Please note that any contributed code will be licensed under the AGPLv3. +Feel free to open issues for anything you find an issue with. Please note that any contributed code +will be licensed under the AGPLv3. ## FAQ ### Question: Is pict-rs stateless -Answer: No. pict-rs relies on an embedded key-value store called `sled` to store metadata about -uploaded media. This database maintains a set of files on the local disk and cannot be configured to -use a network. +Answer: It can be. By default, pict-rs uses on-disk storage for files as well as an on-disk +key-value store called `sled` for metadata. This is for ease of deployment for small setups. If you +need pict-rs to keep no local state (aside from /tmp), it can be configured to use Object Storage +for files and Postgres for metadata. ### Question: Can I use a different database with pict-rs -Answer: No. Currently pict-rs only supports the embedded key-value store called `sled`. In the -future, I would like to support `Postgres` and `BonsaiDB`, but I am currently not offering a -timeline on support. If you care about this and are a rust developer, I would accept changes. +Answer: Yes. pict-rs supports both `sled` and `postgres` for storing metadata. In the future I might +also support `BonsaiDB`. If you want pict-rs to support another database, feel free to submit +changes :) ### Question: How can I submit changes Answer: If you would like to contribute to pict-rs, you can push your code to a public git host of @@ -1166,8 +1129,13 @@ the ownership on the pict-rs volume to `991:991` should solve this problem. Copyright © 2022 Riley Trautman -pict-rs is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version. +pict-rs is free software: you can redistribute it and/or modify it under the terms of the GNU +General Public License as published by the Free Software Foundation, either version 3 of the +License, or (at your option) any later version. -pict-rs is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. This file is part of pict-rs. +pict-rs is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even +the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General +Public License for more details. This file is part of pict-rs. -You should have received a copy of the GNU General Public License along with pict-rs. If not, see [http://www.gnu.org/licenses/](http://www.gnu.org/licenses/). +You should have received a copy of the GNU General Public License along with pict-rs. If not, see +[http://www.gnu.org/licenses/](http://www.gnu.org/licenses/).