Spotify Smart Playlist Builder

🚀 How to Install

Fork the GitHub repository
Go to this GitHub repo and click "Fork" to copy it to your GitHub account.
Create a free Render.com account
Visit render.com and create a free account. You'll use this to host your backend.
- Give your workspace a name
- Click "New Web Service"
- Connect your GitHub repo
- (Optional) Create a project in Render
- Set the start command to: python -m app.app
- Select the instance type (Free tier is sufficient)
- Click "Deploy" – this will fail (don’t worry)
  Click the dashboard button (top left)
  Select your service name
- We’ll return to setting environment variables later
Set up a Spotify Developer App
Visit the Spotify Developer Dashboard, create a new app, and record:
- Go to Dashboard (top right)
- Accept the Terms of Service
- Enter a name
- Enter a description
- Paste in your Render URI
Under "Redirect URIs", add:
https://YOUR-RENDER-APP.onrender.com/callback
- Select "Web API"
- Accept the terms
- Click "Save"
THIS WILL GIVE YOU:
- Client ID
- Client Secret
Create a PostgreSQL Database
In Render, click "New" → "PostgreSQL". Note: databases are not free and will incur a small monthly cost.
- Give it a name
- Specify DB name and username
- Start with the free plan; you may need to upgrade later
- Create Database
  The next page will display the Records:
  - DB Host – copy this from the External Database URL (e.g. dpg-xxx.oregon-postgres.render.com)
  - DB Name
  - DB User
  - DB Password
  - DB Port (typically 5432)
Add Environment Variables to Render
Go back to the dashboard and select the webservice
In your web service's "Environment" tab, add:
- SPOTIFY_CLIENT_ID
- SPOTIFY_CLIENT_SECRET
- SPOTIFY_REDIRECT_URI
- DB_HOST
- DB_NAME
- DB_USER
- DB_PASSWORD
- DB_PORT
- PYTHON_VERSION: 3.11.11
Add Environment Variables to GitHub (Settings → Secrets and variables → Actions)
ADD repository secret
In your GitHub repo under Settings → Secrets and variables → Actions, add:
- SPOTIFY_CLIENT_ID
- SPOTIFY_CLIENT_SECRET
- SPOTIFY_REDIRECT_URI
- DB_HOST – this must be the external host (from the External Database URL)
- To extract just the DB_HOST: copy the External Database URL and remove everything before and including '@'. For example, from:
  postgresql://user:[email protected]/dbname → keep only:
  dpg-xxx.oregon-postgres.render.com
- DB_NAME
- DB_USER
- DB_PASSWORD
- DB_PORT
Deploy the Web App
After setting environment variables:
- Select Manual deploy
- Select 'Clear cache and deploy'
Finish Setup via Web UI
Visit /create-admin on your app (e.g. https://yourapp.onrender.com/create-admin).
Create your username and password, then log in and authorize your Spotify account.
Retrieve Your Refresh Token
After authorizing Spotify, you’ll be redirected to /callback. Copy the SPOTIFY_REFRESH_TOKEN from the URL or response.
Add SPOTIFY_REFRESH_TOKEN
- Go to your Render app → Environment → Add SPOTIFY_REFRESH_TOKEN
- Trigger a manual deploy
- Add the same token to GitHub Secrets
Complete Setup
Once deployed, visit the homepage, log in, and click “Run Initial Sync”.
Enable GitHub Actions
When you fork the repository, GitHub disables Actions by default.
Go to the "Actions" tab of your GitHub repo and click "Enable workflows" to allow scheduled sync jobs to run. Then enable, 00 - Full Library Sync & 2 - Track Spotify Plays
Optional: Google Tag Manager
This project includes a Google Tag Manager (GTM) snippet with a GA4 instance owned by the original project author.
If you don’t wish to use this:
- Remove the GTM snippet entirely from the codebase, or
- Replace it with your own Google Tag Manager container ID
The GTM code is located in the <head> and just after the <body> tag of public-facing pages.
Optional: Buy Me a Coffee
If you like this project, please consider buying me a coffee (or beer!). Your support helps keep development going.