first commit

README.md

@@ -0,0 +1,146 @@
+# 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 uses:
+
+```dockerfile
+FROM ghcr.io/dannyvfilms/floppy:release
+```
+
+To refresh to the current stable upstream image, rebuild/update the Cloudron package:
+
+```bash
+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:
+
+```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.