webmago/winter repository overview

The docker images defined in this repository serve as a starting point for Winter CMS⁠ projects.

Based on official docker PHP images⁠, images include dependencies required by winter, Composer and install the latest release⁠.

This is a docker-octobercms repository fork from @Aspendigital⁠

⁠Supported Tags

• latest
• stable-v1.2.7-php8.0-apache, stable-v1.2.7-php8.1-apache, stable-v1.2.7-php8.2-apachee
• stable-v1.2.7-php8.0-fpm, stable-v1.2.7-php8.1-fpm, stable-v1.2.7-php8.2-fpm
• stable-v1.1.3-php7.4-apache, stable-v1.1.2-php7.4-apache
• stable-v1.1.3-php7.4-fpm, stable-v1.1.2-php7.4-fpm
• stable-v1.1.3-php7.3-apache, stable-v1.1.2-php7.3-apache
• stable-v1.1.3-php7.3-fpm, stable-v1.1.2-php7.3-fpm
• stable-v1.1.3-php7.2-apache, stable-v1.1.2-php7.2-apache
• stable-v1.1.3-php7.2-fpm, stable-v1.1.2-php7.2-fpm

⁠Legacy Tags

⁠Quick Start

To run winter CMS using Docker, start a container using the latest image, mapping your local port 80 to the container's port 80:

$ docker run -p 80:80 --name winter webmago/winter:latest
# `CTRL-C` to stop
$ docker rm winter  # Destroys the container

• Visit http://localhost⁠ using your browser.
• Login to the backend⁠ with the username admin and password admin.
• Hit CTRL-C to stop the container. Running a container in the foreground will send log outputs to your terminal.

Run the container in the background by passing the -d option:

$ docker run -p 80:80 --name winter -d webmago/winter:latest
$ docker stop winter  # Stops the container. To restart `docker start winter`
$ docker rm winter  # Destroys the container

⁠Working with Local Files

Using Docker volumes, you can mount local files inside a container.

The container uses the working directory /var/www/html for the web server document root. This is where the winter CMS codebase resides in the container. You can replace files and folders, or introduce new ones with bind-mounted volumes:

# Developing a plugin
$ git clone [email protected]:aspendigital/oc-resizer-plugin.git
$ cd oc-resizer-plugin
$ docker run -p 80:80 --rm \
  -v $(pwd):/var/www/html/plugins/aspendigital/resizer \
  webmago/winter:latest

Save yourself some keyboards strokes, utilize docker-compose⁠ by introducing a docker-compose.yml file to your project folder:

# docker-compose.yml
version: '2.2'
services:
  web:
    image: webmago/winter
    ports:
      - 80:80
    volumes:
      - $PWD:/var/www/html/plugins/aspendigital/resizer

With the above example saved in working directory, run:

$ docker-compose up -d # start services defined in `docker-compose.yml` in the background
$ docker-compose down # stop and destroy

⁠Database Support

⁠SQLite

On build, an SQLite database is created and initialized⁠ for the Docker image. With that database, users have immediate access to the backend for testing and developing themes and plugins. However, changes made to the built-in database will be lost once the container is stopped and removed.

When projects require a persistent SQLite database, copy or create a new database to the host which can be used as a bind mount:

# Create and provision a new SQLite database:
$ touch storage/database.sqlite
$ docker run --rm \
  -v $(pwd)/storage/database.sqlite:/var/www/html/storage/database.sqlite \
  webmago/winter php artisan winter:up

# Now run with the volume mounted to your host
$ docker run -p 80:80 --name winter \
 -v $(pwd)/storage/database.sqlite:/var/www/html/storage/database.sqlite \
 webmago/winter

⁠MySQL / Postgres

Alternatively, you can host the database using another container:

#docker-compose.yml
version: '2.2'
services:
  web:
    image: webmago/winter:latest
    ports:
      - 80:80
    environment:
      - DB_TYPE=mysql
      - DB_HOST=mysql #DB_HOST should match the service name of the database container
      - DB_DATABASE=wintercms
      - DB_USERNAME=root
      - DB_PASSWORD=root

  mysql:
    image: mysql:5.7
    ports:
      - 3306:3306
    environment:
      - MYSQL_ROOT_PASSWORD=root
      - MYSQL_DATABASE=wintercms

Provision a new database with winter:up:

$ docker-compose up -d
$ docker-compose exec web php artisan winter:up

⁠Cron

You can start a cron process by setting the environment variable ENABLE_CRON to true:

$ docker run -p 80:80 -e ENABLE_CRON=true webmago/winter:latest

Separate the cron process into it's own container:

#docker-compose.yml
version: '2.2'
services:
  web:
    image: webmago/winter:latest
    init: true
    restart: always
    ports:
      - 80:80
    environment:
      - TZ=America/Denver
    volumes:
      - ./.env:/var/www/html/.env
      - ./plugins:/var/www/html/plugins
      - ./storage/app:/var/www/html/storage/app
      - ./storage/logs:/var/www/html/storage/logs
      - ./storage/database.sqlite:/var/www/html/storage/database.sqlite
      - ./themes:/var/www/html/themes

  cron:
    image: webmago/winter:latest
    init: true
    restart: always
    command: [cron, -f]
    environment:
      - TZ=America/Denver
    volumes_from:
      - web

⁠Command Line Tasks

Run the container in the background and launch an interactive shell (bash) for the container:

$ docker run -p 80:80 --name containername -d webmago/winter:latest
$ docker exec -it containername bash

Commands can also be run directly, without opening a shell:

# artisan
$ docker exec containername php artisan env

# composer
$ docker exec containername composer info

A few helper scripts have been added to the image:

# `winter` invokes `php artisan winter:"$@"`
$ docker exec containername winter up

# `artisan` invokes `php artisan "$@"`
$ docker exec containername artisan plugin:install aspendigital.resizer

# `tinker` invokes `php artisan tinker`. Requires `-it` for an interactive shell
$ docker exec -it containername tinker

⁠App Environment

By default, APP_ENV is set to docker.

On image build, a default .env is created⁠ and config files⁠ for the docker app environment are copied to /var/www/html/config/docker. Environment variables can be used to override the included default settings via docker run⁠ or docker-compose⁠.

⁠PHP configuration

Recommended settings for opcache and PHP are applied on image build⁠.

Values set in docker-oc-php.ini can be overridden by passing one of the supported PHP environment variables defined below.

To customize the PHP configuration further, add or replace .ini files found in /usr/local/etc/php/conf.d/.

⁠Environment Variables

Environment variables can be passed to both docker-compose and winter CMS.

⁠Docker Entrypoint

The following variables trigger actions run by the entrypoint script⁠ at runtime.

⁠Winter CMS app environment config

List of variables used in config/docker

* When using a container to serve a database, set the host value to the service name defined in your docker-compose.yml

** Timezone applies to both container and winter CMS config