/docs/terminology.txt

Silver Lining Terminology
=========================

This terminology is not yet implemented, but with a refactoring it
will be:


Provider:
    This is a provider like Rackspace, EC2, etc.  This is generally
    defined in ``~/.silverlining.conf``.  This generally includes account
    information in addition to the actual provider, so if you are
    working with multiple accounts you will have multiple providers.

Node:
    This is a virtual server that has been setup.  It has a name,
    which is also the domain name it can be accessed by.  The name
    doesn't have to be in DNS (``/etc/hosts`` is setup for this).
    Hostnames can be substituted for node names in all cases (but a
    node that has just been created has no hostnames because no sites
    have been deployed to it).  Node names and hostnames can overlap.

Location (FIXME: not a great name):
    This is a hostname, and optionally a path where an application
    will live.  For example, ``blog.example.com/about/``.  Multiple
    locations can be mapped to a single application.

Hostname:
    The host part of a location.

Application Package:
    This is a codebase that can be run.  It has an app.ini file, and a
    runner for the application.

Application:
    This is an application package, ready to deploy.  It also has an
    application name.  Application Packages specify a default name,
    but application names are unique on a node; so if a deployment
    uses a particular application name then it is the identical
    application and will replace the old application.  If, for
    instance, you want to install two distinct versions of the same
    application package -- e.g., two versions of a blog product --
    then you must give them two separate application names.

Deployment:
    This is a specific deployment of an application.  It is named
    based on the application name and a timestamp and unique integer.
    The name is referred to as ``instance_name``.

Site:
    This is an arrangement of applications and their locations, and
    potentially an arrangment of servers to support those applications
    (if the entire site is not deployed on a single server).

Services:
    These are persistent services that the application will use.

deb Package:
    This is unsurprisingly a deb package, installed with apt-get.
    Generally these will be Ubuntu packages, but you can use other
    repositories and install packages by other providers.

``app_dir``:
    This is the directory where Application files have been uploaded
    on a server, generally ``/var/www/APP_NAME.TIMESTAMP``.

``instance_name``:
    This is the name of the deployment, e.g., ``APP_NAME.TIMESTAMP``.

``hostname``:
    This is a host that can be ssh'd to.

``app_name``:
    This is the name of the app on the server (``APP_NAME``).

``node``:
    There are a limited number of times when ``node`` is distinct from
    ``hostname``:

    * first, if you provide ``--node`` then that overrides the
      hostname for ssh, etc.  This can be useful when there is a load
      balancer in front of the server, or many servers provide the
      same hostname (e.g., many load-balanced app servers).

    * second, if the hostname is not mapped to anything (it has not
      been created, it is not in ``/etc/hosts``), then this lets the
      hostname be mapped to a specific node/server.

    In other cases, hostname and node are equivalent, and if a command
    includes the hostname it doesn't require an explicit node.