Skip to content

Commit

Permalink
Merge pull request #381 from blackcandy-org/pre-3.0
Browse files Browse the repository at this point in the history 
Release the v3.0
  • Loading branch information
@aidewoode
aidewoode authored May 31, 2024
2 parents fc2d680 + d18b1d5 commit 584b18a
Show file tree
Hide file tree
Showing 5 changed files with 285 additions and 38 deletions.
98 changes: 61 additions & 37 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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 <https://demo.blackcandy.org> and use demo user (email: admin@admin.com, password: foobar) to login. And feel free to try it.
Please visit <https://demo.blackcandy.org> 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 <your_blackcandy_container>
docker rm <your_blackcandy_container>
docker run <OPTIONS> 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:

[<img src="https://raw.githubusercontent.com/blackcandy-org/ios/master/images/appstore_badge.png" alt="Get it on App Store" height="50">](https://apps.apple.com/app/blackcandy/id6444304071)
[<img src="https://raw.githubusercontent.com/blackcandy-org/android/master/images/fdroid_badge.png" alt="Get it on F-Droid" height="50">](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

Expand All @@ -49,23 +74,23 @@ 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

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
Expand All @@ -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'
Expand All @@ -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
Expand All @@ -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

Expand All @@ -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
Expand Down Expand Up @@ -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 <http://localhost:3000> 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 <http://localhost:3000> use initial admin user to log in (email: admin@admin.com, password: foobar).

## Test
### Running tests

```shell
# Running all test
Expand All @@ -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

Expand Down
29 changes: 29 additions & 0 deletions docs/edge_upgrade.md
View file
Original file line number Diff line number Diff line change
@@ -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.

Binary file added docs/images/screenshot_main.png
View file
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading

0 comments on commit 584b18a

Please sign in to comment.