# Floppy for Cloudron

Unofficial Cloudron package for [Floppy](https://github.com/dannyvfilms/Floppy), using Cloudron-managed PostgreSQL and Redis.

## Why this package is different from Floppy's Docker Compose

Floppy's upstream Docker image expects a normal writable Docker filesystem and its entrypoint changes ownership on several image paths. Cloudron intentionally runs app images read-only except for `/tmp`, `/run`, and `/app/data`. This package therefore keeps the upstream application image but replaces the runtime entrypoint, Supervisor configuration, and Nginx runtime paths.

The package uses:

- Cloudron PostgreSQL -> Floppy `DB_HOST`, `DB_PORT`, `DB_NAME`, `DB_USER`, `DB_PASSWORD`
- Cloudron Redis -> Floppy `REDIS_URL`, cache and Celery URLs
- `/app/data` -> Floppy secret, user configuration, logs and backups
- Cloudron HTTPS proxy -> Floppy `URLS`, `ALLOWED_HOSTS`, forwarded-proto handling

## Install

Install the Cloudron CLI on your workstation, not on the Cloudron server:

```bash
sudo npm install -g cloudron
cloudron login my.example.com
```

Unzip this package and enter the directory:

```bash
cd floppy-cloudron
cloudron install
```

When prompted, choose the desired location, for example `floppy` for `https://floppy.example.com`.

Cloudron can build custom app source directly on the server, so no local Docker registry is required for this workflow.

## First run

On first start the package creates:

```text
/app/data/secret
/app/data/env.sh
```

`secret` is generated automatically and persists across updates/backups.

The initial `env.sh` contains:

```bash
REGISTRATION=True
TMDB_API=
TZ=Europe/Berlin
```

1. Open Floppy and create your user account.
2. Add your TMDb API key to `/app/data/env.sh`.
3. Change `REGISTRATION=True` to `REGISTRATION=False`.
4. Restart the app from the Cloudron dashboard.

You can edit `/app/data/env.sh` with the Cloudron File Manager or via:

```bash
cloudron exec
vi /app/data/env.sh
```

For hnz.io, TMDb is the important metadata provider, so set at least:

```bash
TMDB_API=YOUR_KEY
```

Optional integration keys can be added to `env.sh`, including Trakt, TVDB, MAL, IGDB, Steam, BoardGameGeek, Hardcover, ComicVine and Last.fm.

## Importing your old Trakt data

If you still have working Trakt API credentials for a private-profile OAuth import, add:

```bash
TRAKT_API=...
TRAKT_API_SECRET=...
```

Floppy also supports other import paths from its UI. After migration, hnz.io can use Floppy as the personal-data source while continuing to use TMDb for metadata.

## Cloudron resources

The manifest requests 2 GiB RAM. Floppy automatically adapts worker counts to available resources. This package intentionally starts one combined Celery worker by default, which is the safer layout for a personal Cloudron instance.

If you later give the app more memory and want Floppy's split worker layout, adjust the Supervisor config/package rather than setting arbitrary worker variables in `env.sh`.

## Updating Floppy

This package currently follows Floppy's stable `release` image:

```dockerfile
FROM ghcr.io/dannyvfilms/floppy:release
```

When a new Floppy version is released:

1. Check the [Floppy releases](https://github.com/dannyvfilms/Floppy/releases) and their release notes.
2. Increase `version` in `CloudronManifest.json`, for example from `0.1.4` to `0.1.5`. Cloudron requires a new package version for every update.
3. Log in with the Cloudron CLI and run the update from this repository:

```bash
cd floppy-cloudron
cloudron login my.example.com
cloudron update
```

This rebuilds the package and pulls the latest upstream `release` image. The data in `/app/data` and the Cloudron-managed PostgreSQL and Redis services remain in place during the update.

Afterwards, verify the deployment:

```bash
cloudron logs -f
```

Confirm that the database migrations completed and that Floppy opens normally before relying on the updated instance.

For reproducible production deployments, replace `:release` in the Dockerfile with a tested upstream `:vX.Y.Z` tag. For each later Floppy update, change that tag and increase the package `version` before running `cloudron update` again.

## Logs

Use:

```bash
cloudron logs -f
```

The application processes log primarily to stdout/stderr. Floppy's own file log/backups are directed to `/app/data/logs` and `/app/data/backups`.

## Troubleshooting

If the app does not become healthy:

```bash
cloudron logs -f
```

Verify that migrations completed and that Gunicorn is listening on `127.0.0.1:8001` behind Nginx.

For a shell:

```bash
cloudron exec
```

Useful checks inside the app:

```bash
env | grep '^CLOUDRON_\|^DB_\|^REDIS_'
cd /floppy
python manage.py check
```

Do not replace the Cloudron PostgreSQL variables with a `DATABASE_URL`: Floppy selects PostgreSQL only when `DB_HOST` is set.

## Status

This is an unofficial compatibility package assembled for a custom Cloudron installation. It follows the current Floppy `release` container contract and current Cloudron packaging/addon model, but it has not been executed against your actual Cloudron instance from this environment. Treat the first install as a deployment test and inspect the logs before moving production watch-history data into it.