[docs] Document non-edge installation using Docker Compose

[c-gabri]

Checklist

• I have read the OpenWISP Contributing Guidelines.
• I have manually tested the changes proposed in this pull request.
• I have written new test cases for new code and/or updated existing tests for changes to existing code.
• I have updated the documentation.

Reference to Existing Issue

Closes #516.

Description of Changes

Add documentation for installing any release (not just edge) with the Docker Compose method.

[c-gabri]

Maybe there should also be documentation on how to upgrade using the Docker Compose method, either in this PR or in a new one. Let me know.

[nemesifier]

Thanks @c-gabri.

I invite you to come to the Development Channel on Matrix to coordinate with other contributors.

[nemesifier]

Are we suggesting to modify the makefile?

[c-gabri]

Yes? Otherwise running make start as the documentation suggests would still pull edge images if I understand correctly. But ideally each github release would have the correct TAG already set in the Makefile?

Not knowing this I had initially installed edge and had problems later when wanting to switch to latest.

[nemesifier]

According to the docs, this can be passed as argument:
https://openwisp.io/docs/24.11/docker/developer/instructions.html#makefile-options

Ideally we want to avoid users messing with the source code as it complicates future upgrades.

I also think we need to simplify these additions and provide a real-world example or else we risk complicating the quick start guide.

Eg:

If you want to use a release different than ``edge``, you can pass the
``TAG`` argument to ``make start``, e.g.:

.. code-block:: bash

    make start TAG=24.11

Disclaimer: I haven't tried this yet (forgive me, I am reviewing many PRs per day and I am trying to reply to as most contributors as possible), please try this if you can.

[c-gabri]

I'm testing latest deployment with

git checkout $(git tag | tail -n 1)
make TAG=latest start

assuming the latest release will always be the last one in alphabetical order.

It works but to be honest I'm not convinced at all that we should suggest this: users could easily forget setting the TAG in a future start, accidentally pulling edge images and potentially messing up their installation.

Why do you think local edits to Makefile variables are so bad? Isn't it the same as editing .env? You mention future upgrades, but upgrades without the auto install script are not even documented.

I would either

• suggest users to edit the Makefile appropriately
• even better, TAG should be already set to the correct value for each release (and SKIP_PULL to true: when you start a program you usually don't want to update it)
• alternatively, we should not tell users to use make for starting/stopping at all.

[nemesifier]

Usually the start operations are set in scripts which start the containers at boot, isn't it?
Therefore users should set the tag in their boot scripts.

In the end everyone can do it in a different way if they wish but the files that are under version control are not meant to be modified by users.

If upgrading is not mentioned we can fix that.

[c-gabri]

I don't use any boot scripts for OpenWISP and I don't see why anybody would: since all services in docker-compose.yml are set to restart: always everything starts automatically at boot. But sometimes you're going to have to stop/start manually for maintenance and, if you do it months after deployment, you'll definitely forget to set TAG or SKIP_PULL.

What about the idea of us setting the correct TAG for each release (and SKIP_PULL = true), so users can just do a git checkout to the desired release simply use make start/stop without worrying about anything? It would also simplify upgrades no?

[nemesifier]

No one forbids users to write their own docker-compose.yml as they need right?, in the same way we do with ansible playbooks, we provide some defaults, a set of images, users can remix everything to get what they need.

What about the idea of us setting the correct TAG for each release (and SKIP_PULL = true), so users can just do a git checkout to the desired release simply use make start/stop without worrying about anything? It would also simplify upgrades no?

I don't understand what this means in practice.

[c-gabri]

No one forbids users to write their own docker-compose.yml as they need right?

Of course not and in principle users with sufficient time and determination can figure out pretty much anything by themselves. But from your comments on Matrix I thought we wanted to make deployment easier for users, right? I am an IT guy and I had some trouble.

I don't understand what this means in practice.

It means that on this repo

• the master branch would have a Makefile with TAG = edge
• the 24.11.2 branch/tag would have a Makefile with TAG = 24.11.2
• and so on
• ideally, there would also be a latest branch/tag identical to the latest release branch/tag
• all branches would have a Makefile with SKIP_PULL ?= true

In this way, after users clone the repo and switch to the desired release with a git checkout, running make start (as we instruct them to do) will have the expected behavior, i.e. pulling the correct images on the first start and not updating them by default on the following starts. Am I missing something?

[c-gabri]

Actually I think that is not enough because, with SKIP_PULL ?= true, the version of the images that are pulled is determined by the image lines docker-compose.yml, but right now the version there is always latest, regardless of the checked out branch/tag. So, in addition to what I wrote before

• each release branch/tag would have a docker-compose.yml with the appropriate version for all the images (e.g. for 24.11.2, the openvpn service has image: openwisp/openwisp-openvpn:24.11.2 and so on)
• at that point we could instruct users to simply start/stop with docker compose up -d/stop, which is the standard way for compose projects, and leave make and the Makefile to developers

[nemesifier]

Same here, I believe this can be passed as an argument so rather than advising to edit the Makefile we can adivse to use the argument.

[c-gabri]

As an alternative to using make start/stop and passing parameters, do you think we should just instruct users to use docker compose up -d/stop instead so the Makefile is not involved at all?

[nemesifier]

I think we should not change the structure of this document too much now.