Perkify - Usage
Written by Rich Morin.
Precis: Usage notes for Vagrant-based Perkify
The Perkify - Install page contains installation instructions and a few example commands, but it doesn’t really concentrate on how to use Perkify. So, let’s dig into that topic a little…
Perkify is, at heart, a Linux distribution. Specifically, it is based on Ubuntu, a “batteries included” distribution intended for end users. Because Ubuntu is based on Debian, it has access to an immense suite of installable packages via Debian’s Advanced Package Tool (APT). Using APT and other package managers, we fold in a variety of commands, libraries, etc. If there is something you’d like us to add, please let us know! (Be sure to include relevant links and your reasons for its inclusion.)
Perkify is distributed as a Vagrant “box”, containing a VirtualBox virtual machine (VM) image. Although this description hides a great deal of complexity, you don’t need to know the details in order to manage the VM. And, because everything can be done from the command line, you won’t have to deal with the vagaries of Graphical User Interfaces (GUIs).
Most of Vagrant’s operation and administration is performed
using variations on the
There are dozens of sub-commands,
so this section is just a brief introduction for Perkify users.
For more detailed information, check out this
or the Vagrant
Command-Line Interface page.
This displays help text for the
Mostly, it summarizes the available sub-commands:
$ vagrant -h Usage: vagrant [options] <command> [<args>] -v, --version Print the version and exit. -h, --help Print this help. Common commands: box manages boxes: installation, removal, etc. cloud manages everything related to Vagrant Cloud ... ...
This halts (shuts down) the Vagrant VM and destroys any saved machine state. Use this if you’ve mangled the VM and want to start over from a fresh image.
This halts (shuts down) the Vagrant VM, saving any persistent machine state.
This initializes a new Vagrant environment by creating a
Once Vagrant has been set up, you can generally forget about this sub-command.
This sets up a Secure Shell (SSH) connection to the Vagrant VM. It can be run multiple times, producing multiple shell sessions. It can also start up X11 sessions, etc.
This displays the status of the Vagrant machine(s) on the host system.
vagrant suspend /
This pair of commands is useful if you want to temporarily suspend the VM and resume its operation later. This approach retains both persistent and transient state and avoids doing a full boot of the guest OS.
This starts up a Vagrant VM, possibly downloading the needed image files.
In general, this sub-command should be run in the
Once the Perkify VM has been started (via
it acts very much like an Ubuntu-based system on your
local area network (LAN).
So, it can provide Secure Shell (SSH) access,
web servers, and other networked services.
It can also access both its own file system and that of the host machine.
Although a running Linux system has a number of mounted file systems
df -k for an overview), most Perkify users will only be concerned
with a few directories:
/home/vagrant- the home directory for the
/vagrant- a synchronized copy of
~/perkifyon the host OS
In order to access host files from within the VM, you may want to add more synchronized directories. See Perkify - Configuration for details.
Getting access to a Perkify shell session from the host OS is simple:
just run the
vagrant ssh command.
Getting access from another machine takes only a little more work:
user@foo $ ssh user@bar # SSH to machine `bar` user@bar $ cd perkify # go to `~/perkify` user@bar $ vagrant ssh # SSH to the Perkify VM vagrant@perkify:~$ # and here you are...
Once you have shell access, the next thing you might want to do is search for interesting and/or useful packages. Because Perkify is so large, this can be a challenge, but see the Perkify - Search page for ideas.
It’s quite possible to run a web server within the Perkify VM. In fact, a copy of Apache is enabled by default. However, in order to access web servers from outside the VM, their ports must be “forwarded” to the host machine. For details, read the Forwarded Ports page.
The Apache server normally communicates via port 80.
By convention, Vagrant forwards this port on the VM to port 8080 on the host.
So, you can access this web server as
All you’ll get if you access this URL is a placeholder
located in the
Feel free to season to taste…
Although the Vagrant documentation strongly suggests the use of port forwarding, the Vagrant software is quite willing to let you set up private and public networks, etc. Just understand that any confusion (or security holes) you create are your own problem. For details, read Vagrant’s Networking page.
At this point, you should have enough knowledge to go off on your own. Check out the Package Index and Package List pages for ideas. Also, you’ll certainly have questions about Linux, Ubuntu, and Vagrant. See the Perkify - Resources page for some pointers.
To be continued…