Skip to content

Installation

Jump to bottom
Valentijn Verhallen edited this page Aug 10, 2025 · 8 revisions

Unchained is built upon Symfony 7.3 components, using a custom kernel.

Docker

Installation is easiest using Docker. The project comes with a Docker Compose configuration which is ideal for both production and development. This can easily be adjusted to your liking.
The container is built on PHP-FPM 8.4 - Alpine, in an effort to keep the image as small as possible. This means you are required to add your own webserver/proxy in front.

Sample configuration:

services:
  unchained:
    image: unchained-cms:latest
    # enable this to help you get started
    #environment:
    #  INCLUDE_EXAMPLES: "true"
    networks:
      default:
        aliases:
          - php-fpm
    volumes:
      # see code for details
      - ./.docker/php/conf.d/php-upload.ini:/usr/local/etc/php/conf.d/php-upload.ini:ro
      # The build directory is used for front-end files 
      - build:/var/www/public/build
      # The media directory is used for user uploaded files/images 
      - media:/var/www/public/media

  nginx:
    image: nginx:stable-alpine
    depends_on:
      - php
    volumes:
      # see code for details
      - ./.docker/nginx/default.conf:/etc/nginx/conf.d/default.conf:ro
      # note the mount path variation
      - media:/var/www/media 
      - build:/var/www/build

  # use a local or shared mysql instance
  # other database systems are not supported (yet)
  mariadb:
    image: mariadb
    volumes:
      - mysql:/var/lib/mysql

volumes:
  build:
  media:
  mysql:

Prerequisites

The application relies on the existence of basic configuration files within the default /user directory. It'll attempt to create them when omitted:

  • /user/config.yaml for global configuration
  • /user/applications.yaml for application registration
  • /user/config/framework/security.yaml for the user login
  • /user/assets/user.js as the front-end build entrypoint

If any of the above files do not exist, the container will attempt to use the *.dist default.

Not sure where to start next? You can add the environment variable INCLUDE_EXAMPLES="true" to let the container generate the default applications.

Bare metal

Requirements

Installation

  • Clone this repository:
git clone git@github.com:vpmv/unchained-cms.git
  • Install vendor packages:
php composer.phar install
  • Copy .env to .env.local and configure your environment & database connection.
  • Enable the default administrator by copying /user/config/framework/security.yaml.dist to [..]/framework/security.yaml
  • Install and build front-end:
yarn install
yarn encore prod

It's recommended to install the sources outside your public mount point (e.g. public_html). When public/index.php is nested further, please edit this first line (require_once __DIR__ .'/../config/bootstrap.php') by pointing to the installation directory, e.g. __DIR__.'/../../unchained/config/bootstrap.php.

Post-install

Please refer to Creating Applications to set the stage for your application.

The database tables for your applications are automatically generated during runtime. All you need to do is configure translations; More on translations

Extending the front-end

The front-end is compiled with Symfony's Webpack Encore, and the packages are managed by Yarn.

You can extend on the example entrypoint in /user/assets/user.js. The front-end gets compiled when the image starts (on entrypoint), but it can always be re-run manually:

docker exec <container> yarn encore prod 

# Or when using Docker Compose:
docker compose exec <service> yarn encore prod
Clone this wiki locally