### Start the Docker containers and attach to the app Source: https://github.com/kieraneglin/pinchflat/wiki/Development-and-Contributing Starts the containers in detached mode and then attaches to the main app container to see logs and interact with the REPL. ```bash docker compose up -d && docker attach pinchflat-phx-1 ``` -------------------------------- ### Docker pull, build, and run commands for Pinchflat Source: https://github.com/kieraneglin/pinchflat/wiki/Installation Docker installation steps: pull the image from GHCR (also available on Docker Hub as keglin/pinchflat:latest) or build it locally, then run the container with the required port and volume mappings. Replace the host paths with the directories created in step 1. ```bash docker pull ghcr.io/kieraneglin/pinchflat:latest ``` ```bash docker build . --file selfhosted.Dockerfile -t ghcr.io/kieraneglin/pinchflat:latest ``` ```bash # Be sure to replace /host/path/to/config and /host/path/to/downloads below with # the paths to the directories you created in step 1 docker run \ -p 8945:8945 \ -v /host/path/to/config:/config \ -v /host/path/to/downloads:/downloads \ ghcr.io/kieraneglin/pinchflat:latest ``` -------------------------------- ### Example Payload JSON for Pinchflat Media Item Source: https://github.com/kieraneglin/pinchflat/wiki/[Advanced]-Custom-lifecycle-scripts Example JSON payload for a media item and its associated source and media profile. The source notes this may not be kept up-to-date and recommends generating example JSON using the steps above; the payload may differ per event in the future. ```json { "id": 1, "description": "...", "title": "...", "source_id": 1, "media_filepath": "...", "upload_date": "2000-01-01", "original_url": "https://www.youtube.com/watch?v=abc123", "uuid": "0c496b24-e012-42d1-8f6d-bd2d59c2b1a3", "prevent_download": false, "prevent_culling": false, "inserted_at": "2000-01-01T00:00:00Z", "updated_at": "2000-01-01T00:00:00Z", "culled_at": null, "media_size_bytes": 40687134, "thumbnail_filepath": "..", "duration_seconds": 500, "nfo_filepath": "...", "livestream": false, "media_downloaded_at": "2000-01-01T00:00:00Z", "media_id": "abc123", "media_redownloaded_at": null, "metadata_filepath": null, "short_form_content": false, "subtitle_filepaths": [], "upload_date_index": 0, "source": { "id": 1, "description": "...", "custom_name": "...", "original_url": "https://www.youtube.com/playlist?list=321cba", "uuid": "bb645fa8-9f7b-4dbf-a8e2-0f6a7d55f4d5", "media_profile_id": 1, "index_frequency_minutes": -1, "fast_index": false, "download_media": true, "download_cutoff_date": null, "retention_period_days": null, "title_filter_regex": null, "output_path_template_override": null, "collection_type": "playlist", "collection_name": "...", "inserted_at": "2000-01-01T00:00:00Z", "updated_at": "2000-01-01T00:00:00Z", "banner_filepath": null, "collection_id": "321cba", "fanart_filepath": null, "last_indexed_at": "2000-01-01T00:00:00Z", "nfo_filepath": "...", "poster_filepath": null, "series_directory": "...", "media_profile": { "id": 1, "name": "...", "output_path_template": "...", "download_subs": true, "download_auto_subs": false, "embed_subs": true, "sub_langs": "en", "download_thumbnail": true, "embed_thumbnail": true, "download_metadata": false, "embed_metadata": true, "shorts_behaviour": "exclude", "livestream_behaviour": "exclude", "preferred_resolution": "1080p", "redownload_delay_days": 1, "download_nfo": true, "download_source_images": true, "sponsorblock_behaviour": "disabled", "sponsorblock_categories": [], "inserted_at": "2000-01-01T00:00:00Z", "updated_at": "2000-01-01T00:00:00Z" } } } ``` -------------------------------- ### Example Bash lifecycle script Source: https://github.com/kieraneglin/pinchflat/wiki/[Advanced]-Custom-lifecycle-scripts Example lifecycle script in Bash that receives the event type and JSON data as arguments and prints a message using jq to extract the record ID. ```bash #!/bin/bash EVENT_TYPE=$1 EVENT_DATA=$2 echo "Script called with event type '$EVENT_TYPE' and a record ID #$(echo $EVENT_DATA | jq -r '.id')" ``` -------------------------------- ### Docker Compose configuration for Pinchflat Source: https://github.com/kieraneglin/pinchflat/blob/master/README.md Docker Compose configuration for running Pinchflat with a timezone, port mapping, and volume mounts for config and downloads. Use this with Portainer or any Docker Compose setup. ```yaml version: '3' services: pinchflat: image: ghcr.io/kieraneglin/pinchflat:latest environment: # Set the timezone to your local timezone - TZ=America/New_York ports: - '8945:8945' volumes: - /host/path/to/config:/config - /host/path/to/downloads:/downloads ``` -------------------------------- ### Example Python lifecycle script Source: https://github.com/kieraneglin/pinchflat/wiki/[Advanced]-Custom-lifecycle-scripts Example lifecycle script in Python that parses the JSON data argument and prints a message with the event type and record ID. ```python #!/bin/python3 import sys import json event_type = sys.argv[1] event_data = json.loads(sys.argv[2]) print("Script called with event type '{}' and an ID #{}".format(event_type, event_data["id"])) ``` -------------------------------- ### Open a shell in the Pinchflat container Source: https://github.com/kieraneglin/pinchflat/wiki/Development-and-Contributing Run this command in a separate terminal pane to get a shell inside the container for running tests and other commands. ```bash docker compose exec phx zsh ``` -------------------------------- ### NGINX location block for unauthenticated feed endpoints Source: https://github.com/kieraneglin/pinchflat/wiki/Podcast-RSS-Feeds NGINX location block that excludes feed endpoints from authentication. It matches routes like /sources/:id/feed, /sources/:id/feed_image, /media/:id/stream, and /media/:id/episode_image, optionally with a file extension. The proxy_pass directive forwards requests to the backend; you may need to add more directives depending on your setup. ```nginx location ~* (^/sources/[^/]+/feed(_image)?|^/media/[^/]+/(stream|episode_image))(\.[a-zA-Z0-9]+)?$ { # You may want to add more here depending on your setup proxy_pass $forward_scheme://$server:$port; } ``` -------------------------------- ### Run the test suite Source: https://github.com/kieraneglin/pinchflat/wiki/Development-and-Contributing Executes the project's test suite using Mix. ```bash mix test ``` -------------------------------- ### Docker run with Basic Auth Source: https://github.com/kieraneglin/pinchflat/wiki/Podcast-RSS-Feeds Adds BASIC_AUTH_USERNAME and BASIC_AUTH_PASSWORD environment variables to secure the Pinchflat instance. Test that the app prompts for credentials before continuing. ```bash docker run -p 8945:8945 \ -v /host/path/to/config:/config \ -v /host/path/to/downloads:/downloads \ -e BASIC_AUTH_USERNAME=admin \ -e BASIC_AUTH_PASSWORD=CHANGEME \ ghcr.io/kieraneglin/pinchflat:latest ``` -------------------------------- ### Attach to Pinchflat container for logs and REPL Source: https://github.com/kieraneglin/pinchflat/wiki/Development-and-Contributing Run this command in a terminal pane to see logs and interact with the Elixir REPL inside the running Pinchflat container. ```bash docker attach pinchflat-phx-1 ``` -------------------------------- ### Run full testing, linting, and static analysis Source: https://github.com/kieraneglin/pinchflat/wiki/Development-and-Contributing Runs a comprehensive check that includes testing, linting, and static analysis. ```bash mix check ``` -------------------------------- ### Docker Compose for Pinchflat (Portainer) Source: https://github.com/kieraneglin/pinchflat/wiki/Installation Docker Compose configuration for running Pinchflat with Portainer. Maps ports 8945 and mounts host directories for config and downloads. Note: prefer storing config on a local disk rather than a network share. ```yaml version: '3' services: pinchflat: image: keglin/pinchflat:latest ports: - '8945:8945' volumes: - /host/path/to/config:/config - /host/path/to/downloads:/downloads ``` -------------------------------- ### Build the Docker image without cache Source: https://github.com/kieraneglin/pinchflat/wiki/Development-and-Contributing Builds the Docker image from scratch, ignoring cached layers. Useful for a clean build. ```bash docker compose build --no-cache ``` -------------------------------- ### Podman run command for Pinchflat Source: https://github.com/kieraneglin/pinchflat/blob/master/README.md Podman command to run Pinchflat under a User Namespace with the current user's UID/GID. Uses --userns=keep-id and --user=$UID for file access; consider creating a dedicated pinchflat user and giving it ownership of the config and download directories. ```bash podman run \ --security-opt label=disable \ --userns=keep-id --user=$UID \ -e TZ=America/Los_Angeles \ -p 8945:8945 \ -v /host/path/to/config:/config:rw \ -v /host/path/to/downloads/:/downloads:rw \ ghcr.io/kieraneglin/pinchflat:latest ``` -------------------------------- ### Testing script to save event data Source: https://github.com/kieraneglin/pinchflat/wiki/[Advanced]-Custom-lifecycle-scripts Temporary lifecycle script that saves the event data to /tmp/example.json for testing purposes. ```bash #!/bin/bash EVENT_TYPE=$1 EVENT_DATA=$2 echo $EVENT_DATA >/tmp/example.json echo "Data for '$EVENT_TYPE' saved to /tmp/example.json" ``` -------------------------------- ### Docker run with Basic Auth and EXPOSE_FEED_ENDPOINTS Source: https://github.com/kieraneglin/pinchflat/wiki/Podcast-RSS-Feeds Adds EXPOSE_FEED_ENDPOINTS=yes to exclude feed endpoints from authentication, allowing podcast apps to access XML feeds, assets, and media without credentials. All routes are protected by default. ```bash docker run -p 8945:8945 \ -v /host/path/to/config:/config \ -v /host/path/to/downloads:/downloads \ -e BASIC_AUTH_USERNAME=admin \ -e BASIC_AUTH_PASSWORD=CHANGEME \ -e EXPOSE_FEED_ENDPOINTS=yes \ ghcr.io/kieraneglin/pinchflat:latest ``` -------------------------------- ### Upgrade heroicons to a specific version Source: https://github.com/kieraneglin/pinchflat/blob/master/assets/vendor/heroicons/UPGRADE.md Upgrade heroicons in place to a specified version by downloading and extracting the optimized icons from the GitHub release archive. ```bash export HERO_VSN="2.0.16" ; \ curl -L "https://github.com/tailwindlabs/heroicons/archive/refs/tags/v${HERO_VSN}.tar.gz" | \ tar -xvz --strip-components=1 heroicons-${HERO_VSN}/optimized ``` -------------------------------- ### Prometheus scrape configuration for Pinchflat Source: https://github.com/kieraneglin/pinchflat/wiki/Prometheus-and-Grafana Add this scrape_configs block to your Prometheus configuration to collect metrics from Pinchflat. The target address uses your server's IP and port 8945. Requires ENABLE_PROMETHEUS to be set to any non-empty value. ```yaml scrape_configs: - job_name: pinchflat static_configs: - targets: ['your.server.ip:8945'] ``` -------------------------------- ### Command to test lifecycle script Source: https://github.com/kieraneglin/pinchflat/wiki/[Advanced]-Custom-lifecycle-scripts Command to manually test the lifecycle script by passing the event type and the saved JSON data. ```bash /app/tmp/extras/user-scripts/lifecycle media_downloaded "$(cat /tmp/example.json)" ``` -------------------------------- ### Update yt-dlp manually in Pinchflat Docker container Source: https://github.com/kieraneglin/pinchflat/wiki/Frequently-Asked-Questions Steps to manually update yt-dlp inside the Pinchflat Docker container. First, open a root shell in the container, adjusting the user or container name if needed. Then run the update command; no container restart is required. ```bash docker exec -it --user root pinchflat bash ``` ```bash yt-dlp -U ```