Skip to content

Home

Jump to bottom Edit New page
Michael Härtl edited this page Sep 9, 2015 · 21 revisions

Yii2 Dockerized

1. What is this?

This project is a template for your own Yii2 applications. You can use it as a starting point and modify it to fit your requirements. It's based on the codemix/yii2-base docker image.

Features

  • Ephemeral container, configured via environment variables
  • Testing container for easy testing
  • Optional local configuration overrides for development/debugging (git-ignored)
  • Base scaffold code for login, signup and forgot-password actions
  • Flat configuration file structure
  • Supports docker image based development workflow

Image Variants

The yii2-base image comes in three flavours:

  • Apache with PHP module (based on php:5.6.10-apache)
  • PHP-FPM (based on php:5.6.10-fpm)
  • HHVM (based on estebanmatias92/hhvm:3.7.0-fastcgi)

You can easily choose which one you want to use by modifying the FROM line in your Dockerfile.

2. How to use

To use this image you'll follow these two steps:

  • Create a new project
  • Set up and configure your development environment

We'll cover both steps in more detail below.

Create a new project

As mentioned above, this project is a template for your own projects. So when creating a new project you basically will

  1. copy the code into some directory,
  2. modify the main app configuration, usable environment variables, composer dependencies, README.md, inital DB migration, etc.
  3. commit the above to your repository

To copy the code to your computer, you can use composer to do the main work for you:

composer create-project --no-install codemix/yii2-dockerized myproject

As for step 2 above, you may first want to select a flavour of the docker base. You only need to uncomment the appropriate line in the Dockerfile:

FROM codemix/yii2-base:2.0.6-apache
#FROM codemix/yii2-base:2.0.6-php-fpm
#FROM codemix/yii2-base:2.0.6-hhvm

Then you should check the following files and directories:

  • Dockerfile: Optionally add PHP extensions
  • docker-compose-example.yml: Provide an example machine configuration for other developers
  • config/web.php / config/console.php: Update the main configuration
  • .env-example: Add more environment variables
  • composer.json: Add more dependencies for your project
  • migrations/: Update the initial DB migration to match your DB model
  • README.md: Describe your application

If you think everything is fine, it's time for the first commit to your project's repository. This will now be the starting point for your developers.

Set up a development environment

When you have the project in your repository, it's easy to set up a new development environment, e.g. for a new team member:

git clone <your-repo-url> ./myapp
cd myapp
cp docker-compose-example.yml docker-compose.yml
cp .env-example .env
docker-compose up
# From another terminal window:
docker-compose run --rm web ./yii migrate

It may take some minutes to download the required docker images. When done, you can access the new app from http://localhost:8080.

Note: The local app directory will be mapped into the /var/www/html directory of the web container. So you can always work on your local source files and will immediately see the results under the URL of the container.

The next step is to configure the application. For example you will want to enable YII_DEBUG or set other local configurations during development. So read on in the next section.

3. How to configure

There are different ways, how the application is configured. Namely those are

  • Environment variables
  • Local configuration files

As we follow the 12 factor principles, all main configuration should always happen through environment variables. So why do we support local configuration files at all? Simply to make life as a developer easier: You sometimes may want to add some local configuration, for example add extra logging. Still you don't want to accidentally commit those changes to the repository with the main configuration.

To put it another way: You'll probably only ever use local configuration files during development.

Important: If you find yourself fiddling around with config files on your production servers, you're doing it wrong! Use environment variables instead!

Environment Variables

We will not cover, how you set environment variables on your production system, as this is part of the deployment. You also find some examples in the Docker documentation.

But what about local development? Of course, we also need a way to easily set environment variables to control the app. We have implemented two mechanisms to do so:

  • In the environment section of the docker-compose.yml. This requires to remove and recreate the container each time you change a variable. So we recommend to only put ENABLE_ENV_FILE here and use the next option for the rest.
  • In a .env file in your app directory. Changes there are picked up immediately by the yii app inside the container. We have included an example .env-example that you can use to get started.

Variables in docker-compose.yml have precedence over those in the .env file.

Note: Variables in the .env file are only available in the Yii PHP application, because we use PHP Dotenv to load them. They are not available for example in bash scripts. So if you need them there, you should add them to docker-compose.yml.

The following environment variables are used by the base image:

Important: Some variables can only be set in the docker-compose.yml (marked with dc-only).

Mandatory:

Optional:

  • API_TOKEN (dc-only) the github API token for composer updates.
  • ENABLE_ENV_FILE (dc-only) whether to load env vars from a local .env file. Default is 0.
  • ENABLE_LOCALCONF whether to allow local overrides for web and console configuration (see below). Default is 0.
  • YII_DEBUG whether to enable debug mode for Yii. Default is 0.
  • YII_ENV the Yii app environment. Either prod (default) or dev. Do not use test as this is reserved for the testing container!
  • YII_TRACELEVEL the traceLevel to use for Yii logging. Default is 0.
  • DB_DSN the DSN to use for DB connection. Defaults to mysql:host=db;dbname=web if not set.
  • DB_USER the DB username. Defaults to web if not set.
  • DB_PASSWORD the DB password. Defaults to web if not set.
  • SMTP_HOST the SMTP hostname.
  • SMTP_USER the username for the SMTP server.
  • SMTP_PASSWORD the password for the SMTP server.

Configuration Files

All configuration lives in three files in the config/ directory.

  • web.php configuration for the web application
  • console.php configuration for the console application
  • params.php application parameters for both web and console application

These three files are committed to your repository, so you should be careful about changes there.

To override some settings during development, without accidentally committing them to the repository, you can create local override files (requires ENABLE_LOCALCONF to be set):

  • local.php local overrides for the web configuration
  • console-local.php local overrides for the console configuration

Both files are merged with the respective configuration above. This way you can explicitely override specific parts of the web or console configuration.

Add a custom footer
Add a custom sidebar
Clone this wiki locally