floppy-cloudron/README.md

Floppy for Cloudron

Unofficial Cloudron package for 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:

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

Unzip this package and enter the directory:

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:

/app/data/secret
/app/data/env.sh

secret is generated automatically and persists across updates/backups.

The initial env.sh contains:

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:

cloudron exec
vi /app/data/env.sh

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

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:

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 uses:

FROM ghcr.io/dannyvfilms/floppy:release

To refresh to the current stable upstream image, rebuild/update the Cloudron package:

cloudron update

For fully reproducible production deployments, replace :release in the Dockerfile with a specific upstream :vX.Y.Z tag after testing that release, then bump the Cloudron package version.

Logs

Use:

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:

cloudron logs -f

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

For a shell:

cloudron exec

Useful checks inside the app:

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.