listy/README.md

# Listy

A web application that syncs your liked songs into a monthly playlist built with Go.

## Features

- Spotify OIDC for authentication
- Automatically create a monthly playlist following the naming scheme `YYYY MM`
- Sync songs from your liked playlist to the current monthly playlist
- Reuse playlists following the same naming scheme
- Run the sync script as a one-time command (`listy sync`) or on a time (`listy sync -r 5m`)

## Deployment

Listy can be run as a self-hosted application as a Docker container or with Go installed.

### Create a Spotify application

Head to the [Spotify API dashboard](https://developer.spotify.com/dashboard) and create your application. Call it "Listy" and take note of the generated client ID and secret.

Add the following redirect URI to the application to enable OIDC auth:

http(s)://listy.example.com/auth/oidc/spotify/callback

### Listy configuration

Listy can be configured with environment variables or a config file, placed at the location of the binary or in one of the supported locations found in [`main.go`](./main.go).

The following configuration values are supported:

```yml
spotify:
  # Spotify OIDC client ID
  clientId: <SPOTIFY_CLIENT_ID>
  # Spotify OIDC client secret
  clientSecret: <SPOTIFY_CLIENT_SECRET>
mongodb:
  # MongoDB connection URI
  uri: <MONGODB_URI>
server:
  # session key used for cookie sessions, ideally a random string with at least 32 characters
  sessionKey: <SERVER_SESSION_KEY>
  # server scheme, either http or https
  scheme: <SERVER_SCHEME>
  # server host, such as localhost:5001 or listy.example.com
  host: <SERVER_HOST>
```

#### Support for environment variables

Listy supports environment variables corresponding to the names in the `<>` in the example file above.

### With Docker Compose

Listy can be deployed with Docker compose, and simply requires a MongoDB instance and the configuration file to work.

To deploy your Listy instance, copy the [`docker-compose.yml`](./docker-compose.yml) and optionally create a `.env` file for your sensitive values. The sample config is also provided at [`config.example.yml`](./config.example.yml).

Finally, run the following in the folder where your `docker-compose.yml` and `config.yml` are:

```sh
$ docker compose up -d
```

## License

Listy is licensed under the [MIT license](./LICENSE).

## Contributions

Contributions are welcome, all code must simply pass CI. Contribution guidelines still WIP.

## Roadmap

Some more features are planned, including:

- [ ] Optionally copying over songs from previous monthly lists
- [ ] Notifications
- [ ] Management UI