From c83c0ddc8c06e439672874a3db2e5d5bf9d242da Mon Sep 17 00:00:00 2001 From: Alessandro Rabitti Date: Fri, 28 Jun 2024 10:46:08 +0200 Subject: [PATCH] Improve readme section about local development --- .env | 15 ++++++++++----- CONTRIBUTING.md | 1 + README.md | 17 ++++++++++++++--- 3 files changed, 25 insertions(+), 8 deletions(-) diff --git a/.env b/.env index aba16b74..b64fd2e6 100644 --- a/.env +++ b/.env @@ -1,12 +1,17 @@ +# Required REACT_APP_HOST=localhost:3000 -REACT_APP_ANALYTICS_MEASUREMENT_ID= REACT_APP_LASTFM_API_KEY= -REACT_APP_SENTRY_DSN= -REACT_APP_LINK_TO_TRANSLATIONS="https://github.com/elamperti/OpenWebScrobbler/blob/main/CONTRIBUTING.md#translations" -REACT_APP_GROWTHBOOK_API_KEY= LASTFM_API_KEY= LASTFM_SECRET= -SQLITE_DB_PATH= +SQLITE_DB_PATH="/var/www/html/database/development.db" + +# Optional +DISCOGS_API_KEY= +DISCOGS_SECRET= +REACT_APP_ANALYTICS_MEASUREMENT_ID= +REACT_APP_GROWTHBOOK_API_KEY= +REACT_APP_LINK_TO_TRANSLATIONS="https://github.com/elamperti/OpenWebScrobbler/blob/main/CONTRIBUTING.md#translations" +REACT_APP_SENTRY_DSN= # Only for development: uncomment and set these numbers to your user/group IDs # APACHE_RUN_USER=#1000 diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 6c0f8f68..7ed5daaa 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -26,6 +26,7 @@ Once you have a possible fix, open a pull request so it can be reviewed and merg It's highly encouraged to [open an issue](https://github.com/elamperti/OpenWebScrobbler/issues/new/choose) (or comment on an existing one) before you start coding, especially if you are planning to implement new features or wish to make big changes in the codebase. With this previous discussion, everyone saves time and there's a higher chance to get your work merged. ### Making changes to the database structure + All changes to the database schema must be added as migrations (use [migration #1](./assets/db/migrations/0001_keepOriginalTimestamp.sql) as a guiding template) and remain backwards compatible. All new migrations are applied automatically in the development containers (just keep in mind that each migration runs only once, so you may need to manually revert any failed attempt). --- diff --git a/README.md b/README.md index 48d1440b..557421f7 100644 --- a/README.md +++ b/README.md @@ -5,6 +5,7 @@ ![Screenshot](https://user-images.githubusercontent.com/910672/45590262-55333c00-b90b-11e8-9f95-c360d35ced5f.jpg) ## What is this? + An open source scrobbling client for the web. Just login and scrobble the track(s) you want! This tool lets you scrobble songs you heard on the radio, vinyls or at some place where you need to manually scrobble. You may use it directly from here: [https://openscrobbler.com/](https://openscrobbler.com/) @@ -12,21 +13,28 @@ You may use it directly from here: [https://openscrobbler.com/](https://openscro What is _scrobbling_, you ask? It's tracking the music you listen to, using [last.fm](https://last.fm/). ## Help us make it better! + This tool is open source and free. You can support its development by [becoming a Patron](https://www.patreon.com/OpenScrobbler) (you'll have a distinct identifier in the application and get a sneak peek into what's coming next! :sparkles: ) ### Contributing + Contributions and suggestions are welcome. Please read the [contribution guidelines](https://github.com/elamperti/OpenWebScrobbler/blob/main/CONTRIBUTING.md) for more information. Issues labeled with ["help wanted"](https://github.com/elamperti/OpenWebScrobbler/issues?q=is%3Aissue+is%3Aopen+label%3A%22help+wanted%22) are great candidates if you don't know where to begin! ### Translations + To join the translators team, follow the link at the bottom of the language selector in the application ("Want to add your language?"). ## Development setup -You'll need [a Last.fm API account](https://www.last.fm/api/account/create)! (and probably a Discogs API key as well) - * Run `yarn` to download the required libraries. - * Copy `.env` to `.env.development.local` and fill in the required constants. +* Clone the repository +* Copy `.env` to `.env.development.local`, then set at least the required variables + * You'll need a [Last.fm API account](https://www.last.fm/api/account/create) to be able to interact with Open Scrobbler (it's used for authentication and queries). Once you have your keys, fill in `REACT_APP_LASTFM_API_KEY` and `LASTFM_API_KEY` (same value in both) and `LASTFM_SECRET` + * Optional: to interact with Discogs, create a [Discogs application](https://www.discogs.com/settings/developers) to get API keys and fill in `DISCOGS_API_KEY` and `DISCOGS_SECRET` +* Run `yarn` to download the required libraries. +* Run `yarn start` to initialize the docker container and run the application. ## Testing + You will need to copy `cypress.env.json` to `cypress.development.json` and update the file to execute the tests. Don't use last.fm account credentials from a real account! Tests can be run with `yarn test`, Cypress console can be accessed with `yarn cypress`. @@ -34,10 +42,13 @@ Tests can be run with `yarn test`, Cypress console can be accessed with `yarn cy To check test coverage run `yarn test:coverage` ## Running the application + Just start it with `yarn start` (it will launch both the API server and the React application). ## Building + The `build` script should be enough! :) ## Thank you! + One of the best things about open source is the great community around it. The Open Scrobbler has several contributors and each one of them has made this tool better for everyone. Thanks to [all of them](https://github.com/elamperti/OpenWebScrobbler/graphs/contributors)!