From 89ff3b2d606b745e51962ad76d8c47d488a17c12 Mon Sep 17 00:00:00 2001 From: pushrbx Date: Wed, 25 Oct 2023 19:11:14 +0100 Subject: [PATCH] improved docs around container usage --- container_usage.md | 102 ++++++++++++++++++++++++++++++++++++++------- 1 file changed, 86 insertions(+), 16 deletions(-) diff --git a/container_usage.md b/container_usage.md index 30f4bb4..bce6bd7 100644 --- a/container_usage.md +++ b/container_usage.md @@ -1,5 +1,79 @@ # 🐳 Running Jikan API in a container +The most easiest way to get started is to use our container setup cli script after checking out the repo with git (linux only): + +```bash +./container-setup.sh start +``` + +This will: + +- Prompt you for the required passwords and usernames +- Sets up a production ready setup with `redis`, `typesense` and `mongodb` (almost same as the public api at `api.jikan.moe`) +- Sets mongodb to use max 1gb of memory +- Configures jikan-api to add CORS headers to responses. + +> **Note**: The script supports both `docker` and `podman`. In case of `podman` please bare in mind that sometimes the container name resolution doesn't work on the container network. +> In those cases you might have to install `aardvark-dns` package. On `Arch Linux` podman uses `netavark` network by default (in 2023) so you will need to install the before mentioned package. + +The script has the following prerequisites and will notify you if these are not present: + +- git +- `docker` or `podman` +- `docker-compose` or `podman-compose` + +### Available commands in the cli script + +``` +============================================================ +Jikan API Container Setup CLI +============================================================ +Syntax: ./container-setup.sh [command] +---commands--- +help Print CLI help +build-image Build Image Locally +start Start Jikan API (mongodb, typesense, redis, jikan-api workers) +stop Stop Jikan API +validate-prereqs Validate pre-reqs installed (docker, docker-compose) +execute-indexers Execute the indexers, which will scrape and index data from MAL. (Notice: This can take days) +``` + +### Running the indexer with the script + +When you first startup the app you will have an empty database. To fill it up you can execute the following command: + +```bash +./container-setup.sh execute-indexers +``` + +Please note that this command can take 4-5 days to run. You can run it in the background with the `&` marker: + +```bash +./container-setup.sh execute-indexers & +``` + +If interrupted then you will have to manually resume the indexing, otherwise the above command will just start again from the beginning. + +### Updating to a newer version + +You need to stop the app first: + +```bash +./container-setup.sh stop +``` + +Then remove the jikan-api image from your local storage and pull the new one. Set the `JIKAN_API_VERSION` environment variable to the latest image tag. This can be either `latest` or the version `v4.0.0-11`. + +```bash +JIKAN_API_VERSION=latest ./container-setup.sh start +``` + +## More customised setups + +Some of you might only want to run the `jikan-rest` app with only mongodb, without the more sophisticated search functionality. In those cases we don't have a `docker-compose` config for you. You need to start the `jikan-rest` container with atleast a `mongodb` instance. +The `jikan-rest` container will require a `.env` file mounted where you configure the credentials for `mongodb`. + + ```bash docker run -d --name=jikan-rest -p 8080:8080 -v ./.env:/app/.env jikanme/jikan-rest:latest ``` @@ -14,8 +88,7 @@ docker run -d --name=jikan-rest -p 8080:8080 -v ./.env:/app/.env jikanme/jikan-r > address of these services. > **Tip**: If you run the container on a non-default network, you can use the container names in the configuration to -> specify the address of services like MongoDB and TypeSense. However, this is not a concern if you -> use `docker-compose`. +> specify the address of services like MongoDB and TypeSense. There is also a `Dockerfile` in the repo which you can use to build the container image and startup the app in a container: @@ -25,24 +98,24 @@ docker build -t jikan-rest:nightly . docker run -d --name=jikan-rest -p 8080:8080 -v ./.env:/app/.env jikan-rest:nightly ``` +> Most of the time it's enough to just use the image from [Docker Hub](https://hub.docker.com/r/jikanme/jikan-rest). + ### Docker compose usage ``` docker-compose up ``` -Docker compose will use the `.env` file from the folder where you execute it from to load configurations for the -services. If you don't have a `.env` file yet in the folder, copy the `.env.dist` file, and set the passwords. +This does the same thing as the `container-setup.sh` script mostly, but you will have to create the secret files yourself. The following secret files are required for credentials (put them next to the `docker-compose.yml` file): -Docker compose will start up a production ready setup with redis, typesense and mongodb. -Change the environment variables for the `jikan_rest` service in the `docker-compose.yml` file to customise the configuration of the Jikan API. -By default docker-compose sets it to: -- Not use [queuing](https://laravel.com/docs/9.x/scout#queueing) for search requests. (Not yet supported for typesense.) -- Use typesense search for more accurate search results -- Use redis for microcaching and caching. -- Add CORS headers to responses +- db_admin_password.txt +- db_admin_username.txt +- db_password.txt +- db_username.txt +- redis_password.txt +- typesense_api_key.txt -Of course these defaults can be overridden through the `.env` file or through setting environment variables in the command-line before executing `docker-compose up`. +You can customise the Jikan API config through `./docker/config/.env.compose` file. (E.g. you don't want CORS headers) > **Please note**: The syntax rules of docker compose for `.env` applies > here: https://docs.docker.com/compose/env-file/#syntax-rules @@ -61,7 +134,7 @@ podman run -d --name=jikan-rest -p 8080:8080 -v ./.env:/app/.env --health-start- ### Configuration of the container -You can change the settings of Jikan through setting environment variables via the `-e` command line argument option for +You can also change the settings of Jikan through setting environment variables via the `-e` command line argument option for the `docker run` command. These environment variables are the same as the options found in the `.env` file. We also provide a sample file called `.env.dist`. @@ -106,6 +179,3 @@ the [Configuration Wiki page](https://github.com/jikan-me/jikan-rest/wiki/Config - the php processes ingesting the http requests - [Supercronic](https://github.com/aptible/supercronic), which runs cron jobs. - Queue workers for populating the search index and other background jobs. -- The container does all the scheduled background jobs automatically out-of-the-box: - - Importing new documents into the search index. - - Updating entries from upstream.