Yii3 Web Application Template

The Yii3 web application template follows this directory structure:

• assets/: Asset bundle source files.
• config/: Configuration files.
  • common/: Common configuration and DI definitions.
  • console/: Console-specific configuration.
  • environments/: Environment-specific configuration (dev/test/prod).
  • web/: Web-specific configuration.
• docker/: Docker-specific files.
• public/: Files publicly accessible from the Internet.
  • assets/: Published/compiled assets.
  • index.php: Entry script.
• runtime/: Files generated during runtime.
• src/: Application source code.
  • Console/: Console commands.
  • Shared/: Code shared between web and console applications.
  • Web/: Web-specific code (actions, handlers, layout).
    • Shared/: Shared web components.
      • Layout/: Layout components and templates.
  • bootstrap.php: Application bootstrap (autoloading, environment setup).
  • Environment.php: Environment configuration class.
• tests/: Codeception tests (Console, Functional, Unit, Web).
• vendor/: Installed Composer packages.
• Makefile: Config for make commands.
• yii: Console application entry point.

The production environment uses a Docker Compose configuration that defines an app service designed for high availability and automated deployment.

Environment Variables

The configuration relies on several environment variables for image selection and host configuration:

• ${IMAGE}: The Docker image name.
• ${IMAGE_TAG}: The specific tag for the image.
• ${PROD_HOST}: The hostname for the Caddy reverse proxy. Defaults to app.example.com if not provided.

Environment Files

Environment variables are loaded from the following files in order (later files override earlier ones):

1. ./prod/.env (Required)
2. ./prod/override.env (Optional)

Deployment and Scaling

The service is configured for production-grade deployment with the following settings:

• Replicas: 2 instances are maintained.
• Update Strategy: Uses start-first order (starts new containers before stopping old ones) with a 10s delay and a parallelism of 1. If an update fails, it triggers a rollback.
• Rollback Strategy: Uses stop-first order.
• Restart Policy: Restarts on failure with a 5s delay, up to 3 attempts within a 120s window.

Networking and Reverse Proxy

• The service connects to an external network named caddy_public.
• It uses Caddy labels for automatic reverse proxy configuration. The caddy.reverse_proxy label is set to route traffic to upstreams on port 80.

services:
  app:
    image: ${IMAGE}:${IMAGE_TAG}
    networks:
      - caddy_public
    volumes:
      - runtime:/app/runtime
      - caddy_data:/data
      - caddy_config:/config
    env_file:
      - path: ./prod/.env
      - path: ./prod/override.env
        required: false
    deploy:
      replicas: 2
      update_config:
        delay: 10s
        parallelism: 1
        order: start-first
        failure_action: rollback
        monitor: 10s
      rollback_config:
        parallelism: 0
        order: stop-first
      restart_policy:
        condition: on-failure
        delay: 5s
        max_attempts: 3
        window: 120s
      labels:
        caddy: ${PROD_HOST:-app.example.com}
        caddy.reverse_proxy: "{{upstreams 80}}"

volumes:
  runtime:

networks:
  caddy_public:
    external: true

The project provides a Docker Compose configuration for local development. The app service builds from docker/Dockerfile using the dev target.

Environment Variables

To customize the build and runtime behavior, you can provide the following environment variables:

• UID: Sets the USER_ID build argument for the container user.
• GID: Sets the GROUP_ID build argument for the container group.
• DEV_PORT: Sets the host port mapping. Defaults to 80 if not specified.

Environment Files

The service loads environment variables from:

1. ./dev/.env (Required)
2. ./dev/override.env (Optional)

Volume Mappings

• ../:/app: Mounts the project root to /app in the container.
• ../runtime:/app/runtime: Mounts the local runtime directory to /app/runtime for persistent application data.
• caddy_data:/data: Persistent storage for Caddy data.
• caddy_config:/config: Persistent storage for Caddy configuration.

services:
  app:
    build:
      dockerfile: docker/Dockerfile
      context: ..
      target: dev
      args:
        USER_ID: ${UID}
        GROUP_ID: ${GID}
    env_file:
      - path: ./dev/.env
      - path: ./dev/override.env
        required: false
    ports:
      - "${DEV_PORT:-80}:80"
    volumes:
      - ../:/app
      - ../runtime:/app/runtime
      - caddy_data:/data
      - caddy_config:/config
    tty: true

The application is bootstrapped and executed using the HttpApplicationRunner. This runner requires the application root path, debug mode status, event checking preference, and the current environment. It also configures a temporaryErrorHandler to handle errors during the early stages of the application lifecycle using a Logger with a StreamTarget and an HtmlRenderer.

$runner = new HttpApplicationRunner(
    rootPath: $root,
    debug: Environment::appDebug(),
    checkEvents: Environment::appDebug(),
    environment: Environment::appEnv(),
    temporaryErrorHandler: new ErrorHandler(
        new Logger(
            [
                (new StreamTarget())->setLevels([
                    LogLevel::EMERGENCY,
                    LogLevel::ERROR,
                    LogLevel::WARNING,
                ]),
            ],
        ),
        new HtmlRenderer(),
    ),
);
$runner->run();