Rewrite admin documentation

docs/administrator_documentation/manage_script/database.md

@@ -0,0 +1,27 @@
+# Delete obsolete files from the database
+
+Funkwhale keeps references to files imported using the in-place method. If you move or remove these, it invalidates the reference and Funkwhale can't serve the files.
+
+Use the `check_inplace_files` command to check the database for invalid references. This command loops through all in-place imports and checks if the file is accessible. If the file isn't accessible, the command deletes the database object.
+
+```{warning}
+Running `check_inplace_files` with the `--no-dry-run` flag is irreversible. Make sure you [back up your data](../upgrade_docs/backup.md).
+```
+
+To ensure you don't remove data by accident, this command runs in dry run mode by default. In dry run mode, the command lists the items it will delete. Run the command with the `--no-dry-run` flag to perform the pruning action.
+
+````{tabbed} Debian
+
+```{code} bash
+poetry run python manage.py check_inplace_files
+```
+
+````
+
+````{tabbed} Docker
+
+```{code} bash
+docker-compose run --rm api python manage.py check_inplace_files
+```
+
+````

docs/administrator_documentation/manage_script/fix_uploads.md

@@ -0,0 +1,105 @@
+# Fix uploads
+
+Use the `fix_uploads` command to let Funkwhale sort out common issues with your audio files.
+
+## Commands
+
+### Fix mimetypes
+
+Check and fix file mimetypes with the `--mimetype` flag. This helps prevent issues with serving music files.
+
+````{tabbed} Debian
+
+```{code} bash
+poetry run python manage.py fix_uploads --mimetype
+```
+
+````
+
+````{tabbed} Docker
+
+```{code} bash
+docker-compose run --rm api python manage.py fix_uploads --mimetype
+```
+
+````
+
+### Fix bitrate and duration
+
+Check and fix bitrate and duration with the `--audio-data` flag. This process can take a long time as it needs to access all files.
+
+````{tabbed} Debian
+
+```{code} bash
+poetry run python manage.py fix_uploads --audio-data
+```
+
+````
+
+````{tabbed} Docker
+
+```{code} bash
+docker-compose run --rm api python manage.py fix_uploads --audio-data
+```
+
+````
+
+### Fix file size
+
+Check and fix the file size with the `--size` flag.
+
+````{tabbed} Debian
+
+```{code} bash
+poetry run python manage.py fix_uploads --size
+```
+
+````
+
+````{tabbed} Docker
+
+```{code} bash
+docker-compose run --rm api python manage.py fix_uploads --size
+```
+
+````
+
+### Fix file checksums
+
+Check and fix file checksums with the `--checksum` flag.
+
+````{tabbed} Debian
+
+```{code} bash
+poetry run python manage.py fix_uploads --checksum
+```
+
+````
+
+````{tabbed} Docker
+
+```{code} bash
+docker-compose run --rm api python manage.py fix_uploads --checksum
+```
+
+````
+
+### Change command batch size
+
+Choose the batch size you want to process with the `--batch-size` or -`s` flag. Smaller batches process faster. Defaults to `1000`.
+
+````{tabbed} Debian
+
+```{code} bash
+poetry run python manage.py fix_uploads --batch-size 500
+```
+
+````
+
+````{tabbed} Docker
+
+```{code} bash
+docker-compose run --rm api python manage.py fix_uploads --batch-size 500
+```
+
+````

docs/administrator_documentation/manage_script/index.md

@@ -0,0 +1,18 @@
+# Funkwhale management script
+
+Funkwhale includes a {file}`manage.py` script that can help you automate a lot of admin tasks. Check out the guides in this section for instructions on how to use this tool.
+
+```{toctree}
+---
+caption: Administration tasks
+maxdepth: 1
+---
+
+Manage users <users>
+Prune library <library>
+Clean database <database>
+Add album and artist tags <tags>
+thumbnails
+fix_uploads
+
+```

docs/administrator_documentation/manage_script/library.md

@@ -0,0 +1,111 @@
+# Prune your Funkwhale library
+
+Funkwhale doesn't delete data objects from the database when you delete a file. This is because they might exist in users' playlists, favorites, and listening history. These objects might also be present in another user's private libraries.
+
+Sometimes you may want to clear out dangling metadata. For example, if you import a lot of files with incorrect tags and then delete them.
+
+To help with this, the {file}`manage.py` script includes commands to prune dangling metadata from your database. All prune commands are available under the python manage.py prune_library namespace. To ensure you don't remove data by accident, all commands run in dry run mode by default. Run commands with the `--no-dry-run` flag to perform the pruning action.
+
+```{warning}
+Running `prune_library` commands with the `--no-dry-run` flag is irreversible. Make sure you [back up your data](../upgrade_docs/backup.md).
+```
+
+## Commands
+
+### Prune tracks with no associated uploads
+
+````{tabbed} Debian
+
+```bash
+poetry run python manage.py prune_library --tracks
+```
+
+````
+
+````{tabbed} Docker
+
+```bash
+docker-compose run --rm api python manage.py prune_library --tracks
+```
+
+````
+
+### Prune albums with no associated tracks
+
+````{tabbed} Debian
+
+```{code} bash
+poetry run python manage.py prune_library --albums
+```
+
+````
+
+````{tabbed} Docker
+
+```{code} bash
+docker-compose run --rm api python manage.py prune_library --albums
+```
+
+````
+
+### Prune artists with no associated tracks or albums
+
+````{tabbed} Debian
+
+```{code} bash
+poetry run python manage.py prune_library --artists
+```
+
+````
+
+````{tabbed} Docker
+
+```{code} bash
+docker-compose run --rm api python manage.py prune_library --artists
+```
+
+````
+
+### Prune all tracks, albums, and artist without associated data
+
+````{tabbed} Debian
+
+```{code} bash
+poetry run python manage.py prune_library --tracks --albums --artists
+```
+
+````
+
+````{tabbed} Docker
+
+```{code} bash
+docker-compose run --rm api python manage.py prune_library --tracks --albums --artists
+```
+
+````
+
+There are extra options for pruning your database. Check the command help for more options.
+
+````{tabbed} Debian
+
+```{code} bash
+poetry run python manage.py prune_library --help
+```
+
+````
+
+````{tabbed} Docker
+
+```{code} bash
+docker-compose run --rm api python manage.py prune_library --help
+```
+
+````
+
+```{note}
+The command excludes tracks that are in users' favorites, playlists, and listen history. To include these tracks, add the corresponding `ignore` flag:
+
+- `--ignore-favorites`
+- `--ignore-playlists`
+- `--ignore-listenings`
+```

docs/administrator_documentation/manage_script/tags.md

@@ -0,0 +1,85 @@
+# Add artist and album tags from track metadata
+
+Funkwhale extracts track tags from the file's metadata. Funkwhale applies these tags to the track's album and artist by running a check every few days. You can run the process at any time using the `manage.py` script.
+
+The command performs the following actions:
+
+1. Finds all local artists or albums with no tags.
+2. Gets all the tags associated with the album/artist's tracks.
+3. Applies the track's tags to the album/artist.
+
+## Add tags to albums
+
+To add tags to untagged albums:
+
+```{tabbed} Debian
+
+1. SSH into your Funkwhale server.
+2. Navigate to the Funkwhale directory.
+
+      ```{code} bash
+      cd /srv/funkwhale
+      ```
+
+3. Run the `manage.py` script to generate tags for untagged albums.
+
+      ```{code} bash
+      poetry run python manage.py fw albums add-tags-from-tracks
+      ```
+
+```
+
+```{tabbed} Docker
+
+1. SSH into your Funkwhale server.
+2. Navigate to the Funkwhale directory.
+
+      ```{code} bash
+      cd /srv/funkwhale
+      ```
+
+3. Run the `manage.py` script to generate tags for untagged albums.
+
+      ```{code} bash
+      docker-compose run --rm api python manage.py fw albums add-tags-from-tracks
+      ```
+
+```
+
+## Add tags to artists
+
+To add tags to untagged artists:
+
+```{tabbed} Debian
+
+1. SSH into your Funkwhale server.
+2. Navigate to the Funkwhale directory.
+
+      ```{code} bash
+      cd /srv/funkwhale
+      ```
+
+3. Run the `manage.py` script to generate tags for untagged artists.
+
+      ```{code} bash
+      poetry run python manage.py fw artists add-tags-from-tracks
+      ```
+
+```
+
+```{tabbed} Docker
+
+1. SSH into your Funkwhale server.
+2. Navigate to the Funkwhale directory.
+
+      ```{code} bash
+      cd /srv/funkwhale
+      ```
+
+3. Run the `manage.py` script to generate tags for untagged artists.
+
+      ```{code} bash
+      docker-compose run --rm api python manage.py fw artists add-tags-from-tracks
+      ```
+
+```

docs/administrator_documentation/manage_script/thumbnails.md

@@ -0,0 +1,57 @@
+# Regenerate thumbnails
+
+We increased the quality of thumbnails from 70px to 95px in Funkwhale 1.0. This action removes visual artifacts that affect lower quality thumbnails. You can run the `manage.py` script to generate new thumbnails. If you want to keep thumbnails at their original quality, add `THUMBNAIL_JPEG_RESIZE_QUALITY=70` to your `.env` file.
+
+```{note}
+If you're using S3 storage, the `__sized__` folder is located in your S3 bucket.
+```
+
+To generate new thumbnails:
+
+```{tabbed} Debian
+
+1. SSH into your Funkwhale server.
+2. Navigate to your Funkwhale directory.
+
+      ```{code} bash
+      cd  /srv/funkwhale
+      ```
+
+3. Delete the `__sized__` directory inside your `MEDIA_ROOT` directory. By default this is `/srv/funkwhale/data/media`. This directory contains the current thumbnails.
+
+      ```{code} bash
+      rm -r __sized__/
+      ```
+
+4. Run the `manage.py` script to regenerate the thumbnails.
+
+      ```{code} bash
+      poetry run python manage.py fw media generate-thumbnails
+      ```
+
+```
+
+```{tabbed} Docker
+
+1. SSH into your Funkwhale server.
+2. Navigate to your Funkwhale directory.
+
+      ```{code} bash
+      cd  /srv/funkwhale/
+      ```
+
+3. Delete the `__sized__` directory inside your `MEDIA_ROOT` directory. By default this is `/srv/funkwhale/data/media`. This directory contains the current thumbnails.
+
+      ```{code} bash
+      rm -r data/media/__sized__/
+      ```
+
+4. Run the `manage.py` script to regenerate the thumbnails.
+
+      ```{code} bash
+      docker-compose run --rm api python manage.py fw media generate-thumbnails
+      ```
+
+```
+
+The script generates new thumbnails for all album and artist art on your pod.

docs/administrator_documentation/manage_script/users.md

@@ -0,0 +1,275 @@
+# Manage users with manage.py
+
+The {file}`manage.py` script includes commands for user management. Use these commands to automate managing users from the command line.
+
+All users-related commands are available under the `python manage.py fw users` namespace.
+
+## Create users
+
+You can create users with the {file}`manage.py` script. There are different ways to create users depending on what approach you want to take.
+
+### Create a user interactively
+
+````{tabbed} Debian
+
+```{code} bash
+poetry run python manage.py fw users create
+```
+
+````
+
+````{tabbed} Docker
+
+```{code} bash
+docker-compose run --rm api python manage.py fw users create
+```
+
+````
+
+### Create a user with a random password
+
+````{tabbed} Debian
+
+```{code} bash
+poetry run python manage.py fw users create --username <username> --email <user email> -p ""
+```
+
+````
+
+````{tabbed} Docker
+
+```{code} bash
+docker-compose run --rm api python manage.py fw users create --username <username> --email <user email> -p ""
+```
+
+````
+
+### Create a user with a password set from an environment variable
+
+````{tabbed} Debian
+
+```{code} bash
+export FUNKWHALE_CLI_USER_PASSWORD=<password>
+poetry run python manage.py fw users create --username <username> --email <user email>
+```
+
+````
+
+````{tabbed} Docker
+
+```{code} bash
+export FUNKWHALE_CLI_USER_PASSWORD=<password>
+docker-compose run --rm api python manage.py fw users create --username <username> --email <user email>
+```
+
+````
+
+There are extra options for user configuration, such as quota and {term}`permissions`. Check the command help for more options.
+
+````{tabbed} Debian
+
+```{code} bash
+poetry run python manage.py fw users --help
+```
+
+````
+
+````{tabbed} Docker
+
+```{code} bash
+docker-compose run --rm api python manage.py fw users --help
+```
+
+````
+
+## Update users
+
+You can update user accounts using the {file}`manage.py` script. Update commands are available under the `python manage.py fw users set` namespace.
+
+### Set upload quota for a user
+
+````{tabbed} Debian
+
+```{code} bash
+poetry run python manage.py fw users set --upload-quota 500 <user>
+```
+
+````
+
+````{tabbed} Docker
+
+```{code} bash
+docker-compose run --rm api python manage.py fw users set --upload-quota 500 <user>
+```
+
+````
+
+### Make users staff members
+
+````{tabbed} Debian
+
+```{code} bash
+poetry run python manage.py fw users set --staff --superuser <user 1> <user 2>
+```
+
+````
+
+````{tabbed} Docker
+
+```{code} bash
+docker-compose run --rm api python manage.py fw users set --staff --superuser <user 1> <user 2>
+```
+
+````
+
+### Remove a user's staff privileges
+
+````{tabbed} Debian
+
+```{code} bash
+poetry run python manage.py fw users set --no-staff --no-superuser <user>
+```
+
+````
+
+````{tabbed} Docker
+
+```{code} bash
+docker-compose run --rm api python manage.py fw users set --no-staff --no-superuser <user>
+```
+
+````
+
+### Give a user moderation permissions
+
+````{tabbed} Debian
+
+```{code} bash
+poetry run python manage.py fw users set --permission-moderation <user>
+```
+
+````
+
+````{tabbed} Docker
+
+```{code} bash
+docker-compose run --rm api python manage.py fw users set --permission-moderation <user>
+```
+
+````
+
+### Reset a user's password
+
+````{tabbed} Debian
+
+```{code} bash
+poetry run python manage.py fw users set --password "<password>" <user>
+```
+
+````
+
+````{tabbed} Docker
+
+```{code} bash
+docker-compose run --rm api python manage.py fw users set --password "<password>" <user>
+```
+
+````
+
+### Reset a user's password using an environment variable
+
+````{tabbed} Debian
+
+```{code} bash
+export FUNKWHALE_CLI_USER_UPDATE_PASSWORD=<password>
+poetry run python manage.py fw users set <user>
+```
+
+````
+
+````{tabbed} Docker
+
+```{code} bash
+export FUNKWHALE_CLI_USER_UPDATE_PASSWORD=<password>
+docker-compose run --rm api python manage.py fw users set <user>
+```
+
+````
+
+There are extra options for updating users. Check the command help for more options.
+
+````{tabbed} Debian
+
+```{code} bash
+poetry run python manage.py fw users set --help
+```
+
+````
+
+````{tabbed} Docker
+
+```{code} bash
+docker-compose run --rm api python manage.py fw users set --help
+```
+
+````
+
+## Delete users
+
+### Delete a user's account but leave a reference to them in the database
+
+This prevents the same username being used in future.
+
+````{tabbed} Debian
+
+```{code} py
+poetry run python manage.py fw users rm <user>
+```
+
+````
+
+````{tabbed} Docker
+
+```{code} py
+docker-compose run --rm api python manage.py fw users rm <user>
+```
+
+````
+
+### Delete a user's account, including all references in the database
+
+This means the username can be reused.
+
+````{tabbed} Debian
+
+```{code} py
+poetry run python manage.py fw users rm --hard <user>
+```
+
+````
+
+````{tabbed} Docker
+
+```{code} py
+docker-compose run --rm api python manage.py fw users rm --hard <user>
+```
+
+````
+
+There are extra options for deleting users. Check the command help for more options.
+
+````{tabbed} Debian
+
+```{code} bash
+poetry run python manage.py fw users rm --help
+```
+
+````
+
+````{tabbed} Docker
+
+```{code} bash
+docker-compose run --rm api python manage.py fw users rm --help
+```
+
+````