Documenting NAS box VM setup procedure

[hamishmb]

Yes, let's make that explicit. Terry, would you like me to author a new version, or do you want to make that change?

So we're okay with the bridged adaptor? I might also need to clarify that the end user will need to check their settings and make sure the bridged adaptor is bridging to a real device on their system (rather than the reference to the network device from my system).

[PatrickW]

So we're okay with the bridged adaptor? I might also need to clarify that the end user will need to check their settings and make sure the bridged adaptor is bridging to a real device on their system (rather than the reference to the network device from my system).

Is this intended simply to document how it has been done already? If so, then presumably it must speak of a bridged adaptor, because that is what has actually been done.

If it is also meant to document how it should be done in the future, then I think it's a bit inconsistent. Someone reading the document might see that the NAS VM is recommended to have a bridged adapter and think it is something special about the NAS VM, when in reality it's just two different people choosing a slightly different configuration. Presumably, if you were writing about the Pi VMs, you would have used a bridged adaptor for those, too.

I am of the opinion that it is a bad idea to recommend a bridged adaptor as standard. It's a valid configuration, but it only works if the VM host is connected to a trustworthy LAN that can hand out extra IP addresses via DHCP and doesn't subject each VM to a captive portal, whereas NAT should work anywhere where the host has internet access.

I think the proper way to resolve this is to originally create the base image with a third network adaptor, which gets connected to the default vboxnet0 host-only network. (Using DHCP, like the second adaptor.) This should provide working host-to-guest networking in practically any scenario. Adaptors 1 and 2 would remain as I had them before. I think I would have done this from the outset if I'd not made the mistake of thinking NAT provides host-to-guest networking.

[TerryJC]

Yes, let's make that explicit. Terry, would you like me to author a new version, or do you want to make that change?

I think I would, There has been lots of discussion between Patrick and yourself, which seems to be ongoing. I haven't really followed, let alone understood all of this, so my efforts to update the documentation would almost certainly result in errors.

Picking up on Patrick's suggestion that a new VM should be built, might I suggest that if you do this, you create the updated documentation first and then build the new VM by following it. This is the way I've been testing the documentation for the VPN and it certainly identifies mistakes quicker than any proof-reading will ever so.

Afterwards I'm happy to proof-read it to see if I could follow it.

[TerryJC]

Is this intended simply to document how it has been done already? If so, then presumably it must speak of a bridged adaptor, because that is what has actually been done.

If it is also meant to document how it should be done in the future, then I think it's a bit inconsistent. Someone reading the document might see that the NAS VM is recommended to have a bridged adapter and think it is something special about the NAS VM, when in reality it's just two different people choosing a slightly different configuration. Presumably, if you were writing about the Pi VMs, you would have used a bridged adaptor for those, too.

I am in full agreement with Patrick about this. Documentation must reflect the design and implementation of what has been done, not what you would have done had you thought of the alternative earlier.

Might I suggest that the decision to re-implement the VM or not should rest on several factors:

1. How much will the VM be used in the furure, especially by others who were not involved in the original development. ie us?
2. Does the existing VM work sufficiently well to fulfil the required function? In a business environment 'Good enough' is the watchword, because 'perfect' is expensive even if it is achievable.
3. Since we are not in a business environment, is it worth doing this simply for the advantage of expanding the knowledge base of the developers? Lots of Open Source projects come into being to give the developer experience in that particular area.

I'm sure that there are other valid reasons to do, or not do this enhancement, but I'm sure you get the idea.

[PatrickW]

For all my exposition on this topic, I don't actually think its worth rebuilding the base image VM especially for the purpose of adding an extra NIC to tidy up this documentation detail. But, it is something I would like to remember to do next time around.

In the meantime, I am content to see the bridged configuration in the documentation if we are agreed that it does not have to make a recommendation in order to be a useful document.

I think I've learnt a bit more about the role of this documentation through this discussion.

[TerryJC]

In the meantime, I am content to see the bridged configuration in the documentation if we are agreed that it does not have to make a recommendation in order to be a useful document.

There's no reason why the documentation can't have a Note stating the alternative approach and the pros and cons.

[hamishmb]

I'm happy to add a note to the documentation about this. I also don't consider it worth the time it would take to rebuild the other VMs - they work fine as is.

If I amend the document for these things, are we all good to go for uploading the new NAS box VM to the file server?

[hamishmb]

NB: It seems I neglected to say that the reason I used a bridged adaptor is so that this NAS box VM can be connected on a network with real physical pis, something we'll need to do when we test the database software on real hardware prior to deployment. I feel doing this would be a good idea to double check everything works as expected when valves and pumps and so on are actually being used rather than simulated.

I've made the changes we discussed. Here is an updated version of the document.

[TerryJC]

I have now incorporated Hamish's updated NAS VM documentation into the Installation Spec and uploaded the new version to the File Server.

Hamish, The only changes I made to your text was to change it from second person to third person to be in keeping with the rest of the document.

Apart from that I have incorporated some improvements to the general descriptions that have emerged since the last version was published.

[hamishmb]

Excellent, I'll upload the new VM now.