Docker documentation

[samikeijonen]

There are some documentation how to get Docker up and running in docker-compose.yml file. But here is a summary what steps have we done to make Docker work.

Maybe using Docker should be documented better at Seravo docs.

Bring latest updates from Seravo stack

If you have older project, first step is the get all the updates from Seravo stack to your project.

Create .env file

• Create .env file in the root of the project.
• Add line SITE=[project_name] to the .env file.
• Remember to change [project_name] for real project name which should match name in config.yml file.
• By default [project_name] is wordpress.

Add port bindings

Add port bindings in docker-compose.yml file:

Currently:

    ports:
    - 80
    - 443
    - 22

Added port bindings:

    ports:
    - 80:80
    - 443:443
    - 22:22

Update hosts file

Local URL for the project needs to be added manually in the /etc/hosts file by adding line:

127.0.0.1 [project_name].local

Once again remember to change [project_name] for the real project name.

Start Docker

Start Docker by running docker-compose up.

If everything worked you should be able to access [project_name].local URL in the browser.

Clean up

Sometimes clean up is needed, it can be done with these commands:

docker-compose down -v --remove-orphans
rm -rf .vagrant

How to access Docker container

Accessing Docker container is needed for running WP CLI commands for example.

docker-compose exec --user vagrant wordpress bash

--user vagrant is needed in order to have privileges to run commands like wp-pull-production-db.

If above does not work, try accessing using container ID.

1. Get container ID: docker ps.
2. Access: docker exec -it --user vagrant {ID} sh
3. Or using bash: docker exec -it --user vagrant {ID} bash

Remember to change {ID} for the actual ID.

Summary

There are extra manual steps to take when using Docker. Maybe in the long run some of these can be automated. Like adding port bindings by default?

Anyways we wanted to share our findings and how we have started using Docker.

We have at least tested with macOS Big Sur and WIN 10 with WSL2 system.

cc: @elguitar

[elguitar]

Thank you @samikeijonen for opening a top notch issue! 🥇

I agree that the docker functionality has lacked behind in documentation. We are currently working on with moving bootstrap logic from Vagrant to inside the container. This should make the docker even more comprehensive solution in the future.

I will open a separate issue about automating the .env creation and altering the /etc/hosts.

[k1sul1]

Accessing Docker container is needed for running WP CLI commands for example.

Get container ID: docker ps.
Access: docker exec -it --user vagrant {ID} sh
Or using bash: docker exec -it --user vagrant {ID} bash
Remember to change {ID} for the actual ID

... or you could just use docker-compose exec wordpress bash and skip the 4 steps of bullshit. This image runs on docker-compose, so use docker-compose to manage the instance, not docker directly.

The port bindings are redundant. - 80:80 is the same as - 80, but because YAML is YAML, it should be enclosed in quotes to avoid any unexpected fun;

When mapping ports in the HOST:CONTAINER format, you may experience erroneous results when using a container port lower than 60, because YAML parses numbers in the format xx:yy as a base-60 value. For this reason, we recommend always explicitly specifying your port mappings as strings.

But with the current configuration changing the ports config does absolutely nothing.

[samikeijonen]

Thanks @k1sul1 for your not bullshit comment! I'll try these out.

Edit: Added docker-compose exec wordpress bash example with --user vagrant in the first comment.

[ottok]

Thanks @samikeijonen for submitting documentation. Indeed, the documentation is lacking. The root cause why we haven't documented this feature much, is that Docker containers work nicely only on Linux.

The main reason to run Docker containers is the ability to have multiple projects running in parallel. Docker makes this easy, as each container is lightweight. On Linux you can easily have 10 Seravo/WordPress projects running in parallel, and they start up and announce their domain names automatically via Avahi/Bonjour and everything is dandy – but only on Linux.

On Mac and Windows, Docker actually runs inside a virtual Linux machine, which has it's own network. This means that all Docker instances will have the same IP, not an individual IP like on Linux. This has the downside that you can only bind one container at the time to localhost:80 (and localhost:443 for https).

Your documentation above shows how to run one single Docker container and access it at localhost:80 on Mac (or Windows). On Linux such port binding and DNS entries are unnecessary, as you have direct access to :80, and don't need to use localhost:80.

This is investigated more in detail in #126

The documentation above is OK if you are happy with just one Docker container. That is not much an improvement over Vagrant. We probably need in the future a second container that binds to localhost:80 and only forwards traffic based on DNS name to the actual Seravo/WordPress Docker containers. We haven't yet done this out of the fear of the complexity it introduces and thus it is less of an attractive alternative to Vagrant boxes.

From the documentation above you can omit the /etc/hosts step if you use domain names of form .localhost, as *.localhost always points to 127.0.0.1=localhost on Mac and Linux (maybe also Windows?). However on Linux you can access the host directly with its real IP, so this trick makes sense only on Mac and only when running one single Docker container.

[samikeijonen]

The documentation above is OK if you are happy with just one Docker container. That is not much an improvement over Vagrant.

That's a good clarification. Usually one Docker container is just fine.

Main reason for me using docker-compose up instead of vagrant up is stability. With former I haven't have issues starting the project, with latter too much too often.

From the documentation above you can omit the /etc/hosts step if you use domain names of form .localhost, as *.localhost always points to 127.0.0.1=localhost

Thanks, I'll test it out!

However on Linux you can access the host directly with its real IP, so this trick makes sense only on Mac and only when running one single Docker container.

I don't think many developers using Seravo Stack have Linux. That's why it's important to test these in other environment first (macOS, WIN, or WIN with WSL2).