Configuration and Usage</h1>
<h2 style=" text-align: center;">By Chris Koeritz</h2>
<h3 style=" text-align: center;"> Vintage: cakelampvm v002
- Updated: 2017-11-16</h3>
+ Updated: 2017-11-20 (rev F)</h3>
<p>The cakelampvm project provides a Virtualbox VM that acts as an "internet
in a bottle". The virtual machine provides DNS services (<a title="dns server"
href="http://www.bind9.net/">bind9</a>), a Web server (<a title="patchy"
ssh session more convenient, because copy & paste features work as
expected.</p>
<p>Commands preceded by a greater-than symbol ('>') are intended to be
- run on the Host PC in a Windows command prompt (or in a bash prompt running
- on the Host PC).</p>
+ run on the Host PC in a Windows command prompt (or in a bash prompt
+ running on the Host PC).</p>
<h2> Guest VM Configuration<a id="#config" name="#config"></a></h2>
<ul>
<li>Hostname: <a title="the vm's website, when configured properly" href="https://cakelampvm.com/">cakelampvm.com</a></li>
<ol>
<li>Download and install virtualbox:
https://www.virtualbox.org/wiki/Downloads</li>
- <li>Install the extension pack for virtualbox: This provides USB drivers
- and other features. This is installed on virtualbox itself, not on
- the guests.</li>
+ <li>Install the extension pack for Virtualbox: This provides USB drivers
+ and other features. This is installed on Virtualbox itself (on the
+ Host PC), not on the guests.</li>
<ol>
<li>Download the extension pack at
https://www.virtualbox.org/wiki/Downloads</li>
- <li>Stop any running virtualbox vms.</li>
- <li>Close virtualbox control panel.</li>
+ <li>Stop any running Virtualbox VMs.</li>
+ <li>Close the Virtualbox control panel.</li>
<li>Double-click on the downloaded extensions package (in a file
- explorer) and virtualbox should install it.</li>
+ explorer) and Virtualbox should be launched to install it.</li>
</ol>
- <li>Run the virtualbox control panel.</li>
+ <li>Run the Virtualbox control panel.</li>
<li>Download the cakelampvm guest vm package and unzip it. Store the
unzipped version in some appropriate place where you want the virtual
machine to reside on your host's hard drive.</li>
- <li>Add the guest VM to your list of VMs. From the virtualbox menus,
+ <li>Add the guest VM to your list of VMs. From the Virtualbox menus,
choose the "Machine" menu and select "Add". Point the selector
dialog at the cakelampvm folder you created above and open the
cakelampvm.vbox file.</li>
machines. Before starting it, perform the following network
configuration sections.</li>
</ol>
- <h3>Configure the Host-Only network on
virtualbox<a id="#host-only" name="#host-only"></a></h3>
+ <h3>Configure the Host-Only network on
Virtualbox<a id="#host-only" name="#host-only"></a></h3>
<p>Configuring host-only networking for the VM makes the VM completely local
to your machine. The cakelampvm will not be accessible on the
internet or from the LAN, and can only be accessed by your host PC.</p>
- <p>Note: If the host-only or NAT network exist ahead of time, virtualbox may
+ <p>Note: If the host-only or NAT network exist ahead of time, Virtualbox may
complain about them even if they have the correct configuration.
This can be corrected simply by opening the VM settings and selecting the
appropriate network names again.</p>
</ol>
<p>Additional information on host-only (and other) network adapter types is
at: https://www.virtualbox.org/manual/ch06.html#network_nat_service</p>
- <h3>Configure the NAT Network on
virtualbox<a id="#nat-network" name="#nat-network"></a></h3>
+ <h3>Configure the NAT Network on
Virtualbox<a id="#nat-network" name="#nat-network"></a></h3>
<p>The NAT (Network Address Translation) network allows the VM to get off of
the machine and onto the internet safely. It will use this interface
for any communication off of the host machine. Since the real IP
<img alt="nat net config" src="images/nat_network_config.png"></li>
</ol>
<h2>Starting up the VM<a id="#start-vm" name="#start-vm"></a></h2>
- <p>Using the virtualbox interface, you should now be able to start your
+ <p>Using the Virtualbox interface, you should now be able to start your
virtual machine. Virtualbox will complain if it detects any
remaining configuration problems in the VM, but it should start
normally. The Linux boot sequence will show many lines of text,
before bringing up a black console window with a login dialog.</p>
<p>If Windows complains about the Virtualbox application slamming into its
firewall, then allow the Virtualbox to get through. Usually, telling
- Windows that once is enough, but if any odd network access problems result,
- edit the Windows firewall settings and allow Virtualbox to use both
- "Public" and "Private" networks.</p>
+ Windows that once is enough, but if any odd network access problems
+ result, edit the Windows firewall settings and allow Virtualbox to use
+ both "Public" and "Private" networks.</p>
<p>You can log in directly on the VM console with the developer account, but
it is generally more useful to connect to the cakelampvm over ssh.
If the networking has been established properly, you should be able to do
<p>There is an update feature built into the VM that is quite easy to
use. The updates are driven by the feisty meow script repository in
conjunction with a local scripted command. To activate the "update
- process" for your VM, run the following commands (without the initial '#'
- symbol):</p>
+ process" for your VM, run the following commands on the VM (without the
+ initial '#' symbol):</p>
<p># rpuffer $FEISTY_MEOW_APEX # updates to the latest version
of feisty meow<br>
# revamp_cakelampvm # enacts any configuration changes
the latest version of the feisty meow code. If there are bug fixes
you need for the scripts or you want updated cakelampvm documentation,
that is the command to use.</p>
+ <h2>First Tasks as the Developer User</h2>
+ <p>Here are some first steps that will make the vm your own:</p>
+ <ol>
+ <li>Change your password for the developer account. (This may
+ eventually be required and automatic.) First, log into the VM with
+ ssh. Then type this command:<br>
+ <pre># passwd</pre>
+ The 'passwd' command will ask for your current password, and then for a
+ new password plus a verification of that new password.<br>
+ </li>
+ <li>Change your git configuration for the user and email address. This
+ is how we've configured it so far:<br>
+ <pre># git config --global user.email "developer@cakelampvm.com"</pre>
+ <pre># git config --global user.name "Developer J. Cakemo"</pre>
+ If you're developing on a real project, you probably don't want the
+ bogus email and even more bogus name above attached to your
+ commits. Just run the two commands again but with proper values.</li>
+ </ol>
<h2>Using the guest VM's DNS services<a id="#dns-from-vm" name="#dns-from-vm"></a></h2>
<p>The cakelampvm has been set up to provide a DNS server which will answer
name lookup requests on any of the sites that the cakelampvm is hosting
<p>Once the DNS server is properly set up (by whatever means necessary),
these ping commands should get answering responses (from 10.28.42.20) on
both the cakelampvm VM and on your host PC. Note: ping on Linux
- keeps going forever, so hit control-C when you are tired of seeing the pings:</p>
+ keeps going forever, so hit control-C when you are tired of seeing the
+ pings:</p>
<pre># ping cakelampvm.com</pre>
<pre># ping mapsdemo.cakelampvm.com</pre>
<p>Note that any other answer than 10.28.42.20 for the address is *bzzzt*
steps:</p>
<ol>
<li>Create a folder on the host that is to be shared.</li>
- <li>Right-click on the vm in virtualbox manager and choose "Settings".</li>
+ <li>Right-click on the vm in Virtualbox manager and choose "Settings".</li>
<li>In the "Shared Folders" tab of the settings, go to "Machine Folders".</li>
<li>Click the folder plus icon to create a new share.</li>
<li>Fill in the "Folder Path" on the host PC to the folder that will be
<pre># sudo service bind9 restart</pre>
<p>Afterwards, pinging excalibur.tv should work from both the guest and the
host.</p>
- <h3>Creating a New Apache site</h3>
+ <h3>Creating a New Apache Site</h3>
<p>First, connect to the cakelampvm via ssh as the developer user, e.g.: ssh
developer@cakelampvm.com </p>
<h4>Quick approach: Use the feisty meow "add_apache_site" command.</h4>
<h4>Manual approach: Edit an Apache config file</h4>
<p>Note: the manual approach is not compatible with later use of feisty
meow's "remove_apache_site".</p>
- <p>For Apache, the choice of DNS Option A or B, subdomain or SLD does not
+ <p>For Apache, the choice of DNS Option A or B, subdomain or SLD, does not
matter. The site configuration file just has to accurately specify
the domain in question.</p>
<p>Start with the following template file for the new website, and modify it
- for the appropriate host name:</p>
+ for the appropriate host name and "DocumentRoot" path:</p>
<pre><VirtualHost *:80><br> ServerName excalibur.tv
DocumentRoot /home/apps/excalibur<br> ErrorLog ${APACHE_LOG_DIR}/excalibur.tv-error.log<br> CustomLog ${APACHE_LOG_DIR}/excalibur.tv-access.log combined<br> Include /etc/apache2/conf-library/basic-options.conf<br> Include /etc/apache2/conf-library/rewrite-enabling.conf<br></VirtualHost></pre>
<p>The above example is appropriate for our excalibur app in the
excalibur.tv domain (using DNS Option B). Modifying the excalibur.tv
- references in it is sufficient to retarget it for any domain you want.</p>
+ references in it (and the path in the DocumentRoot) is sufficient to
+ re-target it for any domain you want.</p>
<p>Copy the new site config file into "/etc/apache2/sites-available" with an
appropriate file name that includes the site's domain name. We will
call our config file "excalibur.tv.conf". If you developed the file
it means the DNS is working. If there are no responses or it's some
other IP address talking back, check the instructions in the above DNS
sections.</p>
- <p>Once the DNS is working, try browsing to the site at "http://excalibur.tv".
- That should at least bring up the configured site storage path, even if
- nothing is being served from that folder yet.</p>
+ <p>Once the DNS is working, try browsing to the site at
+ "http://excalibur.tv". That should at least bring up the configured
+ site storage path, even if nothing is being served from that folder yet.</p>
<p>If the new site is not showing up properly, try examining the apache logs
- for error messages that can be corrected. The log files are stored
- in "/var/log/apache2" and are named after the website (if configured as
- shown above).</p>
- <h2>Handy Techniques</h2>
+ for any error messages that can be corrected. The log files are
+ stored in "/var/log/apache2" and are named after the website (if
+ configured through the above process).</p>
+ <h2>Handy Techniques for Using cakelampvm</h2>
<h3>Assorted Guides and Cheat-Sheets</h3>
- <p>Cheat sheet for Vim: <a title="vim commands" href="https://vim.rtorr.com/">https://vim.rtorr.com/</a></p>
- <p>Git branching model that seems to work well: <a title="release and patch process"
+ <p>A Cheat sheet for the Vim editor (there are many of these available): <a
+ title="vim commands" href="https://vim.rtorr.com/">https://vim.rtorr.com/</a></p>
+ <p>A git branching model that seems to work well: <a title="release and patch process"
href="http://nvie.com/posts/a-successful-git-branching-model/">http://nvie.com/posts/a-successful-git-branching-model/</a></p>
<h3>Get the network address on the guest vm</h3>
<p>Run this command: ifconfig</p>
<p>In the results, look for "inet addr". There may be more than one,
if there are multiple network interfaces.</p>
+ <p>The standard IP address is 10.28.42.20 for the cakelampvm.</p>
<h3>How to cleanly reboot or shut down the guest VM</h3>
<p>When you've got the DNS and everything integrated, these commands will
manage the vm's state:</p>
- <p>First, log into the guest VM: ssh developer@cakelampvm.com</p>
- <p>Then, reboot the guest VM: sudo reboot</p>
- <p>Or, halt the guest VM: sudo shutdown -h now</p>
- <p>Using these commands is better than just cycling the power from the
- virtualbox control panel.</p>
- <p><br>
- </p>
- <p><br>
- </p>
+ <p>First, log into the guest VM:</p>
+ <pre># ssh developer@cakelampvm.com</pre>
+ <p>Then, to reboot the guest VM:</p>
+ <pre># sudo reboot</pre>
+ <p>Or, to halt the guest VM:</p>
+ <pre># sudo shutdown -h now</pre>
+ <p>Using these commands is kinder to the VM than just cycling the power from
+ the Virtualbox control panel.</p>
<p><br>
</p>
- <h1>Gritty Details</h1>
+ <h1>Gritty Details of the Nitty Variety<a id="#nitty-gritty" name="#nitty-gritty"></a></h1>
<p>This is the lowest level of plumbing for your VM. Hopefully you
- will not need to engage with this section. The most useful area here
- is the one below about the "virtualbox guest additions", which you will
- probably need at some future point. Oracle releases updates to the
- guest additions fairly regularly.</p>
+ will not need to engage with this section. The most useful doc
+ section here is the one below about the "Virtualbox guest additions",
+ which you will probably need at some future point. Oracle releases
+ updates to the guest additions fairly regularly.</p>
<h2>Configuring the guest VM</h2>
<p>The guest VM should already be set up appropriately. These steps
are provided for reference and updates.</p>
- <h3>Set up virtualbox guest additions for the VM</h3>
+ <h3>Set up Virtualbox guest additions for the VM</h3>
This procedure is needed if the guest provides an older or incompatible
version of the guest additions (which have already been installed on the
guest vm). It may also be necessary when a new version of the guest
<li>On the guest VM, it may be necessary to mount the CD image that's now
available:<br>
<pre># sudo mount /dev/sr0 /media/cdrom</pre>
+ <p>Linux will mention that the device is mounted "read-only".</p>
</li>
<li>Since the VM currently has no windowing system installed, one must
start the Guest Additions install manually:<br>
<pre># cd /media/cdrom<br># sudo sh VBoxLinuxAdditions.run</pre>
</li>
- <li>This should install the guest additions.</li>
+ <li>The latest Virtualbox guest additions should now be installed.</li>
</ol>
<h3>Set up network adapters on guest VM</h3>
<p>The network interfaces should already be configured on the guest within
- the virtualbox configuration. This is available by clicking on the
- VM in the virtualbox manager and selecting "Settings". These are the
+ the Virtualbox configuration. This is available by clicking on the
+ VM in the Virtualbox manager and selecting "Settings". These are the
configuration settings used:</p>
Adapter 1:<br>
Attached to: Host-only Adapter<br>
<p>This is all work that should already have been done. It is
mentioned here just as breadcrumbs for a future vm builder.</p>
<ul>
- <li>Downloaded and installed virtualbox for host computer (where the vm
+ <li>Downloaded and installed Virtualbox for host computer (where the vm
image will be built).</li>
<li>Downloaded ubuntu server 16.04 iso.
(https://www.ubuntu.com/download/server)</li>
- <li>Created a new vm in virtualbox, telling it to start from the ubuntu
+ <li>Created a new vm in Virtualbox, telling it to start from the ubuntu
server iso.</li>
<li>Installed LAMP stack on guest VM. Some help here:
http://howtoubuntu.org/how-to-install-lamp-on-ubuntu</li>
https://askubuntu.com/questions/628938/how-to-install-cakephp-in-ubuntu-14-04</li>
<li>Configured the two network adapters as needed (one for host-only
network and one for nat network). Here's some info about
- virtualbox networking with two adapters similar to our setup:
+ Virtualbox networking with two adapters similar to our setup:
https://askubuntu.com/questions/293816/in-virtualbox-how-do-i-set-up-host-only-virtual-machines-that-can-access-the-in<br>
</li>
<li>Installed and configured Samba service for the guest VM. The
projects / feisty_meow.git / blobdiff