- PinePods 🌲
- Getting Started
PinePods is a Python based app that can sync podcasts for individual accounts that relies on a central database with a web frontend and apps available on multiple platforms
Pinepods is a complete podcasts management system and allows you to play, download, and keep track of podcasts you enjoy. It allows for searching new podcasts using The Podcast Index and provides a modern looking UI to browse through shows and episodes. In addition, Pinepods provides simple user managment and can be used by multiple users at once using a browser or app version. Everything is saved into a Mysql database including user settings, podcasts and episodes. It's fully self-hosted, and I provide an option to use a hosted API or you can also get one from the podcast API and use your own. There's even many different themes to choose from! Everything is fully dockerized and I provide a simple guide found below explaining how to install Pinepods on your own system.
I try and maintain an instance of Pinepods that's publicly accessible for testing over at try.pinepods.online. Feel free to make an account there and try it out before making your own server instance. This is not intended as a permanant method of using Pinepods and it's expected you run your own server so accounts will often be deleted from there.
There's potentially a few steps to getting Pinepods fully installed as after you get your server up and running fully. You can also install the client editions of your choice. The server install of Pinepods runs a server and a browser client over a port of your choice in order to be accessible on the web. With the client installs you simply give your install a specific url to connect to the database and then sign in.
First, the server. It's hightly recommended you run the server using docker compose. Here's the docker compose yaml needed.
version: '3'
services:
db:
image: mariadb:latest
command: --wait_timeout=1800
environment:
MYSQL_TCP_PORT: 3306
MYSQL_ROOT_PASSWORD: myS3curepass
MYSQL_DATABASE: pypods_database
MYSQL_COLLATION_SERVER: utf8mb4_unicode_ci
MYSQL_CHARACTER_SET_SERVER: utf8mb4
MYSQL_INIT_CONNECT: 'SET @@GLOBAL.max_allowed_packet=64*1024*1024;'
volumes:
- /home/user/pinepods/sql:/var/lib/mysql
ports:
- "3306:3306"
restart: always
pinepods:
image: madeofpendletonwool/pinepods:latest
ports:
# Web Portal Port
- "8034:8034"
# API Server Port - Needed for Client Connections
- "8032:8032"
# Image Proxy Port - Needed to Display Some Images
- "8000:8000"
environment:
# Default Admin User Information
USERNAME: myadminuser01
PASSWORD: myS3curepass
FULLNAME: Pinepods Admin
EMAIL: [email protected]
# Database Vars
DB_HOST: db
DB_PORT: 3306
DB_USER: root
DB_PASSWORD: myS3curepass
DB_NAME: pypods_database
# Image/Audio Proxy Vars
PROXY_HOST: proxy.pinepods.online
PROXY_PORT: 8000
PROXY_PROTOCOL: https
REVERSE_PROXY: "True"
# Search Index API Vars
API_URL: 'https://search.pinepods.online/api/search'
# Client API Vars
API_SERVER_PORT: 8032
volumes:
# Mount the download location on the server if you want to. You could mount a nas to this folder or something like that
- /home/user/pinepods/downloads:/opt/pypods/downloads
depends_on:
- db
Make sure you change these variables to variables specific to yourself.
MYSQL_ROOT_PASSWORD: password
USERNAME: pinepods
PASSWORD: password
FULLNAME: John Pinepods
EMAIL: [email protected]
DB_PASSWORD: password # This should match the MSQL_ROOT_PASSWORD
PROXY_HOST: proxy.pinepods.online
PROXY_PORT: 8033
PROXY_PROTOCOL: http
REVERSE_PROXY: "True"
API_URL: 'https://api.pinepods.online/api/search'
Most of those are pretty obvious, but let's break a couple of them down.
First of all, the USERNAME, PASSWORD, FULLNAME, and EMAIL vars are your details for your default admin account. This account will have admin credentails and will be able to log in right when you start up the app. Once started you'll be able to create more users and even more admins but you need an account to kick things off on. If you don't specify credentials in the compose file it will create an account with a random password for you but I would recommend just creating one for yourself.
Second, the PROXY_HOST, PROXY_PORT, PROXY_PROTOCOL, and REVERSE_PROXY vars. Pinepods uses a proxy to route both images and audio files in order to prevent CORs issues in the app (Essentially so podcast images and audio displays correctly and securely). It runs a little internal Flask app to accomplish this. That's the Image/Audio Proxy Vars portion of the compose file. The application itself will then use this proxy to route media though. This proxy can also be ran over a reverse proxy. Here's few examples
Recommended: Routed through proxy, secure, with reverse proxy
PROXY_HOST: proxy.pinepods.online
PROXY_PORT: 8033
PROXY_PROTOCOL: https
REVERSE_PROXY: "True"
Note: With reverse proxies you create a second proxy host. So for example my Pinepods instance itself runs at port 8034 at pinpods.online so my reverse proxy reflects that and I have a dns record for the domain created for pinepods.online to point to my public ip. In addition, my proxy is ran at port 8033 over domain proxy.pinepods.online. I created a seperate dns record for this pointed to my public ip.
Also Note: If you run pinepods over reverse proxy to secure it you must run the proxy server over reverse proxy as well to prevent mixed content in the browser
Direct to ip, insecure, and no reverse proxy
PROXY_HOST: 192.168.0.30
PROXY_PORT: 8033
PROXY_PROTOCOL: http
REVERSE_PROXY: "False"
Hostname, secure, and no reverse proxy
PROXY_HOST: proxy.pinepods.online
PROXY_PORT: 8033
PROXY_PROTOCOL: https
REVERSE_PROXY: "False"
Note: Changing REVERSE_PROXY to False adjusts what the application uses for the reverse proxy. In short it removed the port from the url it uses for routing since the reverse proxy will add the port for you.
So REVERSE_PROXY "True" - App will use https://proxy.pinepods.online
REVERSE_PROXY "False" - App will use https://proxy.pinepods.online:8033
Let's talk quickly about the searching API. This allows you to search for new podcasts and it queries either itunes or the podcast index for new podcasts. The podcast index requires an api key while itunes does not. If you'd rather not mess with the api at all simply set the API_URL to the one below.
API_URL: 'https://api.pinepods.online/api/search'
Above is an api that I maintain. I do not guarantee 100% uptime on this api though, it should be up most of the time besides a random internet or power outage here or there. A better idea though, and what I would honestly recommend is to maintain your own api. It's super easy. Check out the API docs for more information on doing this. Link Below -
https://www.pinepods.online/docs/API/search_api
The Client API server port variable tells Pinepods what port to expose the FastAPI routes on. This is needed to connect to the server with the Pinepods client/app version. The API_SERVER_PORT variable and API server port that is exposed in the compose file need to be the same.
# API Server Port - Needed for Client Connections
- "8032:8032"
...
API_SERVER_PORT: 8032
Either way, once you have everything all setup and your compose file created go ahead and run your
sudo docker-compose up
command on the main pinepods app to pull the container images and get started. Once fully started up you'll be able to access pinepods on the url you configured and you'll be able to start connecting clients as well once you get an API from the settings area in the web app. Check out the Tutorials on the documentation site for more information on how to do basic things.
https://pinepods.online/tutorial-basic/sign-in-homescreen.md
Any of the client additions are super easy to get going. First head over to the releases page on Github
https://github.com/madeofpendletonwool/PinePods/releases
Grab the pinepods.tar file from the newest release.
Extract, and then within the extracted folder you'll find an install.sh file. This file simply drops the icon file, and binary in place then installs a .desktop file so your computer will pick up on the app. Ensure the install file has executable permission
cd /pinepods/folder/location
chmod +x ./install.sh
Then run
./install.sh
From there, you should be able to search your computer for pinepods and find the client installed as long as your desktop environment supports .desktop files. Otherwise, you can also just run the 'pinepods' file from within the folder directory.
Once started you'll need to connect to your server and provide an api key. You can create an api key from the web version of the app. Go to settings and then scroll to the bottom. You'll see where you can generate a new key. Copy that, and put it in the api key textfield.
Your server name is where the api server port comes in.
# API Server Port - Needed for Client Connections
- "8032:8032"
So in my case running on my local computer I could enter http://localhost:8032
If you create a reverse proxy to that port you might enter https://api.mysite.com
Any of the client additions are super easy to get going. First head over to the releases page on Github
https://github.com/madeofpendletonwool/PinePods/releases
Grab the Pinepods-Windows.zip file from the newest release.
Simply extract, and then run.
Once started you'll need to connect to your server and provide an api key. You can create an api key from the web version of the app. Go to settings and then scroll to the bottom. You'll see where you can generate a new key. Copy that, and put it in the api key textfield.
Your server name is where the api server port comes in.
# API Server Port - Needed for Client Connections
- "8032:8032"
So in my case running on my local computer I could enter http://localhost:8032
If you create a reverse proxy to that port you might enter https://api.mysite.com
Any of the client additions are super easy to get going. First head over to the releases page on Github
https://github.com/madeofpendletonwool/PinePods/releases
Grab the Pinepods-Mac.zip file from the newest release.
Simply extract, and then go into Contents/MacOS. From there you can run the app.
You can also place the pinepods app right into your application folder on your mac. Just drag 'pinepods' right in.
Once started you'll need to connect to your server and provide an api key. You can create an api key from the web version of the app. Go to settings and then scroll to the bottom. You'll see where you can generate a new key. Copy that, and put it in the api key textfield.
Your server name is where the api server port comes in.
# API Server Port - Needed for Client Connections
- "8032:8032"
So in my case running on my local computer I could enter http://localhost:8032
If you create a reverse proxy to that port you might enter https://api.mysite.com
Coming Soon
Coming Soon
The Intention is for this app to become available on Windows, Linux, Mac, Android, and IOS. Windows, Linux, Mac, and web are all currently available and working. For a temporary solution for phones you can access the web version from them. The server is run from docker and connects to the clients on all platforms.
- Postgresql backend instead of mysql
- Export and import of following podcasts (basically backups)
- Import of custom rss feeds from URL
- Client sharing. Search network for other clients and play to them Lightweight client
- Rework local images to run through the image proxy for web
- How-to guides on doing things in the app
- Timestamps in playing page
- Full Screen Currently Playing Page (Mostly implemented. There's a couple bugs on the web version to fix)
- playing page not currently removing playing bar on bottom in app version
- Podcast list search
- Exportable backups
- Mass delete options not appearing in web version. This seems to be a bug. It works totally fine in client app
- Implement page views for poddisplays that have over 30 episodes
- Jump to clicked timestamp
- Offline mode for playing locally downloaded episodes
- Allow for episodes to be played without being added
- Add highlight to indicate which page you're on
- Suggestions page - Create podcasts you might like based on the ones you already added
- Make scrolling screens roll up more. So that the currently playing episode doesn't get in the way of your view
- Rotating currently playing
- Customizable login screens
- Better queue interaction. There should be a way to drop down current queue and view without changing route
- MFA Logins - Github integration and cloud logins (OAuth)
- Implement Browser edition sign in retention (This will require some kind of OAuth provider. Part of OAuth and MFA)
- Linux App
- Flatpak
- Snap
- Mobile Apps
- Sign in retention for mobile editions
- Android App
- IOS App
- Packaging and automation
- Add verification before deleting user
- Rating System
- Sharing System
Main Homepage with podcasts displayed
Loads of themes!
Full Podcast Management
Browse through episodes
Markdown and HTML display compatible
