# Developing for AzuraCast
# Best Practices
Development on the main AzuraCast application should always be applicable to a broad community of radio station operators and not specific features to one station or group of stations.
If you would like to build a set of features specific to one station or group of stations, you should take advantage of AzuraCast's plugin architecture. The plugin system takes advantage of event listeners that are built into AzuraCast itself. Check out the example plugin for more details on what is possible via plugins.
# Setting Up a Local Environment
Regardless of your host operating system, it's highly recommended to use Docker when developing locally, as it offers portability, convenience, and a very close approximation of how AzuraCast runs on production environments.
For the steps below, we're assuming you've created a folder where you will store all of your AzuraCast-related projects, like
You will need Git and Docker installed locally. If you're on Windows or Mac, the best way to use Docker is via the native Docker Desktop applications for those platforms.
For Windows, an installer tool like Scoop is highly recommended for dependencies like Git and your terminal of choice. A third-party shell client like Cmder is also often helpful.
# Clone the Repositories
Using Git, clone the AzuraCast core repository and the various Docker containers into a single folder. When developing locally, the Docker containers are built from scratch, so you will need those repositories to be alongside the main "AzuraCast" project in the same folder.
Note for Windows developers: Before cloning the repositories, you should ensure your Git is locally configured to not automatically convert line endings from Linux style (LF) to Windows style (CRLF), which will break AzuraCast. You can set this globally by running:
git config --global core.autocrlf input
In the same folder, run your platform's equivalent of:
git clone https://github.com/AzuraCast/AzuraCast.git git clone https://github.com/AzuraCast/docker-azuracast-nginx-proxy.git git clone https://github.com/AzuraCast/docker-azuracast-db.git git clone https://github.com/AzuraCast/docker-azuracast-influxdb.git git clone https://github.com/AzuraCast/docker-azuracast-redis.git git clone https://github.com/AzuraCast/docker-azuracast-radio.git
All commands from this point forward should be run in the
AzuraCast repository's folder. From the parent folder,
cd AzuraCast to enter the core repository's directory.
# Copy Default Files
AzuraCast repository, copy the example files into their proper locations:
cp azuracast.dev.env azuracast.env cp docker-compose.dev.yml docker-compose.yml
# Modify the Environment File
AzuraCast can automatically load data "fixtures" which will preconfigure a sample station with sensible defaults, to avoid needing to complete the setup process every time.
To customize how the fixtures load in your environment, open the newly copied
azuracast.env file and customize the following values:
INIT_BASE_URL=docker.local INIT_INSTANCE_NAME=local development INIT_ADMIN_USERNAME= INIT_ADMIN_PASSWORD= INIT_MUSIC_PATH=/var/azuracast/www/util/fixtures/init_music
# Build the Docker Containers
Build the Docker containers from your local copies by running:
# Run the in-container installation
Get into the main CLI container by running, from the host computer:
docker-compose run --user="azuracast" --rm web bash
Inside the terminal session that spawns, you should already be at
/var/azuracast/www and logged in as the
To install the necessary dependencies using Composer, run:
If you want to use the data fixtures (see the .env setup above for the necessary customizations) to set up an initial environment for you, run:
azuracast_cli azuracast:setup --load-fixtures
You can now
exit the CLI shell.
# Spin up the Docker containers
Now that your installation is set up and ready, you can spin up your full installation for the first time.
From the host computer, run:
docker-compose up -d
By default, AzuraCast will be available at http://localhost/. A self-signed TLS certificate is also provided out of the box, so you can take advantage of the HTTPS functionality after manually exempting the site via your browser.
# Building Static Assets
AzuraCast uses a special Docker container containing the full static asset build stack. This makes it very easy to rebuild the compiled assets after having made changes to the JS or SCSS files.
To access the static container, run:
./docker.sh static [optional_command]
By default, this will clean up the existing asset manifests and build new CSS and JS files. To access the terminal inside this container, run
./docker.sh static bash.
# Translations (Locales)
There are two steps to the translation process:
# Generating New Translations
When new strings have been added to the application, they should be added to the .POT (localization template) file, so that our CrowdIn translation service recognizes it as a translatable string.
This can be done by running the respective "Generate Locales" commands:
# Backend ./docker.sh cli locales:generate # Frontend ./docker.sh static npm run generate-locales
# Import New Translated Strings
When strings have been translated, they should be converted back into optimized files that can easily be read by the PHP and Vue.js parts of the application, respectively.
This can be done by running the respective "Import Locales" commands:
# Backend ./docker.sh cli locales:import # Frontend ./docker.sh static npm run import-locales