Start using docker-compose and watch the changed files to simplify docs changes.

[jpjoao]

This simplifies how we interact with the documentation locally:

• Introduces a docker-compose.yaml to reduce the noise and complexity to spin up the local environment.
• Reduces the steps (from 2 to 1) to have the local environment up and running.
• Introduces livehtml to make command to allow files to be watched and changes to be re-compiled automagically speeding up the change and change validation process.

Please let me know what are the thoughts on this and if any more changes are needed.

[ostrolucky]

I don't see the point of introducing docker-compose for single service. It doesn't reduce complexity, I would argue contrary

[Guikingone]

Agree with @ostrolucky, not to mention that we don't always use Docker in its "normal" approach (think Docker in Docker, Docker-Machine, etc), the actual docker-compose can lead to more issues 🤔

Second point, I'm not sure that exposing the ports is a good idea, sometimes, we can have reverse-proxy like Traefik and exposing ports can create issues with the Traefik ones (or other solutions), the ports can be moved into a doicker-compose.override.yml IMO.

[jpjoao]

Today on any change you make you need to:

• You build the container (which compiles the docs)
• You run the container (exposing the ports) to see the result.

With this change, you only need to run on command and have the documentation built and updated as you save the changed files.

To accomplish it we no longer copy the files to the container but instead, we map volumes. Running it on the command line would be something like this:

docker build . -t symfony-docs
docker run -it -v ${PWD}:/www --user $(id -u):$(id -g) -p 8080:8000 symfony-docs:latest

It would remain as two steps (same as today) and have some "overcomplicated" command to run the watch job. docker-compose simplifies it to make the build and run one single command and hides some of the complexity of the run command. I would say that it is a nice DX.

Note that there are no changes in ports exposure, we already do it today.

[ostrolucky]

What are the instructions for Windows users? There is no id -u there

[jpjoao]

What are the instructions for Windows users? There is no id -u there

That is a very good question. I don't have a windows machine to test on nor the knowledge of what to do in such case. I don't know what's the behaviour there.
From Docker from Windows docks I see this:

Docker Desktop sets permissions to read/write/execute for users, groups and others 0777 or a+rwx. This is not configurable. See Permissions errors on data directories for shared volumes.

I would assume that for Windows it would simply be a matter of not setting the ENV? docker-compose already assumes an empty one. I would appreciate some help on that.

I removed the need to pass the user. So there is no differences between Windows and Linux (or Mac) usage and it is more straightforward now.

[javiereguiluz]

Just asking: what's the status of this proposal? Do people agree on finishing it? Or is it too controversial to continue? Would you try a different approach? Thanks!

[wouterj]

Hi! I'm going to close this PR as there hasn't been any response for months and local doc set-up isn't the biggest priority for the documentation team.

If people do have a strong opinion on this and want to finish this PR, please comment and I'll reopen.