Skip to content

[docs] Document non-edge installation using Docker Compose #517

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 1 commit into
base: master
Choose a base branch
from
Open

[docs] Document non-edge installation using Docker Compose #517

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
13 changes: 13 additions & 0 deletions docs/user/quickstart.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -122,6 +122,16 @@ and requires less prior knowledge about OpenWISP & networking.
git clone https://github.com/openwisp/docker-openwisp.git
cd docker-openwisp

If you want to use a ``release`` different than ``edge``, run

.. code-block:: bash

git checkout <release>

and set ``TAG=<version>`` in the ``Makefile``. For ``git checkout``
Copy link
Member

@nemesifier nemesifier Oct 4, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Are we suggesting to modify the makefile?

Copy link
Contributor Author

@c-gabri c-gabri Oct 4, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

you'll need to specify the exact release number (``latest`` won't
work).
Copy link
Member

@nemesifier nemesifier Oct 9, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Contributor Author

@c-gabri c-gabri Oct 16, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Member

@nemesifier nemesifier Oct 16, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Contributor Author

@c-gabri c-gabri Oct 17, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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?

Copy link
Member

@nemesifier nemesifier Oct 17, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Contributor Author

@c-gabri c-gabri Oct 18, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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?

Copy link
Contributor Author

@c-gabri c-gabri Oct 19, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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


3. Configure:

Please refer to the :doc:`settings` and :doc:`customization` pages to
Expand All @@ -140,5 +150,8 @@ and requires less prior knowledge about OpenWISP & networking.
If you want to shutdown services for maintenance or any other
purposes, please use ``make stop``.

If you don't want to pull new images each time you run ``make start``, set
``SKIP_PULL ?= true`` in the ``Makefile``.
Copy link
Member

@nemesifier nemesifier Oct 9, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Contributor Author

@c-gabri c-gabri Oct 11, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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?

Copy link
Member

@nemesifier nemesifier Oct 13, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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


If you are facing errors during the installation process, :doc:`read the
FAQ <faq>` for known issues.