Help with basic setup

[thisanimus]

I'm having trouble understanding how to use the new images for local dev. Could you help be understand how to assemble my compose file, or direct me to an example or documentation?

[jasonmccallister]

Hi @thisanimus, for some reason I was not getting notification on discussions in this repo... I just fixed that.

We absolutely need to provide a better getting started guide.

I'll give you a quick run down and try to work into better format:

• Create a Craft project with composer create-project craftcms/craft craft-example

• Navigate to the craft-example directory or open in your code editor and create a docker-compose.yaml file with the following contents:

services:
  web:
    image: craft-example:dev
    build:
      context: .
      dockerfile: Dockerfile
      args:
        - nginx_config=nginx-dev.conf
    env_file: .env
    ports:
      - "8080:8080"
      - "8443:8443"
    volumes:
      - ./:/app
  mysql:
    image: mysql:8.0
    environment:
        MYSQL_ROOT_PASSWORD: root
        MYSQL_DATABASE: craft
        MYSQL_USER: craft
        MYSQL_PASSWORD: craft
    volumes:
      - db_data:/var/lib/mysql
    ports:
      - "3306:3306"
volumes:
    db_data:

• Create a Dockerfile in the same directory with the following contents:

FROM ghcr.io/craftcms/image:8.3
ARG nginx_config=nginx.conf

USER root

COPY .docker/etc/nginx/${nginx_config} /etc/nginx/nginx.conf
COPY .docker/etc/supervisord.d/nginx.ini /etc/supervisord.d/nginx.ini

# set the sockets and pid files to be writable by the appuser
RUN mkdir -p /var/log/nginx && chown -R appuser:appgroup /var/log/nginx
RUN chown -R appuser:appgroup /var/lib/nginx && touch /run/nginx.pid && chown -R appuser:appgroup /run/nginx.pid

COPY --chown=appuser:appgroup . .

USER appuser

note: since containers focus on running one process at a time (by default) these new images run a tool called supervisor that manages processes and ensures they are started and allow you to add additional processes to the container using the supervisord.d directory and .ini files.

• Create a .docker directory in the root of your project and add the following files:

• .docker/etc/nginx/nginx-dev.conf with the following contents:

worker_processes auto;
pid /run/nginx.pid;
daemon off;

events {
    worker_connections 1024;
}

http {
    sendfile on;
    tcp_nopush on;
    tcp_nodelay on;
    keepalive_timeout 65;
    types_hash_max_size 4096;
    server_tokens off;
    client_max_body_size 100m;

    include /etc/nginx/mime.types;

    access_log /dev/stdout;
    error_log /dev/stderr;

    large_client_header_buffers 4 8k;

    # handle requests for healthcheck
    server {
        listen 8000;
        listen [::]:8000;
        server_name _;
        location / {
            return 200 'ok';
        }
    }

    # server configuration for local development
    server {
        listen 8080;
        listen [::]:8080;
        access_log /dev/stdout;
        error_log /dev/stderr;
        root /app/web;
        index index.html index.htm index.php;
        server_name _;
        charset utf-8;

        # Healthchecks: Set /ping to be the healhcheck URL
        location /ping {
            access_log off;
            # set max 5 seconds for healthcheck
            fastcgi_read_timeout 5s;
            include fastcgi_params;
            fastcgi_param SCRIPT_NAME /ping;
            fastcgi_param SCRIPT_FILENAME /ping;
            fastcgi_pass unix:/var/run/php/php-fpm.sock;
        }

        location / {
            # remove trailing slash
            if ($request_uri ~* ^(.+)/$) {
                return 301 $1;
            }

            try_files $uri $uri/ /index.php?$query_string;
        }

        location ~ \.php$ {
            try_files $uri =404;
            fastcgi_split_path_info ^(.+\.php)(/.+)$;
            fastcgi_pass unix:/var/run/php/php-fpm.sock;
            fastcgi_index index.php;
            include fastcgi_params;
            fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
            fastcgi_param PATH_INFO $fastcgi_path_info;
        }
    }
}

• .docker/etc/supervisord.d/nginx.ini with the following contents:

[program:nginx]
command=/usr/sbin/nginx -c /etc/nginx/nginx.conf
stdout_logfile=/dev/stdout
stdout_logfile_maxbytes=0
stderr_logfile=/dev/stderr
stderr_logfile_maxbytes=0
startretries=0
autorestart=true

Now you can run docker compose up and your Craft project will be running in a container and you can access it at http://localhost:8080.

[fredboyle]

@jasonmccallister Would these configurations be generally considered production environment ready? Or are there alternative recommendations for production deployments?

Thanks.