diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/API.md | 40 | ||||
| -rw-r--r-- | doc/INSTALL.md | 96 | ||||
| -rw-r--r-- | doc/example.env | 6 |
3 files changed, 109 insertions, 33 deletions
@@ -37,6 +37,7 @@ - [Creating post](#creating-post) - [Updating post](#updating-post) - [Getting post](#getting-post) + - [Getting around post](#getting-around-post) - [Deleting post](#deleting-post) - [Merging posts](#merging-posts) - [Rating post](#rating-post) @@ -53,7 +54,7 @@ - [Deleting pool category](#deleting-pool-category) - [Setting default pool category](#setting-default-pool-category) - Pools - - [Listing pools](#listing-pool) + - [Listing pools](#listing-pools) - [Creating pool](#creating-pool) - [Updating pool](#updating-pool) - [Getting pool](#getting-pool) @@ -164,9 +165,9 @@ way. The files, however, should be passed as regular fields appended with a accepts a file named `content`, the client should pass `{"contentUrl":"http://example.com/file.jpg"}` as a part of the JSON message body. When creating or updating post content using this method, the server can -also be configured to employ [youtube-dl](https://github.com/ytdl-org/youtube-dl) -to download content from popular sites such as youtube, gfycat, etc. Access to -youtube-dl can be configured with the `'uploads:use_downloader'` permission +also be configured to employ [yt-dlp](https://github.com/yt-dlp/yt-dlp) to +download content from popular sites such as youtube, gfycat, etc. Access to +yt-dlp can be configured with the `'uploads:use_downloader'` permission Finally, in some cases the user might want to reuse one file between the requests to save the bandwidth (for example, reverse search + consecutive @@ -322,7 +323,7 @@ data. { "name": <name>, "color": <color>, - "order": <order> // optional + "order": <order> } ``` @@ -788,7 +789,7 @@ data. | `fav-time` | alias of `fav-date` | | `feature-date` | featured at given date | | `feature-time` | alias of `feature-time` | - | `safety` | having given safety. `<value>` can be either `safe`, `sketchy` (or `questionable`) or `unsafe`. | + | `safety` | having given safety. `<value>` can be either `safe`, `sketchy` or `unsafe`. | | `rating` | alias of `safety` | **Sort style tokens** @@ -951,6 +952,29 @@ data. Retrieves information about an existing post. +## Getting around post +- **Request** + + `GET /post/<id>/around` + +- **Output** + + ```json5 + { + "prev": <post-resource>, + "next": <post-resource> + } + ``` + +- **Errors** + + - the post does not exist + - privileges are too low + +- **Description** + + Retrieves information about posts that are before or after an existing post. + ## Deleting post - **Request** @@ -1365,7 +1389,7 @@ data. ## Creating pool - **Request** - `POST /pools/create` + `POST /pool` - **Input** @@ -2467,7 +2491,7 @@ One file together with its metadata posted to the site. ## Micro post **Description** -A [post resource](#post) stripped down to `name` and `thumbnailUrl` fields. +A [post resource](#post) stripped down to `id` and `thumbnailUrl` fields. ## Note **Description** diff --git a/doc/INSTALL.md b/doc/INSTALL.md index d978e4a..a1598b8 100644 --- a/doc/INSTALL.md +++ b/doc/INSTALL.md @@ -1,5 +1,5 @@ -This assumes that you have Docker (version 17.05 or greater) -and Docker Compose (version 1.6.0 or greater) already installed. +This assumes that you have Docker (version 19.03 or greater) +and the Docker Compose CLI (version 1.27.0 or greater) already installed. ### Prepare things @@ -34,33 +34,79 @@ and Docker Compose (version 1.6.0 or greater) already installed. Read the comments to guide you. Note that `.env` should be in the root directory of this repository. -### Running the Application +4. Pull the containers: -Download containers: -```console -user@host:szuru$ docker-compose pull -``` + This pulls the latest containers from docker.io: + ```console + user@host:szuru$ docker compose pull + ``` + + If you have modified the application's source and would like to manually + build it, follow the instructions in [**Building**](#Building) instead, + then read here once you're done. + +5. Run it! + + For first run, it is recommended to start the database separately: + ```console + user@host:szuru$ docker compose up -d sql + ``` + + To start all containers: + ```console + user@host:szuru$ docker compose up -d + ``` + + To view/monitor the application logs: + ```console + user@host:szuru$ docker compose logs -f + # (CTRL+C to exit) + ``` + +### Building + +1. Edit `docker-compose.yml` to tell Docker to build instead of pull containers: -For first run, it is recommended to start the database separately: -```console -user@host:szuru$ docker-compose up -d sql -``` + ```diff yaml + ... + server: + - image: szurubooru/server:latest + + build: server + ... + client: + - image: szurubooru/client:latest + + build: client + ... + ``` + + You can choose to build either one from source. + +2. Build the containers: + + ```console + user@host:szuru$ docker compose build + ``` + + That will attempt to build both containers, but you can specify `client` + or `server` to make it build only one. + + If `docker compose build` spits out: + + ``` + ERROR: Service 'server' failed to build: failed to parse platform : "" is an invalid component of "": platform specifier component must match "^[A-Za-z0-9_-]+$": invalid argument + ``` + + ...you will need to export Docker BuildKit flags: + + ```console + user@host:szuru$ export DOCKER_BUILDKIT=1; export COMPOSE_DOCKER_CLI_BUILD=1 + ``` -To start all containers: -```console -user@host:szuru$ docker-compose up -d -``` + ...and run `docker compose build` again. -To view/monitor the application logs: -```console -user@host:szuru$ docker-compose logs -f -# (CTRL+C to exit) -``` +*Note: If your changes are not taking effect in your builds, consider building +with `--no-cache`.* -To stop all containers: -```console -user@host:szuru$ docker-compose down -``` ### Additional Features @@ -71,7 +117,7 @@ user@host:szuru$ docker-compose down run from docker: ```console - user@host:szuru$ docker-compose run server ./szuru-admin --help + user@host:szuru$ docker compose run server ./szuru-admin --help ``` will give you a breakdown on all available commands. diff --git a/doc/example.env b/doc/example.env index 59e1e85..303a25e 100644 --- a/doc/example.env +++ b/doc/example.env @@ -10,6 +10,12 @@ BUILD_INFO=latest # otherwise the port specified here will be publicly accessible PORT=8080 +# How many waitress threads to start +# 4 is the default amount of threads. If you experience performance +# degradation with a large number of posts, increasing this may +# improve performance, since waitress is most likely clogging up with Tasks. +THREADS=4 + # URL base to run szurubooru under # See "Additional Features" section in INSTALL.md BASE_URL=/ |