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.

[ralftar]

Thanks @jamesmacwhite! The mountpoint explains it all, I was assuming all Craft executables were containerized. So mainly the container is the runtime environment in this approach?

[jamesmacwhite]

Yes that's a good way of looking at it. Each container is the runtime, depending on the setup, typically these docker images will create a container for NGINX, PHP-FPM, MySQL/MariaDB/Postgres and Redis. There is also a Craft CLI container that basically runs the queue command.

Most of the Craft project will be the mountpoint at /app, so the ./craft executable, vendor folder contents and all templates and files etc are able to be constantly updated and those changes reflected immediately in the docker environment. The only issue you might come across is write permissions, for local dev you can usually just do the CHMOD 777 "fix" but obviously only on local dev, that's because the docker environment uses the www-data user, which will differ to the mountpoint most likely, so for folders like /storage /vendor you may need to do this.

[ralftar]

I am firing one more dummy question: Could one run multiple Craft instances/sites in one docker instance, or would it be considered an anti-pattern?

[jamesmacwhite]

Not impossible, but outside of the intended way these docker images would be used on a typical basis and would require some pretty hefty modifications. So it would be easier just to have a docker environment per project, the one downside to this is needing to ensure to not have port collisions per project, so if project one has NGINX on 8000, project two would need to be 8001 or something else. Which also applies to any other service which forwards a port to localhost to be accessible on the host.

If you wanted to run multiple Craft sites under a single docker container, you'd need to start getting involved with having multiple mountpoints, a reverse proxy for the web side, deploying multiple databases under the single DB container, in addition to other modifications, which at this point, deploying another docker environment is probably easier. Given if your docker-compose-.yml and Dockerfile steps are good, it will be a quick deployment process. Obviously it's more resource intensive, but generally Docker is about as lightweight as any "VM" layer goes, so hopefully not too bad. Better than most other solutions which require a full VM layer which is heavy.

[jasonmccallister]

@ralftar to follow up with the excellent points from @jamesmacwhite...

I am firing one more dummy question: Could one run multiple Craft instances/sites in one docker instance, or would it be considered an anti-pattern?

It is usually one nginx "virtual site" per project, while you "could" get away with multiple installs and changing the nginx config, probably not worth it. If you have a multi-site config, you point all the domains to the container and Craft will sort it out.

it would be easier just to have a docker environment per project, the one downside to this is needing to ensure to not have port collisions per project, so if project one has NGINX on 8000, project two would need to be 8001 or something else

This is exactly the use case for moving Nitro v2 over to Docker, it removes all of the port collisions and focuses on running multiple projects or "sites" as individual containers. All you have to do is install Docker and Nitro and let it work out the complicated details (e.g. we create a proxy container that handles local SSL with trusted local certificates).

multiple databases under the single DB container, in addition to other modifications, which at this point, deploying another docker environment is probably easier

We have a section on running multiple database "engines" with Nitro v2, you can run mysql, mariadb, and postgres running a mix between all the versions, etc. Nitro v2 documentation has a writeup on the docs here: https://craftcms.com/docs/nitro/2.x/multiple-databases.html

As a side note, these images are the base images for the containers that run "sites" in Nitro v2..

Nitro v2 is still in beta, but it is a huge improvement over v1. You can read the documentation for v2 here. The team has been using it internally for more than a month and worked out a lot of bugs before the public beta.

Ryan from CraftQuest.io also has a quick introduction video on using Nitro v2.

As far as general learning about Docker, Bret Fisher has the best course on getting started with Docker on Udemy called Docker Mastery and is well worth the purchase as he breaks down all of the components with great examples.

[jamesmacwhite]

Good to know about Nitro. I didn't want my answer to come across as saying it wasn't possible to run multiple Craft sites under a single docker environment, but if Nitro has done a lot the heavy lighting, then sounds like the way to go, the docker images alone would require some modifications which probably make it less attractive to do on your own, but if Nitro has done a lot of the work, then definitely worth exploring!

[rktjmp]

Edit: See #26 PR for neater instructions.

These are the steps I perform to get craft up to look at.

For what it's worth as someone coming into examine craft, the prospect of installing another cli tool for a platform I don't really use is kind of unappealing when the docker-compose file should provide me a similar experience.

These instructions are not for production use, they are just so you can look at a test install.

1. Copy docker compose file from readme to a clean dir
2. docker-compose up -d
3. docker-compose run -u 0 console sh # run as root so we can mkdir etc
4. composer create-project craftcms/craft temp
5. no do not setup
6. exit # quit docker run sh
7. sudo mv temp/** . # un-nest project, sudo because we made as root
8. sudo chown your_user:your_group -R .
9. sudo chmod -R 777 . # I had a licence.key file that didn't pick up owner ship, sudo to force
10. http://localhost:8080/?p=admin/install
11. Perform setup, mysql host is mysql as compose services have name resolution within their network. Get user, pass and db name from docker-compose file.