Netbox: Document process for persisting optional packages across virtual environment rebuilds

[jeremystretch]

Change Type

[x] Addition
[ ] Correction
[ ] Deprecation
[ ] Cleanup (formatting, typos, etc.)

Area

[x] Installation instructions
[ ] Configuration parameters
[ ] Functionality/features
[ ] REST API
[ ] Administration/development
[ ] Other

Proposed Changes

The v2.7.9 release introduced a new install procedure, where NetBox is installed within a Python virtual environment. On upgrade, this virtual environment is torn down and rebuilt, and all required packages are reinstalled. This ensures that all required dependencies are of the correct version while avoiding pip conflicts.

However, this does not account for optional packages which may have been installed, such as napalm or django-storages. We need a mechanism for users to track the existence of these additional packages to ensure that they too are reinstalled during an upgrade.

(The resolution here may extend beyond mere documentation, but I have opened this as a documentation issue as it seemed to fit best.)

[jeremystretch]

IMO the best solution here is to designate a particular file, e.g. local_requirements, for the enumeration of any optional packages that need to be reinstalled. The upgrade script will check for this file and, if it exists, make a second call to pip: pip3 install -r local_requirements.txt.

Open to other suggestions, though.

[dstarner]

Yea the two options I could see are either have pip freeze > local_requirements.txt and then load it if present, or just add --options to the install script like napalm-enabled, --ldap-enabled, storage-enabled

[fourstone]

why not just go with jeremys suggestion:

requirements.txt (delivered)
requirements_local.txt (locally edited and static, i.e. not touched by the upgrade)

During upgrade both files are used to pull their components.

imho simple and clean.

PS: This kind of change would better fit into a major release, not really in a minor revision.

[jeremystretch]

PS: This kind of change would better fit into a major release, not really in a minor revision.

As I've explained on the discussion list, NetBox versioning implies changes (or the lack thereof) to NetBox's API, major features, and integrations. It has no bearing on routine tasks relating to systems administration. As with every release, it's important to read the release notes prior to upgrading.

[fourstone]

most software projects differentiate between minor changes which are always permissible and architectural or otherwise groundbreaking changes only permissible in major revision numbers. They do this because it was proven to be good for everybody.

What I am trying to say: If you have such a change as now, why not
a: wait until a few such things come together and make a major revision
b: do it now and just give it a major number so everybody is prewarned.

thanks, Martin

[jeremystretch]

This issue is closed. Please see the discussion on the mailing list.