<body>
<h1 style="text-align: center;">The cakelampvm VM:<br>
Configuration and Usage</h1>
- <h2 style=" text-align: center;">By Chris Koeritz</h2>
+ <h2 style=" text-align: center;">By Chris Koeritz<br>
+ <span style="font-family: Comic Sans MS;">feisty meow® concerns ltd</span></h2>
<h3 style=" text-align: center;"> Vintage: cakelampvm v002
- Updated: 2017-11-16 (rev D)</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"
- href="https://httpd.apache.org/">Apache2</a>), a full <a title="ubuntu means compassion and humanity"
- href="https://www.ubuntu.com/">Ubuntu</a> <a title="it's pronounced leenoox"
- href="https://www.linuxfoundation.org/">Linux</a> desktop environment,
- the <a title="flux is change" href="http://fluxbox.org/">Fluxbox</a> <a
- title="a better windows" href="https://www.x.org/">X window manager</a>,
- and a suite of tools called the <a title="feisty meow® concerns ltd. website"
- href="https://feistymeow.org/">Feisty Meow® codebase</a> .
- Together, these services provide you with a very flexible and powerful
- testbed for web development, especially suited for <a title="it's cake" href="https://cakephp.org/">CakePHP</a>.</p>
+ in a bottle", serving up your web sites securely and only to your local
+ host. The virtual machine provides DNS services (<a target="_blank"
+ title="dns server" href="http://www.bind9.net/">bind9</a>), a Web server
+ (<a target="_blank" title="patchy" href="https://httpd.apache.org/">Apache2</a>),
+ a full <a target="_blank" title="ubuntu means compassion and humanity" href="https://www.ubuntu.com/">Ubuntu</a>
+ <a target="_blank" title="it's pronounced leenoox" href="https://www.linuxfoundation.org/">Linux</a>
+ desktop environment, the <a target="_blank" title="flux is change" href="http://fluxbox.org/">Fluxbox</a>
+ <a target="_blank" title="x11 -- best windowing system" href="https://www.x.org/">X
+ window manager</a>, and a suite of tools called the <a target="_blank"
+ title="feisty meow® concerns ltd. website" href="https://feistymeow.org/">Feisty
+ Meow® codebase</a> . Together, these services provide you with a
+ very flexible and powerful testbed for web development, especially suited
+ for <a target="_blank" title="it's cake" href="https://cakephp.org/">CakePHP</a>.
+ This VM was built with the assistance of and was partially funded by <a target="_blank"
+ title="saco design" href="http://sacodesign.com">Saco Design</a> of <a
+ target="_blank" title="winterport" href="http://www.winterportmaine.gov/">Winterport,
+ Maine</a>.</p>
<p>Commands preceded by an octothorpe ('#') below are intended to be typed
into a bash shell running on the cakelampvm virtual machine. The
bash shell can be obtained either by logging into the VM through ssh or by
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>
+ <li>Hostname: <a target="_blank" title="the vm's website, when configured properly"
+ href="https://cakelampvm.com/">cakelampvm.com</a></li>
<li>Local IP Address: 10.28.42.20</li>
<li>Services Included: DNS (bind9), apache2, fluxbox X windowing system, <a
- title="not just in the garden" href="https://www.gnome.org/">gnome
+ target="_blank" title="not just in the garden" href="https://www.gnome.org/">gnome
display manager</a></li>
<li>Main VM User: developer (password distributed separately)</li>
<li>Database Access: mysql root account, password: (password distributed
separately)</li>
</ul>
- <h2>Powering up with the Feisty Meow® scripts<a id="#powerup" name="#powerup"></a></h2>
- The feisty meow scripts are a cohesive bash scripting environment for
- getting a variety of tasks done. The feisty meow scripts recently
- incorporated the "avbash" collection from Saco Designs and added those
- scripts to a new "site_avenger" collection of scripts. The site
- avenger scripts provide tools for bringing up CakePHP web sites and managing
- the collection of repositories for those sites. Each website is
- considered an "application", and the application name itself (e.g.
- "winterportlibrary") can often provide all the details for "powering up" the
- site. The feisty meow team has added additional scripts for managing
- DNS domains and Apache websites that provide the capability to "stand up" an
- entire website around an application, with an accompanying DNS domain and
- Apache2 site definition.
- <p>The site avenger scripts are documented separately within the feisty meow
- codebase. Consult the <span style="text-decoration: underline;">f</span><a
- title="quickstart" href="https://feistymeow.org/feisty_meow/readme.txt">eisty
-meow
- readme</a> file first, as it provides some valuable information on
- configuring the codebase initially. The site avenger script commands
- are documented in the <a title="useful commands" href="https://feistymeow.org/feisty_meow/documentation/feisty_meow_command_reference.txt">feisty
- meow command reference</a> file.</p>
- <p>(The feisty meow codebase is already configured for the developer account
- on the cakelampvm virtual machine.)</p>
<h2>How to set up virtualbox for your host PC<a id="#virtualbox-setup" name="#virtualbox-setup"></a></h2>
<ol>
- <li>Download and install virtualbox:
- https://www.virtualbox.org/wiki/Downloads</li>
+ <li>Download and install virtualbox: <a target="_blank" href="https://www.virtualbox.org/wiki/Downloads">https://www.virtualbox.org/wiki/Downloads</a></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>Download the extension pack (also) at <a target="_blank" href="https://www.virtualbox.org/wiki/Downloads">https://www.virtualbox.org/wiki/Downloads</a></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
<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>
+ internet or from the LAN, and can only be accessed by your host PC.
+ This is a key component of security for your VM and your host PC, and is
+ considered a crucial configuration step.</p>
<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>
+ This can be corrected simply by opening the cakelampvm settings and
+ selecting the appropriate network names again.</p>
<p>To configure the host-only network, follow these steps:</p>
<ol>
<li> Go to virtual box "Preferences" (global preferences, not for a
<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
- address of the VM is hidden behind the NAT firewall on Virtualbox, this
- keeps the VM safe from attackers, and hence your machine stays safe as
- well.</p>
+ for any communication off of the host machine. This is another
+ crucial component for the security of the VM and your host PC. Since
+ the real IP address of the VM is hidden behind the NAT firewall on
+ Virtualbox, this keeps the VM safe from attackers, and hence your machine
+ stays safe as well.</p>
<p>To set up the NAT network, follow these steps:</p>
<ol>
<li> Go to virtual box "Preferences" (global preferences, not for a
<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
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>
+ remaining configuration problems in the VM. 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
this with:</p>
- <pre>ssh developer@cakelampvm.com (or equivalent with your ssh client)</pre>
+ <pre># ssh developer@10.28.42.20 # or the equivalent with your ssh client</pre>
<p>And then provide the password to log in.</p>
- <p>If a feature called "X forwarding" is enabled in your ssh client, then
- you can start graphical applications on the VM and display them on your
- local machine. This works right away on most Linux hosts, but can
- also work on PCs with X window system installed. The section below
- describes how to set up Cygwin to run X server, which enable X forwarding
- to your local display.</p>
- <p>...{insert that info}...</p>
+ <p>Once the DNS services are set up (discussed in detail below), you will be
+ able to run the much friendlier command:</p>
+ <pre># ssh developer@cakelampvm.com</pre>
<h2>Updating cakelampvm to the Latest Model<a id="#update-vm" name="#update-vm"></a></h2>
- <p>The cakelampvm is released with the intention to not be released
- again. Version 001 was not built with that explicit intention, which
- then required the release of Version 002. We hope to not need a v003
- release.</p>
+ <p>The cakelampvm v002 is released with the intention that it not need to be
+ released again. Version 001 was not built with that explicit
+ intention, which then required the release of Version 002. But we
+ hope to not need a v003 release...</p>
<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>
- <p># rpuffer $FEISTY_MEOW_APEX # updates to the latest version
- of feisty meow<br>
- # revamp_cakelampvm # enacts any configuration changes
- needed, plus fixes web folder and other permissions.</p>
+ process" for your VM, run the following commands on the VM (without the
+ initial '#' symbol):</p>
+ <pre># rpuffer $FEISTY_MEOW_APEX # updates to the latest version of feisty meow
+# revamp_cakelampvm # enacts any configuration changes needed,<br> # plus fixes web folder and other permissions.</pre>
<p>These two commands can be run at any time to patch up your VM to the
latest.</p>
<p>The first command ("rpuffer ...") is also useful on its own for getting
- 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>
+ the latest version of the feisty meow code. Run it again if there
+ are bug fixes you need for any of the scripts or if you would like the
+ most up-to-date cakelampvm documentation.</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>Powering up with the Feisty Meow® scripts<a id="#powerup" name="#powerup"></a></h2>
+ The feisty meow scripts are a cohesive bash scripting environment for
+ getting a variety of tasks done. The feisty meow scripts recently
+ incorporated the "avbash" collection from Saco Design and added those
+ scripts to a new "site_avenger" collection of scripts. The site
+ avenger scripts provide tools for bringing up CakePHP web sites and managing
+ the collection of repositories for those sites. Each website is
+ considered an "application", and the application name itself (e.g.
+ "winterportlibrary") can often provide all the details for "powering up" the
+ site. The feisty meow team has added additional scripts for managing
+ DNS domains and Apache websites that provide the capability to "stand up" an
+ entire website around an application, with an accompanying DNS domain and an
+ Apache2 site definition.
+ <p>The site avenger scripts are documented separately within the feisty meow
+ codebase. Consult the <span style="text-decoration: underline;">f</span><a
+ target="_blank" title="quickstart" href="https://feistymeow.org/feisty_meow/readme.txt">eisty
+meow
+ readme</a> file first, as it provides some valuable information on
+ configuring the codebase initially. The site avenger script commands
+ are documented in the <a target="_blank" title="useful commands" href="https://feistymeow.org/feisty_meow/documentation/feisty_meow_command_reference.txt">feisty
+ meow command reference</a> file.</p>
+ <p>(The feisty meow codebase is already configured for the developer account
+ on the cakelampvm virtual machine.)</p>
+ <h2>X11 applications launched from the VM</h2>
+ <p>[incomplete section]</p>
+ <p>If a feature called "X forwarding" is enabled in your ssh client, then
+ you can start graphical applications on the VM and display them on your
+ local machine. This works right away on most Linux hosts, but can
+ also work on PCs with X window system installed. This section
+ describes how to set up Cygwin to run X server, which enables X11
+ forwarding to your local display.</p>
+ <p>...{insert that info}...</p>
<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*
wrong, and means something needs to be fixed.</p>
<p>If these pings succeed (which hopefully they will!), then try accessing
the websites of each domain:</p>
- <pre>(browse to) http://cakelampvm.com</pre>
- <pre>(browse to) http://mapsdemo.cakelampvm.com</pre>
+ <pre>(browse to) <a target="_blank" title="vm website if dns working" href="http://cakelampvm.com">http://cakelampvm.com</a></pre>
+ <pre>(browse to) <a target="_blank" title="mapsdemo app, hopefully functional"
+href="http://mapsdemo.cakelampvm.com">http://mapsdemo.cakelampvm.com</a></pre>
<p>These should show local sites on the VM rather than sites on the
internet. If you instead get failures to find the domains, or if the
"real internet" site comes up for cakelampvm.com (the page covered with
developer's home folder also ("/home/developer").</p>
<p>If you run into any permission problems that prevent file access, either
remotely or within the VM itself, then try running this command to fix
- them:</p>
+ them (repeated from the section above about updating the cakelampvm):</p>
<pre># revamp_cakelampvm</pre>
<p>Afterwards, the www folder and others should allow the developer user to
create new folders at will.</p>
- <p>The revamp command above is also used to deliver new configuration to the
- VM from the feisty meow script environment; running it after any update of
- the feisty meow codebase is a good idea.</p>
<h2>Accessing files on the host PC from the guest VM<a id="#samba-shares" name="#samba-shares"></a></h2>
<p>If you want to share a folder from the host to the guest, perhaps for
driver updates or other conveniences, then make the share with these
<p>Note: these instructions, even the quick approaches below, pale in
comparison to the ease of use of the "standup" command in feisty meow's
site avenger scripts. The standup command is detailed in the <a
- title="useful commands" href="https://feistymeow.org/feisty_meow/documentation/feisty_meow_command_reference.txt">feisty
+ target="_blank" title="useful commands" href="https://feistymeow.org/feisty_meow/documentation/feisty_meow_command_reference.txt">feisty
meow command reference</a> document. These instructions are for
situations when the domain or site is idiosyncratic in some way that
standup doesn't support.</p>
<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 "<a title="it's excalibur, wilbur!"
+ href="http://excalibur.tv">http://excalibur.tv</a>". 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
+ target="_blank" 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 target="_blank" 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>
projects / feisty_meow.git / blobdiff