Skip to content

Commit

Permalink
Add upgrade guide for v3
Browse files Browse the repository at this point in the history
  • Loading branch information
@aidewoode
aidewoode committed May 23, 2024
1 parent a658f32 commit 7cd8669
Show file tree
Hide file tree
Showing 3 changed files with 239 additions and 26 deletions.
47 changes: 27 additions & 20 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -10,18 +10,18 @@

![Screenshot](https://raw.githubusercontent.com/blackcandy-org/blackcandy/pre-3.0/docs/images/screenshot_main.png)

Black Candy is a self hosted music streaming server, your personal music center.
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: [email protected], password: foobar) to login. And feel free to try it.
Please visit <https://demo.blackcandy.org> and use demo user (email: [email protected], password: foobar) to log in. And feel free to try it.

> [!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).
> 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

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:latest
Expand All @@ -30,17 +30,17 @@ docker run -p 3000:3000 ghcr.io/blackcandy-org/blackcandy:latest
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: [email protected], 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: [email protected], password: foobar).

## Upgrade

> [!IMPORTANT]
> If you upgrade to major version, you need to read the upgrade guide carefully before upgrade. Because there are some breaking changes in major version.
> 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]() for upgrade from V2 release.
> - See [Edge Upgrade]() for upgrade from edge release to latest stable release.
> - See [V3 Upgrade](https://github.com/blackcandy-org/blackcandy/blob/pre-3.0/docs/v3_upgrade.md) for upgrade from V2 release.
> - See [Edge Upgrade](https://github.com/blackcandy-org/blackcandy/blob/pre-3.0/docs/edge_upgrade.md) for upgrade from edge release to latest stable release.
Upgrade Black Candy is just pull new image from remote. then remove old container and create a new one.
Upgrade Black Candy is pull new image from remote. Then remove an old container and create a new one.

```shell
docker pull ghcr.io/blackcandy-org/blackcandy:latest
Expand All @@ -59,7 +59,7 @@ docker-compose up

## Mobile App

Black Candy mobile apps are available in following app stores:
Black Candy mobile apps are available in the following app stores:


For Android app, you can also download APK from [GitHub Release](https://github.com/blackcandy-org/android/releases/latest)
Expand All @@ -84,7 +84,7 @@ docker run -v /media_data:/media_data -e MEDIA_PATH=/media_data ghcr.io/blackcan

### 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:latest
Expand All @@ -102,9 +102,9 @@ docker run -v ./storage_data:/app/storage ghcr.io/blackcandy-org/blackcandy:late

### 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.
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 @@ -117,7 +117,7 @@ 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:latest
Expand All @@ -139,7 +139,7 @@ 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 @@ -153,6 +153,14 @@ 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. |

## Edge Version

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
```

## Development

### Requirements
Expand Down Expand Up @@ -185,11 +193,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: [email protected], 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: [email protected], password: foobar).

## Test
### Running tests

```shell
# Running all test
Expand All @@ -201,7 +208,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/pre-3.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.

189 changes: 183 additions & 6 deletions docs/v3_upgrade.md
View file
Original file line number Diff line number Diff line change
@@ -1,17 +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, remove the dependency on Redis and Sidekiq. Also remove the dependencies of Nginx and Docker Compose to running Black Candy server.
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.

Because Black Candy v3 support both SQLite and PostgreSQL as database, and Blakc Candy v2 only support PostgreSQL. So depending on whether you want to migrate to SQLite as database in v3, you can choose different upgrade methods.
> [!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.
## Keep using PostgreSQL as database
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).

> [!WARNING]
> Because Black Candy v3 need to support both SQLite and PostgreSQL, and some data in v2 is not compatible with SQLite, if you keep using PostgreSQL as database, there are still some small data you are going to lose after upgrade. Including: all settings.
## Keep using PostgreSQL as database

1. Pull the v3 image from remote:
### 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 <your_blackcandy_redis_data_volume>
docker volume rm <your_blackcandy_uploads_data_volume>
```

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 <your_blackcandy_db_data_volume>:/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 <your_blackcandy_uploads_data_volume>:/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 <your_blackcandy_container>
docker rm <your_blackcandy_container>
```

Then remove the unused data:

```shell
rm production.sqlite3
rm -r media_cache_data
rm -r log
docker volume rm <your_blackcandy_redis_data_volume>
docker volume rm <your_blackcandy_uploads_data_volume>
docker volume rm <your_blackcandy_db_data_volume>
```

### 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/pre-3.0/README.md) to check the configuration options.

0 comments on commit 7cd8669

Please sign in to comment.