confusing statements in documentation on upgrade of netbox (example upgrade to 2.9.11)

[samvdl]

Hi,

About the documentation notes on upgrading Netbox found on: https://docs.netbox.dev/en/stable/installation/upgrading/
On "Option A: Download a Release"
Just before that I was intrsucted to creat a symbolic link from the "old netbox" to the "new netbox" dir
sudo ln -sfn /opt/netbox-X.Y.Z/ /opt/netbox

But then I'm instructed to copy files (local_requirements.txt, configuration.py, ldap_config.py, all from media, reports and gunicorn.py) from the "new netbox" dir to the old one...

sudo cp /opt/netbox-2.9.11/local_requirements.txt /opt/netbox/
sudo cp /opt/netbox-2.9.11/netbox/netbox/configuration.py /opt/netbox/netbox/netbox/
sudo cp /opt/netbox-2.9.11/netbox/netbox/ldap_config.py /opt/netbox/netbox/netbox/
sudo cp -pr /opt/netbox-2.9.11/netbox/media/ /opt/netbox/netbox/
sudo cp -r /opt/netbox-2.9.11/netbox/scripts /opt/netbox/netbox/
sudo cp -r /opt/netbox-2.9.11/netbox/reports /opt/netbox/netbox/
sudo cp /opt/netbox-2.9.11/gunicorn.py /opt/netbox/

This doesn't make any sense.
Isn't this an error in the documentation? Shouldn't it be the other way around?
like so:

sudo cp /opt/netbox/local_requirements.txt /opt/netbox-2.9.11/
sudo cp /opt/netbox/netbox/netbox/configuration.py /opt/netbox-2.9.11//netbox/netbox/
sudo cp /opt/netbox/netbox/netbox/ldap_config.py /opt/netbox-2.9.11//netbox/netbox/
sudo cp -pr /opt/netbox/netbox/media/ /opt/netbox-2.9.11/netbox/
sudo cp -r /opt/netbox/netbox/scripts /opt/netbox-2.9.11/netbox/
sudo cp -r /opt/netbox/netbox/reports /opt/netbox-2.9.11/netbox/
sudo cp /opt/netbox/gunicorn.py /opt/netbox-2.9.11/netbox/

Thanks,

Kind regards,
Sam

[kkthxbye-code]

Just before that I was intrsucted to creat a symbolic link from the "old netbox" to the "new netbox" dir
sudo ln -sfn /opt/netbox-X.Y.Z/ /opt/netbox

That is a symlink from the new netbox dir to /opt/netbox replacing the old symlink.

So imagine you are comming from this setup:

/opt/netbox -> symlink to /opt/netbox/2.9.11
/opt/netbox/netbox-2.9.11 (old instance)
/opt/netbox/netbox-3.2.6 (newly extracted)

Then you run sudo ln -sfn /opt/netbox-3.2.6 /opt/netbox - now your setup looks like this.

/opt/netbox -> symlink to /opt/netbox/3.2.6
/opt/netbox/netbox-2.9.11 (old instance)
/opt/netbox/netbox-3.2.6 (newly extracted)

Then you copy from your old instance to the new instance (through the symlink).

sudo cp /opt/netbox-2.9.11/local_requirements.txt /opt/netbox/
sudo cp /opt/netbox-2.9.11/netbox/netbox/configuration.py /opt/netbox/netbox/netbox/
sudo cp /opt/netbox-2.9.11/netbox/netbox/ldap_config.py /opt/netbox/netbox/netbox/
...

[samvdl]

sorry I was not clear ... the old instance is v2.8.9 and the new instance is v2.9.11 (I take small steps to test the upgrade procedure)
I understand what you're saying and it's logical to me.

But the documentation in ambiguous on this.
Referring to the documentation: when creating the symlink, X.Y.Z is referring to the new version number
in my case sudo ln -sfn /opt/netbox-2.9.11/ /opt/netbox

...and than copying from the old instance to the new instance.... X.Y.Z is replaced by 2.8.9

Problem is that it is confusing since the meaning X.Y.Z is changed implicitly (to 2.9.11, which is my newer version in my case)... You see my point?
I think so that the documentation should be adapted... use other letters ... I got really confused.
You agree?

tnx,

kind regards,
Sam

[samvdl]

to be complete clear:

The documentation states: sudo ln -sfn /opt/netbox-X.Y.Z/ /opt/netbox

So the new netbox (well new ;-).. hmh mhm) is in this case v2.9.11

sudo ln -sfn /opt/netbox-2.9.11/ /opt/netbox
is actually creating a symlink called 'netbox-2.9.11' with the folder /opt/netbox/ and pointing to /opt/netbox-2.9.11/
the reason of this escapes me completely!
What's the purpose of intention here???

and than the documentation continues by sudo cp /opt/netbox-X.Y.Z/local_requirements.txt /opt/netbox/

so in this case sudo cp /opt/netbox-2.9.11/local_requirements.txt /opt/netbox/, which means copying the local_requirements.txt file from the new version towards the folder of the current version (and basically overwriting this).

This is exactly the opposite as stated in the documentation:
Copy local_requirements.txt, configuration.py, and ldap_config.py (if present) from the current installation to the new version

Anyhow, this contradiction or confusing and ambiguous communication makes my head spin.

[kkthxbye-code]

is actually creating a symlink called 'netbox-2.9.11' with the folder /opt/netbox/ and pointing to /opt/netbox-2.9.11/

If that happens there's something wrong with ln on your machine and you should check that out first. Or more likely, /opt/netbox is a directory on your system and not a symlink.

Usage: ln [OPTION]... [-T] TARGET LINK_NAME

So /opt/netbox-2.9.11 is the target and /opt/netbox is the link name.

Example of upgrading from netbox-2.9.0 to netbox-2.9.11

Before:

lrwxrwxrwx 1 main main   13 Jul 18 14:59 netbox -> netbox-2.9.0/
drwxr-xr-x 2 main main 4096 Jul 18 14:58 netbox-2.9.0
drwxr-xr-x 2 main main 4096 Jul 18 14:56 netbox-2.9.11

Run command:

ln -sfn netbox-2.9.11/ netbox

After:

lrwxrwxrwx 1 main main   14 Jul 18 15:00 netbox -> netbox-2.9.11/
drwxr-xr-x 2 main main 4096 Jul 18 14:56 netbox-2.9.11
drwxr-xr-x 2 main main 4096 Jul 18 14:58 netbox-2.9.0

As you see, the symlink is changed from the old version to the new version. Then you copy from the old instance to the new one (through the symlink).

sudo cp /opt/netbox-X.Y.Z/local_requirements.txt /opt/netbox/

So with the old version replacing X.Y.Z that becomes:

sudo cp /opt/netbox-2.9.0/local_requirements.txt /opt/netbox/

When the documentation specifies that you are to copy FROM the old version, it expects you to replace X.Y.Z with the old version number.

[samvdl]

is actually creating a symlink called 'netbox-2.9.11' with the folder /opt/netbox/ and pointing to /opt/netbox-2.9.11/

If that happens there's something wrong with ln on your machine and you should check that out first. Or more likely, /opt/netbox is a directory on your system and not a symlink.

Indeed! yes '/opt/netbox' is already the directory of the existing netbox installation
I miss the necessary context alignment between reader and writer in the documentation.
So miss understanding because of lack of context... Happens too often.

Usage: ln [OPTION]... [-T] TARGET LINK_NAME

So /opt/netbox-2.9.11 is the target and /opt/netbox is the link name.

Example of upgrading from netbox-2.9.0 to netbox-2.9.11

Before:

lrwxrwxrwx 1 main main   13 Jul 18 14:59 netbox -> netbox-2.9.0/
drwxr-xr-x 2 main main 4096 Jul 18 14:58 netbox-2.9.0
drwxr-xr-x 2 main main 4096 Jul 18 14:56 netbox-2.9.11

Run command:

ln -sfn netbox-2.9.11/ netbox

After:

lrwxrwxrwx 1 main main   14 Jul 18 15:00 netbox -> netbox-2.9.11/
drwxr-xr-x 2 main main 4096 Jul 18 14:56 netbox-2.9.11
drwxr-xr-x 2 main main 4096 Jul 18 14:58 netbox-2.9.0

As you see, the symlink is changed from the old version to the new version. Then you copy from the old instance to the new one (through the symlink).

sudo cp /opt/netbox-X.Y.Z/local_requirements.txt /opt/netbox/

So with the old version replacing X.Y.Z that becomes:

sudo cp /opt/netbox-2.9.0/local_requirements.txt /opt/netbox/

When the documentation specifies that you are to copy FROM the old version, it expects you to replace X.Y.Z with the old version number.

Now it's clear because of the 'forensic context discovery'...
(I did not install the initial netbox setup version and /opt/netbox was NOT a symlink but the native install directory for this V2.8.9)

Tnx for the clarity on that. But don't you agree that this context might be useful to state in the documentation or is it my IQ that is lacking?

[samvdl]

and another thing...
to run the upgrade script: sudo ./upgrade.sh
I assume the one from the new version? (documentation not explicit)
Sosudo PYTHON=/usr/bin/python3.9 /opt/netbox-2.9.11/upgrade.sh within the new enviroment folder (venv) I created and activate within /opt/netbox-2.9.11/...