diff --git a/README.md b/README.md index 160515c1..158d0aac 100644 --- a/README.md +++ b/README.md @@ -4,43 +4,68 @@ # Black Candy [![CI](https://github.com/blackcandy-org/black_candy/actions/workflows/ci.yml/badge.svg)](https://github.com/blackcandy-org/black_candy/actions/workflows/ci.yml) -[![Coverage Status](https://coveralls.io/repos/github/blackcandy-org/black_candy/badge.svg?branch=master)](https://coveralls.io/github/blackcandy-org/black_candy?branch=master) +[![Coverage Status](https://coveralls.io/repos/github/blackcandy-org/blackcandy/badge.svg?branch=master)](https://coveralls.io/github/blackcandy-org/black_candy?branch=master) [![Ruby Style Guide](https://img.shields.io/badge/code_style-standard-brightgreen.svg)](https://github.com/testdouble/standard) ![Docker Pulls](https://img.shields.io/docker/pulls/blackcandy/blackcandy) -Black Candy is a self hosted music streaming server built with [Rails](https://rubyonrails.org) and [Hotwire](https://hotwired.dev). The goal of the project is to create a real personal music center. +![Screenshot](https://raw.githubusercontent.com/blackcandy-org/blackcandy/master/docs/images/screenshot_main.png) -## Screenshot -![screenshot theme dark](https://raw.githubusercontent.com/blackcandy-org/black_candy/master/screenshots/screenshot_theme_dark.png) - -![screenshot theme light](https://raw.githubusercontent.com/blackcandy-org/black_candy/master/screenshots/screenshot_theme_light.png) +Black Candy is a self-hosted music streaming server, your personal music center. ## Try The Demo -Please visit and use demo user (email: admin@admin.com, password: foobar) to login. And feel free to try it. +Please visit and use demo user (email: admin@admin.com, password: foobar) to log in. And feel free to try it. -> **Notice:** This demo user does not have administrator privileges. So you cannot experience all the features in Black Candy. And all music in the demo are from [Free Music Archive](https://freemusicarchive.org/). You can check their [licenses](https://github.com/blackcandy-org/blackcandy/blob/master/docs/demo_music_licenses.md). +> [!NOTE] +> This demo user does not have administrator privileges. So you cannot experience all the features in Black Candy. And all music in the demo are from [Free Music Archive](https://freemusicarchive.org/). You can check their [licenses](https://github.com/blackcandy-org/blackcandy/blob/master/docs/demo_music_licenses.md). ## Installation -> ⚠️ **Notice:** This installation instruction is for edge version, which means the docker image is build base on master branch. Because upcoming major version of Black Candy is going to have a lot of infrastructure changes. So the installation process will have a lot of difference. -> If you are looking for installation instruction for latest stable version, please visit [here](https://github.com/blackcandy-org/black_candy/blob/7f9202bd8a9777d439e95eabd0654e9b4a336be9/README.md). -Black Candy use docker image to install easily. You can simply run Black Candy like this. +Black Candy uses docker image to install easily. You can run Black Candy like this. ```shell -docker run -p 3000:3000 ghcr.io/blackcandy-org/blackcandy:edge +docker run -p 3000:3000 ghcr.io/blackcandy-org/blackcandy:latest + +# Or pull from Docker Hub. +docker run -p 3000:3000 blackcandy/blackcandy:latest ``` -That's all. Now, you can access either http://localhost:3000 or http://host-ip:3000 in a browser, and use initial admin user to login (email: admin@admin.com, password: foobar). +That's all. Now, you can access either http://localhost:3000 or http://host-ip:3000 in a browser, and use initial admin user to log in (email: admin@admin.com, password: foobar). -## Mobile App -Black Candy now has an iOS and Android apps in beta. +## Upgrade -For iOS app, you can visit [here](https://testflight.apple.com/join/TwMUVmDl) and join TestFlight to try it. +> [!IMPORTANT] +> If you upgrade to a major version, you need to read the upgrade guide carefully before upgrade. Because there are some breaking changes in a major version. +> +> - See [V3 Upgrade](https://github.com/blackcandy-org/blackcandy/blob/master/docs/v3_upgrade.md) for upgrade from V2 release. +> - See [Edge Upgrade](https://github.com/blackcandy-org/blackcandy/blob/master/docs/edge_upgrade.md) for upgrade from edge release to latest stable release. -For Android app, you can download the APK from the assets of the latest beta [release](https://github.com/blackcandy-org/android/releases) to give it a try. +Upgrade Black Candy is pull new image from remote. Then remove an old container and create a new one. -Because the mobile apps still in beta, you need use the edge version of Black Candy. +```shell +docker pull ghcr.io/blackcandy-org/blackcandy:latest +docker stop +docker rm +docker run ghcr.io/blackcandy-org/blackcandy:latest +``` + +With docker compose, you can upgrade Black Candy like this: + +```shell +docker pull ghcr.io/blackcandy-org/blackcandy:latest +docker-compose down +docker-compose up +``` + +## Mobile Apps + +Black Candy mobile apps are available in the following app stores: + +[Get it on App Store](https://apps.apple.com/app/blackcandy/id6444304071) +[Get it on F-Droid](https://f-droid.org/packages/org.blackcandy.android/) + + +For Android app, you can also download APK from [GitHub Release](https://github.com/blackcandy-org/android/releases/latest) ## Configuration @@ -49,7 +74,7 @@ Because the mobile apps still in beta, you need use the edge version of Black Ca Black Candy exports the 3000 port. If you want to be able to access it from the host, you can use the `-p` option to map the port. ```shell -docker run -p 3000:3000 ghcr.io/blackcandy-org/blackcandy:edge +docker run -p 3000:3000 ghcr.io/blackcandy-org/blackcandy:latest ``` ### Media Files Mounts @@ -57,15 +82,15 @@ docker run -p 3000:3000 ghcr.io/blackcandy-org/blackcandy:edge You can mount media files from host to container and use `MEDIA_PATH` environment variable to set the media path for black candy. ```shell -docker run -v /media_data:/media_data -e MEDIA_PATH=/media_data ghcr.io/blackcandy-org/blackcandy:edge +docker run -v /media_data:/media_data -e MEDIA_PATH=/media_data ghcr.io/blackcandy-org/blackcandy:latest ``` ### Use PostgreSQL As Database -Black Candy use SQLite as database by default. Because SQLite can simplify the process of installation, and it's an ideal choice for self hosted small server. If you think SQLite is not enough or you are using some cloud service like heroku to host Black Candy, you can also use PostgreSQL as database. +Black Candy use SQLite as database by default. Because SQLite can simplify the process of installation, and it's an ideal choice for self-hosted small server. If you think SQLite is not enough, or you are using some cloud service like heroku to host Black Candy, you can also use PostgreSQL as database. ```shell -docker run -e DB_ADAPTER=postgresql -e DB_URL=postgresql://yourdatabaseurl ghcr.io/blackcandy-org/blackcandy:edge +docker run -e DB_ADAPTER=postgresql -e DB_URL=postgresql://yourdatabaseurl ghcr.io/blackcandy-org/blackcandy:latest ``` ### How to Persist Data @@ -75,14 +100,14 @@ All the data that need to persist in Black Candy are stored in `/app/storage`, S ```shell mkdir storage_data -docker run -v ./storage_data:/app/storage ghcr.io/blackcandy-org/blackcandy:edge +docker run -v ./storage_data:/app/storage ghcr.io/blackcandy-org/blackcandy:latest ``` ### Nginx To Send File -Black Candy supports use Nginx to delivery audio file to client. It's a more effective way than handle by Black Candy backend. And Black Candy docker image are also ready for [nginx-proxy](https://github.com/nginx-proxy/nginx-proxy), which means you can setup a Nginx proxy for Black Candy easily. I recommend you use [nginx-proxy](https://github.com/nginx-proxy/nginx-proxy) with Black Candy. +Black Candy supports use Nginx to delivery audio file to the client. It's a more effective way than handled by Black Candy backend. And Black Candy docker image is also ready for [nginx-proxy](https://github.com/nginx-proxy/nginx-proxy), which means you can set up a Nginx proxy for Black Candy easily. -You can use docker-compose to setup those services. The docker-compose.yml file looks like this: +You can use docker-compose to set up those services. The docker-compose.yml file looks like this: ```yaml version: '3' @@ -95,10 +120,10 @@ services: volumes: - ./blackcandy.local:/etc/nginx/vhost.d/blackcandy.local:ro - /var/run/docker.sock:/tmp/docker.sock:ro - - /media_data:/media_data # Keep the path of media files in container same as blackcandy container. + - /media_data:/media_data # Keep the path of media files in container the same as blackcandy container. app: - image: ghcr.io/blackcandy-org/blackcandy:edge + image: ghcr.io/blackcandy-org/blackcandy:latest volumes: - ./storage_data:/app/storage - /media_data:/media_data @@ -110,14 +135,14 @@ services: ```shell # Get the default sendfile config for blackcandy. This file need to mount to nginx proxy container to add custom configuration for nginx. -curl https://raw.githubusercontent.com/blackcandy-org/black_candy/master/config/nginx/sendfile.conf > blackcandy.local +curl https://raw.githubusercontent.com/blackcandy-org/blackcandy/v3.0.0/config/nginx/sendfile.conf > blackcandy.local docker-compose up ``` ### Logging -Black Candy logs to `STDOUT` by default. So if you want to control the log, Docker already supports a lot of options to handle the log in the container. see: https://docs.docker.com/config/containers/logging/configure/. +Black Candy logs to `STDOUT` by default. So if you want to control the log, Docker already supports a lot of options to handle the log in the container. See: https://docs.docker.com/config/containers/logging/configure/. ## Environment Variables @@ -131,12 +156,12 @@ Black Candy logs to `STDOUT` by default. So if you want to control the log, Dock | FORCE_SSL | false | Force all access to the app over SSL. | | DEMO_MODE | false | Whether to enable demo mode, when demo mode is on, all users cannot access administrator privileges, even user is admin. And also users cannot change their profile. | -## Upgrade +## Edge Version -Pull new image from remote +The edge version of Black Candy base on master branch, which means it's not stable, you may encounter data loss or other issues. However, I don't recommend normal user using an edge version. But if you are a developer who wants to test or contribute to Black Candy, you can use the edge version. ```shell -$ docker pull ghcr.io/blackcandy-org/blackcandy:edge +docker pull ghcr.io/blackcandy-org/blackcandy:edge ``` ## Development @@ -171,11 +196,10 @@ rails db:seed ### Start all services -After you’ve set up everything, now you can running `./bin/dev` to start all service you need to develop. -Then visit use initial admin user to login (email: admin@admin.com, password: foobar). - +After you’ve set up everything, now you can run `./bin/dev` to start all services you need to develop. +Then visit use initial admin user to log in (email: admin@admin.com, password: foobar). -## Test +### Running tests ```shell # Running all test @@ -187,7 +211,7 @@ $ rails lint:all ## Integrations -Black Candy support get artist and album image from Discogs API. You can create a API token from Discogs and set Discogs token on Setting page to enable it. +Black Candy support get artist and album image from Discogs API. You can create an API token from Discogs and set Discogs token on Setting page to enable it. ## Sponsorship diff --git a/docs/edge_upgrade.md b/docs/edge_upgrade.md new file mode 100644 index 00000000..1b820a7d --- /dev/null +++ b/docs/edge_upgrade.md @@ -0,0 +1,29 @@ +# Upgrade from edge release to latest stable release + +> [!WARNING] +> You can be only possible to upgrade from edge release to the nearest stable release. For example, if you are using edge release of v3, you can only upgrade to nearest stable v3 release. You cannot upgrade to v4 stable release directly. You can check out the date of your edge release and the stable release to determine which stable release you can upgrade to. + +## Upgrade from edge to v3 + +If you are using the latest edge release of v3, you should upgrade to the latest stable release of v3 directly by pulling the latest v3 image from remote. + +```shell +docker pull ghcr.io/blackcandy-org/blackcandy:3.0.0 +``` + +However, if you are using the previous edge release of v3, you may encounter errors during your upgrade that prevent you from upgrading directly to the latest stable v3 release. That's because the migration files have changed to support upgrading from v2 to v3, which will cause some particular earlier edge release of v3 cannot upgrade directly to stable v3. Those errors cannot be solved unless you have some experience working on Rails migration. So I highly recommend you to remove all data in `storage_data` directory and reinstall the latest stable release of v3 by following the [README](https://github.com/blackcandy-org/blackcandy/blob/v3.0.0/README.md). + +### Clean up the unused data: + +If you have upgraded to the latest stable release of v3 successfully, you can remove some unused data you may have in edge release. + +Remove unnecessary data in mounted volume if you have: + +```shell +rm -r public/uploads #All images assets already migrated to Active Storage +rm -r storage_data/production_cache.sqlite3* # Previous used by litecache, already migrated to solid_cache +rm -r storage_data/production_queue.sqlite3* # Previous used by litequeue, already migrated to solid_queue +``` + +Remove sidekiq and redis config if they are being used. + diff --git a/docs/images/screenshot_main.png b/docs/images/screenshot_main.png new file mode 100644 index 00000000..e14ad105 Binary files /dev/null and b/docs/images/screenshot_main.png differ diff --git a/docs/v3_upgrade.md b/docs/v3_upgrade.md new file mode 100644 index 00000000..35b125cf --- /dev/null +++ b/docs/v3_upgrade.md @@ -0,0 +1,194 @@ +# Upgrade from Black Candy v2 to v3 + +There are a lot of breaking infrastructure changes in Black Candy v3, including using SQLite as the default database, removing dependencies on Redis and Sidekiq. We have also removed the dependency on Nginx and Docker Compose to run Black Candy server. + +> [!WARNING] +> Because Black Candy v3 needs to support both SQLite and PostgreSQL, and some data in v2 is not compatible with SQLite if you upgrade from v2, there is still some small data you will lose after upgrading. Includes all settings. + +So depending on whether you want to migrate to SQLite as database in v3, you can choose different upgrade methods. You can [keep using PostgreSQL as database](#keep-using-postgresql-as-database) or [migrate to SQLite as database](#migrate-to-sqlite-as-database). + +## Keep using PostgreSQL as database + +### Pull the v3 image from remote: + +```shell +docker pull ghcr.io/blackcandy-org/blackcandy:3.0.0 +``` + +### Stop and remove the old containers: + +```shell +docker-compose down +``` + +### Change the docker-compose file to use the new image: + +Since v3 doesn't depend on redis, sidekiq and nginx, you can remove redis, worker and web service from docker-compose file. Since v3 can start the media listener in the settings page, you also need to remove the listener service in the docker-compose file. Remember you should keep the `production_uploads_data` in volumes configuration in the app service, because v3 still need this data to migrate to store in new location. + +The example docker-compose file is like this: + +```yaml +version: '3' +services: + app: + container_name: 'blackcandy_app' + image: ghcr.io/blackcandy-org/blackcandy:v3.0.0 + ports: + - "80:3000" + volumes: + - ./storage_data:/app/storage + - /media_data:/media_data + - production_uploads_data:/app/public/uploads + environment: + DB_ADAPTER: postgresql + DB_URL: postgresql://postgres@postgres/black_candy_production + MEDIA_PATH: /media_data + depends_on: + - postgres + postgres: + container_name: 'blackcandy_postgres' + image: postgres:11.1-alpine + volumes: + - production_db_data:/var/lib/postgresql/data +volumes: + production_db_data: + production_uploads_data: +``` + +### Start the new container: + +```shell +docker-compose up -d +``` + +After the new container started, Black Candy will automatically migrate the data from v2 to v3. + +### Clean up the unused data: + +After the migration, you can remove the old data in v2: + +First stop the services: + +```shell +docker-compose down +``` + +Then remove the unused data: + +```shell +rm -r media_cache_data +rm -r log +docker volume rm +docker volume rm +``` + +Now you can remove `production_uploads_data` volume in the docker-compose file. The final docker-compose file looks like this: + +```yaml + +version: '3' +services: + app: + container_name: 'blackcandy_app' + image: ghcr.io/blackcandy-org/blackcandy:v3.0.0 + ports: + - "80:3000" + volumes: + - ./storage_data:/app/storage + - /media_data:/media_data + environment: + DB_ADAPTER: postgresql + DB_URL: postgresql://postgres@postgres/black_candy_production + MEDIA_PATH: /media_data + depends_on: + - postgres + postgres: + container_name: 'blackcandy_postgres' + image: postgres:11.1-alpine + volumes: + - production_db_data:/var/lib/postgresql/data +volumes: + production_db_data: +``` + +### Restart the services: + +```shell +docker-compose up -d +``` + +## Migrate to SQLite as database + +As PostgreSQL data is not compatible with SQLite, you need to export the data from PostgreSQL and cover to SQLite database file. + +There are several ways to copy the PostgreSQL data to SQLite. In the following example, I will use [sequel](https://github.com/jeremyevans/sequel) to copy PostgreSQL data to SQLite database file. + +### Stop and remove the old containers: + +```shell +docker-compose down +``` + +### Cover the PostgreSQL data to SQLite database file: + +Make sure you have installed [Ruby](https://www.ruby-lang.org/en/). + +```shell +gem install sequel +``` + +Start a temporary PostgreSQL container for export data: + +```shell +docker run -p 5432:5432 -v :/var/lib/postgresql/data postgres:11.1-alpine +``` + +Use sequel to export the data to SQLite database file: +```shell +sequel -C postgres://postgres@localhost:5432/black_candy_production sqlite://production.sqlite3 +``` + +Create new storage directory for v3, and copy the SQLite database file to it: + +```shell +mkdir storage_data +cp production.sqlite3 storage_data/production.sqlite3 +``` + +### Start the new container to migrate the data: + +```shell +docker run -p 3000:3000 -v ./storage_data:/app/storage -v :/app/public/uploads ghcr.io/blackcandy-org/blackcandy:v3.0.0 +``` + +After the new container started, Black Candy will automatically migrate the data from v2 to v3. + +### Clean up the unused data: + +After the migration, you can remove the old data in v2: + +First stop the container: + +```shell +docker stop +docker rm +``` + +Then remove the unused data: + +```shell +rm production.sqlite3 +rm -r media_cache_data +rm -r log +docker volume rm +docker volume rm +docker volume rm +``` + +### Restart the container: + +```shell +docker run -p 3000:3000 -v /media_data:/media_data -v ./storage_data:/app/storage -e MEDIA_PATH=/media_data ghcr.io/blackcandy-org/blackcandy:v3.0.0 +``` + +Now your Black Candy v2 has been upgraded to v3, you can go the [README](https://github.com/blackcandy-org/blackcandy/blob/v3.0.0/README.md) to check the configuration options. \ No newline at end of file diff --git a/lib/black_candy/version.rb b/lib/black_candy/version.rb index be18502a..d49156a2 100644 --- a/lib/black_candy/version.rb +++ b/lib/black_candy/version.rb @@ -5,7 +5,7 @@ module Version MAJOR = 3 MINOR = 0 PATCH = 0 - PRE = "beta1" + PRE = "" def self.to_s return "Edge" if Rails.root.join(".is-edge-release.txt").exist?