update docs

This commit is contained in:
tobi 2024-03-29 11:24:34 +01:00
parent f0ff929704
commit 5b4ccb054b
2 changed files with 69 additions and 22 deletions

View file

@ -20,18 +20,34 @@ Usage:
Available Commands:
admin gotosocial admin-related tasks
completion generate the autocompletion script for the specified shell
debug gotosocial debug-related tasks
help Help about any command
server gotosocial server-related tasks
testrig gotosocial testrig-related tasks
```
Under `Available Commands`, you can see the standard `server` command. But there are also commands doing admin and testing etc, which will be explained in this document.
Under `Available Commands`, you can see the standard `server` command. But there are also commands doing admin and debugging etc, which will be explained in this document.
**Please note -- for all of these commands, you will still need to set the global options correctly so that the CLI tool knows how eg., how to connect to your database, which database to use, which host and account domain to use etc.**
!!! Info "Passing global config to the CLI"
For all of these commands, you will still need to set the global options correctly so that the CLI tool knows how to connect to your database, which database to use, which host and account domain to use, etc.
You can set these options using environment variables, passing them as CLI flags (eg., `gotosocial [commands] --host example.org`), or by just pointing the CLI tool towards your config file (eg., `gotosocial --config-path ./config.yaml [commands]`).
You can set these options using environment variables, passing them as CLI flags (eg., `gotosocial [commands] --host example.org`), or by just pointing the CLI tool towards your config file (eg., `gotosocial --config-path ./config.yaml [commands]`).
!!! Info
When running CLI commands, you'll get a bit of output like the following:
```text
time=XXXX level=info msg=connected to SQLITE database
time=XXXX level=info msg=there are no new migrations to run func=doMigration
time=XXXX level=info msg=closing db connection
```
This is normal and indicates that the commands ran as expected.
!!! Warning "Restarting GtS after running admin commands"
Because of the way internal caching works in GoToSocial, you may need to restart GoToSocial after running some of these commands in order for the effect of the command to "take". We are still looking for a way to make this unnecessary. In the meantime, commands that require a restart after running the command are highlighted below.
## gotosocial admin
@ -68,7 +84,11 @@ gotosocial admin account create \
### gotosocial admin account confirm
This command can be used to confirm a user+account on your instance, allowing them to log in and use the account. Note that if the account was created using `admin account create` this is not necessary.
This command can be used to confirm a user+account on your instance, allowing them to log in and use the account.
!!! Info
If the account was created using `admin account create` it is not necessary to run `confirm` on the account, it will be confirmed already.
`gotosocial admin account confirm --help`:
@ -93,6 +113,10 @@ gotosocial admin account confirm --username some_username --config-path config.y
This command can be used to promote a user to admin.
!!! Warning "Server restart required"
In order for the change to "take", this command requires a restart of GoToSocial after running the command.
`gotosocial admin account promote --help`:
```text
@ -116,6 +140,10 @@ gotosocial admin account promote --username some_username --config-path config.y
This command can be used to demote a user from admin to normal user.
!!! Warning "Server restart required"
In order for the change to "take", this command requires a restart of GoToSocial after running the command.
`gotosocial admin account demote --help`:
```text
@ -139,6 +167,10 @@ gotosocial admin account demote --username some_username --config-path config.ya
This command can be used to disable an account on your instance: prevent it from signing in or doing anything, without deleting data.
!!! Warning "Server restart required"
In order for the change to "take", this command requires a restart of GoToSocial after running the command.
`gotosocial admin account disable --help`:
```text
@ -162,6 +194,10 @@ gotosocial admin account disable --username some_username --config-path config.y
This command can be used to reenable an account on your instance, undoing a previous `disable` command.
!!! Warning "Server restart required"
In order for the change to "take", this command requires a restart of GoToSocial after running the command.
`gotosocial admin account enable --help`:
```text
@ -185,6 +221,10 @@ gotosocial admin account enable --username some_username --config-path config.ya
This command can be used to set a new password on the given local account.
!!! Warning "Server restart required"
In order for the change to "take", this command requires a restart of GoToSocial after running the command.
`gotosocial admin account password --help`:
```text
@ -352,7 +392,11 @@ This command can be used to prune orphaned media from your GoToSocial.
Orphaned media is defined as media that is in storage under a key that matches the format used by GoToSocial, but which does not have a corresponding database entry. This is useful for excising files that may be remaining from a previous installation, or files that were placed in storage mistakenly.
**This command only works when GoToSocial is not running, since it acquires an exclusive lock on storage. Stop GoToSocial first before running this command!**
!!! Warning "Requires a stopped server"
This command only works when GoToSocial is not running, since it acquires an exclusive lock on storage.
Stop GoToSocial first before running this command!
```text
prune orphaned media from storage
@ -389,7 +433,11 @@ These items will be refetched later on demand, if necessary.
Unused media means avatars/headers/status attachments which are not currently in use by an account or status.
**This command only works when GoToSocial is not running, since it acquires an exclusive lock on storage. Stop GoToSocial first before running this command!**
!!! Warning "Requires a stopped server"
This command only works when GoToSocial is not running, since it acquires an exclusive lock on storage.
Stop GoToSocial first before running this command!
```text
prune unused/stale remote media from storage, older than given number of days

View file

@ -2,10 +2,10 @@
Regardless of the installation method, you'll need to create some users. GoToSocial currently doesn't have a way for users to be created through the web UI, or for people to sign-up through the web UI.
Using the CLI, you can create a user:
In the meantime, you can create a user using the CLI:
```sh
$ gotosocial --config-path /path/to/config.yaml \
./gotosocial --config-path /path/to/config.yaml \
admin account create \
--username some_username \
--email some_email@whatever.org \
@ -17,29 +17,28 @@ In the above command, replace `some_username` with your desired username, `some_
If you want your user to have admin rights, you can promote them using a similar command:
```sh
$ gotosocial --config-path /path/to/config.yaml \
./gotosocial --config-path /path/to/config.yaml \
admin account promote --username some_username
```
Replace `some_username` with the username of the account you just created.
!!! info
When running these commands, you'll get a bit of output like the following:
!!! warning "Promotion requires server restart"
Due to the way caching works in GoToSocial, some admin CLI commands require a server restart after running the command in order for the changes to "take".
For example, after promoting a user to admin, you will need to restart your GoToSocial server so that the new values can be loaded from the database.
```text
time=XXXX level=info msg=connected to SQLITE database
time=XXXX level=info msg=there are no new migrations to run func=doMigration
time=XXXX level=info msg=closing db connection
```
This is normal and indicates that the commands ran as expected.
!!! tip
Take a look at the other available CLI commands [here](../admin/cli.md).
## Containers
When running GoToSocial from a container, you'll need to execute the above command in the conatiner instead. How to do this varies based on your container runtime, but for Docker it should look like:
When running GoToSocial from a container, you'll need to execute the above command in the container instead. How to do this varies based on your container runtime, but for Docker it should look like:
```sh
$ docker exec -it CONTAINER_NAME_OR_ID \
docker exec -it CONTAINER_NAME_OR_ID \
/gotosocial/gotosocial \
admin account create \
--username some_username \