Security:

Please note that API on any media tier (free download/Streaming only) will assume that the function returning the current date (time(); to name it) will return an up-to-date date, coherent with the "modification date" that is added to each file when uploaded on the tier. Make sure the system date of the server hasn't been moved to the past (like, 1 jan 1970, but it is just an example) or to the future. This is a concern both for uploading files and to build API cache freshness.

Help

Primary place for information is the #crero chatroom on the https://libera.chat IRC (Internet Relayed Chat) network. Volunteers to make IRC presence or even willing to pass around information and help people are welcome there.

Additional documentation

Once you have read some parts or more parts of this README file, a good additional reading, documenting interesting points for CreRo deployment for beginners, is to find in the README documentation of crero-yp (which is the YellowPage Service for CreRo instance CMS, allowing Your label to register its CreRo site to advertise in one or more YellowPage Services), especially in the following section: https://github.com/shangril/crero-yp/blob/main/README.md#requirement-for-crero-instance-to-be-listed-in-a-yp-server

Upgrading

Please note that if you got a custom ./style.css, full upgrades with any files will overwrite it. Either, make a backup before, and restore it, or, upgrade excluding the style.css file

Multi-instance on the same server

If you plan to have several instances on the same server, you should set up a subdomain for each of them ; ie labelone.yourserver.tld ; labeltwo.yourserver.tld ; and so on. This is to prepare Syndication, then later, Federation, for which (black/white)listing of other servers will be made based on hostname, not full path. Then having different hostname will allow other instances to (black/white)list each of them at their convenience, and not all, at once, the instances you run on your server.

CreRo

Recommended (strongly) PHP version is PHP 8.1, but PHP 7.0 or above is mandatory and may work, but hasn't been tested for post-September 2022 releases, while PHP 8.1 was. Please refer to the "PHP 8.1 tested things" for details. Core features (a subset, but core) is TESTED and WORKING with PHP 8.2

If something fails (it can for quotes, double quotes, non-ASCII characters in either audio metadata (tags for artist, album, title, year and commment), filename of audio file stored by the server, please 1) upgrade your server to PHP 8.1 b) see "Emergency measures" section at the bottom of the document.

CURL php extension required (likely to be installed already at least on commercial-grade hosting services)

GD php extension required if you need cover art (likely to be already installed alongsite with PHP)

GetID3 -most of what is used in it- is now included in Redist and no longer requires manual download.

.htaccess support required in your webserver (in Apache >= 2.4 it is not enabled by default and you need to set "AllowOverride All" in your Apache host configuration in <Directory "/path/to/crero"></Directory> but most commercial hosting will have it done for you) Please note that most default PHP installation "at home" will have their php.ini session.save-handler set to "file", which prevents the Radio (if enabled) to work properly. As a simple workaround, Session.save-handler should store the sessions in memory (see memcached and php8.1-memcache). In production environnement, your PHP will be likely already configured with memory, or databases.

Your server(s) underlaying operating system must support gettimeofday(2) system calls, plus, system clock must be properly set to the exact time and never be changed over time like moving to an inexact date in the past or the future (such a change could lead to hasardous behaviours, like, Radio-feature DOSing bots succeeding their DOS, people reading "Fan network"-feature chat message posted prior to their chat connexion, loss of chat nicknames or messages, stall or complete fail of Radio-feature stream, API never updating their cache even after a file upload, HTMLCache (if enabled) either not expiring as set up, or, unable to recover when a page-caching while a media tier overload (empty tracklist and so on) is detected and the user is provided with a recovering mechanism, YellowPage API (used by YP services to query Crero, and for possible interinstance (syndication, federation) communication) either serving always outdated data or always requerying metadata and slowing down a lot everything, and, much, much more. So keep your time on time.

Quick jump

You may want to skip to the "crash courses" below in "installation steps" to get a quick overview on how to get your install up.

Notable milestones

• 20221010 release : Rogue media tiers no more able to RCE querying servers. No public media tier AFAIK has never been operated by anyone, exception the author of this line. If you run your own media tiers, front-end NOW requires updated api.php on each tier you operate.

• 20221009 release : Security FIX. Affecting almost any version (20151123 or newer), please upgrade: "material things shop" SEVERE security issue. (2022/10/03 additionnal note: Please read about PHP 8.1 and tested things before enabling it)

• 20220623 release : Support for embed. Example : You got a label at cremroad.com . You got an artist, say Me In The Bath. You want to set up meinthebath.com ; somewhere in your html in meinthebath.com add an iframe with its src attribute set to the http url of your label domain, in our case cremroad.com followed by the following path : /?artist=Me+In+The+Bath&embed=Me+In+The+Bath and you are done. Make sure to escape whitespaces as + and any special caracter not allowed in a URL scheme by the %XX number needed (search for "escaping characters in HTTP GET parameters"). Radio block redesign for something less cumbersome, also. Support for continuous (album after album) playback for embed artist sites.

• 20220605-1 Security patch. Any version affected or almost any back to earlier ones. An unused feature in ./api.php and ./api/api.php could allow a remote attacker to access (read) any file located in the public www directory. Please update ./api.php in your front-end. If you use the "free download" feature, please replace api.php in your free media tier by ./api/api.php provided in this FIX.

• 20220605 Security patch. All versions newer than 20190418 with htmlcache option enabled must upgrade for CRITICAL issue allowing Remote Code Execution (RCE). ./index.php modified.

• 20210711 Security patch. All versions newer than 20200919 must upgrade to fix a security issue that affected .htaccess in /radio/e/, causing exposition of the IPs of the listeners of the radio. Upgrade and make sure you have .htaccess in /radio/e/ still present and working.

• 20180817 release : stats rewritten. Please note that the ancient statistics you may have gathered won't now display correctly in the new stats system. If you need them for future reference, please make a backup before upgrade (ie: go to your admin pannel, select, copy, and paste elsewhere)

As an introduction

CreRo is a CMS for record labels, and was initially written to power Crem Road records.

Full multi tiers architecture with through a simple setup the possibility to use external services such as Clewn Audio to host your (free download) media files - or host your files on your own server, you choose.

Paid download is very partially supported (no anti-stealing protection, see below).

Physical release shop feature.

Streaming only or online music free download.

Radio stream for your catalog ; with Xiph yellowpages registration. If chat network is enabled, possibility for listeners to trigger the skipping of a particular song currently aired.

Physical releases means free download, for now.

Chatroom allowing your fans to network with like-minded listeners.

Sell your online digital music quick instructions: activate download_cart option. Maybe set is_download_cart_name_your_price for either, name your price no minimum, or name your price with minimum. Note that people downloading will get hotlinkable audio file links, with no auth system, and that there is no way to prevent them from passing the links around.

New feature 16.11.30.0033 : create a subdir called "supporters" and put an index.php that you can code as you wish in it if you want to display a hall of fame of your donators. A "Our supporters" link will display then in the donation module.

New Feature 17.03 there is now support for mp3 only catalogs (if you wish to host your audio on your own). Previously flac mp3 and ogg were all three mandatory.

An old undocumented feature : you can code a splash.php free-form HTML/php file and it will be displayed at the top of every page of the main site (not the radio).

PHP 8.1 tested things

1. Streaming-only music
2. Free download music
3. Donation module
4. cover art, thumbnailer on the fly, caching of thumbnails
5. Fan Network (a.k.a online webchat for your visitors)
6. Radio module (inluding "skip song" feature if Fan Network is enabeld). Partial-only: the RadioHasYP Yellowpage registration in dir.xiph.org still needs to be tested on a live ("online and public") server as of 2022 Sept 15, and it will be done within a few day. If something goes wrong, expect a bugfix, don't expect much an update in the README
7. last level cache (HTMLCache option in admin panel) including anti-overload & manual cache purging

Untestested things that should work but feedback is welcome, and, please, set up a server at home instead of testing these functionnalities in your production environnement (Please also note that the CreRo yellopages directory currently shows, and since many year, only one server that has enabled public directory listing ; which is, namely, mine. So then these "production environnem