separate docs
This commit is contained in:
parent
dfa162e021
commit
e4602839f7
3 changed files with 107 additions and 106 deletions
108
README.md
108
README.md
|
@ -1,108 +1,4 @@
|
||||||
# CLI tool for Firefish
|
# CLI tool for Firefish
|
||||||
|
|
||||||
## Install and Update
|
- [Install and update](docs/install.md)
|
||||||
|
- [Usage](docs/usage.md)
|
||||||
### 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
|
|
||||||
```
|
|
||||||
|
|
64
docs/install.md
Normal file
64
docs/install.md
Normal file
|
@ -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
|
||||||
|
```
|
41
docs/usage.md
Normal file
41
docs/usage.md
Normal file
|
@ -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
|
||||||
|
```
|
Loading…
Reference in a new issue