From e4602839f79313dcc416a7e370ba7bbf442adc53 Mon Sep 17 00:00:00 2001 From: naskya Date: Mon, 1 Jul 2024 14:26:16 +0900 Subject: [PATCH] separate docs --- README.md | 108 +----------------------------------------------- docs/install.md | 64 ++++++++++++++++++++++++++++ docs/usage.md | 41 ++++++++++++++++++ 3 files changed, 107 insertions(+), 106 deletions(-) create mode 100644 docs/install.md create mode 100644 docs/usage.md diff --git a/README.md b/README.md index 9b97c93..76c3a37 100644 --- a/README.md +++ b/README.md @@ -1,108 +1,4 @@ # CLI tool for Firefish -## Install and Update - -### Install pre-built executable using [cargo-binstall](https://github.com/cargo-bins/cargo-binstall) - -```sh -# If you don't have cargo-binstall, install it first -curl -L --proto '=https' --tlsv1.2 -sSf https://raw.githubusercontent.com/cargo-bins/cargo-binstall/main/install-from-binstall-release.sh | bash - -# Install pre-built executable -cargo binstall --git https://firefish.dev/firefish/fishctl.git -``` - -You can update the package using the same command. - -```sh -cargo binstall --git https://firefish.dev/firefish/fishctl.git -``` - -### Download pre-built executable file - -You can also download the pre-built executable file from the [release page](https://firefish.dev/firefish/fishctl/-/releases), but you need to manage/update the file on your own. - -### Install from source - -```sh -# Build from source -cargo install --locked --git https://firefish.dev/firefish/fishctl.git -``` - -You can update the package using the same command. - -```sh -cargo install --locked --git https://firefish.dev/firefish/fishctl.git -``` - -### Use pre-built OCI image - -Using the `registry.firefish.dev/firefish/fishctl` container image, `fishctl ___` commands can be executed as - -```sh -# Assuming that $(pwd) (current directory) is the parent of the config directory -# (i.e., the Firefish local repository directory) - -docker run -it --rm --volume "$(pwd)":/firefish --network network_name \ - registry.firefish.dev/firefish/fishctl \ - fishctl ___ - -# or - -podman run -it --rm --volume "$(pwd)":/firefish --network network_name \ - registry.firefish.dev/firefish/fishctl \ - fishctl ___ -``` - -Where `network_name` is the network name on which the database is running. If you want to use this for the host network (i.e., use the container as if it were a locally installed command), you should replace `network_name` with `host`. - -If you are using a container network (which is typically the case if you are using `compose.yml` or `docker-compose.yml` to run Firefish), you need to search for your network name by `docker network ls` or `podman network ls`: - -``` -$ podman network ls # the network name is `firefish_calcnet` in this case -NETWORK ID NAME DRIVER -0060ac847249 firefish_calcnet bridge -2f259bab93aa podman bridge -``` - -## Usage - -Please make sure to `cd` to the Firefish local repository (more precisely, the parent directory of the config directory) before running these commands, or specify that directory using `--base-dir` option. - -If you use a custom Firefish setup and let's say your config files are located at `/etc/firefish/config`, you should provide `--base-dir /etc/firefish` option or `cd` to `/etc/firefish` directory. - -### Update the config files - -[The admin note](https://firefish.dev/firefish/firefish/-/blob/main/docs/notice-for-admins.md) may tell you that you need to update the config files. In such a case, please execute the following command. - -```sh -fishctl config update -``` - -You can also specify the revision to update to, but this feature is for development purposes only. - -```sh -fishctl config update v1 -``` - -### Check the config files - -Execute the following command to check if the config files are valid: - -```sh -fishctl config check -``` - -Please note that some items are only formally checked. Even if the output says it is valid, your settings can be incorrect. - -This command performs a connection check against the PostgreSQL server and the cache server (Valkey/Redis). You can bypass this check using the `--offline` option: - -```sh -fishctl config check --offline -``` - -### Generate VAPID keys for push notifications - -```sh -fishctl generate vapid -``` +- [Install and update](docs/install.md) +- [Usage](docs/usage.md) diff --git a/docs/install.md b/docs/install.md new file mode 100644 index 0000000..653039f --- /dev/null +++ b/docs/install.md @@ -0,0 +1,64 @@ +# Install and update + +## Install pre-built executable using [cargo-binstall](https://github.com/cargo-bins/cargo-binstall) + +```sh +# If you don't have cargo-binstall, install it first +curl -L --proto '=https' --tlsv1.2 -sSf https://raw.githubusercontent.com/cargo-bins/cargo-binstall/main/install-from-binstall-release.sh | bash + +# Install pre-built executable +cargo binstall --git https://firefish.dev/firefish/fishctl.git +``` + +You can update the package using the same command. + +```sh +cargo binstall --git https://firefish.dev/firefish/fishctl.git +``` + +## Download pre-built executable file + +You can also download the pre-built executable file from the [release page](https://firefish.dev/firefish/fishctl/-/releases), but you need to manage/update the file on your own. + +## Install from source + +```sh +# Build from source +cargo install --locked --git https://firefish.dev/firefish/fishctl.git +``` + +You can update the package using the same command. + +```sh +cargo install --locked --git https://firefish.dev/firefish/fishctl.git +``` + +## Use pre-built OCI image + +Using the `registry.firefish.dev/firefish/fishctl` container image, `fishctl ___` commands can be executed as + +```sh +# Assuming that $(pwd) (current directory) is the parent of the config directory +# (i.e., the Firefish local repository directory) + +docker run -it --rm --volume "$(pwd)":/firefish --network network_name \ + registry.firefish.dev/firefish/fishctl \ + fishctl ___ + +# or + +podman run -it --rm --volume "$(pwd)":/firefish --network network_name \ + registry.firefish.dev/firefish/fishctl \ + fishctl ___ +``` + +Where `network_name` is the network name on which the database is running. If you want to use this for the host network (i.e., use the container as if it were a locally installed command), you should replace `network_name` with `host`. + +If you are using a container network (which is typically the case if you are using `compose.yml` or `docker-compose.yml` to run Firefish), you need to search for your network name by `docker network ls` or `podman network ls`: + +``` +$ podman network ls # the network name is `firefish_calcnet` in this case +NETWORK ID NAME DRIVER +0060ac847249 firefish_calcnet bridge +2f259bab93aa podman bridge +``` diff --git a/docs/usage.md b/docs/usage.md new file mode 100644 index 0000000..2407ef3 --- /dev/null +++ b/docs/usage.md @@ -0,0 +1,41 @@ +# Usage + +Please make sure to `cd` to the Firefish local repository (more precisely, the parent directory of the config directory) before running the command, or specify that directory using `--base-dir` option. + +If you use a custom Firefish setup and let's say your config files are located at `/etc/firefish/config`, you should provide `--base-dir /etc/firefish` option or `cd` to `/etc/firefish` directory. + +## Update the config files + +[The admin note](https://firefish.dev/firefish/firefish/-/blob/main/docs/notice-for-admins.md) may tell you that you need to update the config files. In such a case, please execute the following command. + +```sh +fishctl config update +``` + +You can also specify the revision to update to, but this feature is for development purposes only. + +```sh +fishctl config update v1 +``` + +## Check the config files + +Execute the following command to check if the config files are valid: + +```sh +fishctl config check +``` + +Please note that some items are only formally checked. Even if the output says it is valid, your settings can be incorrect. + +This command performs a connection check against the PostgreSQL server and the cache server (Valkey/Redis). You can bypass this check using the `--offline` option: + +```sh +fishctl config check --offline +``` + +## Generate VAPID keys for push notifications + +```sh +fishctl generate vapid +```