Dummies guide to getting started

[jlabs]

I'm looking into using Docker as an alternative to MAMP (and Nitro - as I'm getting errors with the initial setup), and I'm not sure I'm getting off the right foot.

Looking at the README, I created a DockerFile using the craftcms/nginx repo, then created a docker-compose and nginx.conf files with the example data given in the README. These 3 files went into a CraftCMS folder I had created with composer (composer create-project etc.) ... is this correct?

I had created an empty folder the just had the DockerFile, docker-compose.yml, and the nginx.conf files in then ran docker-compose up but it didn't appear to actually install Craft at any stage - even though there's a composer command within docker-compose. Should I be taking come files/content from the stable branch in this repo e.g. 7.3?

[spencech-upbeat]

I'll upvote a request for a QuickStart section on the README that ends with a local url that I can test and see CraftCMS running. Unlike the standard CraftCMS installation, there's not a lot of examples and conversation about this in the dev community, at least that I've found so far. Thanks!

[jamesmacwhite]

I've recently started experimenting with docker and here's my notes.

I think the assumption is that you have possibly followed something like: https://github.com/craftcms/craft and https://craftcms.com/docs/getting-started-tutorial/install/files.html#install-craft-cms-files, which provides you with a Craft 3 install you then add a docker-compose.yml and Dockerfile to it. It is possibly why the repo is like this as to not be too opinionated in terms of what is provided, focusing on the Docker side of things rather than the project setup.

Composer does get installed in the Docker container, but only the binary being available, it doesn't run composer install for you, but there is an example Dockerfile with a composer install example. You could also add something like into your Dockerfile as well. If you wanted Docker to do all the work.

RUN composer create-project craftcms/craft

There's some other examples of Craft CMS 3 and Docker:

https://nystudio107.com/blog/an-annotated-docker-config-for-frontend-web-development
https://github.com/urbantrout/craftcms
https://mattgrayisok.com/a-craft-cms-development-workflow-with-docker-part-1-local-development

Which help compare and understand other interpretations. It can be a bit overwhelming initially, but that's how I've been learning and understanding how Docker and Craft CMS works.

I'd welcome more documentation though, as using Docker is relatively new to me too. For anyone who uses Windows as a host. Make sure to deploy your Craft CMS project in a WSL2 distro, not on the host Windows FS environment. The performance is shocking if not using WSL2, trust me!

[jasonmccallister]

@jlabs this definitely needs a better write up and we will get it on the list ASAP.

[jasonmccallister]

@jlabs we should certainly add a guide for getting started with these docker images... but sometimes all the configuration is can be overwhelming... which is why Nitro v2 is based on Docker and uses these images underneath but orchestrates everything for you. The best part about Nitro v2 is you don't have to mess with networks, ports, and etc...

You can get started with Docker locally using Nitro v2 without all of the configuration... if you are interested here are the updated docs for Nitro https://craftcms.com/docs/nitro/2.x/

[ralftar]

I hope it's OK to piggy-back into this issue with a dummy question.

What is the recommended upgrade regime when Craft CMS releases new versions and patches?

Upgrading natively inside the container won't be good since on the next deploy or restart of the idempotent container will reset it back to when it was built, and also might cause a mismatch between databases running a newer version than the old reset container? (assuming DB not running inside container)

On the oter hand, building a new and upgraded docker image might not run have run database upgrade scripts?

[jamesmacwhite]

@ralftar Do you mean Craft CMS releases itself? This would be handled by composer in the vendor folder, so nothing to worry about in terms of Docker.

[ralftar]

@jamesmacwhite, yes I do. But wont the Craft release as well as the container content be reset to the initial version upon a restart of the container?

[jamesmacwhite]

@ralftar No. Once your docker environment is provisioned the containers created will not be constantly rebuilt. You can technically force this with docker-compose up --rebuild but you wouldn't need to do this unless something within the docker images or environment changed to require this. Otherwise a simply docker-composer up will just start up any existing containers.

Any Craft CMS updates will be handled by composer and deployed within the vendor folder. Technically docker and composer and two separate components. For Craft CMS updates composer update would be all you need. You'd need to run that in a console window attached to the PHP FPM container though.

[ralftar]

@jamesmacwhite Not rebuilt, but reset. Docker containers are not persistent, thus is will be reset on each stop (idempotent pattern) to what it was built as. After running composer update, and succeeded by a restart the container will be reset to it's build version.

[jamesmacwhite]

Bearing in mind the mount points configured at /app mean FS related nothing is lost, so your vendor folder, all project files etc, Running docker-composer up after the containers have been built once puts you right back where you when you stopped them. You don't need to do anything different.