tom.sherman.is
A fork of https://github.com/teal-fm/piper
mmatt.net
1# piper
2
3#### what is piper?
4
5piper is a teal-fm tool that will be used to scrape user data from variety of
6music providers.
7
8#### why doesn't it work?
9
10well its just a work in progress... we build in the open!
11
12## setup
13
14It is recommend to have port forward url while working with piper. Development or running from docker because of external callbacks.
15
16You have a couple of options
17
181. Setup the traditional port forward on your router
192. Use a tool like [ngrok](https://ngrok.com/) with the command `ngrok http 8080` or [Cloudflare tunnels](https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/get-started/create-remote-tunnel/) (follow the 2a. portion of the guide when you get to that point)
20
21Either way make note of what the publicly accessible domain name is for setting up env variables. It will be something like `https://piper.teal.fm` that you can access publicly
22
23#### env variables
24
25Copy [.env.template](.env.template) and name it [.env](.env)
26
27This is a break down of what each env variable is and what it may look like
28
29**_breaking piper/v0.0.2 changes env_**
30
31You now have to bring your own private key to run piper. Can do this via goat `goat key generate -t P-256`. You want the one that is labeled under "Secret Key (Multibase Syntax): save this securely (eg, add to password manager)"
32
33- `ATPROTO_CLIENT_SECRET_KEY` - Private key for oauth confidential client. This can be generated via goat `goat key generate -t P-256`
34- `ATPROTO_CLIENT_SECRET_KEY_ID` - Key ID for oauth confidential client. This needs to be persistent and unique, can use a timestamp. Here's one for you: `1758199756`
35
36- `SERVER_PORT` - The port piper is hosted on
37- `SERVER_HOST` - The server host. `localhost` is fine here, or `0.0.0.0` for docker
38- `SERVER_ROOT_URL` - This needs to be the pubically accessible url created in [Setup](#setup). Like `https://piper.teal.fm`
39- `SPOTIFY_CLIENT_ID` - Client Id from setup in [Spotify developer dashboard](https://developer.spotify.com/documentation/web-api/tutorials/getting-started)
40- `SPOTIFY_CLIENT_SECRET` - Client Secret from setup in [Spotify developer dashboard](https://developer.spotify.com/documentation/web-api/tutorials/getting-started)
41- `SPOTIFY_AUTH_URL` - most likely `https://accounts.spotify.com/authorize`
42- `SPOTIFY_TOKEN_URL` - most likely `https://accounts.spotify.com/api/token`
43- `SPOTIFY_SCOPES` - most likely `user-read-currently-playing user-read-email`
44- `CALLBACK_SPOTIFY` - The first part is your publicly accessible domain. So will something like this `https://piper.teal.fm/callback/spotify`
45
46- `ATPROTO_CLIENT_ID` - The first part is your publicly accessible domain. So will something like this `https://piper.teal.fm/oauth-client-metadata.json`
47- `ATPROTO_METADATA_URL` - The first part is your publicly accessible domain. So will something like this `https://piper.teal.fm/oauth-client-metadata.json`
48- `ATPROTO_CALLBACK_URL` - The first part is your publicly accessible domain. So will something like this `https://piper.teal.fm/callback/atproto`
49
50- `LASTFM_API_KEY` - Your lastfm api key. Can find out how to setup [here](https://www.last.fm/api)
51
52- `TRACKER_INTERVAL` - How long between checks to see if the registered users are listening to new music
53- `DB_PATH`= Path for the sqlite db. If you are using the docker compose probably want `/db/piper.db` to persist data
54
55##### apple music
56
57requires an apple developer account
58
59- `APPLE_MUSIC_TEAM_ID` - Your Apple Developer Account's Team ID, found at `Membership Details` [here](https://developer.apple.com/account)
60- `APPLE_MUSIC_KEY_ID` - Your Key ID from the key you made in [Certificates, Identifiers & Profiles](https://developer.apple.com/account/resources/authkeys/list). You'll need to make a Media ID [here](https://developer.apple.com/account/resources/identifiers/list), then link a new key for MediaKit [there](https://developer.apple.com/account/resources/authkeys/list) to your new identifier. Download the private key and save the Key ID here.
61- `APPLE_MUSIC_PRIVATE_KEY_PATH` - The path to said private key as mentioned above.
62
63## development
64
65make sure you have your env setup following [the env var setup](#env-variables)
66
67assuming you have go installed and set up properly:
68
69run some make scripts:
70
71```
72
73make dev-setup
74```
75
76install air:
77
78```
79go install github.com/air-verse/air@latest
80```
81
82run air:
83
84```
85air
86```
87
88air should automatically build and run piper, and watch for changes on relevant files.
89
90## tailwindcss
91
92To use tailwindcss you will have to install the tailwindcss cli. This will take the [./pages/static/base.css](./pages/static/base.css) and transform it into a [./pages/static/main.css](./pages/static/main.css)
93which is imported on the [./pages/templates/layouts/base.gohtml](./pages/templates/layouts/base.gohtml). When running the dev server tailwindcss will watch for changes and recompile the main.css file.
94
951. Install tailwindcss cli `npm install tailwindcss @tailwindcss/cli`
962. run `npx @tailwindcss/cli -i ./pages/static/base.css -o ./pages/static/main.css --watch`
97
98#### Lexicon changes
99
1001. Copy the new or changed json schema files to the [lexicon folders](./lexicons)
1012. run `make go-lexicons`
102
103Go types should be updated and should have the changes to the schemas
104
105#### docker
106
107We also provide a docker compose file to use to run piper locally. There are a few edits to the [.env](.env) to make it run smoother in a container
108`SERVER_HOST`- `0.0.0.0`
109`DB_PATH` = `/db/piper.db` to persist your piper db through container restarts
110
111Make sure you have docker and docker compose installed, then you can run piper with `docker compose up`