](https://apps.apple.com/app/blackcandy/id6444304071)
[
](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
### Port Mapping
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: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: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.
```shell
docker run -e DB_ADAPTER=postgresql -e DB_URL=postgresql://yourdatabaseurl ghcr.io/blackcandy-org/blackcandy:latest
```
### How to Persist Data
All the data that need to persist in Black Candy are stored in `/app/storage`, So you can mount this directory to host to persist data.
```shell
mkdir storage_data
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 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 set up those services. The docker-compose.yml file looks like this:
```yaml
version: '3'
services:
nginx-proxy:
image: nginxproxy/nginx-proxy
ports:
- "80:80"
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 the same as blackcandy container.
app:
image: ghcr.io/blackcandy-org/blackcandy:latest
volumes:
- ./storage_data:/app/storage
- /media_data:/media_data
environment:
VIRTUAL_HOST: blackcandy.local
MEDIA_PATH: /media_data
NGINX_SENDFILE: "true" # Don't forget to set `NGINX_SENDFILE` environment variable to true to enable nginx sendfile.
```
```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/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/.
## Environment Variables
| Name | Default | Description |
| --- | --- | --- |
| DB_URL | | The URL of PostgreSQL database. You must set this environment variable if you use PostgreSQL as database. |
| MEDIA_PATH | | You can use this environment variable to set media path for Black Candy, otherwise you can set media path in settings page. |
| DB_ADAPTER | "sqlite" | There are two adapters are supported, "sqlite" and "postgresql".|
| NGINX_SENDFILE | false | Whether enable Nginx sendfile. |
| SECRET_KEY_BASE | | When the SECRET_KEY_BASE environment variable is not set, Black candy will generate SECRET_KEY_BASE environment variable every time when service start up. This will cause old sessions invalid, You can set your own SECRET_KEY_BASE environment variable on docker service to avoid it. |
| 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
- Ruby 3.3
- Node.js 20
- libvips
- FFmpeg
Make sure you have installed all those dependencies.
### Install gem dependencies
```shell
bundle install
```
### Install JavaScript dependencies
```shell
npm install
```
### Database Configuration
```shell
rails db:prepare
rails db:seed
```
### Start all services
After you’ve set up everything, now you can run `./bin/dev` to start all services you need to develop.
Then visit 
