# Cleanmedia Setup Guide

This guide will help you set up Cleanmedia for your Dendrite Matrix server. Cleanmedia is a data retention policy tool that helps manage media storage by implementing configurable retention policies for both remote and local media files.

## Prerequisites

Before starting, ensure that:
- Dendrite is properly configured and running.
- You have the correct file paths for your media storage.
- You understand which media files you want to retain/remove.

## Configuration Options

You can customize Cleanmedia's behavior through environment variables in your docker-compose file:

### CRON

The `CRON` variable determines when Cleanmedia will run its cleanup routine. Examples:

```yaml
environment:
  - CRON=0 0 * * *    # Daily at midnight (default)
  - CRON=0 */6 * * *  # Every 6 hours
  - CRON=0 0 */2 * *  # Every 2 days at midnight
  - CRON=0 0 * * 0    # Weekly on Sunday at midnight
  - CRON=0 12 * * 1-5 # Weekdays at noon
```

### CLEANMEDIA_OPTS

The `CLEANMEDIA_OPTS` variable controls how Cleanmedia performs its cleanup:

- `-c /etc/dendrite/dendrite.yaml`: Path to your Dendrite configuration file. Leave it as is.
- `-t 30`: Keep media for 30 days (adjust number as needed).
- `-l`: Include local user media in cleanup (optional).
- `-n`: Dry run mode - simulates cleanup without deleting files.
- `-d`: Debug mode for more verbose output.

### Example Configurations

1. Conservative cleanup (90-day retention, remote media only):
```yaml
environment:
  - CRON=0 0 * * *  # Daily at midnight
  - CLEANMEDIA_OPTS=-c /etc/dendrite/dendrite.yaml -t 90
```

2. Aggressive cleanup (7-day retention, including local media):
```yaml
environment:
  - CRON=0 */12 * * *  # Twice daily
  - CLEANMEDIA_OPTS=-c /etc/dendrite/dendrite.yaml -t 7 -l
```

3. Test run (dry run with debug output):
```yaml
environment:
  - CRON=0 0 * * *  # Daily at midnight
  - CLEANMEDIA_OPTS=-c /etc/dendrite/dendrite.yaml -t 30 -l -n -d
```

## Important Notes

- Always test new configurations with the `-n` (dry run) flag first.
- Local media cleanup (`-l` flag) should be used with caution as files might not be retrievable after deletion.
- User avatars are automatically preserved.
- The service depends on the monolith service being available.
- Volume mounts must match your Dendrite configuration.

## Troubleshooting

1. **Missing Files**
   - Verify volume mount paths match your Dendrite configuration.
   - Check file permissions in mounted directories.
   - Ensure Dendrite service is running properly.

2. **Service Won't Start**
   - Check logs: `docker compose logs cleanmedia`.
   - Verify Dendrite configuration file path.
   - Ensure monolith service is running.

3. **Unexpected Deletions**
   - Always test with `-n` flag first.
   - Review debug logs with `-d` flag.
   - Check retention period settings.

## Next Steps

For more detailed information about Cleanmedia features and configuration options, visit the [Cleanmedia documentation](https://gitlab.com/rogs/cleanmedia).

Proceed to set up the [Whatasapp Bridge](../mautrix-whatsapp/README.md).