201 lines
4.3 KiB
Markdown
201 lines
4.3 KiB
Markdown
# Troubleshoot backend issues
|
||
|
||
The Funkwhale backend is made up of lots of moving parts. This guide shows you how to troubleshoot and gather information about the most important elements of the backend.
|
||
|
||
## Tools
|
||
|
||
If you have access to the Funkwhale backend, you can use logs to get more information about an issue.
|
||
|
||
- **Reverse proxy logs** – check these logs if you have connectivity issues.
|
||
|
||
::::{tab-set}
|
||
|
||
:::{tab-item} Nginx
|
||
:sync: nginx
|
||
|
||
```{code-block} sh
|
||
sudo tail -f /var/log/nginx/access.log # Follow the access log
|
||
sudo tail -f /var/log/nginx/error.log # Follow the error log
|
||
```
|
||
|
||
:::
|
||
|
||
:::{tab-item} Apache2
|
||
:sync: apache2
|
||
|
||
```{code-block} sh
|
||
sudo tail -f /var/log/apache/access.log # Follow the access log
|
||
sudo tail -f /var/log/apache/error.log # Follow the error log
|
||
```
|
||
|
||
::::
|
||
|
||
- **API logs** – check these if you are having issues with the Funkwhale app, federation, or imports.
|
||
|
||
::::{tab-set}
|
||
|
||
:::{tab-item} Debian
|
||
:sync: debian
|
||
|
||
```{code-block} sh
|
||
journalctl -xn -u funkwhale-server
|
||
```
|
||
|
||
:::
|
||
|
||
:::{tab-item} Docker
|
||
:sync: docker
|
||
|
||
```{code-block} sh
|
||
docker compose logs -f --tail=50 api # Follow the last 50 messages
|
||
```
|
||
|
||
:::
|
||
::::
|
||
|
||
- **Celery logs** – check these if a federation or import task isn't working.
|
||
|
||
::::{tab-set}
|
||
|
||
:::{tab-item} Debian
|
||
:sync: debian
|
||
|
||
```{code-block} sh
|
||
journalctl -xn -u funkwhale-worker
|
||
```
|
||
|
||
:::
|
||
|
||
:::{tab-item} Docker
|
||
:sync: docker
|
||
|
||
```{code-block} sh
|
||
docker compose logs -f --tail=50 celery # Follow the last 50 messages
|
||
```
|
||
|
||
:::
|
||
::::
|
||
|
||
## Troubleshoot issues
|
||
|
||
### API issues
|
||
|
||
If the API isn't serving audio files, try the following:
|
||
|
||
- If you’re using Docker, check you have commented out the `MEDIA_ROOT` variable in your `.env` file.
|
||
- Check the `_protected/media` block in your webserver points to your media path. This is `/srv/funkwhale/data/media` by default.
|
||
- If you’re using the in-place import, check you have configured your media paths. Check the `MUSIC_DIRECTORY_PATH`, `MUSIC_DIRECTORY_SERVE_PATH` and `REVERSE_PROXY_TYPE` variables in your `.env` file. Make sure the webserver can read these directories.
|
||
|
||
### Import issues
|
||
|
||
If you're having issues importing files, try the following:
|
||
|
||
- Check that the file is encoded in a supported format
|
||
|
||
:::{dropdown} Supported formats
|
||
|
||
- flac
|
||
- ogg
|
||
- mp3
|
||
- opus
|
||
- aac
|
||
- m4a
|
||
- aiff
|
||
- aif
|
||
|
||
:::
|
||
|
||
- Make sure your files play in another media player.
|
||
- Make sure your files are [tagged correctly](../../user/libraries/content/tag.md).
|
||
- Check the Celery logs for errors during the import.
|
||
|
||
### Federation issues
|
||
|
||
If you are having issues accessing federated content, try the following:
|
||
|
||
- Check that the remote library received your follow request and approved it.
|
||
- Trigger a library scan in the Funkwhale frontend.
|
||
- Check the Celery logs for errors during the scan.
|
||
|
||
### Memory tracing
|
||
|
||
If your Funkwhale server uses more memory than expected, you can check the footprint of requests. This requires a middleware to check memory allocation. To set up this middleware:
|
||
|
||
1. Add the middleware to your `.env` file.
|
||
|
||
```{code-block} text
|
||
ADDITIONAL_MIDDLEWARES_BEFORE=funkwhale_api.common.middleware.PymallocMiddleware
|
||
```
|
||
|
||
2. Enable memory tracing in your `.env` file.
|
||
|
||
```{code-block} text
|
||
PYTHONTRACEMALLOC=1
|
||
```
|
||
|
||
3. Restart your Funkwhale server.
|
||
|
||
::::{tab-set}
|
||
|
||
:::{tab-item} Debian
|
||
:sync: debian
|
||
|
||
```{code-block} sh
|
||
sudo systemctl restart funkwhale.target
|
||
```
|
||
|
||
:::
|
||
|
||
:::{tab-item} Docker
|
||
:sync: docker
|
||
|
||
```{code-block} sh
|
||
docker compose restart
|
||
```
|
||
|
||
:::
|
||
::::
|
||
|
||
The middleware prints out the top 25 memory allocations to the API logs. You can use these to see what requests use the most memory.
|
||
|
||
To disable memory tracing:
|
||
|
||
1. Remove the middleware from your `.env` file.
|
||
|
||
```{code-block} text
|
||
# ADDITIONAL_MIDDLEWARES_BEFORE=funkwhale_api.common.middleware.PymallocMiddleware
|
||
```
|
||
|
||
2. Disable memory tracing in your `.env` file.
|
||
|
||
```{code-block} text
|
||
PYTHONTRACEMALLOC=0
|
||
```
|
||
|
||
3. Restart your Funkwhale server.
|
||
|
||
::::{tab-set}
|
||
|
||
:::{tab-item} Debian
|
||
:sync: debian
|
||
|
||
```{code-block} sh
|
||
sudo systemctl restart funkwhale.target
|
||
```
|
||
|
||
:::
|
||
|
||
:::{tab-item} Docker
|
||
:sync: docker
|
||
|
||
```{code-block} sh
|
||
docker compose restart
|
||
```
|
||
|
||
:::
|
||
::::
|
||
|
||
## Get help
|
||
|
||
If you can't solve the issue yourself, ask the community for help. Check out the [get help](help.md) guide for information about where to ask your question and what details to provide.
|